"""Write portable, source-linked evidence for explicitly invoked offline studies.""" from datetime import datetime, timezone import importlib.metadata import platform from pathlib import Path import sys sys.path.insert(0, str(Path(__file__).resolve().parents[1])) from backend.flagship.ml import _atomic, _hash, _json def write_evidence(destination, *, study, result, elapsed_seconds, input_path=None): root = Path(__file__).resolve().parents[1] sources = ["backend/flagship/ml.py", "scripts/study_evidence.py", f"scripts/study_{study}.py"] if study == "censoring": sources.append("backend/ml/censored_demand.py") packages = {} for name in ("numpy", "pandas", "scipy", "scikit-learn", "lightgbm", "openpyxl"): try: packages[name] = importlib.metadata.version(name) except importlib.metadata.PackageNotFoundError: packages[name] = "unavailable" report = { "schema_version": 1, "study": study, "captured_at": datetime.now(timezone.utc).isoformat(), "command": ["python3", *sys.argv], "elapsed_wall_seconds": elapsed_seconds, "runtime": {"python": platform.python_version(), "platform": platform.platform(), "packages": packages}, "source_sha256": {source: _hash((root / source).read_bytes()) for source in sources}, "result_sha256": _hash(_json(result)), "result": result, } if input_path is not None: # Use the bytes ingestion consumed, not a file that might have been # replaced after the study finished. metadata = result.get("manifest", {}).get("dataset", result.get("provenance", {})) report["input"] = {"filename": Path(input_path).name, "sha256": metadata.get("dataset_sha256")} report["limitations"] = [ "A UK-based online retailer's recorded positive sales; not Indian quick-commerce evidence.", "Cohort includes transactions across countries in the official workbook, not a UK-only customer filter.", "Top products are selected from the initial training period; this is not an all-product benchmark.", "One-step walk-forward evaluation uses preceding observed days; not a 28-day recursive forecast.", "No stockout labels, warehouse inventory observations, causal deployment benefit, or recovered hidden sales.", "Serving history includes observed holdout days; model fitting and validation selection exclude their targets.", "No model is promoted by this study command.", ] else: report["limitations"] = result["limitations"] _atomic(Path(destination), _json(report)) return report