llm_agent_runtime/
lib.rs

1//! # agent-runtime
2//!
3//! A unified Tokio agent runtime that brings together orchestration, memory,
4//! knowledge graph, and a ReAct agent loop in a single crate.
5//!
6//! ## Feature Flags
7//!
8//! | Feature | Content |
9//! |---------|---------|
10//! | `orchestrator` (default) | Circuit breaker, retry, dedup, backpressure, pipeline |
11//! | `memory` (default) | Episodic, semantic, working memory + decay |
12//! | `graph` (default) | In-memory knowledge graph (BFS/DFS/shortest-path) |
13//! | `wasm` | ReAct agent loop, tool registry |
14//! | `full` | All of the above |
15//!
16//! ## Quick Start
17//!
18//! ```rust,no_run
19//! use llm_agent_runtime::prelude::*;
20//!
21//! // build() is now infallible — the typestate pattern enforces that
22//! // with_agent_config() is called before build() at compile time.
23//! let runtime = AgentRuntime::builder()
24//!     .with_agent_config(AgentConfig::new(5, "my-model"))
25//!     .build();
26//!
27//! // run_agent is async; drive it with your async runtime.
28//! // tokio::runtime::Runtime::new().unwrap().block_on(async {
29//! //     let session = runtime
30//! //         .run_agent(AgentId::new("agent-1"), "Hello", |_ctx: String| async {
31//! //             "Thought: done\nAction: FINAL_ANSWER hi".to_string()
32//! //         })
33//! //         .await
34//! //         .unwrap();
35//! //     println!("Steps: {}", session.step_count());
36//! // });
37//! ```
38//!
39//! ## Extension Points
40//!
41//! The primary extension point is the [`PersistenceBackend`] trait (enabled by
42//! the `persistence` feature). Implement it to persist agent sessions and
43//! per-step checkpoints to any storage backend — disk, Redis, S3, or a
44//! database. The bundled [`FilePersistenceBackend`] stores each checkpoint as a
45//! `<key>.bin` file in a local directory and serves as a reference
46//! implementation.
47//!
48//! Additional extension points:
49//! - [`LlmProvider`] (`providers` feature) — plug in any LLM API.
50//! - `CircuitBreakerBackend` (`redis-circuit-breaker` feature) — distributed
51//!   circuit-breaker state via Redis.
52//!
53//! ## Upstream Crates
54//!
55//! This crate implements standalone versions of the APIs from:
56//! - `tokio-prompt-orchestrator` (Mattbusel/tokio-prompt-orchestrator)
57//! - `tokio-agent-memory` (Mattbusel/tokio-agent-memory)
58//! - `mem-graph` (Mattbusel/mem-graph)
59//! - `wasm-agent` (Mattbusel/wasm-agent)
60//! - `tokio-memory` (Mattbusel/tokio-memory)
61
62// Enforce documentation on all public items in production code.
63#![deny(missing_docs)]
64
65// ── Public modules ─────────────────────────────────────────────────────────
66
67pub mod util;
68
69pub mod error;
70pub mod prelude;
71pub mod types;
72
73#[cfg(feature = "memory")]
74pub mod memory;
75
76#[cfg(feature = "graph")]
77pub mod graph;
78
79#[cfg(feature = "orchestrator")]
80pub mod orchestrator;
81
82pub mod agent;
83pub mod metrics;
84pub mod runtime;
85
86#[cfg(feature = "persistence")]
87pub mod persistence;
88
89#[cfg(feature = "providers")]
90pub mod providers;
91
92// ── Top-level re-exports ────────────────────────────────────────────────────
93
94pub use error::AgentRuntimeError;
95
96pub use runtime::{AgentRuntime, AgentRuntimeBuilder, AgentSession};
97
98// Core identifier types — always available.
99pub use types::{AgentId, MemoryId};
100
101// Memory-specific re-exports.
102#[cfg(feature = "memory")]
103pub use memory::MemoryItem;
104
105#[cfg(feature = "graph")]
106pub use graph::{Entity, EntityId, GraphStore, Relationship};
107
108#[cfg(feature = "orchestrator")]
109pub use orchestrator::{CircuitBreaker, Pipeline, RetryKind, RetryPolicy};
110
111pub use agent::{Action, AgentConfig, ReActLoop, ReActStep, ToolSpec, ToolValidator};
112pub use metrics::MetricsSnapshot;
113
114#[cfg(feature = "persistence")]
115pub use persistence::{FilePersistenceBackend, PersistenceBackend};
116
117#[cfg(feature = "providers")]
118pub use providers::LlmProvider;
llm_agent_runtime/lib.rs

llm_agent_runtime/
lib.rs
