nsx-ai 1.0.2

Neuro-Symbolic AI Framework with Agentic Capabilities

---

NSX-AI

Give your Neural Networks "Common Sense".

Deep Learning is amazing at seeing (recognizing a cat, reading handwriting), but it's terrible at thinking (following rules, understanding relationships).

NSX-AI fixes this. It is a bridge that connects PyTorch with Symbolic Logic.

• It lets you train models using Rules instead of just labeled data.
• It stops your AI from making "stupid" mistakes (Hallucinations/Safety violations).
• It allows you to talk to your model in Plain English to define logic.

It's fast, scalable, and ready for messy real-world data.

---

📦 Installation

pip install nsx-ai

---

⚡ Quick Start

If you know what Neuro-Symbolic AI is, here is how you use NSX in 30 seconds.

Goal: Train a network to learn that "If digit is Zero, it implies it is Even" without providing labels.

import torch
import nsx.nsai as ns

# 1. Define Logic Primitives
x = ns.Variable("x")
IsZero = ns.Predicate("IsZero", 1) # Unary Predicate
IsEven = ns.Predicate("IsEven", 1)

# 2. Define the Rule: Zero -> Even
rule = IsEven(x) << IsZero(x)

# 3. Connect to PyTorch
# 'net' is your standard torch.nn.Module
model = ns.NeuroSymbolicModel(net)
model.register(IsZero, output_index=0)
model.register(IsEven, output_index=1)

# 4. Train
# SemanticLoss minimizes rule violations
criterion = ns.SemanticLoss(model.concept_map)
loss = criterion([rule], data_binding={x: images}) 
loss.backward()

---

🌍 Real-World Use Cases

Why do you need this? Because pure Deep Learning fails in these scenarios.

🏥 Case 1: Healthcare & Safety Compliance

The Problem: You are building an AI to prescribe medicines. A standard Neural Network might look at patient history and predict "High Dose" for a Child just because it saw a similar pattern in an adult. This is dangerous.

Why Normal AI Fails: It learns correlations, not safety rules.

The NSX Solution: You inject a Hard Constraint (Logic) into the training.

# Logic: If Patient is a Child, do NOT prescribe Adult Meds.
# ~ means NOT
rule_safety = ~PrescribeAdultMeds(x) << IsChild(x)

# Result:
# Even if the Neural Net "thinks" (99% prob) that the meds are okay,
# the Logic Layer forces the gradient down, teaching the model:
# "No matter what, this is illegal."

✅ Benefit: Guaranteed Safety Guardrails in critical systems.

---

💳 Case 2: Financial Fraud (Relational Logic)

The Problem: You want to detect money laundering. A standard model looks at one transaction at a time. It sees "User A sent $500". Looks normal. It sees "User B sent $500". Looks normal. It misses the fact that A sent to B, and B sent back to A (Circular Trading).

Why Normal AI Fails: It treats data points as isolated islands.

The NSX Solution: NSX supports Relational Logic ($O(N^2)$ Broadcasting). It looks at pairs of data.

# x and y are two different transactions
IsFraud(x) << (Transfer(x, y) & Transfer(y, x) & HighAmount(x))

# Result:
# The model learns to look at the RELATIONSHIP between transaction x and y.
# It detects the cycle that a simple classifier would miss.

✅ Benefit: Detect complex patterns like Circular Trading or Social Graph anomalies.

---

🏗️ Case 3: Industrial Safety (Zero-Shot Learning)

The Problem: You need to detect if workers are wearing safety gear. You have 10,000 site images but zero labels. You don't have time to manually draw boxes around helmets for weeks.

Why Normal AI Fails: No Labels = No Training.

The NSX Solution: You define what "Safe" means using logic, and let the model figure out the rest.

# You don't need 'Safe' labels. You just tell the AI:
# "Safe means Helmet AND Vest."
IsSafe(x) << (HasHelmet(x) & HasVest(x))

# Result:
# The model aligns its internal representation of 'Helmet' and 'Vest'
# to maximize the truth of this rule. It labels itself!

✅ Benefit: Save months of data labeling time and cost.

Explore the full set of example here -

---

Agentic Capabilities

Don't want to write code? Talk to your data. NSX includes an Agent module powered by LLMs (OpenAI/DeepSeek/etc).

from nsx.nsai.agent import LogicTranslator, get_client

# 1. Connect Agent
client = get_client("gpt-4o")
translator = LogicTranslator(client)

# 2. Speak Logic
rule = translator.text_to_rules(
    "A transaction is suspicious if it happens at night and is from a foreign IP.",
    predicates=[IsSuspicious, IsNight, IsForeign]
)

print(rule[0])
# Output: IsSuspicious(x) :- IsNight(x) & IsForeign(x)

🕵️‍♂️ Automated Rule Discovery

New to a dataset? Don't know what rules to write? Let the Agent discover logic for you.

from nsx.nsai.agent import RuleMiner

miner = RuleMiner(client)

# Give it a description of your data
suggestions = miner.propose_rules(
    data_description="Credit card transactions with columns: Amount, Location, Time.",
    predicates=[IsFraud, HighAmount, ForeignLoc]
)

print(suggestions[0])
# Output Hypothesis: IsFraud(x) :- HighAmount(x) & ForeignLoc(x)

🛡️ Hallucination Guardrails

Building a Chatbot? Ensure it doesn't lie or violate safety policies. NSX can act as a Logic Firewall for LLM outputs.

from nsx.nsai.agent import LogicGuard

guard = LogicGuard(client)

# Define Truth
hard_rule = IsSafe(x) << HasHelmet(x)

# Check AI response
ai_response = "The worker is safe because he is wearing a cap."
check = guard.verify(ai_response, rules=[hard_rule])

print(check['is_safe']) 
# Output: False (Violation: Cap is not a Helmet)

Explore docs for more!

---

⚙️ Advanced Features

• Log-Space Arithmetic: We use LogProductTNorms to ensure gradients don't vanish even in deep logic trees.
• Vectorized Compiler: Logic rules are compiled into a static Computation Graph (nn.Module) for maximum GPU speed.
• Auto-Broadcasting: Handles single inputs vs matrix inputs automatically.

---

📄 License

MIT License. Free for Research and Commercial Use.

---

Built for the future of Hybrid AI.