From e28ac52803003438b51b900a1cd13c742465b63c Mon Sep 17 00:00:00 2001 From: LincPay Date: Sat, 15 Aug 2026 15:47:14 +0530 Subject: [PATCH] docs(deploy): the demo data sequence a fresh database needs --- DEPLOYMENT.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 insertions(+) diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md index 2d787cf..4b66ff3 100644 --- a/DEPLOYMENT.md +++ b/DEPLOYMENT.md @@ -215,6 +215,60 @@ none of that risk. **Recommendation: keep the jar.** - [ ] The browser network tab shows `/api/v1/udyam/...` calls returning 200, not HTML - [ ] `UDYAM_JWT_SECRET` is not the committed default +## Populating a fresh database — the demo sequence + +The seeder writes the portfolio, the ledger and the forecasts. It does **not** write +loan history, UPI inflows or the no-feed price series: those are admin calls, so a fresh +database comes up without them and several screens look thinner than they should. + +Run these once, in order, after the seeder's final log line: + +```bash +BASE=http://localhost:8082/api/v1/udyam +TOKEN= + +# 1. DPD history — 24 monthly snapshots per loan, stamped SEEDED_HISTORY +curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/loan-history/generate?months=24" + +# 2. UPI inflows — 26 weeks per enterprise, stamped SIMULATED. +# Stands in for Account Aggregator data until Sahamati FIU registration exists. +curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/upi/simulate" + +# 3. Prices for the commodities with no API anywhere — milk, egg, fodder, sugarcane +curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/ingestion/simulate/no-feed" + +# 4. Derive the features, then score against them +curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/features/compute" +curl -X POST -H "Authorization: Bearer $TOKEN" "$BASE/admin/scoring/run" +``` + +Verify with the coverage endpoints, both of which report synthetic and real separately: + +```bash +curl -H "Authorization: Bearer $TOKEN" "$BASE/admin/loan-history/coverage" +curl -H "Authorization: Bearer $TOKEN" "$BASE/admin/upi/coverage" +``` + +### All of it is labelled, and none of it can overwrite a fact + +Every row written above carries its provenance in the table — `SEEDED_HISTORY` on loan +records, `SIMULATED` on UPI and price rows — and the simulators refuse to overwrite a +non-simulated row even when asked to. Real data can land beside this at any time and +stays distinguishable forever. The console surfaces the distinction rather than leaving +it to a slide. + +Two consequences to state out loud rather than discover later: + +- **`loan-history/coverage` reports `trainable: false`** while no real extract exists, + and that is correct. The seeder derives DPD from the risk band and the UPI simulator + derives inflow drift from the same band, so a model trained on this would learn the + seeder's own rule and validate beautifully while knowing nothing. The synthetic data + is here to exercise the pipeline and fill the console, not to train. +- **This sequence does not give you the real mandi price history.** Steps 1–3 are + synthetic; the three-year Agmarknet backfill is real data and needs `DATAGOV_API_KEY` + plus a long one-off run, or a dump of a database that already has it. Without it + `price_z_score` has no seasonal mean and TW-05 stays quiet. + ## What is deliberately off `udyam.ingestion.enabled` is `false`, so a demo boot never calls a government endpoint,