feat(recommend): horizon-aware recommend_mix opt-in overlay (#982, 953-A) #1014

Merged

bot-backend merged 2 commits from feat/953a-horizon-aware-recommend into main

2026-06-03 07:40:33 +00:00

bot-backend commented

2026-06-03 07:40:31 +00:00

Collaborator

Site Finder v2 / EPIC 9 — таск #982 (953-A): horizon-aware recommend_mix. Additive opt-in, live-endpoint-safe, ADVISORY.

При horizon_months — advisory forecast-overlay под scope["forecast"] через новый forecasting/recommendation.py:

demand_supply (cad_num задан) → #981 rank_segments.
demand_only (без cad_num) → per-bucket pace §9.2×§9.4×§9.5, deficit_index=pace-proxy, balance_units=None, confidence=low, warning «supply не учтён» (без фабрикации).

Default-путь байт-в-байт не тронут (guarded try/except, overlay никогда не роняет живой микс). Bridges room/class drift-guarded vs _BUCKET_PRETTY; локальные §9.x импорты обходят cycle. RecommendMixOutput 4 поля целы; новые input-поля Optional.

55 тестов (invariance + crash-isolation + bridges + оба режима). opus code-review ✅ (7 live-endpoint gate'ов). NOTE: живой endpoint получил ДОРМАНТНЫЙ путь в advisory-движок (фронт не шлёт horizon_months) — точка врезки когда #951-бэктест пройдёт. Closes #982. Refs #953

**Site Finder v2 / EPIC 9 — таск #982 (953-A): horizon-aware recommend_mix.** Additive opt-in, live-endpoint-safe, ADVISORY. При `horizon_months` — advisory forecast-overlay под `scope["forecast"]` через новый `forecasting/recommendation.py`: - **demand_supply** (cad_num задан) → #981 `rank_segments`. - **demand_only** (без cad_num) → per-bucket pace §9.2×§9.4×§9.5, deficit_index=pace-proxy, balance_units=None, confidence=low, warning «supply не учтён» (без фабрикации). Default-путь **байт-в-байт** не тронут (guarded try/except, overlay никогда не роняет живой микс). Bridges room/class drift-guarded vs `_BUCKET_PRETTY`; локальные §9.x импорты обходят cycle. RecommendMixOutput 4 поля целы; новые input-поля Optional. **55 тестов** (invariance + crash-isolation + bridges + оба режима). opus code-review ✅ (7 live-endpoint gate'ов). NOTE: живой endpoint получил ДОРМАНТНЫЙ путь в advisory-движок (фронт не шлёт horizon_months) — точка врезки когда #951-бэктест пройдёт. Closes #982. Refs #953

bot-backend added 2 commits 2026-06-03 07:40:31 +00:00

feat(recommend): horizon-aware forecast-overlay for recommend_mix (#982 , 953-A) eef240a17f

Additive opt-in: when horizon_months is passed, attach an ADVISORY forecast
overlay under scope["forecast"] via new forecasting/recommendation.py
(demand_supply when cad_num set → #981 rank_segments; demand_only otherwise →
per-room-bucket demand pace, NO fabricated supply). Default path stays
byte-identical — overlay is try/except-guarded and never crashes the live mix.

- schemas/recommend.py: horizon_months + cad_num inputs; RecommendForecast{Segment,
  Overlay} output models (ride open scope dict; RecommendMixOutput 4 fields intact)
- forecasting/recommendation.py: pure room/class bridges (inverse of _BUCKET_PRETTY,
  drift-guarded) + build_forecast_overlay (graceful, advisory always True)
- analytics_queries.recommend_mix: +horizon_months/cad_num params + guarded tail
- api/v1/analytics.py: endpoint passthrough
- tests: bridges both directions, both modes, graceful, invariance, crash isolation

NOTE: live recommend endpoint now has a DORMANT path into the advisory forecast
engine (frontend sends no horizon_months yet); wiring point when #951 backtest lands.
45 tests; 413 forecasting+velocity green. opus code-review ✅ (7 live-endpoint gates).

feat(forecasting): recommendation overlay module + schema/route (#982 , 953-A) 574ee43577

Recreate the recommendation.py bridge module + RecommendMixInput
horizon_months/cad_num fields + RecommendForecast{Segment,Overlay} models +
endpoint passthrough + test_recommendation.py — completing the #982 opt-in
whose analytics_queries.recommend_mix wire-in landed in the prior commit.

build_forecast_overlay(db,*,district,cad_num,horizon_months,target_class,
market_buckets) matches the committed call. demand_supply via rank_segments
(cad_num) / demand_only pace-proxy (no cad_num, no fabricated supply, warning).
Pure room/class bridges drift-guarded vs _BUCKET_PRETTY; local §9.x imports
avoid the analytics_queries↔forecasting cycle. 55 tests green.