docs/MIGRATION_1.4.1.md

# Migration to v1.4.1

v1.4.1 is a stabilization patch over v1.4. It does not change the core retrieval architecture or demo corpus.

## Fixes

- fixes `Architecture + API -> Refresh runtime view`, which could raise `NameError: name 'f' is not defined` because the generated curl-example string was truncated in the v1.4 packaged UI source;
- changes visible evaluation wording from `scorecard` to `score card`;
- adds quota-safe Gemini evaluation pacing, defaulting to 12 RPM;
- records recent interactive requests in the same process-local per-key/per-model request ledger used by evaluation pacing;
- honors surfaced Gemini 429 retry guidance before bounded retries;
- prevents structured-output fallback code from immediately issuing another API request after transient 429/5xx failures;
- reports deliberate pacing wait separately from service/pipeline latency;
- reduces Text2SQL evaluation from roughly three Gemini calls per case to one by separating planner-routing evaluation from SQL generation/execution evaluation;
- reduces Deep judge calls to a representative labeled benchmark subset.

## Recommended free-tier setting

Use the active RPM displayed for your API project in Google AI Studio as the source of truth. The UI defaults to 12 RPM, which leaves headroom when a project currently has a 15 RPM limit. Lower the target if the same API key is also receiving traffic outside this Space.

## Upgrade

Apply the v1.4.1 patch over a clean v1.4 tree, then commit normally. The patch does not contain the bundled NIST PDF.

After deployment:

1. run Quick with quota-safe pacing enabled;
2. run Standard and confirm request/pacing telemetry appears in the score card;
3. run Deep immediately afterward to test rolling-window continuity;
4. open `Architecture + API` and click `Refresh runtime view`;
5. confirm the runtime JSON and curl examples populate without a traceback.