feat(cli): write metadata sidecars

Author: AlisinaDevelo

CHANGELOG.md

@@ -10,6 +10,7 @@
 - JSON output for `quorabust-report --format json`.
 - Precision, recall, F1, and configurable threshold sweeps in model reports.
 - `POST /predict?explain=true` feature-value explanations for scored pairs.
+- `quorabust-train --metadata-out` for JSON metadata sidecars.
 
 ### Fixed
 - Capped NumPy below 2.5 so Mypy can parse dependency stubs with the configured

README.md

@@ -59,7 +59,7 @@ quorabust-train --csv data/raw/train.csv --out models/quorabust.pkl
 python -m quorabust --csv data/raw/train.csv --out models/quorabust.pkl   # equivalent
 ```
 
-Options: `--max-rows N`, `--eval-fraction 0.1` (default), `--eval-fraction 0` to train on all rows without a holdout, `--seed`, `--feature-backend {tfidf,embedding}`, `--embedding-model …`, `--registry-dir` (JSONL registry).
+Options: `--max-rows N`, `--eval-fraction 0.1` (default), `--eval-fraction 0` to train on all rows without a holdout, `--seed`, `--feature-backend {tfidf,embedding}`, `--embedding-model …`, `--registry-dir` (JSONL registry), `--metadata-out` (JSON sidecar for reviewing artifact lineage without loading the pickle).
 
 ### Generate a model card
 
@@ -123,7 +123,7 @@ Design notes: [docs/NOTES.md](docs/NOTES.md). Contributing: [CONTRIBUTING.md](CO
 
 ## Enterprise / operations
 
-Governance (security policy, Dependabot, audits), containers, serving, and release expectations are summarized in [docs/ENTERPRISE.md](docs/ENTERPRISE.md) and [docs/SCALING.md](docs/SCALING.md). Saved model pickles include `meta` (CSV checksum, git revision, package version, feature means for drift, metrics); only load trusted artifacts.
+Governance (security policy, Dependabot, audits), containers, serving, and release expectations are summarized in [docs/ENTERPRISE.md](docs/ENTERPRISE.md) and [docs/SCALING.md](docs/SCALING.md). Saved model pickles include `meta` (CSV checksum, git revision, package version, feature means for drift, metrics); only load trusted artifacts. Use `quorabust-train --metadata-out ...` when you only need lineage and metrics.
 
 ## License
 

docs/ENTERPRISE.md

@@ -16,6 +16,12 @@
 
 Training writes `csv_sha256`, `git_revision`, `quorabust_version`, `feature_schema`, `reference_feature_means` (for drift checks), and metric fields into the pickle `meta` dict. Treat `.pkl` files as **trusted** (pickle); load only from controlled storage.
 
+Use `quorabust-train --metadata-out models/quorabust.meta.json` to write the same
+lineage and metric metadata as JSON. Reviewers and release tooling can inspect that
+sidecar without loading executable pickle content. The sidecar is not a replacement for
+the model artifact; it is a safer inspection path. For untrusted artifact distribution,
+prefer a non-pickle format such as `skops` or ONNX in a future release.
+
 ## Serving and SLOs
 
 - **`quorabust-serve`**: FastAPI with `/health`, `/ready`, `/predict`, `/metrics` (Prometheus). Configure **`QUORABUST_MODEL_PATH`** and optional **`QUORABUST_MODEL_B`** for A/B; clients may send **`X-Quorabust-Variant: b`**.

docs/REPORTING.md

@@ -13,6 +13,7 @@ run in CI without the Kaggle dataset.
 quorabust-train \
   --csv examples/smoke_pairs.csv \
   --out /tmp/quorabust-smoke.pkl \
+  --metadata-out /tmp/quorabust-smoke.meta.json \
   --eval-fraction 0 \
   --seed 7
 
@@ -47,6 +48,7 @@ training:
 quorabust-train \
   --csv data/raw/train.csv \
   --out models/quorabust.pkl \
+  --metadata-out models/quorabust.meta.json \
   --eval-fraction 0.1 \
   --seed 42
 

src/quorabust/cli.py

@@ -11,7 +11,7 @@
 from quorabust.drift import feature_means_from_matrix
 from quorabust.lineage import git_revision, sha256_file
 from quorabust.model import eval_classification_metrics, train_duplicate_classifier
-from quorabust.persist import save_classifier
+from quorabust.persist import save_classifier, save_metadata_sidecar
 from quorabust.registry import append_model_record
 
 
@@ -73,6 +73,12 @@ def main(argv: list[str] | None = None) -> int:
         default=None,
         help="If set, append a JSONL record under this directory after training",
     )
+    p.add_argument(
+        "--metadata-out",
+        type=Path,
+        default=None,
+        help="If set, write artifact metadata JSON here without requiring pickle loading",
+    )
     args = p.parse_args(argv)
 
     if not args.csv.is_file():
@@ -139,6 +145,8 @@ def main(argv: list[str] | None = None) -> int:
     meta["reference_feature_means"] = feature_means_from_matrix(feat_names, X_ref)
 
     save_classifier(args.out, builder, clf, meta=meta)
+    if args.metadata_out is not None:
+        save_metadata_sidecar(args.metadata_out, meta)
     if args.registry_dir is not None:
         append_model_record(
             args.registry_dir,

src/quorabust/persist.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import json
 import pickle
 from pathlib import Path
 from typing import Any
@@ -25,3 +26,14 @@ def load_classifier(path: str | Path) -> tuple[Any, XGBClassifier, dict[str, Any
     with Path(path).open("rb") as f:
         data = pickle.load(f)
     return data["builder"], data["clf"], data.get("meta", {})
+
+
+def save_metadata_sidecar(
+    path: str | Path,
+    meta: dict[str, Any],
+) -> Path:
+    """Write artifact metadata as JSON so reviewers do not need to load a pickle."""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(json.dumps(meta, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return p

tests/test_cli.py

@@ -1,3 +1,5 @@
+import json
+
 import pandas as pd
 
 from quorabust.cli import main
@@ -22,6 +24,34 @@ def test_cli_trains_and_writes_pkl(tmp_path):
     assert out.is_file() and out.stat().st_size > 100
 
 
+def test_cli_writes_metadata_sidecar(tmp_path):
+    csv = tmp_path / "train.csv"
+    _write_synthetic_csv(csv)
+    out = tmp_path / "model.pkl"
+    meta = tmp_path / "model.meta.json"
+
+    assert (
+        main(
+            [
+                "--csv",
+                str(csv),
+                "--out",
+                str(out),
+                "--metadata-out",
+                str(meta),
+                "--eval-fraction",
+                "0",
+            ]
+        )
+        == 0
+    )
+
+    payload = json.loads(meta.read_text(encoding="utf-8"))
+    assert payload["n_train"] > 0
+    assert payload["feature_backend"] == "tfidf"
+    assert "eval_accuracy" in payload
+
+
 def test_cli_rejects_bad_columns(tmp_path):
     csv = tmp_path / "bad.csv"
     pd.DataFrame({"a": [1]}).to_csv(csv, index=False)

tests/test_persist.py

@@ -1,8 +1,10 @@
+import json
+
 import numpy as np
 import pandas as pd
 
 from quorabust.model import predict_proba_duplicate, train_duplicate_classifier
-from quorabust.persist import load_classifier, save_classifier
+from quorabust.persist import load_classifier, save_classifier, save_metadata_sidecar
 
 
 def _df():
@@ -29,3 +31,13 @@ def test_save_load_roundtrip(tmp_path):
     p1 = predict_proba_duplicate(builder, clf, q1, q2)
     p2 = predict_proba_duplicate(b2, c2, q1, q2)
     assert np.allclose(p1, p2)
+
+
+def test_save_metadata_sidecar_writes_json(tmp_path):
+    path = tmp_path / "model.meta.json"
+    written = save_metadata_sidecar(path, {"run": "test", "eval_accuracy": 0.9})
+    assert written == path
+    assert json.loads(path.read_text(encoding="utf-8")) == {
+        "run": "test",
+        "eval_accuracy": 0.9,
+    }