feat(api): expose prediction feature values

Author: AlisinaDevelo

CHANGELOG.md

@@ -9,6 +9,7 @@
 - `examples/smoke_pairs.csv` and CI coverage for the train-to-report workflow.
 - 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.
 
 ### Fixed
 - Capped NumPy below 2.5 so Mypy can parse dependency stubs with the configured

README.md

@@ -95,7 +95,7 @@ quorabust-serve --host 0.0.0.0 --port 8000
 # optional second artifact: export QUORABUST_MODEL_B=models/other.pkl
 ```
 
-`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 /metrics` exposes Prometheus text; `POST /predict` accepts `{"question1":[...],"question2":[...]}` and optional header `X-Quorabust-Variant: b`. Add `?explain=true` to return per-pair input feature values. 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.
 

docs/NOTES.md

@@ -13,6 +13,9 @@ The public [Quora Question Pairs](https://www.kaggle.com/c/quora-question-pairs)
 - **TF–IDF** uses `stop_words=None` so short or stopword-heavy questions still produce a vocabulary (important for tests and for “what is …” style duplicates).
 - **Early stopping** is enabled when you pass `eval_df` to `train_duplicate_classifier`; `early_stopping_rounds` defaults to 20 and can be overridden via `xgb_params`.
 - **Artifacts**: use `save_classifier` / `load_classifier` from `quorabust.persist` (or `from quorabust import …`) so the `PairFeatureBuilder` (TF–IDF state) and `XGBClassifier` stay in sync.
+- **Explanations**: `POST /predict?explain=true` returns model input feature values
+  (for example cosine, Jaccard, and length stats). These are inspectable features, not
+  causal natural-language explanations.
 
 ## Training CLI
 

src/quorabust/embedding_features.py

@@ -25,6 +25,9 @@ def __init__(self, model_name: str = "sentence-transformers/all-MiniLM-L6-v2") -
     def fit(self, corpus: list[str] | None = None) -> PairEmbeddingBuilder:
         return self
 
+    def feature_names(self) -> list[str]:
+        return ["cos", "l2", "mad", "len_ratio", "len_sum"]
+
     def fit_from_frame(
         self,
         df: pd.DataFrame,

src/quorabust/explain.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def feature_names_for_builder(
+    builder: Any,
+    feature_schema: list[str] | None = None,
+) -> list[str]:
+    """Return stable feature names for a loaded builder."""
+    if feature_schema:
+        return feature_schema
+    if hasattr(builder, "feature_names"):
+        names = builder.feature_names()
+        if isinstance(names, list) and all(isinstance(x, str) for x in names):
+            return names
+    return []
+
+
+def explain_pair_features(
+    builder: Any,
+    q1: list[str],
+    q2: list[str],
+    *,
+    feature_schema: list[str] | None = None,
+) -> list[dict[str, float]]:
+    """Expose model input feature values for each question pair."""
+    values = builder.transform_pairs(q1, q2)
+    names = feature_names_for_builder(builder, feature_schema)
+    if not names:
+        names = [f"feature_{i}" for i in range(values.shape[1])]
+    return [
+        {name: float(value) for name, value in zip(names, row, strict=False)}
+        for row in values
+    ]

src/quorabust/features.py

@@ -43,6 +43,9 @@ def fit(self, corpus: list[str]) -> PairFeatureBuilder:
         self._fitted = True
         return self
 
+    def feature_names(self) -> list[str]:
+        return ["cos", "jaccard", "len_ratio", "abs_len_diff", "len_sum"]
+
     def fit_from_frame(
         self,
         df: pd.DataFrame,

src/quorabust/serve.py

@@ -13,6 +13,7 @@
 from prometheus_client import CollectorRegistry, Counter, Histogram, generate_latest
 from pydantic import BaseModel, ConfigDict, Field
 
+from quorabust.explain import explain_pair_features
 from quorabust.model import predict_proba_duplicate
 from quorabust.persist import load_classifier
 
@@ -65,6 +66,15 @@ class PredictOut(BaseModel):
                 {
                     "proba_duplicate": [0.82, 0.31],
                     "variant": "a",
+                    "features": [
+                        {
+                            "cos": 0.73,
+                            "jaccard": 0.42,
+                            "len_ratio": 0.8,
+                            "abs_len_diff": 1.0,
+                            "len_sum": 9.0,
+                        }
+                    ],
                 }
             ]
         }
@@ -75,6 +85,13 @@ class PredictOut(BaseModel):
         description="P(duplicate) for each pair, same order as the request lists.",
     )
     variant: str = Field(..., description="Scoring variant (a or b) after A/B fallback rules.")
+    features: list[dict[str, float]] | None = Field(
+        default=None,
+        description=(
+            "Optional per-pair model input feature values when `explain=true`. "
+            "These are feature values, not causal explanations."
+        ),
+    )
 
 
 _PUBLIC_META_KEYS = {
@@ -193,7 +210,8 @@ def metrics() -> PlainTextResponse:
         summary="Predict duplicate probability",
         description=(
             "Scores one or more question pairs. Optional header "
-            "`X-Quorabust-Variant: b` selects the B artifact when configured."
+            "`X-Quorabust-Variant: b` selects the B artifact when configured. "
+            "Set query parameter `explain=true` to return input feature values."
         ),
         responses={
             400: {"description": "question1 and question2 length mismatch"},
@@ -202,6 +220,7 @@ def metrics() -> PlainTextResponse:
     )
     def predict(
         body: PredictBody,
+        explain: bool = False,
         x_quorabust_variant: str | None = Header(
             default=None,
             alias="X-Quorabust-Variant",
@@ -222,7 +241,16 @@ def predict(
         finally:
             latency.labels(v).observe(time.perf_counter() - t0)
         predictions.labels(v).inc()
-        return PredictOut(proba_duplicate=[float(x) for x in proba], variant=v)
+        features = None
+        if explain:
+            schema = _meta.get("feature_schema")
+            features = explain_pair_features(
+                bld,
+                body.question1,
+                body.question2,
+                feature_schema=schema if isinstance(schema, list) else None,
+            )
+        return PredictOut(proba_duplicate=[float(x) for x in proba], variant=v, features=features)
 
     return app
 

tests/test_explain.py

@@ -0,0 +1,30 @@
+import pandas as pd
+
+from quorabust.explain import explain_pair_features, feature_names_for_builder
+from quorabust.features import PairFeatureBuilder
+
+
+def _builder():
+    df = pd.DataFrame(
+        {
+            "question1": ["how to learn python", "best pizza"],
+            "question2": ["python learning tips", "pizza places"],
+        }
+    )
+    return PairFeatureBuilder(max_features=50).fit_from_frame(df)
+
+
+def test_explain_pair_features_returns_named_values():
+    builder = _builder()
+    rows = explain_pair_features(
+        builder,
+        ["how to learn python"],
+        ["python learning tips"],
+    )
+    assert set(rows[0]) == {"cos", "jaccard", "len_ratio", "abs_len_diff", "len_sum"}
+    assert all(isinstance(v, float) for v in rows[0].values())
+
+
+def test_feature_schema_overrides_builder_names():
+    builder = _builder()
+    assert feature_names_for_builder(builder, ["a", "b"]) == ["a", "b"]

tests/test_features.py

@@ -26,6 +26,7 @@ def test_pair_feature_builder_shape_and_monotonic_similarity():
     X = b.transform_pairs(q1, q2)
     assert X.shape == (2, 5)
     assert X[0, 0] >= X[1, 0]
+    assert b.feature_names() == ["cos", "jaccard", "len_ratio", "abs_len_diff", "len_sum"]
 
 
 def test_fit_from_frame():

tests/test_serve.py

@@ -45,6 +45,7 @@ def test_serve_health_ready_predict(tmp_path):
         body = r.json()
         assert "proba_duplicate" in body
         assert body["variant"] == "a"
+        assert body["features"] is None
         m = client.get("/metrics")
         assert m.status_code == 200
         assert b"quorabust_predictions_total" in m.content
@@ -84,6 +85,26 @@ def test_models_returns_safe_public_metadata(tmp_path):
     assert "id" not in model
 
 
+def test_predict_can_return_feature_explanations(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.post(
+            "/predict?explain=true",
+            json={"question1": ["hello"], "question2": ["hello there"]},
+        )
+    assert r.status_code == 200
+    features = r.json()["features"]
+    assert features and set(features[0]) == {
+        "cos",
+        "jaccard",
+        "len_ratio",
+        "abs_len_diff",
+        "len_sum",
+    }
+
+
 def test_models_without_loaded_artifacts_is_unavailable():
     app = create_app(model_path_a="/nonexistent/quorabust_missing.pkl")
     with TestClient(app) as client: