forecast-api

Prophet model behind FastAPI, containerized. POST /forecast with a date range → predictions + confidence bands.

Structure

forecast-api/
├── train.py           # trains Prophet, pickles to model/prophet_model.pkl
├── app/main.py         # FastAPI app, /forecast + /health
├── requirements.txt
├── Dockerfile
└── model/              # gitignored — generated by train.py

train.py currently fits on synthetic daily data (trend + weekly/yearly seasonality + noise). Swap load_training_data() for your real series — just needs ds/y columns.

Run locally (no Docker)

pip install -r requirements.txt
python train.py                # writes model/prophet_model.pkl
uvicorn app.main:app --reload  # http://localhost:8000/docs

Run with Docker

docker build -t forecast-api .
docker run -p 8000:8000 forecast-api

Model is trained during the image build (baked in), so container start is instant — no cold-start training. For a real model, swap the RUN python train.py build step for pulling a versioned artifact from a registry (S3/GCS/MLflow) instead.

API

POST /forecast

{"start_date": "2026-08-01", "end_date": "2026-08-05"}

→

{
  "predictions": [
    {"date": "2026-08-01", "yhat": 175.6, "yhat_lower": 169.1, "yhat_upper": 181.4},
    ...
  ],
  "interval_width": 0.8
}

• Max range: 730 days (guards against pathological requests)
• end_date < start_date → 422 with a clear validation message

GET /health — 200 {"status": "ok"} if the model is loaded, 503 otherwise.

Verified

• Ran locally with uvicorn, hit /health and /forecast with curl — real Prophet predictions returned, not mocked.
• Validated bad date ranges (end < start, >730-day span) return 422 with the field-level error, not a 500.
• Dockerfile is written but not build-tested — no Docker daemon in this sandbox. Build it locally before you trust it; if install_cmdstan() fails in the image, it's almost always a missing build-essential/curl or a cmdstan version mismatch with cmdstanpy.

Gaps you'd still want before calling this "production"

• No model versioning / retraining pipeline (this is next: CI/CD gap)
• No auth on the endpoint
• No request logging / tracing (observability gap — LangSmith-style, or just structured logs + Prometheus)
• Single global model — no per-entity (e.g. per-user) forecasting yet