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

Author	SHA1	Message	Date
Light1YT	574ee43577	feat(forecasting): recommendation overlay module + schema/route (#982 , 953-A) 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.	2026-06-03 12:40:03 +05:00
Light1YT	eef240a17f	feat(recommend): horizon-aware forecast-overlay for recommend_mix (#982 , 953-A) 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).	2026-06-03 12:28:00 +05:00

Author

SHA1

Message

Date

Light1YT

574ee43577

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

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.

2026-06-03 12:40:03 +05:00

Light1YT

eef240a17f

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

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).

2026-06-03 12:28:00 +05:00