docs/MIGRATION.md

# Blueprint Rewrite — Migration Notes

## What changed conceptually

Old: LLM does a thin extraction -> keyword router picks a scenario family ->
Python templates with hardcoded value lists fill the gaps -> specialized
generators for the verticals we've hand-tuned.

New: one rich LLM call authors a complete **DemoBlueprint** (all semantics:
real domain nouns, distributions, formulas, seasonality, and 3-5 **planted
insights** with the exact Spotter questions that reveal them) -> one generic
deterministic **BlueprintEngine** executes any blueprint -> a **validator**
proves each planted insight is demo-visible in the actual rows, and a cheap
boost-and-regenerate loop fixes weak ones at the contract level.

The LLM decides what the data means; deterministic code decides what the rows
are. No vertical-specific code anywhere downstream of the blueprint.

## New files

| File | Role |
|---|---|
| `demoprep_app/scenario/blueprint.py` | DemoBlueprint dataclasses + `problems()` validation (repair messages are written for the LLM) |
| `demoprep_app/scenario/blueprint_author.py` | The one LLM call. The user's request is quoted verbatim as highest authority; few-shot examples replace scenario families. Up to 2 repair rounds. |
| `demoprep_app/scenario/directives.py` | Deterministic extraction + enforcement of explicit user schema instructions (named tables, prohibitions). Direct fix for the McKesson routing failure. |
| `demoprep_app/dataset/engine.py` | The only generator. Deterministic given (blueprint, seed). Also decides date-dimension-vs-inline-date per blueprint, resolving the open date-modeling question. |
| `demoprep_app/dataset/validator.py` | Integrity + formula + planted-insight checks over the in-memory bundle |
| `demoprep_app/pipeline/build_demo.py` | THE pipeline (there is exactly one): author -> generate -> validate -> boost loop -> DDL. Canonical entry `build_demo()`; `dataset_first.py` remains only as a deprecated import shim during cutover. |
| `SINGLE_PIPELINE.md` | Surgery guide for chat_interface.py: delete the `data_generation_mode`/`DEMOPREP_DATASET_FIRST` fork (which currently **defaults to legacy**), the silent "falling back to DDL-first" branch, the legacy LLM-DDL stage, and the LegitData population path. |
| `tests/test_blueprint_pipeline.py` | LLM-free smoke test (run: `PYTHONPATH=. python tests/test_blueprint_pipeline.py`) |
| `tests/test_mckesson_regression.py` | Replays the real McKesson failure: extracts directives from the actual prompts, rejects the exact FACILITIES/SERVICE_LINES output the old app produced, and builds the correct 6-table / 2-fact demo. |

## Delete (no longer imported)

- `demoprep_app/scenario/selector.py` — keyword routing
- `demoprep_app/scenario/extractor.py` — thin extraction
- `demoprep_app/scenario/families.py` — templates-as-code (their knowledge now
  lives as few-shot JSON in `blueprint_author.py`; port any families you find
  valuable as additional compact examples)
- `demoprep_app/dataset/generators/` — all of it: `base.py`, `router.py`,
  `retail_sales.py`, `saas_sales.py`, `template_generator.py`

## Untouched

- `demoprep_app/dataset/contracts.py` (DatasetBundle/Table/Column)
- `demoprep_app/ddl/` DatasetDdlCompiler
- `demoprep_app/integrations/snowflake.py` `populate_dataset_bundle`
- `chat_interface.py` call site (signature preserved; `use_llm_contract` kept
  as a no-op arg)

Two files in this package are **test stubs only** — replace with your real
modules when dropping in: `demoprep_app/scenario/contract.py` and
`demoprep_app/ddl/__init__.py`. If your real `ScenarioContract` has different
field names, adjust `_compat_scenario()` in `engine.py` (one function, ~30
lines — the only place the two worlds touch).

## The McKesson failure, specifically

The 2026-07 incident (custom prompt naming 6 exact tables -> keyword-routed to
the healthcare_operations family -> FACILITIES / SERVICE_LINES / PAYERS /
REGIONS / HEALTHCARE_OPERATIONS) is now impossible three ways:

1. `selector.py` and `families.py` are deleted — there is no keyword router
   and no hardcoded table set to route into.
2. The author prompt quotes the user's request verbatim as the highest
   authority, with an explicit warning against modeling the industry's
   generic operations instead of the company's actual business.
3. `directives.py` extracts named tables (DIM_*/FACT_* tokens) and
   prohibitions ("do not create facilities...", "not a hospital operations
   demo") from the user's own words and enforces them deterministically.
   Violations feed the LLM repair loop; any that survive retries abort the
   build with `USER DIRECTIVE VIOLATED` — the wrong story can never
   silently ship. `chat_interface.py` should pass the raw custom prompt as
   `user_request=` (falls back to `use_case` otherwise).

Blueprints also now support **1-3 fact tables over shared dimensions**
(`facts: [FactSpec]`), because real custom specs like McKesson's have two.
Measure names must be unique across facts; insights resolve to the fact
owning their measure; each fact can name its date column (e.g. MONTH_DATE).

## Behavior changes to be aware of

1. **Fails loudly.** No silent fallback to templates. If the LLM can't produce
   a valid blueprint after repair rounds, the build raises with the validation
   report. A template demo is worse than a clear error you can retry.
2. **Planted insights flow downstream.** `bundle.scenario.metadata["planted_insights"]`
   carries id/headline/spotter_question/expected_finding — wire these into the
   liveboard question generator and Spotter Viz story so the demo narrative and
   the data are guaranteed to agree. That's the Demo to Win payoff.
3. **Date dimension is now a per-scenario LLM decision** (blueprint field
   `date.include_date_dimension`, forced true when `fiscal_or_custom_calendar`
   is set) instead of always-emitted. Matches the design guidance in the
   architecture doc.
4. **`performance` and insight magnitude compound.** A store with
   performance 0.8 that is also a 0.75 laggard insight lands around 0.6x.
   The validator only requires half the promised effect to realize, so this
   is safe, but the effect can be stronger than the headline claims. If that
   bothers you, have the author prompt forbid overlapping the two.
5. **Determinism.** Seed derives from `company_url|use_case`, so rebuilding
   the same demo produces the same data — good for the e2e quality harness.

## Suggested follow-ups (not included)

- Port your best `families.py` entries into 2-3 more few-shot examples.
- Feed `planted_insights` into `liveboard_creator.py` question generation.
- e2e harness: assert `build.validation.passed` and surface `build.warnings`.