ceylon_runtime/
lib.rs

1//! # Ceylon Runtime
2//!
3//! A Rust-based agent mesh framework for building local and distributed AI agent systems.
4//!
5//! ## Architecture
6//!
7//! Ceylon Runtime is modular, split into focused sub-crates that are re-exported here:
8//!
9//! | Crate | Description |
10//! |-------|-------------|
11//! | [`core`] | Core abstractions: Agent, Memory, Mesh, Message |
12//! | [`llm`] | LLM integration with 13+ providers |
13//! | [`local`] | Local mesh implementation |
14//! | [`memory`] | Memory backend implementations |
15//! | [`logging`]/[`metrics`] | Observability |
16//! | [`mcp`] | Model Context Protocol (feature: `mcp`) |
17//!
18//! ## Features
19//!
20//! - **Agent Framework**: Build autonomous AI agents with a simple trait-based API
21//! - **Local Mesh**: Connect multiple agents for inter-agent communication
22//! - **LLM Integration**: Built-in support for OpenAI, Anthropic, Ollama, Google, and 10+ more
23//! - **Memory Backends**: Pluggable memory (in-memory, SQLite, Redis)
24//! - **TOML Configuration**: Load agents from config files
25//! - **Async-first**: Built on Tokio for high performance
26//! - **Observability**: Structured logging and metrics
27//!
28//! ## Quick Start
29//!
30//! ### Custom Agent
31//!
32//! ```rust,no_run
33//! use ceylon_runtime::{Agent, AgentContext, LocalMesh, Message};
34//! use ceylon_runtime::core::error::Result;
35//! use ceylon_runtime::core::mesh::Mesh;
36//! use async_trait::async_trait;
37//!
38//! struct MyAgent { name: String }
39//!
40//! #[async_trait]
41//! impl Agent for MyAgent {
42//!     fn name(&self) -> String { self.name.clone() }
43//!
44//!     async fn on_message(&mut self, msg: Message, _ctx: &mut AgentContext) -> Result<()> {
45//!         println!("Received: {:?}", msg.topic);
46//!         Ok(())
47//!     }
48//! }
49//!
50//! #[tokio::main]
51//! async fn main() -> anyhow::Result<()> {
52//!     let mesh = LocalMesh::new("my-mesh");
53//!     mesh.add_agent(Box::new(MyAgent { name: "agent".into() })).await?;
54//!     mesh.start().await?;
55//!     Ok(())
56//! }
57//! ```
58//!
59//! ### LLM Agent
60//!
61//! ```rust,no_run
62//! use ceylon_runtime::{LlmAgent, AgentContext};
63//!
64//! #[tokio::main]
65//! async fn main() -> anyhow::Result<()> {
66//!     let mut agent = LlmAgent::builder("assistant", "ollama::gemma3:latest")
67//!         .with_system_prompt("You are helpful.")
68//!         .with_temperature(0.7)
69//!         .build()?;
70//!
71//!     let mut ctx = AgentContext::new("test".into(), None);
72//!     let response = agent.send_message_and_get_response("Hello!", &mut ctx).await?;
73//!     println!("{}", response);
74//!     Ok(())
75//! }
76//! ```
77//!
78//! ### TOML Configuration
79//!
80//! ```rust,no_run
81//! use ceylon_runtime::{LlmAgent, LlmAgentFromConfig};
82//! use ceylon_runtime::config::AgentConfig;
83//!
84//! let config = AgentConfig::from_file("agent.toml").unwrap();
85//! let agent = LlmAgent::from_config(config).unwrap();
86//! ```
87//!
88//! ## Feature Flags
89//!
90//! - `sqlite` - SQLite memory backend
91//! - `redis` - Redis memory backend  
92//! - `mcp` - Model Context Protocol support
93//! - `full` - All optional features
94
95// Configuration module
96pub mod config;
97
98// Re-export sub-crates as modules
99pub use ceylon_core as core;
100pub use ceylon_llm as llm;
101pub use ceylon_local as local;
102pub use ceylon_memory as memory;
103pub use ceylon_observability::logging;
104pub use ceylon_observability::metrics;
105
106#[cfg(feature = "mcp")]
107pub use ceylon_mcp as mcp;
108
109// Convenience re-exports at crate root
110pub use ceylon_core::{
111    Agent, AgentContext, Memory, MemoryEntry, MemoryQuery, Mesh, Message, VectorMemory,
112};
113pub use ceylon_llm::{LLMConfig, LlmAgent, LlmAgentBuilder, UniversalLLMClient};
114pub use ceylon_local::LocalMesh;
115pub use ceylon_memory::InMemoryBackend;
116pub use config::{AgentConfig, MeshConfig};
117
118#[cfg(feature = "sqlite")]
119pub use ceylon_memory::SqliteBackend;
120
121#[cfg(feature = "redis")]
122pub use ceylon_memory::RedisBackend;
123
124#[cfg(feature = "mcp")]
125pub use ceylon_mcp::{McpAgentServer, McpClient, McpTransport};
126
127/// Extension trait for creating [`LlmAgent`] from TOML configuration.
128///
129/// Import this trait to use [`LlmAgent::from_config`]:
130///
131/// ```rust,no_run
132/// use ceylon_runtime::{LlmAgent, LlmAgentFromConfig};
133/// use ceylon_runtime::config::AgentConfig;
134///
135/// let config = AgentConfig::from_file("agent.toml").unwrap();
136/// let agent = LlmAgent::from_config(config).unwrap();
137/// ```
138pub trait LlmAgentFromConfig {
139    /// Create an LlmAgent from an [`AgentConfig`].
140    fn from_config(config: AgentConfig) -> core::error::Result<LlmAgent>;
141}
142
143impl LlmAgentFromConfig for LlmAgent {
144    fn from_config(config: AgentConfig) -> core::error::Result<LlmAgent> {
145        let mut builder = LlmAgentBuilder::new(&config.name, &config.model)
146            .with_system_prompt(&config.system_prompt);
147
148        if let Some(ref api_key) = config.api_key {
149            builder = builder.with_api_key(api_key);
150        }
151
152        if let Some(temperature) = config.temperature {
153            builder = builder.with_temperature(temperature);
154        }
155
156        if let Some(max_tokens) = config.max_tokens {
157            builder = builder.with_max_tokens(max_tokens);
158        }
159
160        builder.build()
161    }
162}
ceylon_runtime/lib.rs

ceylon_runtime/
lib.rs
