ares/
lib.rs

1//! # A.R.E.S - Agentic Retrieval Enhanced Server
2//!
3//! A production-grade agentic chatbot server built in Rust with multi-provider
4//! LLM support, tool calling, RAG, MCP integration, and advanced research capabilities.
5//!
6//! ## Overview
7//!
8//! A.R.E.S can be used in two ways:
9//!
10//! 1. **As a standalone server** - Run the `ares-server` binary
11//! 2. **As a library** - Import components into your own Rust project
12//!
13//! ## Quick Start (Library Usage)
14//!
15//! Add to your `Cargo.toml`:
16//!
17//! ```toml
18//! [dependencies]
19//! ares-server = "0.2"
20//! ```
21//!
22//! ### Basic Example
23//!
24//! ```rust,ignore
25//! use ares::{Provider, LLMClient};
26//!
27//! #[tokio::main]
28//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
29//!     // Create an Ollama provider
30//!     let provider = Provider::Ollama {
31//!         base_url: "http://localhost:11434".to_string(),
32//!         model: "llama3.2:3b".to_string(),
33//!     };
34//!
35//!     // Create a client and generate a response
36//!     let client = provider.create_client().await?;
37//!     let response = client.generate("Hello, world!").await?;
38//!     println!("{}", response);
39//!
40//!     Ok(())
41//! }
42//! ```
43//!
44//! ### Using Tools
45//!
46//! ```rust,ignore
47//! use ares::{ToolRegistry, tools::calculator::Calculator};
48//! use std::sync::Arc;
49//!
50//! let mut registry = ToolRegistry::new();
51//! registry.register(Arc::new(Calculator));
52//!
53//! // Tools can be used with LLM function calling
54//! let tool_definitions = registry.definitions();
55//! ```
56//!
57//! ### Multi-Turn Tool Calling with ToolCoordinator
58//!
59//! ```rust,ignore
60//! use ares::llm::{Provider, ToolCoordinator, ToolCallingConfig};
61//! use ares::tools::ToolRegistry;
62//! use std::sync::Arc;
63//!
64//! let provider = Provider::from_env()?;
65//! let client = provider.create_client().await?;
66//! let registry = Arc::new(ToolRegistry::new());
67//!
68//! // Create a unified coordinator that works with any LLM provider
69//! let coordinator = ToolCoordinator::new(client, registry, ToolCallingConfig::default());
70//!
71//! // Execute a tool-calling conversation
72//! let result = coordinator.execute(Some("You are a helpful assistant."), "What is 25 * 4?").await?;
73//! println!("Response: {}", result.content);
74//! println!("Tool calls made: {}", result.tool_calls.len());
75//! ```
76//!
77//! ### Configuration-Driven Setup
78//!
79//! ```rust,ignore
80//! use ares::{AresConfigManager, AgentRegistry, ProviderRegistry, ToolRegistry};
81//! use std::sync::Arc;
82//!
83//! // Load configuration from ares.toml
84//! let config_manager = AresConfigManager::new("ares.toml")?;
85//! let config = config_manager.config();
86//!
87//! // Create registries from configuration
88//! let provider_registry = Arc::new(ProviderRegistry::from_config(&config));
89//! let tool_registry = Arc::new(ToolRegistry::with_config(&config));
90//! let agent_registry = AgentRegistry::from_config(
91//!     &config,
92//!     provider_registry,
93//!     tool_registry,
94//! );
95//! ```
96//!
97//! ## Feature Flags
98//!
99//! | Feature | Description |
100//! |---------|-------------|
101//! | `ollama` | Ollama local inference (default) |
102//! | `openai` | OpenAI API support |
103//! | `llamacpp` | Direct GGUF model loading |
104//! | `local-db` | Local SQLite database (default) |
105//! | `turso` | Remote Turso database |
106//! | `qdrant` | Qdrant vector database |
107//! | `mcp` | Model Context Protocol support |
108//!
109//! ## Modules
110//!
111//! - [`agents`] - Agent framework for multi-agent orchestration
112//! - [`api`] - REST API handlers and routes
113//! - [`auth`] - JWT authentication and middleware
114//! - [`db`] - Database abstraction (SQLite, Turso)
115//! - [`llm`] - LLM client implementations
116//! - [`tools`] - Tool definitions and registry
117//! - [`workflows`] - Declarative workflow engine
118//! - [`types`] - Common types and error handling
119//!
120//! ## Architecture
121//!
122//! A.R.E.S uses a hybrid configuration system:
123//!
124//! - **TOML** (`ares.toml`): Infrastructure config (server, auth, providers)
125//! - **TOON** (`config/*.toon`): Behavioral config (agents, models, tools)
126//!
127//! Both support hot-reloading for zero-downtime configuration changes.
128
129#![cfg_attr(docsrs, feature(doc_cfg))]
130#![warn(missing_docs)]
131#![warn(rustdoc::missing_crate_level_docs)]
132
133/// AI agent orchestration and management.
134pub mod agents;
135/// HTTP API handlers and routes.
136pub mod api;
137/// JWT authentication and middleware.
138pub mod auth;
139/// Command-line interface and scaffolding.
140pub mod cli;
141/// Database clients (Turso/SQLite, Qdrant).
142pub mod db;
143/// LLM provider clients and abstractions.
144pub mod llm;
145/// Model Context Protocol (MCP) server integration.
146#[cfg(feature = "mcp")]
147pub mod mcp;
148/// Conversation memory and context management.
149pub mod memory;
150/// Retrieval Augmented Generation (RAG) components.
151pub mod rag;
152/// Multi-agent research coordination.
153pub mod research;
154/// Built-in tools (calculator, web search).
155pub mod tools;
156/// Core types (requests, responses, errors).
157pub mod types;
158/// Configuration utilities (TOML, TOON).
159pub mod utils;
160/// Workflow engine for agent orchestration.
161pub mod workflows;
162
163// Re-export commonly used types
164pub use agents::{AgentRegistry, AgentRegistryBuilder};
165pub use db::TursoClient;
166pub use llm::client::LLMClientFactoryTrait;
167pub use llm::{
168    ConfigBasedLLMFactory, LLMClient, LLMClientFactory, LLMResponse, Provider, ProviderRegistry,
169};
170pub use tools::registry::ToolRegistry;
171pub use types::{AppError, ErrorCode, Result};
172pub use utils::toml_config::{AresConfig, AresConfigManager};
173pub use utils::toon_config::DynamicConfigManager;
174pub use workflows::{WorkflowEngine, WorkflowOutput, WorkflowStep};
175
176use crate::auth::jwt::AuthService;
177use std::sync::Arc;
178
179/// Application state shared across handlers
180#[derive(Clone)]
181pub struct AppState {
182    /// TOML-based infrastructure configuration with hot-reload support
183    pub config_manager: Arc<AresConfigManager>,
184    /// TOON-based dynamic behavioral configuration with hot-reload support
185    pub dynamic_config: Arc<DynamicConfigManager>,
186    /// Database client
187    pub turso: Arc<TursoClient>,
188    /// LLM client factory (config-based)
189    pub llm_factory: Arc<ConfigBasedLLMFactory>,
190    /// Provider registry for model/provider management
191    pub provider_registry: Arc<ProviderRegistry>,
192    /// Agent registry for creating config-driven agents
193    pub agent_registry: Arc<AgentRegistry>,
194    /// Tool registry for agent tools
195    pub tool_registry: Arc<ToolRegistry>,
196    /// Authentication service
197    pub auth_service: Arc<AuthService>,
198}
ares/lib.rs

ares/
lib.rs
