stateset_nsr/
lib.rs

1// Copyright (c) 2024-2025 StateSet Inc.
2// Licensed under the Business Source License 1.1 (BSL-1.1)
3// See LICENSE file for details. Change Date: December 8, 2028. Change License: Apache-2.0
4
5// Safety: This crate minimizes unsafe code - only used via ndarray macros
6#![deny(unsafe_code)]
7#![doc = include_str!("../README.md")]
8// Allow clippy lints that require breaking API changes or complex refactoring
9#![allow(clippy::upper_case_acronyms)] // Keep NSR, VSA, MCTS naming per user decision
10#![allow(clippy::too_many_arguments)] // Some builders legitimately need many params
11#![allow(clippy::type_complexity)] // Complex types in neural/reasoning modules
12#![allow(clippy::should_implement_trait)] // Domain-specific ops differ from std::ops
13#![allow(clippy::needless_range_loop)] // Many legitimate uses in transformer/matrix code
14#![allow(clippy::only_used_in_recursion)] // Legitimate pattern in recursive functions
15
16//! # StateSet NSR - Neuro-Symbolic Reasoning Framework
17//!
18//! A hybrid AI framework that combines neural network pattern recognition with
19//! symbolic reasoning and knowledge representation for robust, explainable AI.
20//!
21//! ## Architecture
22//!
23//! The NSR framework consists of two major subsystems:
24//!
25//! ### 1. Traditional Neuro-Symbolic Reasoning (Legacy)
26//!
27//! - **Knowledge Base** - Symbolic knowledge representation using graphs and logic
28//! - **Neural Engine** - Pattern recognition and embedding generation
29//! - **Reasoning Engine** - Hybrid inference combining both approaches
30//!
31//! ### 2. Neural-Symbolic Recursive Machine
32//!
33//!
34//! - **Grounded Symbol System (GSS)** - Core representation combining perception, syntax, and semantics
35//! - **Neural Perception** - Maps raw inputs to symbolic sequences
36//! - **Dependency Parser** - Transition-based parser for syntactic structure
37//! - **Program Induction** - Functional programs for semantic computation
38//! - **Deduction-Abduction** - Novel learning algorithm for end-to-end training
39//!
40//! ## Example - Traditional API
41//!
42//! ```rust,no_run
43//! use stateset_nsr::{NSREngine, KnowledgeBase, ReasoningConfig};
44//!
45//! #[tokio::main]
46//! async fn main() -> anyhow::Result<()> {
47//!     let engine = NSREngine::builder()
48//!         .with_knowledge_base(KnowledgeBase::new())
49//!         .with_config(ReasoningConfig::default())
50//!         .build()
51//!         .await?;
52//!
53//!     let result = engine.reason("What is the capital of France?").await?;
54//!     println!("Answer: {:?}", result);
55//!     Ok(())
56//! }
57//! ```
58//!
59//! ## Example - NSR Machine API
60//!
61//! ```rust,no_run
62//! use stateset_nsr::nsr::{
63//!     NSRMachine, NSRConfig, GroundedInput, SemanticValue,
64//!     presets, TrainingExample,
65//! };
66//!
67//! #[tokio::main]
68//! async fn main() -> anyhow::Result<()> {
69//!     // Create NSR machine for SCAN-like tasks
70//!     let mut machine = presets::scan_machine();
71//!
72//!     // Perform inference
73//!     let inputs = vec![
74//!         GroundedInput::text("walk"),
75//!         GroundedInput::text("twice"),
76//!     ];
77//!     let result = machine.infer(&inputs).await?;
78//!
79//!     println!("Output: {:?}", result.output());
80//!     Ok(())
81//! }
82//! ```
83
84pub mod agents;
85pub mod app;
86pub mod cache;
87pub mod config;
88pub mod knowledge;
89pub mod neural;
90pub mod nsr;
91pub mod reasoning;
92pub mod utils;
93
94#[cfg(feature = "server")]
95pub mod api;
96
97// Re-exports for convenient access
98pub use agents::{AgentContext, AgentDecision, ReasoningAgent};
99pub use cache::{Cache, CacheConfig, CacheStats, EmbeddingCache, InferenceCache};
100pub use config::{KnowledgeConfig, NSRConfig, NeuralConfig, ReasoningConfig};
101pub use knowledge::Substitution;
102pub use knowledge::{
103    query::{Query, QueryResult},
104    Constraint, Entity, KnowledgeBase, Relation, Rule, Triple,
105};
106pub use neural::{
107    inference::{InferenceEngine, InferenceResult},
108    Embedding, EmbeddingModel, NeuralBackend,
109};
110pub use reasoning::{
111    logic::LogicalExpression, Explanation, NSREngine, ReasoningPath, ReasoningResult,
112};
113
114// Re-export error types for library consumers to match on specific errors
115pub use nsr::error::{
116    GSSError, LLMSynthesisError, LearningError, MCTSError, NSRError, NSRResult, ParserError,
117    PerceptionError, ProgramError, VSAError,
118};
119
120/// Crate version extracted from Cargo.toml at compile time.
121pub const VERSION: &str = env!("CARGO_PKG_VERSION");
122
123/// Prelude module for common imports
124pub mod prelude {
125    pub use crate::{
126        AgentContext, Embedding, Entity, KnowledgeBase, NSRConfig, NSREngine, NeuralBackend,
127        ReasoningAgent, ReasoningConfig, ReasoningResult, Relation, Rule, Triple, VERSION,
128    };
129    // Provide both anyhow::Result for convenience and NSRResult for typed errors
130    pub use crate::{NSRError, NSRResult};
131    pub use anyhow::Result;
132    pub use async_trait::async_trait;
133}
stateset_nsr/lib.rs

stateset_nsr/
lib.rs
