# Confirmation Outlook — Northpoint Manufacturing

A full-stack demo of a **predictive supply-chain tool**: instead of reporting last week's
order-confirmation rate, it forecasts **which materials will miss confirmation next week**,
splits the at-risk book into recoverable vs structural, and hands an operator the lever to pull.

**▶ Live: https://demo.appliediqsolutions.com** — no login, synthetic data.
Write-up: https://appliediqsolutions.com/confirmation-outlook/

**Northpoint Manufacturing is fictional. Every row of data is synthetic** — generated by a
seeded, documented generator — and every number on screen is then **computed by a real engine**
that has no access to the generator's hidden state. The build fails if the engine can't honestly
recover the planted structure (42-assertion validation gate).

> Built by Ian Provencher. A de-identified rebuild of a production pattern from my
> supply-chain work — no proprietary data, code, or branding.

## What it demonstrates

| Layer | What's real about it |
|---|---|
| **Predictive engine** (`app/predict.py`) | Every probability is a **measured frequency** over week-to-week transitions — a risk table by (failing now × receipt-short × stressed) with min-support fallback, not a fitted black box. |
| **Held-out validation** | The final week is excluded from calibration and predicted from the prior week's signals: ~97% of actual failures inside the flagged register, ~80% worklist precision. The persistence floor is reported **separately** from the leading signal, so no metric takes credit it didn't earn. |
| **Data layer** | SQLite — synthetic world + precomputed warm state baked at Docker build time (cold start < 2 s). Rollups run live SQL. |
| **Serving** | One process: FastAPI REST (`/api/*`), **MCP** (`/mcp/`) for AI clients, and the React front, same validated numbers everywhere. |
| **AI chat** (`/api/ask`) | Claude answering over the same read-only tools, hard-capped for public use (per-IP sliding window + daily budget, `app/ratelimit.py`). |
| **Front** (`web/`) | Vite + React, hand-rolled SVG charts, dark/light instrument theme, glossary tooltips, xlsx exports. |

## Run it

```bash
docker compose up --build       # then open http://localhost:7860
```

Or bare Python (3.12+):

```bash
pip install -r requirements.txt
python -m app.build_db          # generate + bake + 42-assertion selfcheck
cd web && npm ci && npm run build && cd ..
uvicorn app.api:app --port 7860
```

The Ask tab needs `ANTHROPIC_API_KEY` in the environment; everything else runs keyless.

## Verify it yourself

- `python -m app.selfcheck` — the validation gate (headline memoryless, risk gradient monotone,
  held-out recall/precision, partition assertions, measured-vs-planted recovery).
- `pytest tests` — API contract tests.
- `docs/METHODOLOGY.md` — how the synthetic world is constructed and why the validation is honest.
- Every displayed number is one `curl` away: `/api/headline`, `/api/forecast`, `/api/register`.

## Architecture

```
generate.py ──> SQLite (synthetic world) ──> engine.py / predict.py ──> bake.py (warm state)
                                                        │
                              service.py (one JSON-safe source of truth)
                                    │            │             │
                                REST /api/*   MCP /mcp/   React front /
                                    └── agent.py (Claude tool loop, rate-limited)
```