nous 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

nous/training/schedulers.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+from ..rules.sparse import SparseRuleLayer
+
+def make_sparse_regression_hook(
+    base_lambda: float = 3e-4, warmup: int = 40, ramp: int = 80,
+    temp_start: float = 0.60, temp_end: float = 0.25, temp_epochs: int = 200,
+    disable_topk: bool = True
+):
+    """
+    Return an after-epoch scheduler hook for sparse regression:
+      - L0 penalty ramp,
+      - Hard-Concrete temperature schedule,
+      - Disable top-k gating to preserve gradients.
+    """
+    def hook(model, epoch: int):
+        # 1) L0 schedule
+        l0_factor = 0.0 if epoch < warmup else min(1.0, (epoch - warmup) / max(1, ramp))
+        for blk in model.blocks:
+            if isinstance(blk, SparseRuleLayer):
+                blk.l0_lambda = base_lambda * l0_factor
+
+        # 2) HC temperature schedule
+        alpha = min(1.0, epoch / max(1, temp_epochs))
+        t = temp_start * (1 - alpha) + temp_end * alpha
+        for blk in model.blocks:
+            if isinstance(blk, SparseRuleLayer):
+                blk.hard_concrete.temperature = t
+
+        # 3) Disable top-k (for regression)
+        if disable_topk:
+            for blk in model.blocks:
+                if hasattr(blk, "top_k_rules"):
+                    blk.top_k_rules = blk.num_rules
+    return hook

nous/training/train.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+import inspect
+from typing import Callable, Optional, Dict
+
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+
+def train_model(
+    model: nn.Module,
+    train_loader: DataLoader,
+    val_loader: DataLoader,
+    criterion: nn.Module,
+    optimizer: torch.optim.Optimizer,
+    epochs: int,
+    patience: int,
+    device,
+    after_epoch_hook: Optional[Callable[..., None]] = None,
+    # Progress controls
+    verbose: int = 1,
+    log_every: int = 10,
+    use_tqdm: bool = False,
+    print_l0: bool = True,
+) -> float:
+    """
+    Train with early stopping. Adds L0 loss (if model exposes compute_total_l0_loss) and gradient clipping.
+
+    Progress
+    - verbose >= 1 prints epoch-level logs every `log_every` epochs, on improvement, and on first/last epoch.
+    - use_tqdm shows a progress bar over epochs with train/val (and L0) in the postfix.
+    - after_epoch_hook can be:
+        (model, epoch)                      -- legacy signature
+        (model, epoch, metrics_dict)        -- extended signature
+      where metrics_dict contains:
+        {epoch, train_loss, val_loss, l0_loss, improved}.
+    """
+    model.to(device)
+    best_val_loss = float('inf')
+    epochs_no_improve = 0
+    best_model_state = None
+
+    # Epoch iterator (optionally tqdm)
+    if use_tqdm:
+        try:
+            from tqdm.auto import tqdm as _tqdm
+            epoch_iter = _tqdm(range(epochs), leave=False, desc="Training")
+        except Exception:
+            epoch_iter = range(epochs)
+    else:
+        epoch_iter = range(epochs)
+
+    for epoch in epoch_iter:
+        # -------------------------
+        # Train
+        # -------------------------
+        model.train()
+        total_train_loss = 0.0
+        total_l0_loss = 0.0
+        steps = 0
+
+        for X_batch, y_batch in train_loader:
+            X_batch, y_batch = X_batch.to(device), y_batch.to(device)
+            optimizer.zero_grad()
+
+            outputs = model(X_batch)
+            if isinstance(criterion, nn.CrossEntropyLoss) or (outputs.ndim == 2 and outputs.size(-1) > 1):
+                target = y_batch.long()    # classification
+            else:
+                target = y_batch.float()   # regression
+            loss = criterion(outputs, target)
+
+            l0_loss = getattr(model, "compute_total_l0_loss", lambda: torch.tensor(0.0, device=device))()
+            total_loss = loss + l0_loss
+
+            total_loss.backward()
+            nn.utils.clip_grad_norm_(model.parameters(), max_norm=0.5)
+            optimizer.step()
+
+            total_train_loss += float(loss.item())
+            total_l0_loss += float(l0_loss.item()) if isinstance(l0_loss, torch.Tensor) else float(l0_loss)
+            steps += 1
+
+        avg_train_loss = total_train_loss / max(1, steps)
+        avg_l0_loss = total_l0_loss / max(1, steps)
+
+        # -------------------------
+        # Validate
+        # -------------------------
+        model.eval()
+        total_val_loss = 0.0
+        with torch.no_grad():
+            for X_batch, y_batch in val_loader:
+                X_batch, y_batch = X_batch.to(device), y_batch.to(device)
+                outputs = model(X_batch)
+                if isinstance(criterion, nn.CrossEntropyLoss) or (outputs.ndim == 2 and outputs.size(-1) > 1):
+                    target = y_batch.long()
+                else:
+                    target = y_batch.float()
+                vloss = criterion(outputs, target)
+                total_val_loss += float(vloss.item())
+        avg_val_loss = total_val_loss / max(1, len(val_loader))
+
+        improved = avg_val_loss < (best_val_loss - 1e-6)
+
+        # -------------------------
+        # Progress reporting
+        # -------------------------
+        if use_tqdm and hasattr(epoch_iter, "set_postfix"):
+            postfix: Dict[str, str] = {"train": f"{avg_train_loss:.4f}", "val": f"{avg_val_loss:.4f}"}
+            if print_l0:
+                postfix["l0"] = f"{avg_l0_loss:.4f}"
+            try:
+                epoch_iter.set_postfix(postfix)  # type: ignore[attr-defined]
+            except Exception:
+                pass
+
+        if verbose >= 1:
+            should_log = (
+                epoch == 0
+                or (epoch + 1 == epochs)
+                or improved
+                or ((epoch + 1) % max(1, log_every) == 0)
+            )
+            if should_log:
+                msg = f"Epoch [{epoch+1}/{epochs}] train={avg_train_loss:.4f} val={avg_val_loss:.4f}"
+                if print_l0:
+                    msg += f" l0={avg_l0_loss:.4f}"
+                if improved:
+                    msg += " (*)"
+                print(msg)
+
+        # -------------------------
+        # Hook (backward compatible)
+        # -------------------------
+        if after_epoch_hook is not None:
+            metrics: Dict[str, float | int | bool] = dict(
+                epoch=epoch,
+                train_loss=avg_train_loss,
+                val_loss=avg_val_loss,
+                l0_loss=avg_l0_loss,
+                improved=improved,
+            )
+            try:
+                sig = inspect.signature(after_epoch_hook)
+                if len(sig.parameters) >= 3:
+                    after_epoch_hook(model, epoch, metrics)  # extended
+                else:
+                    after_epoch_hook(model, epoch)           # legacy
+            except Exception:
+                # Fallback to legacy on any inspection/runtime error
+                try:
+                    after_epoch_hook(model, epoch)
+                except Exception:
+                    pass
+
+        # -------------------------
+        # Early stopping
+        # -------------------------
+        if improved:
+            best_val_loss = avg_val_loss
+            epochs_no_improve = 0
+            best_model_state = {k: v.cpu().clone() for k, v in model.state_dict().items()}
+        else:
+            epochs_no_improve += 1
+            if epochs_no_improve >= patience:
+                if verbose >= 1:
+                    print(f"Early stopping at epoch {epoch+1} (best val={best_val_loss:.4f})")
+                break
+
+    # Restore best
+    if best_model_state:
+        model.load_state_dict(best_model_state)
+        model.to(device)
+        if verbose >= 1:
+            print(f"Restored best model (val={best_val_loss:.4f})")
+
+    return best_val_loss

nous/types.py

@@ -0,0 +1,4 @@
+from typing import Any
+
+TensorLike = Any
+NDArrayLike = Any

nous/utils/__init__.py

@@ -0,0 +1,3 @@
+from .seed import set_global_seed
+
+__all__ = ["set_global_seed"]

nous/utils/metrics.py

@@ -0,0 +1,2 @@
+from __future__ import annotations
+# Placeholder for future metric utilities

nous/utils/seed.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+import random
+import numpy as np
+import torch
+
+def set_global_seed(seed: int = 42) -> None:
+    """
+    Set seeds for Python, NumPy, and PyTorch (CPU/CUDA).
+    """
+    random.seed(seed)
+    np.random.seed(seed)
+    torch.manual_seed(seed)
+    torch.cuda.manual_seed_all(seed)

nous/version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

nous-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,41 @@
+nous/__init__.py,sha256=l2QKn4xsdUxcOmbUuiTS79dSqGGa9O5c-lkpKkCw_WI,2724
+nous/facts.py,sha256=GrCinW97CCcBWQ-VfajE44vlKOCR3gijC-l36d4A59w,4843
+nous/model.py,sha256=DjT0PnOuBzJQ2ueOfeQENYLg_SVIG5AqOGzYWlk4z3Y,8910
+nous/prototypes.py,sha256=FWF3VGSAYsXh-3qNwRT_3nZdIk8A5JYK5gKBlccrxA0,1873
+nous/types.py,sha256=RclD7jN8lTT_AqLtTZsoPjsd9HysVZLBz_OaAUzM4n8,61
+nous/version.py,sha256=1KhrBItVjTCR-Sumh0o09b_aKrjTTcJrpTBh5GBw6Lk,21
+nous/data/__init__.py,sha256=q2AgrdHg1zcE5dyaHw13sLFJI2DNpEBaTMHGByNYDFM,143
+nous/data/california.py,sha256=jauBm7Hwivohp79cK9lbPGtjwvnrdrUDZoHlc591Nvc,1297
+nous/data/wine.py,sha256=WvsXsfX_AnukpkboeMye3b2xceBy6Di528Y5HP-AmuY,1252
+nous/explain/__init__.py,sha256=NWpPGMgX4DtGEf_oj6Gbbjh9_k2XD1N7zuojy3SwPbk,957
+nous/explain/aggregator.py,sha256=VM3U8zvpwCN_fyN5_geglL6rCshGFblkpiJnXvBuce4,1297
+nous/explain/cf.py,sha256=iidWOC92ZSNwcoGDCinx85ZmOJntLjp_bBNi7PsrTbw,5878
+nous/explain/facts_desc.py,sha256=BAPkLSq0uLyTaSZFDXmTTS1onB_ju_f-R_I5N3O7Npg,1178
+nous/explain/fidelity.py,sha256=VNUUJqa0mfeWCozc_l-L82DcySwk4Hl171_hnUkpjbk,2401
+nous/explain/generate.py,sha256=HMnhwfaFYKdZNcXYKindnGpIquU0IM79OWM7tbF5yzA,3683
+nous/explain/global_book.py,sha256=i2SeJ4cB5uIZsSLBZgW2Tkv60Tr8M_aAuakeA1TrElU,2185
+nous/explain/loo.py,sha256=fw6aXhMj9jkFyWviiGulU7Ymt6NFAcpYFl5JwHDbXBE,5768
+nous/explain/mse.py,sha256=VfABHZqrVEPOpTxKtfJ7E8Cw5U3VzADC_RIpKD1UMPM,3769
+nous/explain/pruning.py,sha256=GHFIAjaAtCmCsl7hsrP7ALBY5lZ_Rml107bjRCFiSQs,4899
+nous/explain/stability.py,sha256=CHW7TTvySPfoCz_VGN578zKVi6ChvCNP9iajDQQppNk,1844
+nous/explain/traces.py,sha256=SO_PwkMBIJLWNqmK8WRCD8rBJ5s58QO1hUviEYZd3Ps,11569
+nous/explain/utils.py,sha256=6u_dlUeRA9p4IA6yKjAkuUfE2GFMOH9ZfFnqRiVmeA0,564
+nous/export/__init__.py,sha256=lKmcutGQ9xt3th61KEZyttBwnYBktxYfPJPRXO8olys,257
+nous/export/numpy_infer.py,sha256=Oh2CtNqMlxLWhxJOGfp2CXeFqT94eLMi8OfTBa77oyk,15573
+nous/rules/__init__.py,sha256=6PkHHNLuXs9bJIKSWV6mo6I76HBOib7Vu_uwBxBX0A0,259
+nous/rules/blocks.py,sha256=MsU7t93kY_HVRAIODLhQOFdtIoyL9aw1Pe-yuV2wPrw,2569
+nous/rules/fixed.py,sha256=0ABVPmhb5b6CX4Iy2-HJt3W3U9-y5zLRzcsJY40Xpoc,985
+nous/rules/softmax.py,sha256=K8_VJHmRcCTcyitouL_eagWNk_k8AzsuxdYuHDCt5yA,4142
+nous/rules/sparse.py,sha256=jc2GdHT7uQ0CqXOdMw56_EmtDQ_KQiB62SHDRFlvgj4,6249
+nous/training/__init__.py,sha256=CrFOoYJhOGVk6LO3wVEx9TmsxWkwXw3I5Evcs_XZ5t8,259
+nous/training/evaluation.py,sha256=3RiQW74WIO3KYXvspB8WNj2cWbSivHp-9EYvy2xcIc4,2019
+nous/training/schedulers.py,sha256=hZgvxQ0ht5ks76dNRYbBsE1t_20gqWM7LhYSfmuyiRo,1276
+nous/training/train.py,sha256=znaKYO21vkexaYxxBQY8g0ZvRx8MUac95I2AbY-xwKQ,6331
+nous/utils/__init__.py,sha256=OEkCOgzF-mJ-jf_jeWebPhSMa0BLdIalFPCXTltQe-c,64
+nous/utils/metrics.py,sha256=IF9uwjnniFP7r2G3GK9TiX7_CycTh4Jvb1I_-bPgrXg,76
+nous/utils/seed.py,sha256=h0w9y5ExThWDmZjHI79AsQkJrFbFzPfco1OBIs2nNGI,311
+nous-0.2.0.dist-info/licenses/LICENSE,sha256=07nO-ZFpy_s_msfks8VsONyV2cBBggqsEQD2h5sdVRo,1069
+nous-0.2.0.dist-info/METADATA,sha256=u03tWgz3y7ClPSFRzurCAMMlUhPytglX6SEOTjl8w3k,6612
+nous-0.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nous-0.2.0.dist-info/top_level.txt,sha256=yUcst4OAspsyKhX0y5ENzFkJKzR_gislA5MykV1pVbk,5
+nous-0.2.0.dist-info/RECORD,,

nous/causal.py

@@ -1,63 +0,0 @@
-# nous/causal.py
-import torch
-import torch.nn as nn
-from typing import Literal
-from .models import NousNet
-
-def find_counterfactual(
-    model: NousNet,
-    x_sample: torch.Tensor,
-    target_output: float,
-    task: Literal['regression', 'classification'] = 'classification',
-    lr: float = 0.01,
-    steps: int = 200,
-    l1_lambda: float = 0.5
-) -> dict:
-    """
-    Finds a minimal change to the input to achieve a target output.
-    
-    Args:
-        model (NousNet): The trained model.
-        x_sample (torch.Tensor): The original input tensor.
-        target_output (float): For classification, the desired probability (e.g., 0.8). 
-                               For regression, the desired absolute value (e.g., 150.0).
-        task (Literal['regression', 'classification']): The type of task.
-        lr, steps, l1_lambda: Optimization parameters.
-
-    Returns:
-        dict: A dictionary containing the counterfactual sample and a list of changes.
-    """
-    if task == 'classification':
-        if not (0 < target_output < 1): 
-            raise ValueError("Target for classification must be a probability between 0 and 1.")
-        if model.output_head.out_features > 1: 
-            raise NotImplementedError("Counterfactual analysis for multi-class models is not yet supported.")
-        # Calculate target in logit space for numerical stability
-        target = torch.log(torch.tensor(target_output) / (1 - torch.tensor(target_output)))
-    else: # regression
-        target = torch.tensor(target_output, dtype=torch.float32)
-
-    x_sample = x_sample.clone().detach()
-    delta = torch.zeros_like(x_sample, requires_grad=True)
-    optimizer = torch.optim.Adam([delta], lr=lr)
-    
-    for _ in range(steps):
-        optimizer.zero_grad()
-        x_perturbed = x_sample + delta
-        prediction = model(x_perturbed.unsqueeze(0)).squeeze()
-        
-        target_loss = (prediction - target)**2
-        l1_loss = torch.norm(delta, p=1)
-        total_loss = target_loss + l1_lambda * l1_loss
-        
-        # This will now only be called for scalar losses, as multi-class is caught above
-        total_loss.backward()
-        optimizer.step()
-
-    final_x = x_sample + delta.detach()
-    changes = []
-    for i, name in enumerate(model.feature_names):
-        if not torch.isclose(x_sample[i], final_x[i], atol=1e-3):
-            changes.append((name, x_sample[i].item(), final_x[i].item()))
-            
-    return {"counterfactual_x": final_x, "changes": changes}

nous/interpret.py

@@ -1,111 +0,0 @@
-# nous/interpret.py
-import torch
-import pandas as pd
-import matplotlib.pyplot as plt
-import seaborn as sns
-import networkx as nx
-from .models import NousNet
-from .layers import LearnedAtomicFactLayer, BetaFactLayer
-
-def trace_decision_graph(model: NousNet, x_sample: torch.Tensor) -> dict:
-    """Traces the full reasoning path for a single sample."""
-    if x_sample.dim() == 1: x_sample = x_sample.unsqueeze(0)
-    model.eval()
-    graph_data = {"trace": {}}
-    with torch.no_grad():
-        facts = model.atomic_fact_layer(x_sample).squeeze(0)
-        graph_data['trace']['Atomic Facts'] = {name: {"value": facts[i].item()} for i, name in enumerate(model.atomic_fact_layer.fact_names)}
-        h = facts.unsqueeze(0)
-        for i, block in enumerate(model.nous_blocks):
-            h, concepts, rule_activations = block(h)
-            concepts, rule_activations = concepts.squeeze(0), rule_activations.squeeze(0)
-            graph_data['trace'][f'Rules L{i}'] = {name: {"value": rule_activations[j].item()} for j, name in enumerate(block.rule_layer.rule_names)}
-            graph_data['trace'][f'Concepts L{i}'] = {name: {"value": concepts[j].item()} for j, name in enumerate(block.concept_names)}
-    return graph_data
-
-def explain_fact(model: NousNet, fact_name: str) -> pd.DataFrame:
-    """Provides a detailed breakdown of a single learned fact, showing feature weights."""
-    fact_layer = model.atomic_fact_layer
-    if not isinstance(fact_layer, LearnedAtomicFactLayer):
-        raise TypeError("explain_fact is only applicable to 'beta' or 'sigmoid' fact layers.")
-    try:
-        fact_index = fact_layer.fact_names.index(fact_name)
-    except ValueError:
-        raise ValueError(f"Fact '{fact_name}' not found.")
-    
-    with torch.no_grad():
-        w_left, w_right = fact_layer.projection_left.weight[fact_index], fact_layer.projection_right.weight[fact_index]
-        threshold = fact_layer.thresholds[fact_index]
-    df = pd.DataFrame({
-        "feature": model.feature_names,
-        "left_weight": w_left.cpu().detach().numpy(),
-        "right_weight": w_right.cpu().detach().numpy(),
-    })
-    df['net_effect'] = df['left_weight'] - df['right_weight']
-    print(f"Explanation for fact '{fact_name}':")
-    print(f"Fact is TRUE when: (Sum(left_weight * feat) - Sum(right_weight * feat)) > {threshold.item():.3f}")
-    return df.sort_values(by='net_effect', key=abs, ascending=False)
-
-def plot_fact_activation_function(model: NousNet, fact_name: str, x_range=(-3, 3), n_points=200):
-    """Visualizes the learned activation function for a single learned fact."""
-    fact_layer = model.atomic_fact_layer
-    if not isinstance(fact_layer, LearnedAtomicFactLayer):
-        raise TypeError("This function is only for 'beta' or 'sigmoid' fact layers.")
-    try:
-        fact_index = fact_layer.fact_names.index(fact_name)
-    except ValueError:
-        raise ValueError(f"Fact '{fact_name}' not found.")
-        
-    diff_range = torch.linspace(x_range[0], x_range[1], n_points)
-    
-    with torch.no_grad():
-        if isinstance(fact_layer, BetaFactLayer):
-            k = torch.nn.functional.softplus(fact_layer.k_raw[fact_index]) + 1e-4
-            nu = torch.nn.functional.softplus(fact_layer.nu_raw[fact_index]) + 1e-4
-            activations = (1 + torch.exp(-k * diff_range))**(-nu)
-            label = f'Learned Beta-like (k={k:.2f}, ν={nu:.2f})'
-        else: # SigmoidFactLayer
-            steepness = torch.nn.functional.softplus(fact_layer.steepness[fact_index]) + 1e-4
-            activations = torch.sigmoid(steepness * diff_range)
-            label = f'Learned Sigmoid (steepness={steepness:.2f})'
-            
-    plt.figure(figsize=(8, 5))
-    plt.plot(diff_range.numpy(), activations.numpy(), label=label, linewidth=2.5)
-    plt.plot(diff_range.numpy(), torch.sigmoid(diff_range).numpy(), label='Standard Sigmoid', linestyle='--', color='gray')
-    plt.title(f"Activation Function for Fact:\n'{fact_name}'")
-    plt.xlabel("Difference Value (Left Projection - Right Projection - Threshold)")
-    plt.ylabel("Fact Activation (Truth Value)")
-    plt.legend(); plt.grid(True, linestyle=':'); plt.ylim(-0.05, 1.05); plt.show()
-
-def plot_final_layer_contributions(model: NousNet, x_sample: torch.Tensor):
-    """Calculates and plots which high-level concepts most influenced the final prediction."""
-    if x_sample.dim() == 1: x_sample = x_sample.unsqueeze(0)
-    model.eval()
-    with torch.no_grad():
-        h = model.atomic_fact_layer(x_sample)
-        for block in model.nous_blocks: h, _, _ = block(h)
-        final_activations = h.squeeze(0)
-        
-        output_dim = model.output_head.out_features
-        weights = model.output_head.weight.squeeze(0)
-        title = "Top Final Layer Concept Contributions"
-        
-        if output_dim > 1:
-            predicted_class = model.output_head(h).argmax().item()
-            weights = model.output_head.weight[predicted_class]
-            title += f" for Predicted Class {predicted_class}"
-            
-    contributions = final_activations * weights
-    concept_names = model.nous_blocks[-1].concept_names
-    
-    df = pd.DataFrame({'concept': concept_names, 'contribution': contributions.cpu().detach().numpy()})
-    df = df.sort_values('contribution', key=abs, ascending=False).head(15)
-    
-    plt.figure(figsize=(10, 6)); 
-    colors = ['#5fba7d' if c > 0 else '#d65f5f' for c in df['contribution']]
-    sns.barplot(x='contribution', y='concept', data=df, palette=colors, dodge=False)
-    plt.title(title); plt.xlabel("Contribution (Activation * Weight)"); plt.ylabel("Final Layer Concept"); plt.show()
-
-def plot_logic_graph(*args, **kwargs):
-    print("Graph visualization is planned for a future release.")
-    pass