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.5"
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//! | `postgres` | PostgreSQL database (default) |
105//! | `qdrant` | Qdrant vector database |
106//! | `mcp` | Model Context Protocol support |
107//!
108//! ## Modules
109//!
110//! - [`agents`] - Agent framework for multi-agent orchestration
111//! - [`api`] - REST API handlers and routes
112//! - [`auth`] - JWT authentication and middleware
113//! - [`db`] - Database abstraction (PostgreSQL)
114//! - [`llm`] - LLM client implementations
115//! - [`tools`] - Tool definitions and registry
116//! - [`workflows`] - Declarative workflow engine
117//! - [`types`] - Common types and error handling
118//!
119//! ## Architecture
120//!
121//! A.R.E.S uses a hybrid configuration system:
122//!
123//! - **TOML** (`ares.toml`): Infrastructure config (server, auth, providers)
124//! - **TOON** (`config/*.toon`): Behavioral config (agents, models, tools)
125//!
126//! Both support hot-reloading for zero-downtime configuration changes.
127
128#![cfg_attr(docsrs, feature(doc_cfg))]
129#![warn(missing_docs)]
130#![warn(rustdoc::missing_crate_level_docs)]
131
132/// AI agent orchestration and management.
133pub mod agents;
134/// HTTP API handlers and routes.
135pub mod api;
136/// JWT authentication and middleware.
137pub mod auth;
138/// Command-line interface and scaffolding.
139pub mod cli;
140/// Database clients (Turso/SQLite, Qdrant).
141pub mod db;
142/// LLM provider clients and abstractions.
143pub mod llm;
144/// Model Context Protocol (MCP) server integration.
145#[cfg(feature = "mcp")]
146pub mod mcp;
147/// Conversation memory and context management.
148pub mod memory;
149/// Multi-tenant models (Tenant, ApiKey, Quota).
150pub mod models;
151/// Middleware for API key auth and usage tracking.
152pub mod middleware;
153/// Retrieval Augmented Generation (RAG) components.
154pub mod rag;
155/// Multi-agent research coordination.
156pub mod research;
157/// Built-in tools (calculator, web search).
158pub mod tools;
159/// Core types (requests, responses, errors).
160pub mod types;
161/// Configuration utilities (TOML, TOON).
162pub mod utils;
163/// Workflow engine for agent orchestration.
164pub mod workflows;
165
166// Re-export commonly used types
167pub use agents::{AgentRegistry, AgentRegistryBuilder};
168pub use db::tenants::TenantDb;
169pub use db::PostgresClient;
170pub use llm::client::LLMClientFactoryTrait;
171pub use llm::{
172    ConfigBasedLLMFactory, LLMClient, LLMClientFactory, LLMResponse, Provider, ProviderRegistry,
173};
174pub use models::{ApiKey, Tenant, TenantContext, TenantQuota, TenantTier};
175pub use tools::registry::ToolRegistry;
176pub use types::{AppError, ErrorCode, Result};
177pub use utils::toml_config::{AresConfig, AresConfigManager};
178pub use utils::toon_config::DynamicConfigManager;
179pub use workflows::{WorkflowEngine, WorkflowOutput, WorkflowStep};
180
181use crate::auth::jwt::AuthService;
182use std::sync::Arc;
183
184/// Application state shared across handlers
185#[derive(Clone)]
186pub struct AppState {
187    /// TOML-based infrastructure configuration with hot-reload support
188    pub config_manager: Arc<AresConfigManager>,
189    /// TOON-based dynamic behavioral configuration with hot-reload support
190    pub dynamic_config: Arc<DynamicConfigManager>,
191    /// Database client
192    pub db: Arc<dyn crate::db::traits::DatabaseClient>,
193    /// Multi-tenant database
194    pub tenant_db: Arc<TenantDb>,
195    /// LLM client factory (config-based)
196    pub llm_factory: Arc<ConfigBasedLLMFactory>,
197    /// Provider registry for model/provider management
198    pub provider_registry: Arc<ProviderRegistry>,
199    /// Agent registry for creating config-driven agents
200    pub agent_registry: Arc<AgentRegistry>,
201    /// Tool registry for agent tools
202    pub tool_registry: Arc<ToolRegistry>,
203    /// Authentication service
204    pub auth_service: Arc<AuthService>,
205    /// MCP client registry for external services like Eruka
206    #[cfg(feature = "mcp")]
207    pub mcp_registry: Option<Arc<crate::mcp::McpRegistry>>,
208    /// Deploy registry for tracking deployment operations
209    pub deploy_registry: crate::api::handlers::deploy::DeployRegistry,
210}
ares/lib.rs

ares/
lib.rs
