soul_core/
lib.rs

1//! # soul-core
2//!
3//! Async agentic runtime for Rust — the engine that powers autonomous agent loops
4//! with steerable execution, multi-provider LLM abstraction, and semantic context management.
5//!
6//! ## Quick Start
7//!
8//! ```rust,no_run
9//! use soul_core::semantic_recursion::{SemanticContextEngine, RetrievalQuery};
10//!
11//! let mut engine = SemanticContextEngine::new();
12//!
13//! // Ingest a conversation
14//! let req = engine.ingest_user_request("Explain Rust async");
15//! let resp = engine.ingest_llm_response("Rust async uses tokio...", req, Some("claude"));
16//!
17//! // Symlink for compact references
18//! let hash = engine.symlink_node(req).unwrap();
19//! // hash is a 6-char hex like "A3F2B1"
20//!
21//! // Fragment long messages into semantic clusters
22//! let fragments = engine.symlink_fragmented(resp);
23//! // Each cluster gets its own symlink hash
24//!
25//! // Retrieve relevant context with token budget
26//! let window = engine.retrieve(&RetrievalQuery {
27//!     text: "async programming".into(),
28//!     max_tokens: 4000,
29//!     max_results: 5,
30//!     include_graph_neighbors: true,
31//! });
32//! ```
33//!
34//! ## Architecture
35//!
36//! The crate is organized into these core modules:
37//!
38//! | Module | Purpose |
39//! |--------|---------|
40//! | [`types`] | Core types: `Message`, `Role`, `ContentBlock`, `ToolDefinition`, `AgentConfig` |
41//! | [`provider`] | Multi-provider LLM abstraction (Anthropic, OpenAI) with SSE streaming |
42//! | [`agent`] | Steerable agent loop with tool execution, compaction triggers, interruption |
43//! | [`context`] | Token-aware context window management with compaction and circuit breaker |
44//! | [`session`] | JSONL-based session persistence with lane serialization |
45//! | [`tool`] | Async tool trait and registry for agent tool execution |
46//! | [`hook`] | Three-tier hook pipeline: modifying (sequential), void (parallel), persist (hot path) |
47//! | [`subagent`] | Subagent spawner for parallel task delegation |
48//! | [`memory`] | Hierarchical memory (MEMORY.md + topic files, bootstrap files) |
49//! | [`error`] | Error types with thiserror: Provider, RateLimited, Auth, ContextOverflow, etc. |
50//! | [`planner`] | Task graph with dependencies, status tracking, timing, and display rendering |
51//! | [`rlm`] | Context-as-document engine — agent's conversation history managed via DSL REPL (infinite context) |
52//! | [`semantic_recursion`] | Knowledge graph context engine — symlinks, TF-IDF, semantic fragmentation (infinite context) |
53//!
54//! ## Context Management: The Core Innovation
55//!
56//! The [`semantic_recursion`] module implements a "social graph for LLM context":
57//!
58//! - **Graph nodes** represent every piece of context: user requests, LLM responses,
59//!   tool calls, external data, compaction summaries
60//! - **Graph edges** encode relationships: RespondsTo, FollowsInSequence, CompactedInto,
61//!   TriggeredTool, ProvidesData, DerivedFrom
62//! - **Nothing is ever deleted** — compaction deactivates nodes but preserves them with
63//!   CompactedInto edges. `full_ancestry()` traces through any depth back to originals
64//! - **Symlinks** replace messages with 6-char hash references (`[A3F2B1]: summary`).
65//!   LLMs can call `resolve_symlink` tool to expand any hash
66//! - **Semantic fragmentation** splits messages into clusters via agglomerative clustering
67//!   on TF-IDF embeddings. Close sentences group together, distant content gets separate symlinks
68//! - **Token-budgeted retrieval** combines keyword relevance, vector similarity, and graph
69//!   neighbor expansion to craft optimal context windows per task
70
71pub mod agent;
72pub mod context;
73pub mod cost;
74pub mod error;
75pub mod executor;
76pub mod gateway;
77#[cfg(feature = "native")]
78pub mod harness;
79pub mod hook;
80pub mod lua;
81pub mod mcp;
82pub mod memory;
83pub mod observation;
84pub mod permission;
85pub mod planner;
86#[cfg(feature = "native")]
87pub mod policy;
88pub mod provider;
89pub mod rlm;
90pub mod semantic_recursion;
91pub mod session;
92pub mod skill;
93pub mod snapshot;
94pub mod soullog;
95pub mod subagent;
96pub mod tool;
97pub mod types;
98pub mod vexec;
99pub mod vfs;
100
101pub use error::SoulError;
102pub use types::*;
soul_core/lib.rs

soul_core/
lib.rs
