StateSet NSR - Neuro-Symbolic Reasoning Framework

A state-of-the-art hybrid AI framework in Rust that combines neural network pattern recognition with symbolic logical reasoning for robust, explainable AI systems.

Research-grade neuro-symbolic AI: Implements ICLR 2024 NSR architecture with advanced features including program synthesis, MCTS-based abduction, Graph-of-Thoughts reasoning, Vector Symbolic Architecture, and compositional generalization.

Table of Contents

• Overview
• Architecture
• The Core NSR Feedback Loop
• Installation
• Quick Start
• API Reference
• Advanced Features
• Examples
• Documentation
• Benchmarks
• Contributing
• License

Overview

StateSet NSR implements a two-tier Neural-Symbolic Reasoning architecture:

Tier 1: NSR Engine (Production)

Traditional hybrid reasoning engine combining symbolic and neural approaches:

• 5 Reasoning Strategies: SymbolicFirst, NeuralFirst, HybridWeighted, Cascading, Ensemble
• Knowledge Graph: Entity-relation-entity triples with rule-based inference
• LLM Integration: OpenAI, Anthropic, Local/Ollama providers
• REST API: Production-ready Axum-based async API

Tier 2: NSR Machine (Research/ICLR 2024)

State-of-the-art neuro-symbolic machine with cutting-edge ML features:

• Grounded Symbol System (GSS): Core representation from ICLR 2024
• Program Synthesis: Functional programs for semantic computation
• 10+ Advanced Modules: MCTS, VSA, Graph-of-Thoughts, Metacognition, and more

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        StateSet NSR Framework                            │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                    NSR Engine (Production)                        │    │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │    │
│  │  │Neural Layer  │  │Symbolic Layer│  │ Logic Engine │           │    │
│  │  │• LLM Clients │  │• Facts/Rules │  │• Unification │           │    │
│  │  │• Embeddings  │  │• Knowledge   │  │• Resolution  │           │    │
│  │  │• Inference   │  │• Constraints │  │• Chaining    │           │    │
│  │  └──────────────┘  └──────────────┘  └──────────────┘           │    │
│  │                          │                                        │    │
│  │           5 Reasoning Strategies                                  │    │
│  │  SymbolicFirst │ NeuralFirst │ HybridWeighted │ Cascading │ Ensemble │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                 NSR Machine (Research/ICLR 2024)                  │    │
│  │  ┌────────────────────────────────────────────────────────────┐  │    │
│  │  │              Grounded Symbol System (GSS)                   │  │    │
│  │  │   Input (x) → Symbol (s) → Value (v) → Edges (e)           │  │    │
│  │  └────────────────────────────────────────────────────────────┘  │    │
│  │                              │                                    │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐           │    │
│  │  │Perception│ │ Parser   │ │Synthesis │ │ Learning │           │    │
│  │  │ Module   │ │(Dep Tree)│ │(Programs)│ │(Ded-Abd) │           │    │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘           │    │
│  │                              │                                    │    │
│  │  ┌─────────────────────────────────────────────────────────────┐│    │
│  │  │              Advanced Modules (10+)                          ││    │
│  │  │ • Graph-of-Thoughts  • VSA (Hyperdimensional)               ││    │
│  │  │ • MCTS Abduction     • Metacognition                        ││    │
│  │  │ • Library Learning   • Continual Learning                   ││    │
│  │  │ • Differentiable Logic • Probabilistic Inference            ││    │
│  │  │ • Inference Scaling  • Explainability                       ││    │
│  │  └─────────────────────────────────────────────────────────────┘│    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │                         REST API (Axum)                           │    │
│  │  /api/v1/reason │ /api/v1/entities │ /api/v1/query │ /health     │    │
│  └─────────────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘

The Core NSR Feedback Loop

What makes this a true Neural-Symbolic Recursive AI (not just neural + symbolic bolted together) is the feedback loop where each component improves the others through recursive self-modification:

┌─────────────────────────────────────────────────────────────────────────┐
│                    NSR RECURSIVE FEEDBACK LOOP                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌─────────────┐                                                       │
│   │   INPUT     │  Raw data: text, images, numbers                      │
│   └──────┬──────┘                                                       │
│          │                                                              │
│          ▼                                                              │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              NEURAL PERCEPTION                               │      │
│   │                                                              │      │
│   │   p(s|x; θ_p) - Maps raw input to symbol probabilities      │      │
│   │   "sees fur, whiskers, pointy ears, hears meow"             │      │
│   └──────┬──────────────────────────────────────────────────────┘      │
│          │ symbols: [fur, whiskers, meow]                               │
│          ▼                                                              │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              DEPENDENCY PARSER                               │      │
│   │                                                              │      │
│   │   p(e|s; θ_s) - Builds syntactic structure                  │      │
│   │   Creates tree: meow(fur, whiskers)                         │      │
│   └──────┬──────────────────────────────────────────────────────┘      │
│          │ edges: [(meow→fur), (meow→whiskers)]                         │
│          ▼                                                              │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              SYMBOLIC EVALUATOR                              │      │
│   │                                                              │      │
│   │   p(v|e,s; θ_l) - Executes functional programs              │      │
│   │   Rule: IF meow THEN CAT                                    │      │
│   │   Output: "CAT"                                             │      │
│   └──────┬──────────────────────────────────────────────────────┘      │
│          │ output: CAT                                                  │
│          ▼                                                              │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              COMPARE TO TARGET                               │      │
│   │                                                              │      │
│   │   output == expected?                                       │      │
│   │   CAT == CAT? ✓ Success → Continue                         │      │
│   │   CAT != DOG? ✗ Error → Trigger ABDUCTION                  │      │
│   └──────┬──────────────────────────────────────────────────────┘      │
│          │                                                              │
│          ▼ (on error)                                                   │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │         ★ RECURSIVE ABDUCTION (The Key Innovation) ★        │      │
│   │                                                              │      │
│   │   Search for modifications that produce correct output:     │      │
│   │                                                              │      │
│   │   1. CHANGE SYMBOLS: Try different symbol assignments       │      │
│   │      "Maybe 'tailless' should map to CAT_VARIANT?"         │      │
│   │                                                              │      │
│   │   2. RESTRUCTURE EDGES: Try different parse trees           │      │
│   │      "Maybe meow should be the root, not fur?"             │      │
│   │                                                              │      │
│   │   3. UPDATE PROGRAMS: Modify semantic rules                 │      │
│   │      "Rule update: TAIL is no longer mandatory for CAT"    │      │
│   │                                                              │      │
│   │   Uses: MCTS, Beam Search, or Gradient Descent             │      │
│   └──────┬──────────────────────────────────────────────────────┘      │
│          │ refined hypothesis                                           │
│          ▼                                                              │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              TRAIN ALL COMPONENTS                            │      │
│   │                                                              │      │
│   │   • Update perception weights (better symbol grounding)     │      │
│   │   • Update parser weights (better structure learning)       │      │
│   │   • Update program library (better semantic rules)          │      │
│   │   • Discover abstractions (library learning)                │      │
│   └──────┬──────────────────────────────────────────────────────┘      │
│          │                                                              │
│          └──────────────► REPEAT (Recursive Self-Improvement)           │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

The Manx Cat Example

This feedback loop enables the system to adapt to anomalies automatically:

BEFORE: System knows cats have tails
  Input: [fur, tail, meow] → CAT ✓
  Input: [fur, NO_TAIL, meow] → ??? (confused)

ABDUCTION TRIGGERED:
  - System encounters tailless cats (Manx breed)
  - Searches for hypothesis modifications
  - Discovers: "meow" is the key discriminator, not "tail"
  - Updates rule: TAIL is no longer mandatory for CAT

AFTER: System adapted its rules
  Input: [fur, NO_TAIL, meow] → CAT ✓ (correct!)

Why This Matters

Run the Example

cargo run --example cat_nsr_real

This demonstrates all three pillars:

1. Neural Perception: [fur, whiskers, meow] → symbol probabilities
2. Symbolic Reasoning: meow → CAT (learned rule)
3. Recursive Learning: System adapts to Manx cats (35 abduction steps)

Quick Start

⚠️ Default builds use deterministic, exact-match-friendly perception and a lightweight parser with deterministic fallbacks for fast demos. For production-quality neural perception and parsing, configure real backends (e.g., ONNX/Candle/Torch) and train the models before relying on results.

Use OpenAI embeddings for perception

use stateset_nsr::{nsr::NSRMachineBuilder, KnowledgeBase};
use stateset_nsr::neural::MockNeuralBackend; // replace with real OpenAI backend via config/env
use std::sync::Arc;

// Example with a backend-provided embedding dimension
let backend = Arc::new(stateset_nsr::neural::HttpNeuralBackend::new(
    "https://api.openai.com/v1/embeddings",
    std::env::var("OPENAI_API_KEY")?,
    "text-embedding-3-small",
    1536,
));

let machine = NSRMachineBuilder::new()
    .with_neural_backend(backend)
    .add_symbol("cat")
    .add_symbol("dog")
    .build();

Set NSR_NEURAL_BACKEND=openai (or backend = "openai" in config.toml) with a valid OPENAI_API_KEY to enable the HTTP backend globally.

Defaults:

• Binds to 127.0.0.1 unless you explicitly set NSR_HOST or --host
• Neural backend defaults to auto: prefers OpenAI if a key is present, otherwise FastEmbed (if compiled), otherwise mock. Supported backends: auto, mock, fastembed, openai (plus onnx with --features onnx)
• When binding to a non-loopback host, NSR_CORS_ORIGINS (or server.cors_allowed_origins) must be set; the server will refuse to start with permissive CORS in that case.
• Persistence defaults to data/knowledge.json when not configured; set NSR_KB_PATH or NSR_DATABASE_URL (recommended for non-loopback/prod deployments) to pick an explicit store.
• API keys are required; none are printed to stdout
• Postgres persistence: set NSR_DATABASE_URL (optional NSR_DATABASE_MAX_CONNECTIONS); otherwise file snapshot or in-memory is used

Quality & verification

• Offline sanity: cargo test --test cat_end_to_end (deterministic perception → program → evaluation).
• Full suite: cargo test --all-features (also run in CI).
• Real OpenAI embeddings: cargo test --test openai_perception -- --nocapture (requires OPENAI_API_KEY or NSR_NEURAL_API_KEY).
• Quality/readiness details and roadmap live in QUALITY.md.

Installation

# Clone the repository
git clone https://github.com/stateset/stateset-nsr
cd stateset-nsr

# Build the project
cargo build --release

# Run examples
cargo run --example basic_reasoning
cargo run --example nsr_machine_advanced

Basic Usage: NSR Engine

use stateset_nsr::reasoning::NSREngine;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Build engine with knowledge base
    let engine = NSREngine::builder()
        .mock()
        .build()
        .await?;

    // Add knowledge
    engine.add_entity(Entity::new("Socrates", EntityType::Instance)).await?;
    engine.add_triple("Socrates", "is_a", "Human").await?;
    engine.add_triple("Human", "is_a", "Mortal").await?;

    // Perform reasoning
    let result = engine.reason("Is Socrates mortal?").await?;

    println!("Answer: {:?}", result.answer);
    println!("Confidence: {:.2}", result.confidence);
    println!("Reasoning: {:?}", result.reasoning_type);

    Ok(())
}

Advanced Usage: NSR Machine

use stateset_nsr::nsr::{
    NSRMachineBuilder, GroundedInput, SemanticValue,
    program::{Program, Primitive},
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Build machine with advanced features
    let mut machine = NSRMachineBuilder::new()
        .embedding_dim(128)
        .hidden_size(256)
        .enable_synthesis(true)
        // Enable advanced modules
        .with_graph_of_thoughts()
        .with_vsa()
        .with_metacognition()
        .with_mcts()
        .with_explainability()
        // Add vocabulary
        .add_symbol("walk")
        .add_symbol("run")
        .add_symbol("twice")
        .build();

    // Define symbol semantics
    let walk_id = machine.vocabulary().get_by_name("walk").unwrap();
    machine.set_symbol_program(
        walk_id,
        Program::constant(SemanticValue::String("WALK".to_string())),
    );

    // Perform inference
    let inputs = vec![GroundedInput::text("walk")];
    let result = machine.infer(&inputs).await?;

    println!("Output: {:?}", result.output());
    println!("Confidence: {:.4}", result.confidence());

    Ok(())
}

Notes on Running Tests in Containerized/Networked Filesystems

If you see Invalid cross-device link (os error 18) while running cargo test or cargo build, it usually means the build artifacts cannot be hard-linked across mount points (common with Docker volumes or networked filesystems). Point Cargo to a target directory on the same filesystem to avoid the issue:

export CARGO_TARGET_DIR="$(pwd)/target-local"
# Optional: disable incremental to avoid hard-linking entirely
export CARGO_INCREMENTAL=0
cargo test

NSR Engine

The NSR Engine is the production-ready hybrid reasoning system combining neural and symbolic AI.

Reasoning Strategies

use stateset_nsr::reasoning::{NSREngine, ReasoningStrategy};

let engine = NSREngine::builder()
    .with_strategy(ReasoningStrategy::HybridWeighted {
        neural_weight: 0.6,
        symbolic_weight: 0.4
    })
    .build()?;

Forward & Backward Chaining

// Forward chaining - derive new facts from rules
let inferred = engine.forward_chain();
println!("Derived {} new facts", inferred.len());

// Backward chaining - prove a goal
let goal = Atom::new("mortal", vec![Term::constant("Socrates")]);
let proofs = engine.backward_chain(&goal);
for proof in proofs {
    println!("Proof: {:?}", proof);
}

Knowledge Graph Operations

// Add entities and relationships
engine.add_entity(Entity::new("Paris", EntityType::Instance)).await?;
engine.add_entity(Entity::new("France", EntityType::Instance)).await?;
engine.add_triple("Paris", "capital_of", "France").await?;

// Query the knowledge base
let result = engine.reason("What is the capital of France?").await?;

To keep your facts across restarts, set knowledge.persistence_path (or NSR_KB_PATH) and the server/agents/REPL will load on startup and persist on shutdown.

For Postgres-backed persistence, set database.url/NSR_DATABASE_URL; SeaORM will auto-create core tables (entities, relations, triples, rules, constraints, snapshot) and store both rows and a snapshot row that takes precedence over file snapshots.

NSR Machine

The NSR Machine implements the ICLR 2024 neuro-symbolic recursive architecture with 10+ advanced modules.

When you enable advanced modules, inference now engages them directly: Graph-of-Thoughts seeds a reasoning scaffold, VSA supplies semantic priors, differentiable logic refreshes symbol embeddings, and MCTS can refine low-confidence parses. Because of that stateful interplay, NSRMachine::infer takes &mut self.

Core: Grounded Symbol System (GSS)

The GSS is the unified representation combining:

• Grounded Input (x): Raw input segment (text, image, number)
• Abstract Symbol (s): Learned symbol ID
• Semantic Value (v): Computed meaning
• Edges (e): Dependency structure

use stateset_nsr::nsr::gss::{GroundedSymbolSystem, GSSNode, GroundedInput};

let mut gss = GroundedSymbolSystem::new();
gss.add_node(GSSNode::new(GroundedInput::text("hello")).with_symbol(0));
gss.add_node(GSSNode::new(GroundedInput::text("world")).with_symbol(1));
gss.add_edge(0, 1);  // hello -> world dependency

Advanced Modules

Graph-of-Thoughts (GoT)

Complex reasoning with branching and merging thought paths:

let mut machine = NSRMachineBuilder::new()
    .with_graph_of_thoughts()
    .build();

// Add thoughts and create reasoning graph
let root = machine.add_thought("Initial hypothesis", 0.8).unwrap();
let branches = machine.branch_thought(root, vec![
    ("Path A: Deductive approach".to_string(), 0.9),
    ("Path B: Inductive approach".to_string(), 0.7),
]);

// Connect reasoning paths
machine.connect_thoughts(branches[0], branches[1]);

Vector Symbolic Architecture (VSA)

Hyperdimensional computing for robust semantic memory (10,000-dimensional vectors):

let mut machine = NSRMachineBuilder::new()
    .with_vsa()
    .add_symbol("cat")
    .add_symbol("dog")
    .build();

// Encode symbols as hypervectors
let cat_id = machine.vocabulary().get_by_name("cat").unwrap();
let dog_id = machine.vocabulary().get_by_name("dog").unwrap();

let cat_hv = machine.vsa_encode_symbol(cat_id).unwrap();
let dog_hv = machine.vsa_encode_symbol(dog_id).unwrap();

// Bind: Create composite concept (cat-chases-dog)
let bound = machine.vsa_bind(&cat_hv, &dog_hv).unwrap();

// Bundle: Create set union {cat, dog} = animals
let bundled = machine.vsa_bundle(&[cat_hv, dog_hv]).unwrap();

// Add named concepts for memory
machine.vsa_add_concept("animal");
machine.vsa_add_concept("pet");

MCTS Abduction

Monte Carlo Tree Search for hypothesis exploration:

use stateset_nsr::nsr::mcts::MCTSConfig;

let mcts_config = MCTSConfig {
    exploration_constant: 1.414,  // UCB exploration
    num_simulations: 100,
    max_depth: 20,
    temperature: 1.0,
    use_dirichlet_noise: true,
    ..Default::default()
};

let mut machine = NSRMachineBuilder::new()
    .with_mcts_config(mcts_config)
    .build();

// Search for GSS that produces target output
let target = SemanticValue::Integer(5);
if let Some(result) = machine.mcts_search(initial_gss, &target) {
    println!("Found solution with value: {:.4}", result.value);
    println!("Simulations: {}", result.simulations);
}

Metacognition

Self-monitoring with uncertainty estimation:

let mut machine = NSRMachineBuilder::new()
    .with_metacognition()
    .build();

// Track predictions for uncertainty modeling
machine.track_prediction(vec![0.8, 0.15, 0.05]);
machine.track_prediction(vec![0.7, 0.2, 0.1]);

// Get uncertainty estimate
if let Some(uncertainty) = machine.estimate_uncertainty() {
    println!("Epistemic: {:.4}", uncertainty.epistemic);  // Model uncertainty
    println!("Aleatoric: {:.4}", uncertainty.aleatoric);  // Data uncertainty
    println!("Total: {:.4}", uncertainty.total);
}

Inference Scaling

Adaptive computation depth based on confidence:

let machine = NSRMachineBuilder::new()
    .with_inference_scaling()
    .build();

// Check if more computation is within budget
let can_continue = machine.can_continue_reasoning(depth, iteration);

// Get recommended depth based on confidence
let recommended = machine.scale_reasoning_depth(confidence, current_depth);

Library Learning

DreamCoder-style automatic abstraction discovery:

let mut machine = NSRMachineBuilder::new()
    .with_library_learning()
    .build();

// After training on multiple programs...
let abstractions = machine.learn_library();
for abs in &abstractions {
    println!("Discovered: {} (arity {})", abs.name, abs.arity);
}

Continual Learning

Prevent catastrophic forgetting with EWC and replay buffers:

let mut machine = NSRMachineBuilder::new()
    .with_continual_learning()
    .build();

// Record experiences for replay
machine.record_experience(example, difficulty);

All Features at Once

let machine = NSRMachineBuilder::new()
    .embedding_dim(256)
    .hidden_size(512)
    .with_all_advanced_features()  // Enable everything
    .build();

// Check enabled features
println!("Features: {:?}", machine.enabled_features());
// ["library_learning", "metacognition", "explainability", "continual_learning",
//  "mcts", "probabilistic", "graph_of_thoughts", "inference_scaling", "vsa",
//  "differentiable_logic"]

Presets for Common Tasks

use stateset_nsr::nsr::presets;

// SCAN-like compositional tasks
let machine = presets::scan_machine();

// PCFG string manipulation
let machine = presets::pcfg_machine();

// HINT arithmetic tasks
let machine = presets::hint_machine();

// COGS semantic parsing
let machine = presets::cogs_machine();

REST API

Start the Server

cargo run --release -- serve --port 8080

Core Endpoints

Example Requests

# Reasoning with strategy selection
curl -X POST http://localhost:8080/api/v1/reason \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Is Socrates mortal?",
    "strategy": "HybridWeighted",
    "options": {
      "max_depth": 5,
      "confidence_threshold": 0.7
    }
  }'

# Response
{
  "answer": "Yes, Socrates is mortal",
  "confidence": 0.95,
  "reasoning_type": "hybrid",
  "explanation": {...},
  "metadata": {
    "query_time_ms": 42,
    "facts_used": 3,
    "rules_fired": 2
  }
}

Examples

The repository includes comprehensive examples demonstrating various features:

Basic Examples

cargo run --example basic_reasoning      # Knowledge graph + reasoning
cargo run --example api_client           # REST API client
cargo run --example knowledge_graph      # Graph construction
cargo run --example nsr_openai_quickstart # Minimal OpenAI wiring (set OPENAI_API_KEY)

Advanced NSR Machine Examples

cargo run --example nsr_machine_openai_quickstart # NSRMachine + OpenAI embeddings/LLM summary
cargo run --example nsr_machine_advanced    # All NSR Machine features
cargo run --example symbolic_learning       # Program synthesis & learning
cargo run --example probabilistic_reasoning # Uncertainty & inference scaling
cargo run --example cognitive_architecture  # Full cognitive system (GoT, VSA, etc.)
cargo run --example mcts_abduction          # MCTS hypothesis exploration

Domain-Specific Examples

cargo run --example family_genealogy     # Family relationships
cargo run --example financial_services   # Financial reasoning
cargo run --example healthcare_clinical  # Clinical decision support
cargo run --example supply_chain         # Supply chain optimization
cargo run --example retail_commerce      # E-commerce reasoning
cargo run --example medical_diagnosis    # Medical diagnosis

Project Structure

src/
├── app/                    # NSR AI Application Layer
│   ├── engine.rs          # NSREngine (main entry point)
│   ├── llm.rs             # LLM client abstraction
│   ├── logic.rs           # Prolog-like logic engine
│   ├── reasoning.rs       # Recursive reasoning loop
│   ├── symbolic.rs        # Facts, Rules, Tasks
│   ├── pipeline.rs        # NSR pipeline orchestration
│   ├── cache.rs           # Query result caching
│   └── tools.rs           # Tool registry
├── nsr/                    # NSR Machine (ICLR 2024)
│   ├── machine.rs         # NSRMachine orchestrator (1,560 lines)
│   ├── gss.rs             # Grounded Symbol System (706 lines)
│   ├── perception.rs      # Neural perception module
│   ├── parser.rs          # Dependency parser
│   ├── program.rs         # Program synthesis (1,185 lines)
│   ├── learning.rs        # Deduction-Abduction learning
│   ├── graph_of_thoughts.rs # GoT reasoning
│   ├── vsa.rs             # Vector Symbolic Architecture (1,045 lines)
│   ├── mcts.rs            # Monte Carlo Tree Search (990 lines)
│   ├── metacognition.rs   # Self-monitoring (978 lines)
│   ├── library_learning.rs # DreamCoder-style learning (981 lines)
│   ├── continual.rs       # Continual learning
│   ├── probabilistic.rs   # Probabilistic inference (927 lines)
│   ├── differentiable_logic.rs # Differentiable theorem proving
│   ├── inference_scaling.rs # Adaptive computation
│   ├── explain.rs         # Explainability
│   └── transformer.rs     # Transformer architecture
├── reasoning/              # NSR Engine reasoning
│   ├── mod.rs             # NSREngine + strategies (1,156 lines)
│   ├── logic.rs           # First-order logic
│   ├── hybrid.rs          # Hybrid reasoning
│   └── explanation.rs     # Explanation generation
├── knowledge/              # Knowledge representation
│   ├── graph.rs           # Knowledge graph
│   ├── rules.rs           # Rule engine
│   ├── query.rs           # Query execution
│   └── constraints.rs     # Constraint validation
├── neural/                 # Neural backends
│   ├── embeddings.rs      # Vector embeddings
│   ├── inference.rs       # Neural inference
│   ├── fastembed.rs       # FastEmbed integration
│   └── ort.rs             # ONNX Runtime
├── api/                    # REST API (Axum)
│   ├── routes.rs          # Route definitions
│   ├── handlers.rs        # Endpoint handlers (1,250+ lines)
│   ├── state.rs           # Application state
│   └── metrics.rs         # Prometheus metrics
├── agents/                 # Autonomous agents
├── config/                 # Configuration
├── bin/nsr_ai.rs          # CLI application
├── main.rs                # Server entry point
└── lib.rs                 # Library exports

Configuration

Config File (config.toml)

[server]
host = "0.0.0.0"
port = 8080
rate_limit = 60  # requests per minute

[reasoning]
confidence_threshold = 0.7
max_reasoning_depth = 10
similarity_threshold = 0.8
default_strategy = "HybridWeighted"

[neural]
backend = "openai"            # auto-detected if OpenAI key is present
embedding_dimension = 1536    # matches text-embedding-3-small
model = "text-embedding-3-small"

[nsr_machine]
embedding_dim = 256
hidden_size = 512
max_seq_len = 100
beam_width = 8
enable_synthesis = true

[logging]
level = "info"
format = "json"

Environment Variables

export NSR_LLM_PROVIDER=openai    # openai, anthropic, local, mock
export NSR_API_KEY=sk-...         # API key for LLM provider
export NSR_MODEL=gpt-4            # Model name
export NSR_BASE_URL=http://...    # Base URL for local LLM
export NSR_NEURAL_BACKEND=openai  # Optional; auto-selected if OpenAI key is present
export NSR_NEURAL_MODEL=text-embedding-3-small
export NSR_NEURAL_API_KEY=$OPENAI_API_KEY

OpenAI quickstart

export OPENAI_API_KEY=sk-...
export NSR_NEURAL_MODEL=text-embedding-3-small   # or text-embedding-3-large (3072-dim)
export NSR_NEURAL_BACKEND=openai
# Optional: NSR_NEURAL_API=https://api.openai.com/v1/embeddings
# Optional: NSR_PARSER_CHECKPOINT=/path/to/parser.safetensors (required for non-loopback binds)

cargo run -- serve --host 0.0.0.0 --port 8080

On non-loopback hosts the server will refuse to start if it would fall back to the mock backend or if a parser checkpoint is missing. Provide a real backend key and a trained parser checkpoint for production. For highest embedding quality, use NSR_NEURAL_MODEL=text-embedding-3-large and set NSR_EMBEDDING_DIM=3072.

Production profile (secure defaults)

• NSR_NEURAL_BACKEND=openai, NSR_NEURAL_MODEL=text-embedding-3-large, NSR_EMBEDDING_DIM=3072, OPENAI_API_KEY set.
• NSR_PUBLIC_ROUTES_REQUIRE_AUTH=true (default) and NSR_API_KEYS configured; always send x-api-key.
• NSR_CORS_ORIGINS=https://your.domain (comma-separated). Required when binding to non-loopback hosts; server will refuse to start otherwise.
• NSR_KB_PATH=/var/lib/nsr/knowledge.json (or Postgres URL) so knowledge persists.
• NSR_PARSER_CHECKPOINT=/var/lib/nsr/parser.safetensors (required for non-loopback/prod deployments).
• Rate-limit tuned: NSR_RATE_LIMIT=60 (or stricter) per minute; optionally set per-key rate_limit_per_minute in server.api_keys. Keep NSR_MAX_BODY_SIZE bounded.
• Metrics: Prometheus /metrics exports LLM/embedding latencies and token counts; scrape and alert on nsr_llm_requests_total / nsr_llm_request_duration_ms.

Feature Flags

[features]
default = ["server"]
server = ["axum", "tower", "tower-http"]
onnx = ["ort"]           # ONNX Runtime support
torch = ["tch"]          # PyTorch bindings
embeddings = ["fastembed"]  # FastEmbed support

Testing & Benchmarks

# Run all tests
cargo test

# Run specific module tests
cargo test --lib nsr::machine
cargo test --lib reasoning

# Run integration tests
cargo test --test api_integration

# Deterministic reasoning and neural backend contract tests
cargo test reasoning_golden_tests neural_backend_tests
# Opt-in FastEmbed smoke (requires embeddings feature and local model availability)
NSR_RUN_FASTEMBED_TESTS=1 cargo test -p stateset-nsr --features embeddings -- fastembed_smoke

# Run benchmarks
cargo bench

# Run with coverage
cargo tarpaulin --out Html

For planned lightweight eval expectations and how to run them, see docs/EVALS.md.

Performance

The NSR framework is optimized for production use:

• Async/await throughout with Tokio runtime
• DashMap for concurrent thread-safe state
• Query caching for repeated operations
• Clause indexing for efficient rule matching
• Batch inference for neural operations

Research References

The NSR Machine implements concepts from:

1. ICLR 2024 NSR Paper: Grounded Symbol System architecture
2. DreamCoder: Library learning and program synthesis
3. AlphaGo/Zero: MCTS for hypothesis search
4. Neural Theorem Provers: Differentiable logic
5. Elastic Weight Consolidation: Continual learning

Documentation

• API Reference - REST API documentation
• Advanced Modules - MCTS, GoT, VSA, Metacognition, Library Learning
• Deployment Guide - Production deployment with Docker/Kubernetes
• Benchmarks - Performance benchmarks
• Migration Guide - Basic to advanced NSR
• Optional OpenAI smoke: NSR_RUN_OPENAI_SMOKE=1 OPENAI_API_KEY=... cargo test -p stateset-nsr --test openai_smoke

License

This project is licensed under the Business Source License 1.1 (BSL-1.1).

Key Terms:

• Free Use: Development, testing, personal, and non-production use
• Production Use: Allowed, except for offering a competing hosted NSR service
• Change Date: December 8, 2028
• Change License: Apache License 2.0

After the Change Date, this software will be available under the Apache 2.0 license.

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

Citation

If you use StateSet NSR in your research, please cite:

@software{stateset_nsr,
  title = {StateSet NSR: Neuro-Symbolic Reasoning Framework},
  author = {StateSet},
  year = {2024},
  url = {https://github.com/stateset/stateset-nsr}
}

Related Projects

• stateset-agents - RL agents framework
• stateset-api - Commerce API