Metadata-Version: 2.4
Name: sprint-forecast
Version: 0.1.0
Summary: Exact-state sprint success forecasting for small agile teams
Author: Emmett Miller
License-Expression: MIT
Project-URL: Repository, https://github.com/emmett08/stochastic-sprint-forecast
Project-URL: Issues, https://github.com/emmett08/stochastic-sprint-forecast/issues
Keywords: agile,bayesian,forecasting,monte-carlo,sprint
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: requests>=2.31
Provides-Extra: scipy
Requires-Dist: scipy>=1.10; extra == "scipy"
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.1.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Dynamic: license-file

# 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`.
