feat(data,api): seeder Phase 1 — exogenous signals, multi-seasonality, changepoints, returns, substitution

[w7-mgfcode]

Summary

Phase 1 of the seeder realism extension (closes #88). Adds opt-in mechanics so the synthetic dataset can exercise exogenous-aware forecasting, multi-seasonal patterns, trend changepoints, returns volume, and cross-product substitution.

• New persisted tables: exogenous_signal (weather / macro / events) and sales_returns.
• New demand multipliers in SalesDailyGenerator: yearly seasonality, changepoint impulse + exponential decay, linear weather effect, stockout substitution.
• New API surface: GET /seeder/exogenous, 6 new Phase 1 fields on GenerateParams, expanded SeederStatus.
• Single additive Alembic migration; downgrade restores prior schema cleanly.

Regression invariant: with every Phase 1 flag off, all six existing scenarios (retail_standard, holiday_rush, high_variance, stockout_heavy, new_launches, sparse) produce byte-identical seeded output. Enforced by app/shared/seeder/tests/test_phase1_regression.py.

What's included

Area	Files
Schema migration	alembic/versions/f7a8b9c0d123_*
ORM models	app/features/data_platform/models.py (+ExogenousSignal, +SalesReturn)
Seeder config	app/shared/seeder/config.py (+5 dataclasses + wiring on SeederConfig)
Generators	app/shared/seeder/generators/{exogenous,returns}.py + extensions to facts.py
Orchestration	app/shared/seeder/core.py (_generate_exogenous, returns, expanded delete + verify, expanded SeederResult)
API	app/features/seeder/{schemas,service,routes}.py (+6 fields, +GET /seeder/exogenous, +ChangepointEventParam, +ExogenousSignalResponse)
Tests	8 new unit/integration files + updates to existing mocks for new query counts
Docs	docs/DATA-SEEDER.md Phase 1 section

Test plan

• uv run ruff check . — clean
• uv run ruff format --check . — clean
• uv run mypy app/ — 0 issues, 175 files
• uv run pyright app/ — 0 errors (49 pre-existing warnings)
• uv run pytest -m "not integration" — 786 passed (4 pre-existing .env-bleed failures, confirmed against dev baseline)
• uv run pytest -m integration — 110 passed (including 8 new Phase 1 + 16 existing seeder DB tests)
• uv run alembic downgrade -1 && uv run alembic upgrade head — roundtrips cleanly on real Postgres
• Regression invariant — all 6 scenarios byte-identical with Phase 1 toggles off

Non-goals (deferred to later phases)

• Multi-channel sales splits → Phase 2
• Product lifecycle / bundles / markdowns / lead-time → Phase 2
• Scenario library + composer → Phase 3
• Async jobs + WebSocket progress + preview + export → Phase 4

Out-of-band

The 4 failing config/agent-key tests are the pre-existing .env-bleed issue documented in docs/_base/RUNBOOKS.md; they fail identically on origin/dev and are unrelated to this PR.

[sourcery-ai]

Sorry @w7-mgfcode, you have reached your weekly rate limit of 500000 diff characters.

Please try again later or upgrade to continue using Sourcery

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f781a38e-9a32-46ec-b4a7-2fccc4022631

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/seeder-realism-exogenous

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}