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 18 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//! | [`policy`] | Deny-by-default policy engine |
25//! | [`sandbox`] | Sandboxed execution (workdir jail, resource limits) |
26//! | [`audit`] | Tamper-evident audit log (HMAC-SHA256 chained) |
27//! | [`mcp`] | MCP client + server (JSON-RPC 2.0 over stdio + SSE) |
28//! | [`swarm`] | Swarm orchestration, worker profiles, health monitoring |
29//! | [`heartbeat`] | Autonomous heartbeat agent |
30//! | [`background`] | Background task manager with disk persistence |
31//! | [`scheduler`] | Scheduling & triggers (cron, webhook, file-watch) |
32//! | [`server`] | HTTP server mode (health, readiness, metrics) |
33//! | [`telemetry`] | OpenTelemetry tracing (OTLP gRPC/stdout) |
34//! | [`ravenfabric`] | RavenFabric mesh client |
35//! | [`eval`] | Eval harness with assertions and run traces |
36//! | [`error`] | Unified error types |
37//!
38//! ## Quick Start
39//!
40//! ```rust,no_run
41//! use ravenclaws::config::Config;
42//! use ravenclaws::llm::{create_client, LLMProviderTrait};
43//!
44//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
45//! let config = Config::load(None)?;
46//! let llm = create_client(&config.llm)?;
47//! let response = llm.chat(vec![
48//!     ravenclaws::llm::ChatMessage {
49//!         role: "user".to_string(),
50//!         content: "Hello!".to_string(),
51//!     },
52//! ]).await?;
53//! println!("{}", response.choices[0].message.content);
54//! # Ok(())
55//! # }
56//! ```
57//!
58//! ## Security
59//!
60//! RavenClaws uses a deny-by-default security model:
61//! - All tool calls are validated by [`PolicyEngine`] before execution
62//! - Shell commands execute in a [`Sandbox`] with resource limits
63//! - All operations are logged to a tamper-evident [`AuditLog`]
64//! - API keys are zeroized on drop
65//!
66//! ## Feature Flags
67//!
68//! - `otel-grpc` (default) — OpenTelemetry tracing via OTLP gRPC exporter
69//! - `otel-stdout` — OpenTelemetry tracing via stdout exporter
70//!
71//! ## Minimum Supported Rust Version (MSRV)
72//!
73//! Rust 1.86 or later. This crate uses edition 2021.
74//!
75//! ## Semver Guarantees
76//!
77//! RavenClaws follows semantic versioning. The public API consists of all items
78//! documented in this module and re-exported below. Items marked `#[doc(hidden)]`
79//! or in `__private` modules are not part of the public API and may change in
80//! minor releases.
81//!
82//! All public enums and structs are `#[non_exhaustive]` — new variants/fields may
83//! be added in minor releases. Match statements on enums must include a wildcard
84//! arm, and struct literals must use `..` syntax.
85
86pub mod agent;
87pub mod audit;
88pub mod background;
89pub mod config;
90pub mod error;
91pub mod eval;
92pub mod heartbeat;
93pub mod llm;
94pub mod mcp;
95pub mod patterns;
96pub mod policy;
97pub mod ravenfabric;
98pub mod sandbox;
99pub mod scheduler;
100pub mod server;
101pub mod swarm;
102pub mod telemetry;
103pub mod tools;
104
105// ── Re-exports of commonly used types ──────────────────────────────────────
106
107pub use agent::{
108    delete_checkpoint, load_checkpoint, run_agent_loop, run_agent_loop_with_mcp,
109    run_agent_loop_with_mcp_and_registry, run_agent_loop_with_registry, save_checkpoint,
110    AgentLoopConfig, CheckpointState, ConversationMemory,
111};
112pub use audit::AuditLog;
113pub use background::BackgroundTaskManager;
114pub use config::{
115    Config, LLMConfig, LLMProvider, McpConfig, McpServerConfig, RuntimeConfig, SecurityConfig,
116};
117pub use error::RavenClawsError;
118pub use eval::EvalRunner;
119pub use heartbeat::HeartbeatAgent;
120pub use llm::{create_client, ChatMessage, ChatResponse, LLMProviderTrait, MultiModelManager};
121pub use mcp::{McpClient, McpClientManager, McpServer, McpSseServer};
122pub use patterns::{
123    run_debate, run_debate_multi, run_research_synthesize, run_research_synthesize_multi,
124    run_review_loop, run_review_loop_multi, run_voting, run_voting_multi, PatternConfig,
125};
126pub use policy::PolicyEngine;
127pub use ravenfabric::RavenFabricClient;
128pub use sandbox::Sandbox;
129pub use scheduler::Scheduler;
130pub use server::run_server;
131pub use swarm::SwarmOrchestrator;
132pub use telemetry::TelemetryGuard;
133pub use tools::{ToolCall, ToolImpl, ToolRegistry, ToolResult};
ravenclaws/lib.rs

ravenclaws/
lib.rs
