glin-ml 0.1.0__tar.gz

glin_ml-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.pytest_cache/
+build/
+dist/

glin_ml-0.1.0/Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.11-slim
+
+WORKDIR /app
+
+COPY pyproject.toml README.md LICENSE ./
+COPY glin/ glin/
+
+RUN pip install --no-cache-dir .
+
+EXPOSE 8000
+
+ENTRYPOINT ["glin"]
+CMD ["serve", "--mode", "http", "--host", "0.0.0.0", "--port", "8000"]

glin_ml-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akash Chatterjee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

glin_ml-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.5
+Name: glin-ml
+Version: 0.1.0
+Summary: Instant, exactly-explainable statistical classifiers for AI agents, over MCP.
+Project-URL: Homepage, https://github.com/AkashChatterjee/glin
+Project-URL: Repository, https://github.com/AkashChatterjee/glin
+Author-email: Akash Chatterjee <akashc2310@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,ebm,explainable-ai,machine-learning,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: click<9,>=8.1
+Requires-Dist: interpret-core<0.8,>=0.7
+Requires-Dist: joblib<2,>=1.3
+Requires-Dist: mcp<2.0,>=1.0.0
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: pandas<3,>=2
+Requires-Dist: scikit-learn<2,>=1.3
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# glin
+
+CLI tool and Python library that equips AI agents with an instant, statistical "gut feeling" (System 1 thinking).
+
+`glin` trains an [Explainable Boosting Machine](https://interpret.ml/) on a CSV, then exposes it to LLM agents over [MCP](https://modelcontextprotocol.io/) — locally over stdio, or remotely over MCP's standard `streamable-http` transport. Every prediction comes with an exact, zero-approximation breakdown of which features drove it, straight from the model's own additive structure (no SHAP/LIME approximation).
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Train a model
+
+```bash
+glin train path/to/data.csv --target churn --name churn_v1
+```
+
+Models are saved under `~/.glin/models/<name>/`.
+
+```bash
+glin list
+```
+
+## Use it locally (Claude Desktop, Cursor, ...)
+
+Add to your MCP client's config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "glin": {
+      "command": "glin",
+      "args": ["serve", "--mode", "stdio"]
+    }
+  }
+}
+```
+
+## Deploy it remotely (e.g. one EC2 box, any MCP-aware agent)
+
+```bash
+docker build -t glin .
+docker run -p 8000:8000 -v ~/.glin:/root/.glin glin
+```
+
+Then point any MCP client at the standard streamable-http endpoint:
+
+```bash
+claude mcp add --transport http glin http://<host>:8000/mcp
+```
+
+## Tools exposed over MCP
+
+- `list_models()` — all trained models available.
+- `inspect_model(model_name)` — feature schema and target classes.
+- `predict(model_name, features, top_n=10)` — predicted class and probabilities, plus the full glassbox audit: base rate, every term's contribution (sorted by magnitude), and an explicit additivity check against the model's own predicted probability.
+
+## Data requirements
+
+`glin train` validates your CSV before doing any work — hard problems (e.g. a target column with only one class) stop training with a clear error; soft issues (e.g. a date-like column) print a warning and training proceeds anyway. These rules live in `glin/validation.py` as a flat, appendable list, so support for a currently-unsupported shape below can be added by adding one rule and one preprocessing case, without touching the rest of the pipeline.
+
+**Feature columns — supported today:**
+
+| Data shape | What happens |
+|---|---|
+| Numeric (int/float), including `NaN` | Passed through as-is; EBM natively bins missing values into their own split. |
+| Dirty numeric strings (blanks, e.g. `" "` for a new customer's total charges) | Coerced to `float64` if ≥80% of non-null values parse as numbers; unparseable cells become `NaN`. |
+| Categorical strings, any cardinality up to 250 unique values | Standardized (lowercased, stripped) and one-hot-style binned by EBM; missing/unseen values map to a `__missing__` sentinel. |
+| Boolean columns | Treated as a 0/1 continuous numeric feature. |
+
+**Feature columns — not yet supported** (each is flagged by `glin train`'s validator when detected):
+
+| Data shape | What actually happens | Why |
+|---|---|---|
+| Dates / timestamps | No date features are extracted. The column is either dropped (if high-cardinality) or kept as a meaningless categorical label — no time-based signal survives either way. | Cut from V1 scope; a real dataset need should drive adding cyclical date-feature extraction. |
+| Free text / natural language | Dropped once it exceeds 250 unique values; below that threshold it becomes a set of (almost certainly useless) categorical labels. | glin doesn't do NLP; a text column isn't a set of classes. |
+| Currency symbols / thousands separators (`$`, `€`, `£`, `,`) | Not stripped. `"$1,234.56"` fails the ≥80% numeric-parse threshold and falls back to categorical (i.e. garbage). Clean these before training. | Cut from V1 scope under an "assume a healthy dataset" simplification. |
+| Lists / dicts / nested JSON in a cell | Not parsed structurally; treated as an opaque string. | No structured extraction implemented. |
+| Row identifiers (sequential IDs, UUIDs, hashes) | Dropped intentionally — not a gap, this is by design. | IDs carry no predictive signal. |
+
+**Target column requirements:**
+
+- At least 2 distinct non-null values (binary or multiclass) — a single-class target is a hard error.
+- Rows with a missing target value are dropped automatically (with a warning); the rest are unaffected.
+- A numeric target with many distinct values (>20) triggers a warning that it looks like a regression target — `glin` trains classifiers, not regressors.

glin_ml-0.1.0/README.md

@@ -0,0 +1,86 @@
+# glin
+
+CLI tool and Python library that equips AI agents with an instant, statistical "gut feeling" (System 1 thinking).
+
+`glin` trains an [Explainable Boosting Machine](https://interpret.ml/) on a CSV, then exposes it to LLM agents over [MCP](https://modelcontextprotocol.io/) — locally over stdio, or remotely over MCP's standard `streamable-http` transport. Every prediction comes with an exact, zero-approximation breakdown of which features drove it, straight from the model's own additive structure (no SHAP/LIME approximation).
+
+## Install
+
+```bash
+pip install -e .
+```
+
+## Train a model
+
+```bash
+glin train path/to/data.csv --target churn --name churn_v1
+```
+
+Models are saved under `~/.glin/models/<name>/`.
+
+```bash
+glin list
+```
+
+## Use it locally (Claude Desktop, Cursor, ...)
+
+Add to your MCP client's config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "glin": {
+      "command": "glin",
+      "args": ["serve", "--mode", "stdio"]
+    }
+  }
+}
+```
+
+## Deploy it remotely (e.g. one EC2 box, any MCP-aware agent)
+
+```bash
+docker build -t glin .
+docker run -p 8000:8000 -v ~/.glin:/root/.glin glin
+```
+
+Then point any MCP client at the standard streamable-http endpoint:
+
+```bash
+claude mcp add --transport http glin http://<host>:8000/mcp
+```
+
+## Tools exposed over MCP
+
+- `list_models()` — all trained models available.
+- `inspect_model(model_name)` — feature schema and target classes.
+- `predict(model_name, features, top_n=10)` — predicted class and probabilities, plus the full glassbox audit: base rate, every term's contribution (sorted by magnitude), and an explicit additivity check against the model's own predicted probability.
+
+## Data requirements
+
+`glin train` validates your CSV before doing any work — hard problems (e.g. a target column with only one class) stop training with a clear error; soft issues (e.g. a date-like column) print a warning and training proceeds anyway. These rules live in `glin/validation.py` as a flat, appendable list, so support for a currently-unsupported shape below can be added by adding one rule and one preprocessing case, without touching the rest of the pipeline.
+
+**Feature columns — supported today:**
+
+| Data shape | What happens |
+|---|---|
+| Numeric (int/float), including `NaN` | Passed through as-is; EBM natively bins missing values into their own split. |
+| Dirty numeric strings (blanks, e.g. `" "` for a new customer's total charges) | Coerced to `float64` if ≥80% of non-null values parse as numbers; unparseable cells become `NaN`. |
+| Categorical strings, any cardinality up to 250 unique values | Standardized (lowercased, stripped) and one-hot-style binned by EBM; missing/unseen values map to a `__missing__` sentinel. |
+| Boolean columns | Treated as a 0/1 continuous numeric feature. |
+
+**Feature columns — not yet supported** (each is flagged by `glin train`'s validator when detected):
+
+| Data shape | What actually happens | Why |
+|---|---|---|
+| Dates / timestamps | No date features are extracted. The column is either dropped (if high-cardinality) or kept as a meaningless categorical label — no time-based signal survives either way. | Cut from V1 scope; a real dataset need should drive adding cyclical date-feature extraction. |
+| Free text / natural language | Dropped once it exceeds 250 unique values; below that threshold it becomes a set of (almost certainly useless) categorical labels. | glin doesn't do NLP; a text column isn't a set of classes. |
+| Currency symbols / thousands separators (`$`, `€`, `£`, `,`) | Not stripped. `"$1,234.56"` fails the ≥80% numeric-parse threshold and falls back to categorical (i.e. garbage). Clean these before training. | Cut from V1 scope under an "assume a healthy dataset" simplification. |
+| Lists / dicts / nested JSON in a cell | Not parsed structurally; treated as an opaque string. | No structured extraction implemented. |
+| Row identifiers (sequential IDs, UUIDs, hashes) | Dropped intentionally — not a gap, this is by design. | IDs carry no predictive signal. |
+
+**Target column requirements:**
+
+- At least 2 distinct non-null values (binary or multiclass) — a single-class target is a hard error.
+- Rows with a missing target value are dropped automatically (with a warning); the rest are unaffected.
+- A numeric target with many distinct values (>20) triggers a warning that it looks like a regression target — `glin` trains classifiers, not regressors.

glin_ml-0.1.0/glin/__init__.py

@@ -0,0 +1,3 @@
+"""glin: instant, exactly-explainable statistical classifiers for AI agents."""
+
+__version__ = "0.1.0"

glin_ml-0.1.0/glin/cli.py

@@ -0,0 +1,100 @@
+"""glin CLI: train, list, serve."""
+from __future__ import annotations
+
+import click
+import pandas as pd
+
+from glin import engine, server
+from glin.engine import DEFAULT_MODELS_ROOT
+from glin.validation import validate_dataset
+
+
+@click.group()
+def main() -> None:
+    """glin: instant, exactly-explainable statistical classifiers for AI agents."""
+
+
+@main.command()
+@click.argument("csv_path", type=click.Path(exists=True, dir_okay=False))
+@click.option("--target", required=True, help="Name of the target column to predict.")
+@click.option("--name", required=True, help="Unique name to save this model under.")
+def train(csv_path: str, target: str, name: str) -> None:
+    """Train an EBM classifier on CSV_PATH and save it as --name."""
+    df = pd.read_csv(csv_path)
+
+    validation = validate_dataset(df, target)
+    for issue in validation.warnings:
+        click.echo(f"Warning: {issue.message}")
+    if not validation.is_valid:
+        for issue in validation.errors:
+            click.echo(f"Error: {issue.message}")
+        raise SystemExit(1)
+
+    bundle = engine.train_model(df, target, model_name=name)
+    model_dir = engine.save_bundle(bundle, DEFAULT_MODELS_ROOT)
+
+    preprocessor = bundle["preprocessor"]
+    click.echo(f"Trained model '{name}' -> {model_dir}")
+    click.echo(f"  Classes: {bundle['target_classes']}")
+    click.echo(
+        f"  Features kept: {len(preprocessor.output_columns_)} "
+        f"({len(preprocessor.numeric_columns_)} numeric, "
+        f"{len(preprocessor.categorical_columns_)} categorical)"
+    )
+    click.echo(f"  Features dropped: {preprocessor.dropped_columns_}")
+
+
+@main.command(name="list")
+def list_cmd() -> None:
+    """List all trained models."""
+    if not DEFAULT_MODELS_ROOT.exists():
+        click.echo("No models trained yet.")
+        return
+
+    rows = []
+    for model_dir in sorted(DEFAULT_MODELS_ROOT.iterdir()):
+        metadata_path = model_dir / engine.METADATA_FILENAME
+        if not metadata_path.exists():
+            continue
+        meta = engine.load_metadata(model_dir)
+        n_features = len(meta["features"]["numeric"]) + len(meta["features"]["categorical"])
+        rows.append(
+            (
+                meta["model_name"],
+                meta["target_column"],
+                ", ".join(str(c) for c in meta["target_classes"]),
+                str(n_features),
+                meta["created_at"],
+            )
+        )
+
+    if not rows:
+        click.echo("No models trained yet.")
+        return
+
+    headers = ("Model Name", "Target Column", "Classes", "Features Kept", "Created Date")
+    widths = [max(len(h), *(len(r[i]) for r in rows)) for i, h in enumerate(headers)]
+
+    def fmt_row(values: tuple[str, ...]) -> str:
+        return "  ".join(v.ljust(w) for v, w in zip(values, widths))
+
+    click.echo(fmt_row(headers))
+    click.echo(fmt_row(tuple("-" * w for w in widths)))
+    for row in rows:
+        click.echo(fmt_row(row))
+
+
+@main.command()
+@click.option("--mode", type=click.Choice(["stdio", "http"]), default="stdio")
+@click.option("--host", default="0.0.0.0")
+@click.option("--port", default=8000, type=int)
+def serve(mode: str, host: str, port: int) -> None:
+    """Run the glin MCP server (stdio for local clients, http for remote agents)."""
+    if mode == "stdio":
+        server.run_stdio()
+    else:
+        server.run_http(host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

glin_ml-0.1.0/glin/engine.py

@@ -0,0 +1,260 @@
+"""EBM training, exact local-explanation extraction, and joblib bundle I/O.
+
+Glassbox math reference (verified against interpret-core==0.7.8 at
+implementation time, see tests/test_engine_additivity.py):
+
+  binary:     P(y=1|x) = sigmoid(intercept_[0] + sum(term contribution scores))
+  multiclass: P(y=k|x) = softmax(intercept_ + sum(term contribution score vectors))[k]
+
+Interaction terms are identified via ``model.term_features_`` (index tuples
+into ``feature_names_in_``), never by parsing ``term_names_`` strings — the
+join delimiter is an implementation detail of the library, not a stable
+contract.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import joblib
+import numpy as np
+import pandas as pd
+from interpret.glassbox import ExplainableBoostingClassifier
+from sklearn.preprocessing import LabelEncoder
+
+from glin.preprocessor import EBMTabularPreprocessor
+from glin.validation import validate_dataset
+
+BUNDLE_FILENAME = "bundle.joblib"
+METADATA_FILENAME = "metadata.json"
+DEFAULT_MODELS_ROOT = Path.home() / ".glin" / "models"
+
+
+def _to_native(value: Any) -> Any:
+    """numpy scalars aren't JSON-serializable; metadata.json needs plain types."""
+    if isinstance(value, np.generic):
+        return value.item()
+    return value
+
+
+def _sigmoid(x: float) -> float:
+    return 1.0 / (1.0 + np.exp(-x))
+
+
+def _softmax(x: np.ndarray) -> np.ndarray:
+    shifted = x - np.max(x)
+    exp = np.exp(shifted)
+    return exp / exp.sum()
+
+
+def train_model(
+    df: pd.DataFrame,
+    target_column: str,
+    *,
+    model_name: str,
+    max_bins: int = 256,
+    interactions: int = 10,
+    random_state: int = 42,
+) -> dict[str, Any]:
+    """Fits EBMTabularPreprocessor on the feature columns and an
+    ExplainableBoostingClassifier on the transformed output. Works for
+    binary or multiclass targets (interpret-core automatically strips
+    interaction terms for multiclass models). Raises ValueError if the
+    dataset fails a hard validation rule (see glin.validation); returns any
+    soft warnings alongside the trained bundle."""
+    validation = validate_dataset(df, target_column)
+    if not validation.is_valid:
+        raise ValueError("; ".join(issue.message for issue in validation.errors))
+
+    df = df.dropna(subset=[target_column])
+    X_raw = df.drop(columns=[target_column])
+    y_raw = df[target_column]
+
+    label_encoder = LabelEncoder()
+    y = label_encoder.fit_transform(y_raw)
+    target_classes = [_to_native(c) for c in label_encoder.classes_]
+
+    preprocessor = EBMTabularPreprocessor()
+    X = preprocessor.fit_transform(X_raw)
+
+    if X.shape[1] == 0:
+        raise ValueError(
+            "every feature column was dropped (ID-like, constant, or too "
+            "high-cardinality) — nothing left to train on"
+        )
+
+    model = ExplainableBoostingClassifier(
+        feature_names=list(X.columns),
+        feature_types=preprocessor.get_feature_types(),
+        max_bins=max_bins,
+        interactions=interactions,
+        random_state=random_state,
+    )
+    model.fit(X, y)
+
+    return {
+        "model_name": model_name,
+        "target_column": target_column,
+        "preprocessor": preprocessor,
+        "model": model,
+        "target_classes": target_classes,
+        "warnings": [issue.message for issue in validation.warnings],
+    }
+
+
+def save_bundle(bundle: dict[str, Any], models_root: Path) -> Path:
+    model_dir = Path(models_root) / bundle["model_name"]
+    model_dir.mkdir(parents=True, exist_ok=True)
+
+    joblib.dump(
+        {
+            "preprocessor": bundle["preprocessor"],
+            "model": bundle["model"],
+            "target_classes": bundle["target_classes"],
+        },
+        model_dir / BUNDLE_FILENAME,
+    )
+
+    preprocessor: EBMTabularPreprocessor = bundle["preprocessor"]
+    model = bundle["model"]
+    metadata = {
+        "model_name": bundle["model_name"],
+        "target_column": bundle["target_column"],
+        "target_classes": bundle["target_classes"],
+        "features": {
+            "numeric": preprocessor.numeric_columns_,
+            "categorical": preprocessor.categorical_columns_,
+        },
+        "dropped_columns": preprocessor.dropped_columns_,
+        "hyperparameters": {
+            "max_bins": _to_native(model.max_bins),
+            "interactions": _to_native(model.interactions),
+            "random_state": _to_native(model.random_state),
+        },
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+    (model_dir / METADATA_FILENAME).write_text(json.dumps(metadata, indent=2))
+    return model_dir
+
+
+def load_bundle(model_dir: Path) -> dict[str, Any]:
+    return joblib.load(Path(model_dir) / BUNDLE_FILENAME)
+
+
+def load_metadata(model_dir: Path) -> dict[str, Any]:
+    return json.loads((Path(model_dir) / METADATA_FILENAME).read_text())
+
+
+def predict_record(bundle: dict[str, Any], features: dict[str, Any]) -> dict[str, Any]:
+    X = bundle["preprocessor"].transform(features)
+    proba = bundle["model"].predict_proba(X)[0]
+    target_classes = bundle["target_classes"]
+    predicted_idx = int(np.argmax(proba))
+
+    return {
+        "predicted_class": target_classes[predicted_idx],
+        "probabilities": {
+            str(target_classes[i]): float(proba[i]) for i in range(len(target_classes))
+        },
+    }
+
+
+def _term_contributions(
+    model: ExplainableBoostingClassifier, data: dict, features: dict[str, Any]
+) -> list[dict[str, Any]]:
+    feature_names_in = list(model.feature_names_in_)
+    contributions = []
+
+    for i, term_idx_tuple in enumerate(model.term_features_):
+        is_interaction = len(term_idx_tuple) > 1
+        involved = [feature_names_in[idx] for idx in term_idx_tuple]
+        raw_value = (
+            [features.get(f) for f in involved] if is_interaction else features.get(involved[0])
+        )
+        contributions.append(
+            {
+                "feature": " & ".join(involved),
+                "is_interaction": is_interaction,
+                "value": raw_value,
+                "score": np.asarray(data["scores"][i], dtype=float),
+            }
+        )
+    return contributions
+
+
+def explain_record(
+    bundle: dict[str, Any], features: dict[str, Any], top_n: int = 10
+) -> dict[str, Any]:
+    """Full glassbox audit: intercept, per-term contributions (sorted by
+    magnitude, main effects and interactions together), and an explicit
+    additivity check against the model's own predict_proba. Binary targets
+    use the PRD's exact sigmoid formula; targets with more than two classes
+    generalize it via softmax over per-class score vectors."""
+    preprocessor = bundle["preprocessor"]
+    model = bundle["model"]
+    target_classes = bundle["target_classes"]
+    n_classes = len(target_classes)
+
+    X = preprocessor.transform(features)
+    data = model.explain_local(X).data(0)
+    contributions = _term_contributions(model, data, features)
+    proba = model.predict_proba(X)[0]
+    intercept = np.asarray(model.intercept_, dtype=float)
+    predicted_class = target_classes[int(np.argmax(proba))]
+
+    if n_classes == 2:
+        base_rate = float(intercept[0])
+        total_logit = base_rate + sum(float(c["score"]) for c in contributions)
+
+        for c in contributions:
+            c["score"] = float(c["score"])
+            c["direction"] = (
+                f"favors {target_classes[1]}" if c["score"] > 0 else f"favors {target_classes[0]}"
+            )
+
+        contributions.sort(key=lambda c: abs(c["score"]), reverse=True)
+
+        reconstructed = float(_sigmoid(total_logit))
+        model_probability = float(proba[1])
+
+        return {
+            "predicted_class": predicted_class,
+            "base_rate": base_rate,
+            "probabilities": {
+                str(target_classes[i]): float(proba[i]) for i in range(n_classes)
+            },
+            "contributions": contributions[:top_n],
+            "reconstructed_probability": reconstructed,
+            "model_probability": model_probability,
+            "additivity_verified": bool(abs(reconstructed - model_probability) < 1e-3),
+        }
+
+    # Multiclass: each term's score is an (n_classes,)-shaped vector; the
+    # additive link is softmax rather than sigmoid.
+    total_logits = intercept + sum(c["score"] for c in contributions)
+
+    for c in contributions:
+        top_class_idx = int(np.argmax(c["score"]))
+        c["score_by_class"] = {
+            str(target_classes[k]): float(c["score"][k]) for k in range(n_classes)
+        }
+        c["direction"] = f"favors {target_classes[top_class_idx]}"
+        c["score"] = float(np.max(np.abs(c["score"])))
+
+    contributions.sort(key=lambda c: abs(c["score"]), reverse=True)
+
+    reconstructed_vec = _softmax(total_logits)
+    reconstructed = {str(target_classes[k]): float(reconstructed_vec[k]) for k in range(n_classes)}
+    model_probability = {str(target_classes[k]): float(proba[k]) for k in range(n_classes)}
+
+    return {
+        "predicted_class": predicted_class,
+        "base_rate": {str(target_classes[k]): float(intercept[k]) for k in range(n_classes)},
+        "probabilities": model_probability,
+        "contributions": contributions[:top_n],
+        "reconstructed_probability": reconstructed,
+        "model_probability": model_probability,
+        "additivity_verified": bool(np.all(np.abs(reconstructed_vec - proba) < 1e-3)),
+    }