ares/

lib.rs

//! # A.R.E.S - Agentic Retrieval Enhanced Server
//!
//! A production-grade agentic chatbot server built in Rust with multi-provider
//! LLM support, tool calling, RAG, MCP integration, and advanced research capabilities.
//!
//! ## Overview
//!
//! A.R.E.S can be used in two ways:
//!
//! 1. **As a standalone server** - Run the `ares-server` binary
//! 2. **As a library** - Import components into your own Rust project
//!
//! ## Quick Start (Library Usage)
//!
//! Add to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! ares-server = "0.5"
//! ```
//!
//! ### Basic Example
//!
//! ```rust,ignore
//! use ares::{Provider, LLMClient};
//!
//! #[tokio::main]
//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
//!     // Create an Ollama provider
//!     let provider = Provider::Ollama {
//!         base_url: "http://localhost:11434".to_string(),
//!         model: "llama3.2:3b".to_string(),
//!     };
//!
//!     // Create a client and generate a response
//!     let client = provider.create_client().await?;
//!     let response = client.generate("Hello, world!").await?;
//!     println!("{}", response);
//!
//!     Ok(())
//! }
//! ```
//!
//! ### Using Tools
//!
//! ```rust,ignore
//! use ares::{ToolRegistry, tools::calculator::Calculator};
//! use std::sync::Arc;
//!
//! let mut registry = ToolRegistry::new();
//! registry.register(Arc::new(Calculator));
//!
//! // Tools can be used with LLM function calling
//! let tool_definitions = registry.definitions();
//! ```
//!
//! ### Multi-Turn Tool Calling with ToolCoordinator
//!
//! ```rust,ignore
//! use ares::llm::{Provider, ToolCoordinator, ToolCallingConfig};
//! use ares::tools::ToolRegistry;
//! use std::sync::Arc;
//!
//! let provider = Provider::from_env()?;
//! let client = provider.create_client().await?;
//! let registry = Arc::new(ToolRegistry::new());
//!
//! // Create a unified coordinator that works with any LLM provider
//! let coordinator = ToolCoordinator::new(client, registry, ToolCallingConfig::default());
//!
//! // Execute a tool-calling conversation
//! let result = coordinator.execute(Some("You are a helpful assistant."), "What is 25 * 4?").await?;
//! println!("Response: {}", result.content);
//! println!("Tool calls made: {}", result.tool_calls.len());
//! ```
//!
//! ### Configuration-Driven Setup
//!
//! ```rust,ignore
//! use ares::{AresConfigManager, AgentRegistry, ProviderRegistry, ToolRegistry};
//! use std::sync::Arc;
//!
//! // Load configuration from ares.toml
//! let config_manager = AresConfigManager::new("ares.toml")?;
//! let config = config_manager.config();
//!
//! // Create registries from configuration
//! let provider_registry = Arc::new(ProviderRegistry::from_config(&config));
//! let tool_registry = Arc::new(ToolRegistry::with_config(&config));
//! let agent_registry = AgentRegistry::from_config(
//!     &config,
//!     provider_registry,
//!     tool_registry,
//! );
//! ```
//!
//! ## Feature Flags
//!
//! | Feature | Description |
//! |---------|-------------|
//! | `ollama` | Ollama local inference (default) |
//! | `openai` | OpenAI API support |
//! | `llamacpp` | Direct GGUF model loading |
//! | `postgres` | PostgreSQL database (default) |
//! | `qdrant` | Qdrant vector database |
//! | `mcp` | Model Context Protocol support |
//!
//! ## Modules
//!
//! - [`agents`] - Agent framework for multi-agent orchestration
//! - [`api`] - REST API handlers and routes
//! - [`auth`] - JWT authentication and middleware
//! - [`db`] - Database abstraction (PostgreSQL)
//! - [`llm`] - LLM client implementations
//! - [`tools`] - Tool definitions and registry
//! - [`workflows`] - Declarative workflow engine
//! - [`types`] - Common types and error handling
//!
//! ## Architecture
//!
//! A.R.E.S uses a hybrid configuration system:
//!
//! - **TOML** (`ares.toml`): Infrastructure config (server, auth, providers)
//! - **TOON** (`config/*.toon`): Behavioral config (agents, models, tools)
//!
//! Both support hot-reloading for zero-downtime configuration changes.

#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_docs)]
#![warn(rustdoc::missing_crate_level_docs)]

/// AI agent orchestration and management.
pub mod agents;
/// HTTP API handlers and routes.
#[cfg(feature = "postgres")]
pub mod api;
/// JWT authentication and middleware.
#[cfg(feature = "postgres")]
pub mod auth;
/// Command-line interface and scaffolding.
pub mod cli;
/// Database clients (Turso/SQLite, Qdrant).
pub mod db;
/// LLM provider clients and abstractions.
pub mod llm;
/// Model Context Protocol (MCP) server integration.
#[cfg(feature = "mcp")]
pub mod mcp;
/// Conversation memory and context management.
pub mod memory;
/// Middleware for API key auth and usage tracking.
#[cfg(feature = "postgres")]
pub mod middleware;
/// Multi-tenant models (Tenant, ApiKey, Quota).
pub mod models;
/// Retrieval Augmented Generation (RAG) components.
pub mod rag;
/// Multi-agent research coordination.
#[cfg(feature = "postgres")]
pub mod research;
/// SKILL.md file discovery and loading (requires `skills` feature).
#[cfg(feature = "skills")]
pub mod skills;
/// Built-in tools (calculator, web search).
pub mod tools;
/// Core types (requests, responses, errors).
pub mod types;
/// Configuration utilities (TOML, TOON).
pub mod utils;
/// Workflow engine for agent orchestration.
#[cfg(feature = "postgres")]
pub mod workflows;

// Re-export commonly used types
pub use agents::{AgentRegistry, AgentRegistryBuilder};
#[cfg(feature = "postgres")]
pub use db::tenants::TenantDb;
#[cfg(feature = "postgres")]
pub use db::PostgresClient;
pub use llm::client::LLMClientFactoryTrait;
pub use llm::{
    ConfigBasedLLMFactory, LLMClient, LLMClientFactory, LLMResponse, Provider, ProviderRegistry,
};
pub use models::{ApiKey, Tenant, TenantContext, TenantQuota, TenantTier};
pub use tools::registry::ToolRegistry;
pub use types::{AppError, ErrorCode, Result};
pub use utils::toml_config::{AresConfig, AresConfigManager};
pub use utils::toon_config::DynamicConfigManager;
#[cfg(feature = "postgres")]
pub use workflows::{WorkflowEngine, WorkflowOutput, WorkflowStep};

use std::sync::Arc;

/// Application state shared across handlers (requires postgres feature for full server)
#[cfg(feature = "postgres")]
use crate::auth::jwt::AuthService;

/// Application state shared across handlers
#[cfg(feature = "postgres")]
#[derive(Clone)]
pub struct AppState {
    /// TOML-based infrastructure configuration with hot-reload support
    pub config_manager: Arc<AresConfigManager>,
    /// TOON-based dynamic behavioral configuration with hot-reload support
    pub dynamic_config: Arc<DynamicConfigManager>,
    /// Database client
    pub db: Arc<dyn crate::db::traits::DatabaseClient>,
    /// Multi-tenant database
    pub tenant_db: Arc<TenantDb>,
    /// LLM client factory (config-based)
    pub llm_factory: Arc<ConfigBasedLLMFactory>,
    /// Provider registry for model/provider management
    pub provider_registry: Arc<ProviderRegistry>,
    /// Agent registry for creating config-driven agents
    pub agent_registry: Arc<AgentRegistry>,
    /// Tool registry for agent tools
    pub tool_registry: Arc<ToolRegistry>,
    /// Authentication service
    pub auth_service: Arc<AuthService>,
    /// MCP client registry for external services like Eruka
    #[cfg(feature = "mcp")]
    pub mcp_registry: Option<Arc<crate::mcp::McpRegistry>>,
    /// Deploy registry for tracking deployment operations
    pub deploy_registry: crate::api::handlers::deploy::DeployRegistry,
    /// Emergency stop flag — when true, all agent requests are rejected with 503.
    /// Set/cleared via POST /api/admin/agents/emergency-stop.
    pub emergency_stop: Arc<std::sync::atomic::AtomicBool>,
    /// External context provider for agent calls.
    /// OSS: NoOpContextProvider. Managed: ErukaContextProvider (from dirmacs-core).
    pub context_provider: Arc<dyn crate::agents::context_provider::ContextProvider>,
}

/// Returns the base ARES router with all generic endpoints.
///
/// Extension crates can `.merge()` additional routes and `.layer()` middleware
/// on top of this to build managed platform binaries.
///
/// # Example
///
/// ```rust,ignore
/// use ares::{base_router, AppState};
///
/// let app = base_router(state.clone())
///     .merge(my_custom_routes(state.clone()))
///     .layer(my_custom_middleware());
/// ```
#[cfg(feature = "postgres")]
pub fn base_router(state: AppState) -> axum::Router {
    axum::Router::new()
        .route("/health", axum::routing::get(|| async { "OK" }))
        .nest(
            "/api",
            api::routes::create_router(state.auth_service.clone(), state.tenant_db.clone()),
        )
        .with_state(state)
}