[selvarajuv]

Summary

Adds the EBM pricing model end to end: training runs as a background job on ingested performance
and weather data, and GET /hotels/{id}/recommendations now returns a real rate from the hotel's
active model instead of a placeholder. Also moves Postgres to Neon and standardizes the backend
layers and API docs.

Closes #43

Type of change

• feat — new feature
• fix — bug fix
• docs — documentation only
• refactor — code change that neither fixes a bug nor adds a feature
• perf — performance improvement
• test — adding or updating tests
• chore / build / ci — tooling, deps, or pipeline changes

Changes

• Model: EBM versioned per hotel (one active at a time), with an 80% price range, a per-night
  uncertainty value and occupancy-weighted training (decisions 0001–0009).
• Training (new API): POST /hotels/{id}/train (description, date window, activate, EBM
  settings) runs as a job. Also GET /hotels/{id}/models, GET /models/{id} and POST /models/{id}/activate.
• Recommendations (response changed): served by the active model, using only data already
  ingested. Weather is recorded, then forecast, then typical for that week. Returns the rate, range,
  uncertainty and the factors behind the price (detail + amount). is_placeholder is now always
  false.
• Ingest: runs as background jobs through the API, with cities as the market. Endpoints moved
  to routes/ingest.py; URLs unchanged.
• Backend layers: repositories never commit, services raise domain errors mapped to HTTP in
  one place, and there's one router per domain.
• Database: hosted on Neon, using the pooled URL for the app and the direct URL for Alembic.
  just <recipe> --neon switches between local and Neon (decision 0027).
• API docs: every field is described, and /docs example bodies are built from the fields'
  defaults and examples (decision 0030).
• Tests: the outdated suite is replaced with a health check test.

Database migrations

• No schema changes
• Includes an Alembic migration (just migrate-create "...")
• Migration runs cleanly (just migrate) and rolls back (just migrate-down)

Checklist

• Commits follow Conventional Commits
• Lint passes (just lint) and code is formatted (just format)
• Pre-commit hooks run clean (just hooks installed)
• Updated docs / README / .env.example where relevant
• Tested locally (just dev) and verified the API at http://localhost:8000/docs

How to test

1. Run neon env pull, then just dev --neon. Or run just dev for local Postgres, which also
   applies migrations.
2. Ingest data:

• POST /hotels/{id}/ingest/performance with a CSV and a base_rate.
• POST /hotels/{id}/ingest/weather with {"start": "...", "end": "..."}.

3. Train: POST /hotels/{id}/train with a description, then poll GET /jobs/{id} until it
   succeeds.
4. Get a price: GET /hotels/{id}/recommendations?date=YYYY-MM-DD.
5. Compare versions with GET /hotels/{id}/models and switch with POST /models/{id}/activate.
6. Run just test.

Notes for reviewers

• History is squashed to 10 commits by topic. The large ones are the layer refactor and the
  jobs/cities redesign.
• Events and flights aren't in the model yet: our PredictHQ plan has no events before 2026-07-01,
  and there's no flights ingest. Their model inputs are left empty.
• Tests are thin: only the health check runs in CI.
• Pyright isn't run in CI: it shows 24 errors in files outside this work.
• Follow-ups:
• store each model's settings and window in their own columns, then bring back retraining from
  an earlier version;
• drop the unused training_summary column;
• untrack .cache.sqlite.