# Sprint forecast (exact-state, simulation-first)

This repository contains a reference implementation of the amended model:

- **Supply / capacity**: daily capacity is a product of planned hours, Bernoulli
  availability, an enumerated blocked/disruption state, and an **unbounded**
  lognormal productivity multiplier.
- **Demand / workload**: remaining work is modelled from **three-point
  estimates** with **global + per-engineer bias correction** on the log scale,
  then mapped to unbounded lognormal item-effort distributions.
- **AI attribution**: AI usage can be introduced as a covariate in both the
  demand-side (bias model / workload) and the supply-side (focus multipliers).
  The implementation computes **counterfactual success probabilities** with AI
  turned off.
- **Bayesian pooling**: conjugate pooling utilities (Beta--Binomial,
  Dirichlet--Multinomial) and linear-Gaussian shrinkage estimators for bias and
  focus parameters.

The core API is `SprintSuccessForecaster`.

## Quickstart

Install:

```bash
python -m pip install sprint-forecast
```

Run the demo:

```bash
python -m sprint_forecast.demo
```

## Zenhub sprint forecast

`run_forecast.py` supports pulling per-issue three-point estimates for the current open Zenhub sprint:

- Set `workload_source.type` to `zenhub_sprint_issues` (see `config.example.json`)
- Provide `ZENHUB_API_TOKEN`
- Export `.scarf/pert-hours.json` from the PERT Hours Tracker (or disable `workload_source.pert.require_*`)

## Sprint process

See `docs/sprint-process.md` for the recommended workflow (assignments, PERT in effective hours, actual tracking, required fields, and AI assumptions).

## Structure

- `sprint_forecast/` – library code
- `examples/` – runnable example
- `tests/` – unit tests (`python -m unittest`)

## Notes

- The implementation targets Python 3.11+.
- Randomness is handled via NumPy's `Generator`.
