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.

Looking for something specific? Start at the documentation index — it has reading paths for new users, API consumers, operators, and contributors.

§Overview

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

§What’s New in v0.7.1

NSR can now sit directly on the execution boundary of an agentic workflow. Callers declare an exact, fully grounded authorization_goal; the engine approves only when facts and rules derive that exact predicate. This removes semantic guessing between an agent’s requested action and the policy result.

Exact tool authorization: bind approval to the precise agent, operation, and resource, such as can_use_tool(research_agent, browser).
Safe precedence: explicit deny wins over review, review wins over permit, and absence of proof remains a refusal.
Delegation and multi-hop proofs: authorization can flow through grounded delegation and capability rules while preserving consistent variable joins.
Sound negation-as-failure: a negated premise succeeds only when no matching positive fact exists under the current binding; evaluation-budget exhaustion fails closed.
Auditable responses: evaluated_goal, replayable proof steps, policy hashes, and actionable refusal gaps make the result inspectable and repeatable.
Backward compatibility: requests without authorization_goal continue through legacy action/query inference and receive a migration warning.

Validated with 1,711 production-feature library tests and live adversarial checks covering exact permits, denials, review, subject isolation, cycles, delegation, and negation.

§What’s New in v0.5.0

Seam integrity across tenancy, idempotency and proof fidelity — see CHANGELOG. Three changes are breaking and one needs an operator check before deploy: quota enforcement, previously a no-op, now works, so any tenant already over its tier limit will start receiving 402 on creates. Audit live KB counts against tier limits first.

§What’s New in v0.4.0

Concurrent inference (ADR-012): NSRMachine::infer takes &self behind reader-writer locks — decision/chat requests on one org’s machine run in parallel; training and administration serialize on a short write window. Proven by an equivalence test (8 workers ≡ sequential) and a throughput bench; measured 43% wall-clock reduction on the integration suite from concurrency alone.
Batch Verified Decisions (POST /v1/decisions/batch): portfolio scoring with per-item evidence and metering; items past the request-time budget are never evaluated, never billed. Shipped across all four SDKs and the dashboard.
Benchmark closures with an honest ledger: SCAN length, PCFG systematicity, and Compositional MT moved 0–50% → 100% via labeled symbolic routes — and the dedicated *_LEARNED rows then closed too: MT_LEARNED and PCFG_LEARNED both at 100% (trained transition parser — no Earley grammar at inference; train-time supervision is seeded by a hand-coded category heuristic). Held-out splits are small (MT n=4, PCFG n=1): exact-match closures locked at floor 1.00 in CI, not large-sample claims. See docs/PAPER_BENCHMARK_RESULTS.md for the table, floors, and mechanism.
Verified Decisions whitepaper: the decision model, per-outcome evidence packages, and OpenAI/Anthropic integration patterns — docs/VERIFIED_DECISIONS_WHITEPAPER.md.
Quality: first fully-green dashboard e2e suite (28/28, WCAG-AA axe gate on 13 pages), integration suite 4.7× faster, abduction scoring repairs (unit-pinned), SDK wire-format tests on all four clients, zero clippy warnings.
Fixes that matter: org-scoped symbol writes no longer vanish for tenants; large decision batches can no longer bill for undelivered items.
Prior highlights (v0.3.x): Verified Decision API + proof harness, Anthropic/OpenAI drop-in endpoints, metered Stripe billing (exactly-once), closed-loop flywheel, SBOM + cosign on releases.

Full details: CHANGELOG.md.

§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

§Grounding Emulator

Simulation engine for seeding NSR agents with pre-trained symbolic knowledge:

Multi-backend: Mock (synthetic), Playwright (web/CDP), Docker (desktop), QEMU (legacy OS)
Perception Fusion: Accessibility trees + DOM + vision fused into 33-field composite symbols
Knowledge Seeding: Auto-generates symbol vocabularies, KB triples, rules, and patterns

§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/runtime/knowledge.json (gitignored) when not configured, bootstrapped from the tracked seed data/knowledge.json on first run; 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

# Install CLI from npm
npm install -g @stateset/nsr-cli

# Validate CLI install
nsr --help

# 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

§Note on the C Compiler (aws-lc-sys)

The TLS stack pulls in aws-lc-sys, whose build script rejects GCC versions affected by GCC bug 95189 (a miscompiled memcmp; GCC ≤ 9.4 among others) with ### COMPILER BUG DETECTED ###. If your system compiler is affected, build with clang instead:

CC=clang CXX=clang++ cargo build

§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

§Provider-compatible endpoints (drop-in for OpenAI and Anthropic SDKs)

Endpoint	Method	Compatibility
`/v1/chat/completions`	POST	OpenAI Chat Completions (streaming, tools, `usage`, `system_fingerprint`)
`/v1/models`	GET	OpenAI model list
`/v1/responses`	POST	OpenAI Responses API
`/v1/messages`	POST	Anthropic Messages (content blocks, `tool_use`, SSE events, `stop_reason`)

Point the official OpenAI or Anthropic SDK’s base_url at your NSR deployment and use any NSR API key. Errors come back in each provider’s native error envelope. See SDKS.md for full examples.

§Verified Decision API (flagship neuro-symbolic-recursive surface)

Endpoint	Method	Returns
`/v1/decisions`	POST	`approved \| denied \| refused` + cited proof chain + confidence + safe refusal
`/v1/decisions/batch`	POST	Per-item decisions + batch summary; items past the time budget are never evaluated or billed (`batch_deadline_exceeded`)
`/v1/decisions/recent`	GET	Most recent decisions for the org (ephemeral analytics; newest first)
`/v1/decisions/stats`	GET	Windowed aggregates: outcome counts, billable volume, p50/p95 latency, top-cited rules

The canonical NSR use case: auditable, policy-grounded decisions instead of free text. A pure LLM will confidently approve actions that violate policy; /v1/decisions forces canonical GSS classification plus tenant-scoped NSRMachine inference, returns that evidence alongside the recursive proof, and refuses when it can’t ground the answer. Metered per verified decision. Proof harness: cargo run --example verified_decision_harness (100% decision accuracy / 100% refusal correctness / 0 unsafe approvals across 9 cases). See docs/VERIFIED_DECISION_API.md.

For agent tool calls, declare the exact proof target instead of asking the engine to infer it from prose:

curl -X POST https://api.nsr.stateset.com/v1/decisions \
  -H "X-API-Key: $NSR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "May research_agent use the browser?",
    "action": "use_tool",
    "mode": "safe",
    "authorization_goal": {
      "name": "can_use_tool",
      "args": ["research_agent", "browser"]
    },
    "facts": [
      {"predicate": {"name": "tool_granted", "args": ["research_agent", "browser"]}}
    ],
    "rules": [{
      "name": "permit_granted_tool",
      "if": [{"name": "tool_granted", "args": ["?agent", "?tool"]}],
      "then": [{"name": "can_use_tool", "args": ["?agent", "?tool"]}]
    }]
  }'

The natural-language query is descriptive. authorization_goal is the authoritative permit target and must contain no variables, nulls, empty string arguments, or negation. Prompt text alone cannot create a trusted policy fact.

§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": "hybrid",
    "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

emulator/                   # Grounding Emulator (separate crate)
├── src/
│   ├── types.rs           # Core types: CompositeSymbol[33], A11yNode, CanonicalRole
│   ├── backends/          # Environment backends
│   │   ├── mock.rs        # 3 preset apps (login, file manager, email)
│   │   └── playwright.rs  # CDP browser backend (screenshot + a11y + DOM)
│   ├── perception/        # Extraction and multi-source fusion
│   │   ├── extractor.rs   # Frame capture, image signatures, pixel diffs
│   │   └── fusion.rs      # Cross-platform normalization, spatial relations
│   ├── grounding/         # Symbol encoding and knowledge production
│   │   ├── pipeline.rs    # PerceptionFrame → 33-field CompositeSymbol
│   │   ├── symbols.rs     # Agglomerative clustering → vocabulary
│   │   └── seeder.rs      # Records → entities, triples, rules, patterns
│   ├── scenarios/         # Task definitions and curriculum planning
│   │   ├── generator.rs   # 6 built-in templates (atomic → complex)
│   │   └── curriculum.rs  # Difficulty-progressive scheduling
│   ├── orchestrator.rs    # Fleet management and scenario execution
│   └── storage/
│       └── records.rs     # JSON Lines persistence (date-rotated)
└── Cargo.toml             # Independent crate, features: playwright, docker

docs/
├── GETTING_STARTED.md     # Tutorial with visual diagrams
├── EMULATOR.md            # Grounding emulator concepts and integration
├── 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)

The complete, annotated reference is config.example.toml — copy it and edit. A minimal excerpt:

[server]
host = "0.0.0.0"
port = 8080
rate_limit_per_minute = 60  # 0 to disable

[reasoning]
confidence_threshold = 0.7
max_reasoning_depth = 10
similarity_threshold = 0.8

[neural]
backend = "openai"            # auto-detected if OpenAI key is present
embedding_dimension = 3072    # default for text-embedding-3-large
model = "text-embedding-3-large"

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

§Grounding Emulator

The grounding emulator (emulator/ crate) simulates software applications in headless environments to produce pre-trained symbolic knowledge for NSR agents. Instead of learning from scratch, agents arrive knowing what buttons, text fields, and forms look like across dozens of applications.

Environment Fleet          Perception Fusion         Knowledge Seeding
─────────────────          ─────────────────         ─────────────────
Mock (synthetic)  ─┐       A11y trees ──┐            Symbol vocabulary
Playwright (CDP)  ─┤──►    DOM trees  ──┼──► 33-field ──► KB triples
Docker (Xvfb)    ─┤       Screenshots ─┘   symbols     Rules + patterns
QEMU (legacy OS)  ─┘                                    Negative patterns

§Quick example

use nsr_emulator::{Orchestrator, OrchestratorConfig};
use nsr_emulator::backends::MockBackend;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let mut orchestrator = Orchestrator::new(OrchestratorConfig::default());
    orchestrator.add_backend(Box::new(MockBackend::with_preset_apps()));

    let records = orchestrator.run_curriculum().await?;
    let output = orchestrator.finalize();

    println!("{} symbols, {} triples, {} patterns",
        output.symbol_vocabulary.len(),
        output.triples.len(),
        output.patterns.len(),
    );
    Ok(())
}

For the full guide, see emulator/README.md and docs/EMULATOR.md.

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

§Paper benchmark suite

nsr paper-bench runs the SCAN / PCFG / HINT / Compositional MT splits from the ICLR 2024 NSR paper and reports per-split accuracy against the paper-reported targets.

nsr paper-bench                          # every split, ASCII table with PASS/MISS
nsr paper-bench --task HINT              # one task
nsr paper-bench --markdown               # PR-body friendly
nsr paper-bench --json                   # machine-readable BenchmarkSummary

On every PR, the paper-bench CI job runs the full suite, uploads the JSON/markdown artifacts, and fails when any split underperforms its target (override with the paper-bench:override label). Regression floors are enforced in CI via cargo test --release --test paper_reproduction -- --ignored. Current per-split results and the symbolic-vs-learned methodology live in docs/PAPER_BENCHMARK_RESULTS.md. See docs/CLI.md#paper-bench for the full reference and src/nsr/benchmarks.rs::paper_target for the target table.

§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

➡️ Master documentation index — reading paths for new users, API consumers, operators, contributors, and researchers.

§Getting Started

Quickstart — 5-minute server + CLI + curl path
Business Quickstart — the production integration path: verified decisions, safe retries, verifiable webhooks, grounding
API Getting Started — 5-minute HTTP path to your first verified decision
Getting Started (Rust SDK) - Rust library tutorial with worked examples

§Reference

API Getting Started - HTTP quickstart leading with POST /v1/decisions
NSR API Usage Guide - Practical curl-first walkthrough for auth, CRUD, reasoning, NSR-L, and SSE
API Reference - REST API documentation
Platform Technical Overview - How the server, recursive solver, NSR machine, and symbolic runtime fit together
Recursive Chat Endpoint Overview - What POST /api/v2/nsr/chat/solve does, how it executes, and what it returns
Action Gate Regression Harness - Local and CI proof that governed actions stay behind validation gates
Why NSR Matters - Market thesis, buyer pain, and why accountable agents matter more than better chatbots
NSR Reasoning Pipeline - Request-time NSR machine and chat API walkthrough
Advanced Modules - MCTS, GoT, VSA, Metacognition, Library Learning
Performance Guide - Memory requirements, latency benchmarks, scaling

§Grounding Emulator

Emulator README - Quick start, backends, configuration, and API reference
Emulator Guide - Concepts, architecture, and integration with NSR

§Architecture

Architecture Decision Records - Design rationale and trade-offs (12 ADRs, including ADR-012 concurrent inference)

§Whitepapers

WHITEPAPER.md — canonical technical whitepaper
Verified Decisions Whitepaper — the Decision API, per-outcome evidence packages, and OpenAI/Anthropic integration patterns
docs/whitepapers/ — variant whitepapers (NSR-L logic language, advisor updates, technical whitepaper)

§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 policy::CanonicalSandboxAction;
pub use policy::GuiActionKind;
pub use policy::SandboxActionCandidate;
pub use policy::SandboxExpectedEffects;
pub use policy::SandboxMachineProofNode;
pub use policy::SandboxObservedResult;
pub use policy::SandboxPolicyContext;
pub use policy::SandboxPolicyEvaluation;
pub use policy::SandboxPolicyEvidence;
pub use policy::SandboxPolicyMachineEvaluation;
pub use policy::SandboxPolicyPhase;
pub use policy::SandboxPolicyRequest;
pub use policy::SandboxPolicyRuleMatch;
pub use policy::SandboxPolicyVerdict;
pub use policy::SandboxProofStep;
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: Autonomous reasoning agents that combine strategies with knowledge and LLM backends. Reasoning Agents Module
api: REST HTTP API (Axum) — only available when the server feature is enabled. Axum-based API Server
app: Application-layer engine with recursive goal solving and the AppEngine builder. NSR AI Application Layer
cache: Multi-tier caching for embeddings, inference results, and knowledge-base lookups.
cli: Command-line interface internals for the nsr binary. CLI module for the NSR platform — 43 submodules.
compiler: NSR-L language compiler: parser, type checker, and code emission. Query Compiler Pipeline
config: Typed configuration for the engine, knowledge base, neural backends, and reasoning. Configuration Module
connectors: Commerce connectors: grounded decisions on live store data (trait + sync applier). Commerce connectors — grounded decisions on live store data.
gss_v3: GSS v3 seed schema for the compiler pipeline. GSS v3 seed schema for the compiler pipeline.
knowledge: Knowledge representation: entities, triples, rules, constraints, and queries. Knowledge Base Module
neural: Neural backends (OpenAI, FastEmbed, ONNX, Vertex, Mock) and the NeuralBackend trait. Neural Network Integration Module
nsr: NSR Machine: Grounded Symbol System, program synthesis, MCTS, VSA, and related research modules. Neural-Symbolic Recursive Machine (NSR)
policy: Sandbox policy evaluation for governed agent actions. Sandbox policy evaluation for governed agent actions.
prelude: Prelude with the most common imports for library consumers.
reasoning: Reasoning engine: strategies, logic, explanations, and the NSREngine facade. Neuro-Symbolic Reasoning Engine
streaming: Streaming integrations (Kafka, SSE) for real-time ingestion and inference. Streaming Ingestion Module
utils: Miscellaneous helpers used across the crate. Utility functions and helpers

Constants§

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