ravenclaws/
lib.rs

1//! # RavenClaws
2//!
3//! Lightweight, secure Rust agent framework with multi-provider LLM support.
4//!
5//! RavenClaws is a single-binary agent runtime that supports:
6//! - **Single agent mode** — one prompt, one response
7//! - **Swarm mode** — multiple parallel agents with different personas
8//! - **Supervisor mode** — task decomposition with sub-agent spawning
9//! - **Heartbeat mode** — autonomous long-running agents
10//! - **REPL mode** — interactive conversation
11//! - **Server mode** — HTTP server with health/metrics endpoints
12//! - **MCP server mode** — expose tools over stdio via MCP protocol
13//!
14//! ## Architecture
15//!
16//! The crate is organized into 20 modules:
17//!
18//! | Module | Purpose |
19//! |---|---|
20//! | [`agent`] | Agent implementations, agent loop, conversation memory |
21//! | [`llm`] | LLM provider abstraction + 5 client implementations |
22//! | [`config`] | Configuration structs, TOML/env loading, validation |
23//! | [`tools`] | Tool abstraction, registry, 5 built-in tools |
24//! | [`persistence`] | SQLite-backed conversation persistence with retention policies |
25//! | [`plugins`] | WASM plugin system for extending RavenClaws without recompiling |
26//! | [`policy`] | Deny-by-default policy engine |
27//! | [`sandbox`] | Sandboxed execution (workdir jail, resource limits) |
28//! | [`audit`] | Tamper-evident audit log (HMAC-SHA256 chained) |
29//! | [`mcp`] | MCP client + server (JSON-RPC 2.0 over stdio + SSE) |
30//! | [`swarm`] | Swarm orchestration, worker profiles, health monitoring |
31//! | [`heartbeat`] | Autonomous heartbeat agent |
32//! | [`background`] | Background task manager with disk persistence |
33//! | [`scheduler`] | Scheduling & triggers (cron, webhook, file-watch) |
34//! | [`server`] | HTTP server mode (health, readiness, metrics) |
35//! | [`telemetry`] | OpenTelemetry tracing (OTLP gRPC/stdout) |
36//! | [`ravenfabric`] | RavenFabric mesh client |
37//! | [`eval`] | Eval harness with assertions and run traces |
38//! | [`error`] | Unified error types |
39//!
40//! ## Quick Start
41//!
42//! ```rust,no_run
43//! use ravenclaws::config::Config;
44//! use ravenclaws::llm::{create_client, LLMProviderTrait};
45//!
46//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
47//! let config = Config::load(None)?;
48//! let llm = create_client(&config.llm)?;
49//! let response = llm.chat(vec![
50//!     ravenclaws::llm::ChatMessage::new("user", "Hello!"),
51//! ]).await?;
52//! println!("{}", response.choices[0].message.content);
53//! # Ok(())
54//! # }
55//! ```
56//!
57//! ## Security
58//!
59//! RavenClaws uses a deny-by-default security model:
60//! - All tool calls are validated by [`PolicyEngine`] before execution
61//! - Shell commands execute in a [`Sandbox`] with resource limits
62//! - All operations are logged to a tamper-evident [`AuditLog`]
63//! - API keys are zeroized on drop
64//!
65//! ## Feature Flags
66//!
67//! - `otel-grpc` (default) — OpenTelemetry tracing via OTLP gRPC exporter
68//! - `otel-stdout` — OpenTelemetry tracing via stdout exporter
69//!
70//! ## Minimum Supported Rust Version (MSRV)
71//!
72//! Rust 1.86 or later. This crate uses edition 2021.
73//!
74//! ## Semver Guarantees
75//!
76//! RavenClaws follows semantic versioning. The public API consists of all items
77//! documented in this module and re-exported below. Items marked `#[doc(hidden)]`
78//! or in `__private` modules are not part of the public API and may change in
79//! minor releases.
80//!
81//! All public enums and structs are `#[non_exhaustive]` — new variants/fields may
82//! be added in minor releases. Match statements on enums must include a wildcard
83//! arm, and struct literals must use `..` syntax.
84
85pub mod agent;
86pub mod audit;
87pub mod background;
88pub mod config;
89pub mod error;
90pub mod eval;
91pub mod heartbeat;
92pub mod llm;
93pub mod load;
94pub mod mcp;
95pub mod patterns;
96pub mod persistence;
97pub mod plugins;
98pub mod policy;
99pub mod ravenfabric;
100pub mod sandbox;
101pub mod scheduler;
102pub mod server;
103pub mod swarm;
104pub mod telemetry;
105pub mod tools;
106
107// ── Re-exports of commonly used types ──────────────────────────────────────
108
109pub use agent::{
110    delete_checkpoint, load_checkpoint, run_agent_loop, run_agent_loop_with_images,
111    run_agent_loop_with_mcp, run_agent_loop_with_mcp_and_images,
112    run_agent_loop_with_mcp_and_registry, run_agent_loop_with_registry, save_checkpoint,
113    AgentLoopConfig, CheckpointState, ConversationMemory,
114};
115pub use audit::AuditLog;
116pub use background::BackgroundTaskManager;
117pub use config::{
118    Config, LLMConfig, LLMProvider, McpConfig, McpServerConfig, RuntimeConfig, SecurityConfig,
119};
120pub use error::RavenClawsError;
121pub use eval::EvalRunner;
122pub use heartbeat::HeartbeatAgent;
123pub use llm::{
124    create_client, load_image, ChatMessage, ChatResponse, ContentPart, ImageUrlContent,
125    LLMProviderTrait, MultiModelManager,
126};
127pub use load::{Admission, LoadConfig, LoadManager, LoadMetrics, RequestOutcome};
128pub use mcp::{McpClient, McpClientManager, McpServer, McpSseServer};
129pub use patterns::{
130    run_debate, run_debate_multi, run_research_synthesize, run_research_synthesize_multi,
131    run_review_loop, run_review_loop_multi, run_voting, run_voting_multi, PatternConfig,
132};
133pub use persistence::{ConversationStore, RetentionPolicy, StoredMessage, StoredSession};
134pub use plugins::{PluginError, PluginTool, WasmPlugin, WasmPluginManager};
135pub use policy::PolicyEngine;
136pub use ravenfabric::RavenFabricClient;
137pub use sandbox::Sandbox;
138pub use scheduler::Scheduler;
139pub use server::run_server;
140pub use swarm::SwarmOrchestrator;
141pub use telemetry::TelemetryGuard;
142pub use tools::{ToolCall, ToolImpl, ToolRegistry, ToolResult};
ravenclaws/lib.rs

ravenclaws/
lib.rs
