docs/specs/0002-python-script-export.md

Spec 0002 - Reproduction script export (offline-runnable)

Status: implemented (2026-07-09) Phase: 0 Design doc ref: §14 Requested by: Mohammad (Slack brief: "provide users with the Python script used for their analysis so they can reproduce it independently")

Problem

Runs are reproducible in principle (metadata records everything) but a researcher must reassemble the analysis by hand. The platform should hand them a runnable script.

Contract

• New export: GET /api/jobs/{id}/script → reproduce_analysis_<run8>.py + a pinned requirements-repro.txt (exact installed versions of sentence-transformers, torch, numpy, pandas).
• The script must run OUTSIDE the platform with only: the downloaded input CSV, Python, and internet access for the (pinned-revision) model download. No platform credentials, ever.
• Script contents (generated from the run's metadata, not from live state): model provider_model_id + revision, prefix logic when usage_config.requires_prefix (E5!), normalize_embeddings flag, the exact construct items + reverse_scored flags (embedded verbatim), text column, empty-row dropping identical to the platform, cosine similarity, per-item sim columns + ccr_score with identical rounding, CSV output path, and a header comment: run_id, created_at, item_hash, platform version, output_schema_version.
• UI: "Download Python script" button in the results view export row.

Non-goals

Notebook export; R script; re-running inside the platform from a script.

Tests

• test_script_export_endpoint_returns_python (200, content-type, filename)
• test_script_contains_pinned_model_and_items (revision string, all item texts, prefix for E5 runs)
• test_script_is_valid_python (compile() the generated source)
• integration (marked, real-model, not in default suite): run script on sample corpus → similarities match platform export within atol=1e-5.

Implementation notes

• Generator = template string in a new engine-side reproducibility.py; inputs strictly from job metadata (guarantees script matches what actually ran).
• Requirements pinning: importlib.metadata versions at run time, stored in metadata, echoed to file.

Deviations

• Requirements served at /script-requirements (separate endpoint) rather than bundled zip.
• Real-model parity integration test deferred to spec 0005's parity suite (fake-backend tests + compile check in place).