Crate stateset_nsr

Expand description

§StateSet NSR - Neuro-Symbolic Recursive AI 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.

§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

Traditional AI	NSR AI
Neural OR Symbolic	Neural AND Symbolic in feedback loop
Fixed rules	Rules that adapt through abduction
Black box	Explainable reasoning
Fails on anomalies	Learns from anomalies
No self-improvement	Recursive self-modification

§Run the Example

cargo run --example cat_nsr_real

This demonstrates all three pillars:

Neural Perception: [fur, whiskers, meow] → symbol probabilities
Symbolic Reasoning: meow → CAT (learned rule)
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-large",
    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

Strategy	Description	Use Case
SymbolicFirst	Try logic first, fall back to neural	Rule-heavy domains
NeuralFirst	Use neural embeddings, enhance with symbolic	Pattern matching
HybridWeighted	Combine both with configurable weights	Balanced reasoning
Cascading	Neural first, symbolic verification	High-confidence needs
Ensemble	Multiple approaches vote on result	Maximum accuracy

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

Endpoint	Method	Description
`/health`	GET	Health check
`/metrics`	GET	Prometheus metrics
`/api/v1/reason`	POST	Main reasoning endpoint
`/api/v1/forward-chain`	POST	Forward chaining inference
`/api/v1/backward-chain`	POST	Backward chaining inference
`/api/v1/explain`	POST	Generate explanations
`/api/v1/entities`	GET/POST	Entity management
`/api/v1/entities/:id`	DELETE	Delete an entity
`/api/v1/entities/batch`	POST/DELETE	Batch create/delete entities
`/api/v1/triples`	POST/DELETE	Create/delete facts
`/api/v1/triples/batch`	POST	Batch create triples
`/api/v1/rules`	GET/POST	Rule management
`/api/v1/rules/:id`	DELETE	Delete a rule
`/api/v1/query`	POST	Query knowledge base
`/api/v1/sessions`	POST/GET	Session management

§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/
├── nsr/                    # NSR Machine (ICLR 2024)
│   ├── machine/           # NSRMachine module (11 sub-modules)
│   │   ├── mod.rs         # Re-exports and tests
│   │   ├── config.rs      # NSRConfig with feature flags
│   │   ├── builder.rs     # Fluent builder API
│   │   ├── core.rs        # NSRMachine struct
│   │   ├── inference.rs   # Perception pipeline & beam search
│   │   ├── semantics.rs   # Semantic computation
│   │   ├── symbols.rs     # Symbol management
│   │   ├── advanced.rs    # GoT, VSA, MCTS integration
│   │   ├── learning.rs    # Training & evaluation
│   │   ├── features.rs    # Runtime feature toggles
│   │   ├── presets.rs     # SCAN, PCFG, HINT presets
│   │   └── results.rs     # InferenceResult, Stats
│   ├── recursive_reasoning/ # LLM-based reasoning (11 sub-modules)
│   │   ├── mod.rs         # Re-exports and tests
│   │   ├── scan.rs        # SCAN domain types
│   │   ├── grammar.rs     # Compositional grammar
│   │   ├── parser.rs      # Earley parser
│   │   ├── evaluator.rs   # Semantic evaluator
│   │   ├── reasoner.rs    # Main reasoning loop
│   │   ├── prompts.rs     # LLM prompt templates
│   │   └── ...            # Config, results, parsing
│   ├── mcts/              # Monte Carlo Tree Search (10 sub-modules)
│   │   ├── mod.rs         # Re-exports and tests
│   │   ├── config.rs      # MCTSConfig
│   │   ├── search.rs      # MCTS search algorithm
│   │   ├── node.rs        # Tree nodes, UCB scoring
│   │   ├── actions.rs     # GSS actions
│   │   ├── value_network.rs # Value estimation
│   │   ├── policy_network.rs # Action priors
│   │   └── rollout.rs     # Rollout policies
│   ├── gss.rs             # Grounded Symbol System
│   ├── perception.rs      # Neural perception
│   ├── parser.rs          # Dependency parser
│   ├── program.rs         # Program synthesis
│   ├── vsa.rs             # Vector Symbolic Architecture
│   ├── graph_of_thoughts.rs # GoT reasoning
│   ├── metacognition.rs   # Self-monitoring
│   ├── library_learning.rs # Abstraction discovery
│   ├── continual.rs       # Continual learning
│   ├── probabilistic.rs   # Probabilistic inference
│   └── ...                # Other modules
├── reasoning/              # NSR Engine reasoning
│   ├── mod.rs             # NSREngine + strategies
│   ├── logic.rs           # First-order logic
│   ├── hybrid.rs          # Hybrid reasoning
│   └── explanation.rs     # Explanation generation
├── knowledge/              # Knowledge representation
├── neural/                 # Neural backends (OpenAI, ONNX, FastEmbed)
├── api/                    # REST API (Axum)
├── agents/                 # Autonomous agents
└── bin/nsr_ai.rs          # CLI application

docs/
├── GETTING_STARTED.md     # Tutorial with visual diagrams
├── PERFORMANCE.md         # Memory & latency benchmarks
├── adr/                   # Architecture Decision Records
│   ├── 001-gss-representation.md
│   ├── 002-dual-engine-architecture.md
│   ├── 003-neural-backend-abstraction.md
│   ├── 004-deduction-abduction-loop.md
│   ├── 005-vsa-algebra-selection.md
│   ├── 006-async-first-design.md
│   ├── 007-error-handling-strategy.md
│   └── 008-feature-toggle-system.md
└── ...                    # API, Advanced Modules, Deployment

§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-large
model = "text-embedding-3-large"

[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-large
export NSR_NEURAL_API_KEY=$OPENAI_API_KEY

§OpenAI quickstart

export OPENAI_API_KEY=sk-...
export NSR_NEURAL_MODEL=text-embedding-3-large   # or text-embedding-3-large (3072-dim)
export NSR_NEURAL_BACKEND=openai

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:

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

§Documentation

§Getting Started

Getting Started Guide - Tutorial with visual diagrams for new users

§Reference

API Reference - REST API documentation
Advanced Modules - MCTS, GoT, VSA, Metacognition, Library Learning
Performance Guide - Memory requirements, latency benchmarks, scaling

§Architecture

Architecture Decision Records - Design rationale and trade-offs

§Operations

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}
}

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

§StateSet NSR - Neuro-Symbolic Reasoning Framework

A hybrid AI framework that combines neural network pattern recognition with symbolic reasoning and knowledge representation for robust, explainable AI.

§Architecture

The NSR framework consists of two major subsystems:

§1. Traditional Neuro-Symbolic Reasoning (Legacy)

Knowledge Base - Symbolic knowledge representation using graphs and logic
Neural Engine - Pattern recognition and embedding generation
Reasoning Engine - Hybrid inference combining both approaches

§2. Neural-Symbolic Recursive Machine

Grounded Symbol System (GSS) - Core representation combining perception, syntax, and semantics
Neural Perception - Maps raw inputs to symbolic sequences
Dependency Parser - Transition-based parser for syntactic structure
Program Induction - Functional programs for semantic computation
Deduction-Abduction - Novel learning algorithm for end-to-end training

§Example - Traditional API

use stateset_nsr::{NSREngine, KnowledgeBase, ReasoningConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let engine = NSREngine::builder()
        .with_knowledge_base(KnowledgeBase::new())
        .with_config(ReasoningConfig::default())
        .build()
        .await?;

    let result = engine.reason("What is the capital of France?").await?;
    println!("Answer: {:?}", result);
    Ok(())
}

§Example - NSR Machine API

use stateset_nsr::nsr::{
    NSRMachine, NSRConfig, GroundedInput, SemanticValue,
    presets, TrainingExample,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create NSR machine for SCAN-like tasks
    let mut machine = presets::scan_machine();

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

    println!("Output: {:?}", result.output());
    Ok(())
}

Re-exports§

pub use agents::AgentContext;
pub use agents::AgentDecision;
pub use agents::ReasoningAgent;
pub use cache::Cache;
pub use cache::CacheConfig;
pub use cache::CacheStats;
pub use cache::EmbeddingCache;
pub use cache::InferenceCache;
pub use config::KnowledgeConfig;
pub use config::NSRConfig;
pub use config::NeuralConfig;
pub use config::ReasoningConfig;
pub use knowledge::Substitution;
pub use knowledge::query::Query;
pub use knowledge::query::QueryResult;
pub use knowledge::Constraint;
pub use knowledge::Entity;
pub use knowledge::KnowledgeBase;
pub use knowledge::Relation;
pub use knowledge::Rule;
pub use knowledge::Triple;
pub use neural::inference::InferenceEngine;
pub use neural::inference::InferenceResult;
pub use neural::Embedding;
pub use neural::EmbeddingModel;
pub use neural::NeuralBackend;
pub use reasoning::logic::LogicalExpression;
pub use reasoning::Explanation;
pub use reasoning::NSREngine;
pub use reasoning::ReasoningPath;
pub use reasoning::ReasoningResult;
pub use nsr::error::GSSError;
pub use nsr::error::LLMSynthesisError;
pub use nsr::error::LearningError;
pub use nsr::error::MCTSError;
pub use nsr::error::NSRError;
pub use nsr::error::NSRResult;
pub use nsr::error::ParserError;
pub use nsr::error::PerceptionError;
pub use nsr::error::ProgramError;
pub use nsr::error::VSAError;

Modules§

agents: Reasoning Agents Module
api: Axum-based API Server
app: NSR AI Application Layer
cache: Caching Layer for Performance Optimization
config: Configuration Module
knowledge: Knowledge Base Module
neural: Neural Network Integration Module
nsr: Neural-Symbolic Recursive Machine (NSR)
prelude: Prelude module for common imports
reasoning: Neuro-Symbolic Reasoning Engine
utils: Utility functions and helpers

Constants§

VERSION: Crate version extracted from Cargo.toml at compile time.