Module 305 — Documentation for quantitative models (assumptions + model card)

import os
from datetime import datetime

# -----------------------------
# Inputs (normally from run artefacts)
# -----------------------------
cfg = {
    "run_id": "2026-02-09_170000_ab12cd34",
    "model_name": "OLS baseline",
    "owner": "Quant team",
    "target": {"name": "y", "horizon": 1, "unit": "arbitrary"},
    "data": {"dataset_id": "sha256:...abc123", "coverage": "synthetic demo"},
    "features": {"cols": ["lag1", "lag2", "lag3", "lag5"]},
    "validation": {"scheme": "rolling", "train_len": 240, "test_len": 60},
    "constraints": {"latency_ms": 200, "interpretability": "high"},
}

metrics = {
    "rmse_mean": 1.23,
    "rmse_worst_fold": 1.95,
    "mae_mean": 0.97,
}

run_dir = os.path.join("runs", cfg["run_id"])
os.makedirs(run_dir, exist_ok=True)

# -----------------------------
# Assumptions page (markdown)
# -----------------------------
assumptions_md = f"""# Assumptions — {cfg["model_name"]}

## Scope
- **Purpose:** Forecast {cfg["target"]["name"]} at horizon h={cfg["target"]["horizon"]}.
- **Decision:** Inform downstream decision logic (definition external to this document).
- **Not for:** Use outside the validated horizon or outside the documented data coverage.

## Data assumptions
- **Dataset ID:** {cfg["data"]["dataset_id"]}
- **Coverage:** {cfg["data"]["coverage"]}
- **Timestamp policy:** Index must be monotonic and unique.
- **Missing data policy:** Missing timestamps are not treated as zeros. Gaps are handled explicitly.

## Feature and target assumptions
- **Features:** {cfg["features"]["cols"]}
- **Causality:** Features at time t use only information available at or before t.
- **Target:** y_target = y shifted by -h (future), never used as a feature.

## Regime assumptions
- Performance may degrade under distribution shifts (volatility, liquidity, behaviour changes).
- Use rolling validation and monitor drift signals.

## Operational assumptions
- **Latency budget:** <= {cfg["constraints"]["latency_ms"]} ms per scoring call (target).
- **Refresh cadence:** Assumed consistent with horizon h.

## Controls
- Invariants: monotonic timestamps, no duplicates, train end < test start.
- Smoke test: pipeline runs on a small sample before full runs.
"""

with open(os.path.join(run_dir, "ASSUMPTIONS.md"), "w", encoding="utf-8") as f:
    f.write(assumptions_md)

# -----------------------------
# Model card (markdown)
# -----------------------------
model_card_md = f"""# Model card — {cfg["model_name"]}

## Model name / version
- **Run ID:** {cfg["run_id"]}
- **Date:** {datetime.now().strftime("%Y-%m-%d")}
- **Owner:** {cfg["owner"]}

## Intended use
- Forecast **{cfg["target"]["name"]}** at horizon **h={cfg["target"]["horizon"]}**.
- Used for time-consistent forecasting experiments and baseline comparisons.

## Not intended use
- Not intended for horizons other than h={cfg["target"]["horizon"]}.
- Not intended for use without monitoring or outside the dataset coverage.

## Data
- **Dataset ID:** {cfg["data"]["dataset_id"]}
- **Coverage:** {cfg["data"]["coverage"]}
- **Key features:** {cfg["features"]["cols"]}

## Method
- **Model class:** {cfg["model_name"]}
- **Baselines:** last-value, seasonal naive (recommended comparisons)
- **Validation:** {cfg["validation"]["scheme"]} CV (train_len={cfg["validation"]["train_len"]}, test_len={cfg["validation"]["test_len"]})

## Performance (summary)
- **RMSE mean:** {metrics["rmse_mean"]}
- **RMSE worst fold:** {metrics["rmse_worst_fold"]}
- **MAE mean:** {metrics["mae_mean"]}

## Limitations
- Sensitive to regime shifts and drift in feature distributions.
- May underperform in extreme volatility regimes.

## Monitoring
- Data integrity: missing timestamps, duplicates, monotonicity.
- Drift: rolling feature distribution drift (mean/std), error drift by fold/window.
- Runtime: latency, failure rate, artefact completeness.

## Human oversight
- Review cadence: weekly during development, monthly in production.
- Intervention triggers: drift alarms, repeated worst-window failures, latency breach.
"""

with open(os.path.join(run_dir, "MODEL_CARD.md"), "w", encoding="utf-8") as f:
    f.write(model_card_md)

print("Wrote documentation to:", run_dir)
print(" - ASSUMPTIONS.md")
print(" - MODEL_CARD.md")