nous 0.1.0__tar.gz → 0.2.0__tar.gz

nous-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: nous
+Version: 0.2.0
+Summary: Nous: A Neuro-Symbolic Library for Interpretable AI
+Author-email: Islam Tlupov <tlupovislam@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Islam Tlupov
+        
+        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.
+        
+Project-URL: Repository, https://github.com/EmotionEngineer/nous
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.1
+Requires-Dist: numpy>=1.22
+Requires-Dist: pandas>=1.5
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.5; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: matplotlib>=3.6; extra == "dev"
+Requires-Dist: seaborn>=0.12; extra == "dev"
+Requires-Dist: tqdm>=4.65; extra == "dev"
+Requires-Dist: ucimlrepo>=0.0.5; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: matplotlib>=3.6; extra == "examples"
+Requires-Dist: seaborn>=0.12; extra == "examples"
+Requires-Dist: tqdm>=4.65; extra == "examples"
+Requires-Dist: ucimlrepo>=0.0.5; extra == "examples"
+Dynamic: license-file
+
+# Nous — A Neuro-Symbolic Library for Interpretable AI
+
+[![PyPI](https://img.shields.io/pypi/v/nous.svg)](https://pypi.org/project/nous/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Make tabular models you can read.  
+Nous learns compact logical rules and optional case‑based prototypes inside one differentiable model — so prediction and explanation come from the same place.
+
+- 🧩 One white‑box → two styles: rules and/or prototypes
+- 🔀 Learned AND / OR / k‑of‑n mixtures capture interactions without bloat
+- ✂️ Minimal, faithful stories: pruning + sufficiency/comprehensiveness checks
+- 🚀 Practical: competitive accuracy, NumPy export, unit‑tested toolkit
+
+## Key Features
+
+- Intrinsic interpretability (not post‑hoc): explanations are part of the forward pass
+- Switchable style: enable/disable prototypes; choose rule selection (fixed / softmax / sparse); add calibrators
+- Fidelity diagnostics: pruned‑forward inference, minimal‑sufficient explanations, stability tools
+- Ready to ship: pure‑NumPy export for inference without PyTorch
+
+## Installation
+
+```bash
+# Stable from PyPI
+pip install nous
+
+# With example extras (plots, progress, UCI fetchers)
+pip install "nous[examples]"
+
+# Dev setup (tests, linters, type checks)
+pip install "nous[dev]"
+```
+
+Requirements (core):
+- Python 3.9+
+- torch>=2.1
+- numpy>=1.22
+- pandas>=1.5
+- scikit-learn>=1.2
+
+Extras:
+- examples: matplotlib>=3.6, seaborn>=0.12, tqdm>=4.65, ucimlrepo>=0.0.5
+- dev: pytest>=7.0, pytest-cov>=4.0, mypy>=1.5, ruff>=0.5, black>=23.0, matplotlib>=3.6, seaborn>=0.12, tqdm>=4.65, ucimlrepo>=0.0.5
+
+## Recommended Configurations
+
+| Profile | Rule selection | Calibrators | Prototypes | Use when | Speed |
+|--------|-----------------|-------------|------------|----------|-------|
+| Fast baseline | fixed | off | off | quick sweeps, ablations | ⚡⚡⚡ |
+| Default rules | softmax | on  | off | general use, strong accuracy | ⚡⚡ |
+| Explain‑everything | softmax | on  | on  | rich case‑based narratives | ⚡ |
+
+Tips:
+- Train with prototypes off for speed; enable them only on the final model if you need case‑based stories.
+- 300 epochs with patience≈50 works well on common tabular datasets.
+
+## Bench Snapshot (5‑fold CV, typical)
+
+| Dataset | Metric | Nous (rules) | Nous (+proto) | EBM | XGBoost |
+|--------|--------|--------------|---------------|-----|---------|
+| HELOC (cls) | AUC | ~0.791 | ~0.792 | ~0.799 | ~0.796 |
+| Adult (cls) | AUC | ~0.913 | ~0.914 | ~0.926 | ~0.929 |
+| Breast Cancer (cls) | Acc | ~0.975 | ~0.983 | ~0.970 | ~0.965 |
+| California (reg) | RMSE | ~0.514 | ~0.505 | ~0.562 | ~0.439 |
+
+Numbers vary with seed/HPO. See examples/benchmark.ipynb for reproducible runs.
+
+## What makes Nous different?
+
+- The explanation is the model: rules and prototypes live in the forward pass
+- Interactions without clutter: AND/OR/k‑of‑n mixtures keep explanations short
+- Verified stories: minimal‑sufficient explanations + pruned‑forward confidence checks
+- Lightweight deployment: NumPy export (no torch at inference)
+
+## Repository Layout
+
+- examples/
+  - benchmark.ipynb — end‑to‑end comparison on classic tabular data
+  - wine_classification.py, california_regression.py — minimal scripts
+  - export_numpy_demo.py — deploy without torch
+- nous/
+  - model.py (NousNet), facts.py (calibrated L−R facts)
+  - rules/* (fixed/softmax/sparse), explain/* (pruning, fidelity, traces, prototypes)
+  - training/* (loop, schedulers), export/* (NumPy), utils/*
+- tests/ — unit tests for forward, rules, facts, prototypes, explanations, export
+
+## License
+
+MIT — see LICENSE.

nous-0.2.0/README.md

@@ -0,0 +1,89 @@
+# Nous — A Neuro-Symbolic Library for Interpretable AI
+
+[![PyPI](https://img.shields.io/pypi/v/nous.svg)](https://pypi.org/project/nous/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Make tabular models you can read.  
+Nous learns compact logical rules and optional case‑based prototypes inside one differentiable model — so prediction and explanation come from the same place.
+
+- 🧩 One white‑box → two styles: rules and/or prototypes
+- 🔀 Learned AND / OR / k‑of‑n mixtures capture interactions without bloat
+- ✂️ Minimal, faithful stories: pruning + sufficiency/comprehensiveness checks
+- 🚀 Practical: competitive accuracy, NumPy export, unit‑tested toolkit
+
+## Key Features
+
+- Intrinsic interpretability (not post‑hoc): explanations are part of the forward pass
+- Switchable style: enable/disable prototypes; choose rule selection (fixed / softmax / sparse); add calibrators
+- Fidelity diagnostics: pruned‑forward inference, minimal‑sufficient explanations, stability tools
+- Ready to ship: pure‑NumPy export for inference without PyTorch
+
+## Installation
+
+```bash
+# Stable from PyPI
+pip install nous
+
+# With example extras (plots, progress, UCI fetchers)
+pip install "nous[examples]"
+
+# Dev setup (tests, linters, type checks)
+pip install "nous[dev]"
+```
+
+Requirements (core):
+- Python 3.9+
+- torch>=2.1
+- numpy>=1.22
+- pandas>=1.5
+- scikit-learn>=1.2
+
+Extras:
+- examples: matplotlib>=3.6, seaborn>=0.12, tqdm>=4.65, ucimlrepo>=0.0.5
+- dev: pytest>=7.0, pytest-cov>=4.0, mypy>=1.5, ruff>=0.5, black>=23.0, matplotlib>=3.6, seaborn>=0.12, tqdm>=4.65, ucimlrepo>=0.0.5
+
+## Recommended Configurations
+
+| Profile | Rule selection | Calibrators | Prototypes | Use when | Speed |
+|--------|-----------------|-------------|------------|----------|-------|
+| Fast baseline | fixed | off | off | quick sweeps, ablations | ⚡⚡⚡ |
+| Default rules | softmax | on  | off | general use, strong accuracy | ⚡⚡ |
+| Explain‑everything | softmax | on  | on  | rich case‑based narratives | ⚡ |
+
+Tips:
+- Train with prototypes off for speed; enable them only on the final model if you need case‑based stories.
+- 300 epochs with patience≈50 works well on common tabular datasets.
+
+## Bench Snapshot (5‑fold CV, typical)
+
+| Dataset | Metric | Nous (rules) | Nous (+proto) | EBM | XGBoost |
+|--------|--------|--------------|---------------|-----|---------|
+| HELOC (cls) | AUC | ~0.791 | ~0.792 | ~0.799 | ~0.796 |
+| Adult (cls) | AUC | ~0.913 | ~0.914 | ~0.926 | ~0.929 |
+| Breast Cancer (cls) | Acc | ~0.975 | ~0.983 | ~0.970 | ~0.965 |
+| California (reg) | RMSE | ~0.514 | ~0.505 | ~0.562 | ~0.439 |
+
+Numbers vary with seed/HPO. See examples/benchmark.ipynb for reproducible runs.
+
+## What makes Nous different?
+
+- The explanation is the model: rules and prototypes live in the forward pass
+- Interactions without clutter: AND/OR/k‑of‑n mixtures keep explanations short
+- Verified stories: minimal‑sufficient explanations + pruned‑forward confidence checks
+- Lightweight deployment: NumPy export (no torch at inference)
+
+## Repository Layout
+
+- examples/
+  - benchmark.ipynb — end‑to‑end comparison on classic tabular data
+  - wine_classification.py, california_regression.py — minimal scripts
+  - export_numpy_demo.py — deploy without torch
+- nous/
+  - model.py (NousNet), facts.py (calibrated L−R facts)
+  - rules/* (fixed/softmax/sparse), explain/* (pruning, fidelity, traces, prototypes)
+  - training/* (loop, schedulers), export/* (NumPy), utils/*
+- tests/ — unit tests for forward, rules, facts, prototypes, explanations, export
+
+## License
+
+MIT — see LICENSE.

nous-0.2.0/nous/__init__.py

@@ -0,0 +1,103 @@
+from .version import __version__
+from .model import NousNet
+from .facts import BetaFactLayer, PiecewiseLinearCalibrator
+from .prototypes import ScaledPrototypeLayer
+from .rules import FixedPairRuleLayer, SoftmaxRuleLayer, SparseRuleLayer, SimpleNousBlock
+
+# Explainability (core API)
+from .explain import (
+    rule_impact_df,
+    minimal_sufficient_explanation,
+    select_pruning_threshold_global,
+    select_pruning_threshold_global_bs,
+    global_rulebook,
+    generate_enhanced_explanation,
+    explanation_fidelity_metrics,
+    explanation_stability,
+    aggregator_mixture_report,
+    suggest_rule_counterfactuals,
+    render_fact_descriptions,
+    AGG_NAMES,
+)
+from .explain.aggregator import format_agg_mixture
+
+# Prototype tracing utilities
+from .explain.traces import (
+    describe_prototype,
+    prototype_report_global,
+    prototype_contribution_df,
+    prototype_top_rules,
+    trace_rule_to_base_facts,
+    get_last_block_static_metadata,
+)
+
+# Export utilities
+from .export import (
+    export_numpy_inference,
+    validate_numpy_vs_torch,
+    export_and_validate,
+    load_numpy_module,
+)
+
+# Training and evaluation
+from .training import (
+    train_model,
+    evaluate_classification,
+    evaluate_regression,
+    make_sparse_regression_hook,
+)
+
+# Dataset helpers (used in examples)
+from .data import get_wine_data, get_california_housing_data
+
+# Utilities
+from .utils import set_global_seed
+
+__all__ = [
+    "__version__",
+    # Core model and components
+    "NousNet",
+    "BetaFactLayer",
+    "PiecewiseLinearCalibrator",
+    "ScaledPrototypeLayer",
+    "FixedPairRuleLayer",
+    "SoftmaxRuleLayer",
+    "SparseRuleLayer",
+    "SimpleNousBlock",
+    # Explainability (core)
+    "rule_impact_df",
+    "minimal_sufficient_explanation",
+    "select_pruning_threshold_global",
+    "select_pruning_threshold_global_bs",
+    "global_rulebook",
+    "generate_enhanced_explanation",
+    "explanation_fidelity_metrics",
+    "explanation_stability",
+    "aggregator_mixture_report",
+    "suggest_rule_counterfactuals",
+    "render_fact_descriptions",
+    "AGG_NAMES",
+    "format_agg_mixture",
+    # Prototype tracing utilities
+    "describe_prototype",
+    "prototype_report_global",
+    "prototype_contribution_df",
+    "prototype_top_rules",
+    "trace_rule_to_base_facts",
+    "get_last_block_static_metadata",
+    # Export utilities
+    "export_numpy_inference",
+    "validate_numpy_vs_torch",
+    "export_and_validate",
+    "load_numpy_module",
+    # Training and evaluation
+    "train_model",
+    "evaluate_classification",
+    "evaluate_regression",
+    "make_sparse_regression_hook",
+    # Dataset helpers
+    "get_wine_data",
+    "get_california_housing_data",
+    # Utilities
+    "set_global_seed",
+]

nous-0.2.0/nous/data/__init__.py

@@ -0,0 +1,4 @@
+from .wine import get_wine_data
+from .california import get_california_housing_data
+
+__all__ = ["get_wine_data", "get_california_housing_data"]

nous-0.2.0/nous/data/california.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+import numpy as np
+from typing import Tuple, List
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler
+from sklearn.datasets import fetch_california_housing
+
+def get_california_housing_data(scale_y: bool = True):
+    """
+    Load California Housing and return standardized X and (optionally) standardized y.
+    Returns
+    -------
+    X_train, X_val, X_test, y_train, y_val, y_test, feature_names, class_names, task_type, y_scaler
+    """
+    data = fetch_california_housing()
+    X, y = data.data, data.target
+    feature_names = data.feature_names
+
+    X_train_full, X_test, y_train_full, y_test = train_test_split(X, y, test_size=0.2, random_state=42)
+
+    x_scaler = StandardScaler()
+    X_train_full = x_scaler.fit_transform(X_train_full)
+    X_test = x_scaler.transform(X_test)
+
+    X_train, X_val, y_train, y_val = train_test_split(X_train_full, y_train_full, test_size=0.2, random_state=42)
+
+    y_scaler = None
+    if scale_y:
+        y_scaler = StandardScaler()
+        y_train = y_scaler.fit_transform(y_train.reshape(-1,1)).ravel()
+        y_val   = y_scaler.transform(y_val.reshape(-1,1)).ravel()
+    return X_train, X_val, X_test, y_train, y_val, y_test, feature_names, None, "regression", y_scaler

nous-0.2.0/nous/data/wine.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+import numpy as np
+from typing import Tuple, List
+from sklearn.model_selection import train_test_split
+from sklearn.preprocessing import StandardScaler, LabelEncoder
+
+def get_wine_data():
+    """
+    Load Wine dataset via ucimlrepo and return standardized splits.
+    Returns
+    -------
+    X_train, X_val, X_test, y_train, y_val, y_test, feature_names, class_names, task_type, y_scaler
+    """
+    from ucimlrepo import fetch_ucirepo
+    wine = fetch_ucirepo(id=109)
+    X, y_df = wine.data.features, wine.data.targets
+    feature_names = X.columns.tolist()
+    y = LabelEncoder().fit_transform(y_df.values.ravel())
+    class_names = [f"Class_{i+1}" for i in range(len(np.unique(y)))]
+    X_train_full, X_test, y_train_full, y_test = train_test_split(
+        X, y, test_size=0.2, random_state=42, stratify=y
+    )
+    preprocessor = StandardScaler()
+    X_train_full = preprocessor.fit_transform(X_train_full)
+    X_test = preprocessor.transform(X_test)
+    X_train, X_val, y_train, y_val = train_test_split(
+        X_train_full, y_train_full, test_size=0.2, random_state=42, stratify=y_train_full
+    )
+    return X_train, X_val, X_test, y_train, y_val, y_test, feature_names, class_names, "classification", None

nous-0.2.0/nous/explain/__init__.py

@@ -0,0 +1,26 @@
+from .aggregator import AGG_NAMES, aggregator_mixture_report, format_agg_mixture
+from .facts_desc import render_fact_descriptions
+from .loo import rule_impact_df
+from .mse import minimal_sufficient_explanation
+from .pruning import select_pruning_threshold_global, select_pruning_threshold_global_bs
+from .global_book import global_rulebook
+from .generate import generate_enhanced_explanation
+from .fidelity import explanation_fidelity_metrics
+from .stability import explanation_stability
+from .cf import suggest_rule_counterfactuals
+
+__all__ = [
+    "AGG_NAMES",
+    "aggregator_mixture_report",
+    "format_agg_mixture",
+    "render_fact_descriptions",
+    "rule_impact_df",
+    "minimal_sufficient_explanation",
+    "select_pruning_threshold_global",
+    "select_pruning_threshold_global_bs",
+    "global_rulebook",
+    "generate_enhanced_explanation",
+    "explanation_fidelity_metrics",
+    "explanation_stability",
+    "suggest_rule_counterfactuals",
+]

nous-0.2.0/nous/explain/aggregator.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+import numpy as np
+import pandas as pd
+from typing import List
+from ..model import NousNet
+
+AGG_NAMES = ['AND', 'OR', 'k-of-n', 'NOT']
+
+def format_agg_mixture(weights) -> str:
+    parts = []
+    for i in range(weights.shape[0]):
+        w = float(weights[i])
+        if w > 1e-6:
+            parts.append(f"{w:.2f} {AGG_NAMES[i]}")
+    return " + ".join(parts) if parts else "∅"
+
+def aggregator_mixture_report(model: NousNet, X, max_samples: int = 1000, device=None) -> pd.DataFrame:
+    device = device or next(model.parameters()).device
+    n = min(len(X), max_samples)
+    acc = []
+    for i in range(n):
+        _, _, internals = model.forward_explain(X[i], device=device)
+        for key in [k for k in internals.keys() if k.startswith("block_")]:
+            aw = internals[key]['aggregator_weights']
+            if aw is None:
+                continue
+            acc.append(aw.cpu().numpy())
+    if not acc:
+        return pd.DataFrame(columns=["AND", "OR", "k-of-n", "NOT", "entropy"])
+    A = np.concatenate(acc, axis=0)
+    mean = A.mean(axis=0)
+    ent = (-A * np.clip(np.log(A + 1e-12), -50, 50)).sum(axis=1).mean()
+    cols = AGG_NAMES[:A.shape[1]]
+    return pd.DataFrame([dict(**{c: float(v) for c, v in zip(cols, mean)}, entropy=float(ent))])

nous-0.2.0/nous/explain/cf.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+import numpy as np
+import torch
+from typing import Optional, Sequence, List, Dict, Any
+from ..model import NousNet
+from .loo import rule_impact_df
+
+def suggest_rule_counterfactuals(
+    model: NousNet, x_sample, feature_names: Sequence[str], class_names: Optional[Sequence[str]] = None,
+    target: str = "flip",              # 'flip' (classification), 'margin_drop', 'reg_delta'
+    target_value: Optional[float] = None,  # for margin_drop/reg_delta
+    y_scaler=None,
+    k_rules: int = 3, fact_target_level: float = 0.1, max_features: int = 2,
+    loo_mode: str = 'frozen', top_m_rules: int = 10, use_pre_norm: bool = False,
+    alphas: Sequence[float] = (0.5, 1.0, 1.5, 2.0),
+    device=None
+) -> List[Dict[str, Any]]:
+    """
+    Suggest counterfactual input deltas guided by influential rules using β-fact geometry.
+    Verifies suggested deltas by forward_explain.
+    """
+    device = device or next(model.parameters()).device
+    task = model.config['task_type']
+
+    base_probas, base_logits, base_internals = model.forward_explain(x_sample, device=device)
+    if task == "classification":
+        pred_idx = int(np.argmax(base_probas))
+        runner_up = int(np.argsort(base_logits)[-2]) if base_logits.size > 1 else pred_idx
+        base_margin = float(base_logits[pred_idx] - base_logits[runner_up])
+    else:
+        base_pred = float(base_logits[0])
+
+    imp = rule_impact_df(
+        model, x_sample, feature_names, class_names=class_names,
+        loo_mode=loo_mode, top_m_rules=top_m_rules, use_pre_norm=use_pre_norm
+    )
+    if imp.empty:
+        return []
+
+    if task == "classification":
+        margin_col = [c for c in imp.columns if c.startswith("Δmargin(")][0]
+        imp = imp.sort_values(by=margin_col, ascending=False)
+    else:
+        imp = imp.sort_values(by="Δprediction", ascending=False)
+    imp = imp.head(k_rules)
+
+    x = torch.tensor(x_sample, dtype=torch.float32, device=device).unsqueeze(0)
+    if model.calibrators is not None:
+        x_cal = torch.stack([calib(x[:, i]) for i, calib in enumerate(model.calibrators)], dim=1)
+    else:
+        x_cal = x
+    diff, k_vec, nu_vec, net_w = model.fact.compute_diff_and_params(x_cal)  # [1,F], [F], [F], [F,D]
+    facts_act = model.fact(x_cal).squeeze(0)
+
+    suggestions = []
+    for _, row in imp.iterrows():
+        b = int(row["block"]) - 1
+        r = int(row["rule"]) - 1
+        details = base_internals[f'block_{b}']
+        facts_used = details.get("facts_used", None)
+        if isinstance(facts_used, torch.Tensor):
+            facts_used = facts_used.cpu().numpy()
+        if facts_used is None or facts_used.shape[0] <= r:
+            continue
+        used = facts_used[r]
+        used = [int(used)] if np.ndim(used) == 0 else [int(u) for u in used.tolist()]
+
+        used_sorted = sorted(used, key=lambda fid: float(facts_act[fid].item()), reverse=True)[:max(1, min(len(used), 2))]
+
+        deltas: Dict[int, float] = {}
+        for fid in used_sorted:
+            y_now = float(facts_act[fid].item()) + 1e-12
+            kf = float(k_vec[fid].item())
+            nuf = float(nu_vec[fid].item())
+            diff_now = float(diff[0, fid].item())
+            w = net_w[fid].detach().clone()  # [D]
+
+            y_target = float(fact_target_level)
+            # Invert β: diff_target = (logit(y_target^(1/nu))) / k
+            diff_target = float(torch.logit(torch.tensor(y_target, device=device).pow(1.0/max(nuf,1e-6))))
+            diff_target = diff_target / max(kf, 1e-6)
+            delta_diff = diff_target - diff_now
+
+            w_np = w.cpu().numpy()
+            idxs = np.argsort(-np.abs(w_np))[:max_features]
+            w_sel = torch.zeros_like(w)
+            w_sel[idxs] = w[idxs]
+            denom = float(w_sel.pow(2).sum().item())
+            if denom < 1e-12:
+                continue
+            delta_x_cal = (delta_diff / denom) * w_sel  # minimal L2 shift in x̃
+
+            delta_x = delta_x_cal.clone()
+            if model.calibrators is not None:
+                for i in idxs:
+                    xi = x[0, i]
+                    slope_i = model.calibrators[i].local_slope(xi)
+                    delta_x[i] = delta_x_cal[i] / slope_i
+
+            for i in idxs:
+                deltas[i] = deltas.get(i, 0.0) + float(delta_x[i].item())
+
+        if not deltas:
+            continue
+
+        feat_deltas = sorted([(feature_names[i], d) for i, d in deltas.items()], key=lambda t: -abs(t[1]))
+        success = False
+        new_out = None
+        for a in alphas:
+            x_try = x.clone()
+            for i, d in deltas.items():
+                x_try[0, i] = x_try[0, i] + a * d
+            prob2, logit2, _ = model.forward_explain(x_try.squeeze(0).cpu().numpy(), device=device)
+            if task == "classification":
+                new_pred = int(np.argmax(prob2))
+                new_margin = float(logit2[pred_idx] - logit2[runner_up])
+                if target == "flip" and new_pred != pred_idx:
+                    success, new_out = True, {"pred": new_pred, "margin": new_margin}
+                    break
+                if target == "margin_drop" and target_value is not None and new_margin <= base_margin - float(target_value):
+                    success, new_out = True, {"pred": new_pred, "margin": new_margin}
+                    break
+            else:
+                new_pred = float(logit2[0])
+                if target == "reg_delta" and target_value is not None:
+                    if (new_pred - base_pred) <= float(target_value):
+                        success, new_out = True, {"pred": new_pred}
+                        break
+
+        suggestions.append({
+            "rule": (b+1, r+1),
+            "facts": [f"F{fid+1}" for fid in used_sorted],
+            "deltas": feat_deltas,
+            "verified": success,
+            "new_out": new_out
+        })
+    return suggestions

nous-0.2.0/nous/explain/facts_desc.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+from typing import Dict, Sequence
+from ..model import NousNet
+
+def render_fact_descriptions(model: NousNet, feature_names: Sequence[str], top_k_feats: int = 4, eps: float = 0.03) -> Dict[int, str]:
+    """
+    Create human-readable descriptions of base β-facts using (L-R) weights.
+    """
+    L, R, th, k, nu = model.fact.get_rule_parameters()
+    desc = {}
+    for fid in range(L.shape[0]):
+        net = L[fid] - R[fid]
+        pos = [(feature_names[i], net[i]) for i in range(len(net)) if net[i] > eps]
+        neg = [(feature_names[i], -net[i]) for i in range(len(net)) if net[i] < -eps]
+        pos = sorted(pos, key=lambda t: -abs(t[1]))[:top_k_feats]
+        neg = sorted(neg, key=lambda t: -abs(t[1]))[:top_k_feats]
+        pos_str = " + ".join([f"{w:.2f}·{n}" for n, w in pos]) if pos else "0"
+        neg_str = " + ".join([f"{w:.2f}·{n}" for n, w in neg]) if neg else "0"
+        base = f"β( [L−R](x̃) = ({pos_str}) − ({neg_str}) > {th[fid]:.2f}; k={k[fid]:.2f}, ν={nu[fid]:.2f} )"
+        if model.calibrators is not None:
+            base += "  where x̃ are calibrated features"
+        desc[fid] = base
+    return desc