nous 0.3.0

Nous: A Neuro-Symbolic Library for Interpretable AI

Nous — A Neuro-Symbolic Library for Interpretable AI

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

# 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.