feat(api): expose safe model metadata

Author: Your Name

CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Added
 - `quorabust-report` for generating Markdown model cards from saved artifacts and
   optional labeled holdout CSVs.
+- `GET /models` serving endpoint for safe loaded-model metadata.
 
 ## 0.3.2
 

README.md

@@ -93,6 +93,8 @@ quorabust-serve --host 0.0.0.0 --port 8000
 ```
 
 `GET /metrics` exposes Prometheus text; `POST /predict` accepts `{"question1":[...],"question2":[...]}` and optional header `X-Quorabust-Variant: b`. Interactive docs: **`/docs`**. Load testing: [docs/LOAD_TESTING.md](docs/LOAD_TESTING.md). Grafana: [docs/GRAFANA.md](docs/GRAFANA.md).
+`GET /models` returns allowlisted metadata for loaded variants without leaking local
+artifact paths or training CSV paths.
 
 ## Project layout
 

src/quorabust/serve.py

@@ -77,6 +77,31 @@ class PredictOut(BaseModel):
     variant: str = Field(..., description="Scoring variant (a or b) after A/B fallback rules.")
 
 
+_PUBLIC_META_KEYS = {
+    "feature_backend",
+    "feature_schema",
+    "n_train",
+    "n_eval",
+    "seed",
+    "quorabust_version",
+    "git_revision",
+    "csv_sha256",
+    "reference_feature_means",
+}
+
+
+def _public_model_meta(meta: dict[str, Any]) -> dict[str, Any]:
+    public = {k: meta[k] for k in _PUBLIC_META_KEYS if k in meta}
+    eval_metrics = {
+        k.removeprefix("eval_"): v
+        for k, v in sorted(meta.items())
+        if k.startswith("eval_") and isinstance(v, int | float)
+    }
+    if eval_metrics:
+        public["eval_metrics"] = eval_metrics
+    return public
+
+
 def create_app(
     model_path_a: str | None = None,
     model_path_b: str | None = None,
@@ -134,6 +159,25 @@ def ready() -> dict[str, str]:
             raise HTTPException(status_code=503, detail="model a not loaded")
         return {"status": "ready"}
 
+    @app.get(
+        "/models",
+        tags=["operations"],
+        summary="List loaded model metadata",
+        description=(
+            "Returns allowlisted metadata for loaded variants. Local artifact paths and "
+            "training CSV paths are intentionally omitted."
+        ),
+        responses={503: {"description": "No models loaded"}},
+    )
+    def models() -> dict[str, dict[str, dict[str, Any]]]:
+        if not state:
+            raise HTTPException(status_code=503, detail="no models loaded")
+        variants = {
+            name: _public_model_meta(meta)
+            for name, (_, _, meta) in state.items()
+        }
+        return {"variants": variants}
+
     @app.get("/metrics", tags=["operations"])
     def metrics() -> PlainTextResponse:
         data = generate_latest(registry)

tests/test_serve.py

@@ -15,7 +15,19 @@ def _tiny_pkl(path):
         }
     )
     b, clf = train_duplicate_classifier(df, xgb_params={"n_estimators": 12, "max_depth": 3})
-    save_classifier(path, b, clf, meta={"id": "a"})
+    save_classifier(
+        path,
+        b,
+        clf,
+        meta={
+            "id": "a",
+            "csv": "/private/path/train.csv",
+            "feature_backend": "tfidf",
+            "feature_schema": ["cos", "jaccard", "len_ratio", "abs_len_diff", "len_sum"],
+            "n_train": len(df),
+            "eval_accuracy": 0.8,
+        },
+    )
 
 
 def test_serve_health_ready_predict(tmp_path):
@@ -58,6 +70,26 @@ def test_openapi_includes_predict_examples(tmp_path):
     assert examples and "question1" in examples[0]
 
 
+def test_models_returns_safe_public_metadata(tmp_path):
+    p = tmp_path / "m.pkl"
+    _tiny_pkl(p)
+    app = create_app(model_path_a=str(p))
+    with TestClient(app) as client:
+        r = client.get("/models")
+    assert r.status_code == 200
+    model = r.json()["variants"]["a"]
+    assert model["feature_backend"] == "tfidf"
+    assert model["eval_metrics"]["accuracy"] == 0.8
+    assert "csv" not in model
+    assert "id" not in model
+
+
+def test_models_without_loaded_artifacts_is_unavailable():
+    app = create_app(model_path_a="/nonexistent/quorabust_missing.pkl")
+    with TestClient(app) as client:
+        assert client.get("/models").status_code == 503
+
+
 def test_serve_ab_variant_header(tmp_path):
     pa = tmp_path / "a.pkl"
     pb = tmp_path / "b.pkl"