# deal-forecaster

Sales pipeline forecasting and quota analytics for CRM revenue teams: forecast computes a probability-weighted pipeline total from a list of deals (amount x stage win-probability), grouped by stage...


An intelligent microservice adapter pack for sales pipeline forecasting and quota analytics. The math
is deterministic and exact and runs fully offline. Only `whatIf`'s optional narrative uses the shared
LLM helper (when `options.narrate` is set and a model is reachable), and it silently falls back to a
templated sentence otherwise. Hybrid results are tagged `{ mode: 'heuristic' | 'llm' }` — the numbers
are always exact regardless of mode.

## Tools

| Tool | What it does |
|---|---|
| `forecast` | Probability-weighted pipeline total from a list of `deals` (amount x win-probability), grouped by stage and owner, with top deals and open-pipeline breakdown. |
| `winProbability` | Maps a pipeline `stage` (lead, qualified, discovery, proposal, negotiation, verbal, closed-won, closed-lost) to a default close-rate %. Omit `stage` to get the whole map. |
| `quotaPacing` | From `closed`, `quota` and `daysLeft` (optional `daysElapsed`), reports attainment, run-rate, daily rate needed, projected attainment and a status (quota-hit / on-track / at-risk / off-track). |
| `categoryForecast` | Best-case / most-likely (commit) / worst-case scenario totals with the basis of each band. |
| `whatIf` | Re-scores the pipeline under hypotheticals (`stageShift`, `amountMultiplier`, `winRateDelta`, `includeStages`, `excludeStages`) and reports the delta vs baseline. **Hybrid narrative.** |

## Deal shape

```js
{ id?, name?, amount, stage, probability?, owner?, closeDate? }
```

`amount` accepts numbers or currency strings (`"$12,000"`). If `probability` is omitted it is derived
from `stage`; unknown stages default to a conservative 10%. `probability` may be a fraction (`0.45`)
or a percent (`45`).

## Usage

```js
import pack from './index.js';

const deals = [
  { id: 'A', amount: 50000, stage: 'negotiation', owner: 'sam' },
  { id: 'B', amount: 20000, stage: 'proposal', owner: 'lee' },
  { id: 'C', amount: 80000, stage: 'lead' },
];

pack.adapters.forecast({ deals });               // weighted pipeline total + breakdowns
pack.adapters.winProbability({ stage: 'proposal' });
pack.adapters.quotaPacing({ closed: 120000, quota: 200000, daysLeft: 12, daysElapsed: 18 });
pack.adapters.categoryForecast({ deals });       // best / commit / worst
await pack.adapters.whatIf({ deals, changes: { stageShift: 1, amountMultiplier: 1.1 } });
```

## DRY boundary notes

- Not generic stats: `numbers` / `statistics` own series analytics (percentiles, anomalies). This pack
  is CRM-specific pipeline math (stage→win-rate, commit/best/worst scenarios, quota pacing).
- Not `finance`: no NPV / interest / loan math. This is revenue forecasting on opportunities.
- Self-contained: no cross-pack imports except `../_shared/llm.js`.


---
Source: shared/engines/adapters/domain/deal-forecaster/README.md
Canonical: https://docs.leumas.tech/p/adapters/domain/deal-forecaster