Almanac

The forecast that reads the news, while the math stays math.

The LLM is a sensor, not a judge. The model turns messy reality into typed claims that carry their evidence. Deterministic code verifies those claims, makes every decision and computes every number. Humans approve anything that acts.

What it measures

Almanac forecasts how much stock a shop will need, starting by repairing the history: a day that sold out understates real demand, so that day is corrected before anything is fitted.

The forecast is ordinary statistics, and the output is a range to order within rather than a single number, with a plain sentence about what you lose at each end.

Free-text notes about local events become typed signals stored beside the numbers; in this phase they never silently move a quantity.

Published limits

verbatim from EVAL.md, produced by a real eval run On a seeded synthetic store with planted stockouts, censored-demand repair lands within 6.9% of the planted true demand (MAPE 0.0687 against a 0.20 bound) and the forecast within 8.6% on held-out days (MAPE 0.0862 against a 0.25 bound), with order envelopes always correctly ordered and monotone in service level (1.0); the generator is synthetic and stationary, so it does not measure accuracy against real retail demand, promotions or supply shocks.

This is an API

There is no web application here. Every endpoint below is JSON, and both reads and writes require a bearer token; unauthenticated requests are refused with 401. The interactive schema at /docs is deliberately public so the route map can be read without credentials.

method	path	what it does
POST	`/api/v1/ingest`	ingest sales history CSV, repair censored demand
POST	`/api/v1/forecasts`	forecast with prediction intervals
GET	`/api/v1/forecasts/{sku}`	stored forecast
POST	`/api/v1/envelopes`	order envelope with regret notes
GET	`/api/v1/envelopes/{sku}`	stored envelope
POST	`/api/v1/autopsy`	score a forecast against actuals
POST	`/api/v1/signals`	context signal from a free-text note (key-gated)
GET	`/api/v1/signals`	stored signals

Links

Source on GitHub — code, eval reports, failure gallery
/docs — interactive API schema, and /openapi.json
/health — liveness
Incident postmortem — the 2026-07-27 unauthenticated reads, with its exposure window and the fact that no access logs existed
portfolio-ops — the deploy gate that proves this estate after every deploy

version 0.3.2 · commit 82508d6 · built 2026-08-03T02:40:12Z · environment production
Values are baked from build arguments. unknown means the image was built without them, which is reported rather than replaced with a plausible-looking string.