Nous: A Neuro-Symbolic Library for Interpretable AI

Nous (Greek: νοῦς, “mind”) is a neuro-symbolic library for interpretable learning in PyTorch. Nous models are built from facts and rules, and explanations are derived from the model’s computation via intervention-style forward evaluation (not post-hoc gradients).

Design: features → facts → rules → prediction
Explanations: recompute forward passes under controlled rule/fact interventions

Installation

pip install nous

Optional extras:

pip install "nous[examples]"
pip install "nous[dev]"

Core Concepts (short)

Quick Start (SoftLogitAND)

SoftLogitAND is a strong default for tabular tasks when you want a clean rules-first structure.

import torch
import torch.nn as nn
from sklearn.preprocessing import StandardScaler
from torch.utils.data import DataLoader, TensorDataset

from nous import SoftLogitAND
from nous.training import train_model

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# X_train, y_train, X_val, y_val are numpy arrays
scaler = StandardScaler().fit(X_train)
Xtr = scaler.transform(X_train).astype("float32")
Xva = scaler.transform(X_val).astype("float32")

model = SoftLogitAND(
    input_dim=Xtr.shape[1],
    n_rules=256,
    n_thresh_per_feat=4,
    tau=0.7,
    use_negations=True,
)
model.init_from_data(Xtr)
model.to(device)

train_loader = DataLoader(
    TensorDataset(torch.tensor(Xtr), torch.tensor(y_train, dtype=torch.float32)),
    batch_size=512, shuffle=True
)
val_loader = DataLoader(
    TensorDataset(torch.tensor(Xva), torch.tensor(y_val, dtype=torch.float32)),
    batch_size=512, shuffle=False
)

train_model(
    model=model,
    train_loader=train_loader,
    val_loader=val_loader,
    criterion=nn.BCEWithLogitsLoss(),
    optimizer=torch.optim.AdamW(model.parameters(), lr=2e-3, weight_decay=1e-4),
    epochs=200,
    patience=25,
    device=device,
)

Model Zoo (high level)

Model Zoo: minimal interpretation example (global + local)

This is the “notebook-style” workflow, but kept small: train a zoo_v2 model, predict, then extract:

• global rules (global_rules_df)
• local contributions (local_contrib_df)
• text explanation (explain_prediction)
• optional export (export_global_rules)

import numpy as np
import torch
import torch.nn as nn
from sklearn.preprocessing import StandardScaler

from nous.zoo_v2 import EvidenceNet
from nous.explain.zoo_v2 import global_rules_df, local_contrib_df, explain_prediction, export_global_rules

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")

# Assume:
#   X_train_raw: (N, D) float numpy
#   y_train: (N,) in {0,1}
#   feature_names: list[str] length D

# 1) Scale for training (common for zoo_v2)
scaler = StandardScaler().fit(X_train_raw)
X_train = scaler.transform(X_train_raw).astype("float32")

# 2) Train a zoo_v2 model (binary classification => output_dim=1)
model = EvidenceNet(input_dim=X_train.shape[1], n_rules=128, init_kappa=6.0, beta=6.0, output_dim=1).to(device)
opt = torch.optim.AdamW(model.parameters(), lr=2e-3, weight_decay=1e-4)
loss_fn = nn.BCEWithLogitsLoss()

Xt = torch.tensor(X_train, device=device)
yt = torch.tensor(y_train, dtype=torch.float32, device=device)

model.train()
for _ in range(100):
    opt.zero_grad(set_to_none=True)
    logits = model(Xt).view(-1)
    loss = loss_fn(logits, yt)
    loss.backward()
    opt.step()

# 3) Predict (probability)
model.eval()
with torch.no_grad():
    p0 = torch.sigmoid(model(Xt[:1]).view(-1)).item()
print("pred_proba(x0):", p0)

# 4) Interpret
# For explain helpers: pass X_ref and x in the *pre-scaler* space if you provide scaler=...
X_ref = X_train_raw[:5000]
x0_raw = X_train_raw[0]

df_g = global_rules_df(
    model,
    feature_names,
    scaler=scaler,          # makes thresholds readable in the raw/original feature space
    X_ref=X_ref,
    readability="clinical",
    top_rules=12,
    top_feats=4,
    n_trees=6,              # used by forest-style models; safe to keep for others
)
print(df_g.head())

df_l, meta = local_contrib_df(
    model,
    x0_raw,                 # raw x (pre-scaler) because scaler=... is provided
    feature_names,
    scaler=scaler,
    X_ref=X_ref,
    readability="clinical",
    top_rules=12,
)
print("local meta:", meta)
print(df_l.head())

print(explain_prediction(
    model, x0_raw, feature_names,
    scaler=scaler, X_ref=X_ref,
    readability="clinical", top_rules=8
))

# 5) Optional: export global rules
export_global_rules(model, feature_names, path="rules.txt",  format="txt",  scaler=scaler, X_ref=X_ref, readability="clinical", top_rules=30, top_feats=4, n_trees=6)
export_global_rules(model, feature_names, path="rules.json", format="json", scaler=scaler, X_ref=X_ref, readability="clinical", top_rules=30, top_feats=4, n_trees=6)

Real‑world Benchmarks (5‑Fold CV)

These are small reference runs (mean ± std across folds) comparing selected Nous (torch) models with XGBoost and EBM. They are provided as sanity/reference points.

QSAR Fish Toxicity (Regression)

Concrete Compressive Strength (Regression)

Myocardial Infarction Complications (Multiclass)

Citation

@software{tlupov2025nous,
  author = {Tlupov, Islam},
  title = {Nous: A Neuro-Symbolic Library for Interpretable AI},
  url = {https://github.com/EmotionEngineer/nous},
  year = {2025}
}

License: MIT