paladin-ai 0.1.0

Enterprise AI orchestration framework with multi-agent coordination patterns
Documentation

Paladin

General Overview

Paladin is a Rust-based, modular content processing platform built with Hexagonal Architecture principles. It provides configurable pipelines to ingest, normalize, analyze, enrich, store, and deliver diverse content types (web pages, documents, feeds, and streams) at scale.

Key capabilities include configurable content ingestion, NLP/LLM analysis and summarization, metadata extraction and subject tagging, content filtering and lifecycle management, and flexible delivery channels (HTTP/webhooks, email, push, and queue-based adapters). Clear ports-and-adapters boundaries make integrations, testing, and replacement of components straightforward. Paladin is designed for content aggregation, monitoring, enrichment, and automated delivery workflows where extensibility, observability, and reliable storage across SQL/NoSQL/file backends are important.

Quick Start (CLI)

Paladin provides a powerful command-line interface for quick agent creation and orchestration without writing code:

Installation

# Clone the repository
git clone https://github.com/DF3NDR/paladin-dev-env.git
cd paladin

# Build the CLI
cargo build --release

# The binary will be available at target/release/paladin

Feature Flags

Paladin uses Cargo feature flags to control which dependencies and functionality are compiled. This enables minimal builds for specific use cases.

Default Build (minimal):

[dependencies]
paladin = "0.2.0"  # Only llm-openai enabled

Full Build (all features):

[dependencies]
paladin = { version = "0.2.0", features = ["full"] }

Custom Build (production):

[dependencies]
paladin = { version = "0.2.0", features = ["llm-anthropic", "redis-queue", "s3-storage", "web-server"] }

Available Features

Flag Purpose Dependencies
LLM Providers
llm-openai OpenAI GPT models (default) reqwest
llm-anthropic Anthropic Claude models reqwest
llm-deepseek DeepSeek models reqwest
llm-all All LLM providers All of above
Subsystems
vision Multimodal AI capabilities None
content-processing PDF, web scraping, RSS, tokenization pdf-extract, scraper, tiktoken-rs, rss
web-server REST API server actix-web, axum
notifications Email with templates lettre, handlebars
Infrastructure
redis-queue Redis async queue adapter redis
s3-storage S3/MinIO file storage rust-s3
openai-embeddings OpenAI embedding support None
qdrant Vector database adapter qdrant-client
CLI
cli Command-line tooling (paladin-cli binary) clap, dialoguer, indicatif, console, serde_yaml
Convenience
full All optional features All of above

📖 Documentation: See docs/FEATURE_FLAGS.md for detailed feature documentation and docs/MIGRATION.md for breaking changes.

First-Time Setup

Run the interactive onboarding wizard to configure your environment:

paladin onboarding

This wizard will:

  • Guide you through provider selection (OpenAI, DeepSeek, Anthropic)
  • Help you set up API keys securely
  • Validate your configuration
  • Create a .env file with your settings
  • Generate sample configurations to get started

Quick Commands

# Verify your setup
paladin setup-check

# List available features
paladin features

# Generate an AI workflow from description
paladin muster "Create a 3-step data analysis pipeline" -o pipeline.yaml

# Quick multi-agent discussion
paladin council "Should we adopt microservices?" -n 5

# Run a configuration
paladin run -c examples/cli_configs/basic_paladin.yaml -i "Hello, explain Rust ownership"

# Interactive mode
paladin run -c config.yaml --interactive

Documentation

Workspace Crates

The public crates live under crates/.

Crate Purpose Docs
paladin-core Pure domain types and aggregate roots README, CHANGELOG
paladin-ports Hexagonal architecture contracts README, CHANGELOG
paladin-battalion Multi-agent orchestration runtime README, CHANGELOG
paladin-llm LLM provider adapters README, CHANGELOG
paladin-memory Garrison and Sanctum memory adapters README, CHANGELOG
paladin-web Web server adapters README, CHANGELOG
paladin-notifications Notification adapters README, CHANGELOG
paladin-content Content ingestion and processing adapters README, CHANGELOG
paladin-storage SQL repository adapters README, CHANGELOG

See docs/CLI_USAGE.md for comprehensive CLI documentation.

Architectural Overview

Paladin is an enterprise capable AI Orchestration system designed using hexagonal architecture principles to provide robust and flexible handling of a large range of functionality including processing any type of content (structured documents, test, audio, video, images, etc), notification management (push, email, sms, etc), machine learning integrations (LLM's, ML, etc), and content delivery mechanisms (web servers, streaming, apis, etc).

This project utilizes clearly defined Ports and Adapters, enabling seamless integration with external services such as email, SMS, push notifications, webhooks, machine learning models, and more. The design ensures high modularity, scalability, and ease of maintenance.

Project Structure

  • src/application – Application layer containing use cases, ports, and storage repositories.

    • use_cases – Business logic and services like content aggregation, filtering, summarization, and analysis.
    • ports – Interfaces for interaction with external systems.
    • storage – Abstracts various storage mechanisms (SQL, NoSQL, File storage).

Features

Ports and Adapters

The project clearly defines Ports as interfaces to external systems, enabling adapters to easily integrate specific implementations.

Output Ports:

  • Notification Publisher: Abstracts notification services for channels like Email, SMS, Push, Slack, Discord, etc.
  • Content Delivery: Manages content distribution methods, including HTTP, email, webhooks, and push notifications.
  • Logging: Provides a standardized logging mechanism.
  • Search Engine: Defines interactions with external search services.

Input Ports:

  • Content Ingestion: Facilitates fetching and ingestion of external content.
  • RPC Gateway: Exposes application functionalities via REST, GraphQL, gRPC, etc.
  • Machine Learning (ML): Interfaces with ML models like TensorFlow or PyTorch.
  • LLM Port: Provides integration with Low-Level Models for content analysis.
  • NLP Port: Interfaces with Natural Language Processing services.

Use Cases

  • Content Aggregation and Summarization: Aggregates various content sources and generates concise summaries.
  • Content Filtering: Implements filtering mechanisms based on keywords or criteria.
  • ML and NLP Analysis: Leverages machine learning and NLP models to analyze and enrich content.
  • Subject Tagging and Searching: Advanced tagging, indexing, and search capabilities.
  • Paladin: Autonomous AI agents with memory and context management.
  • Garrison Memory System: Persistent conversation history with windowing and search capabilities.
  • Arsenal Tool System: External tool integration via Model Context Protocol (MCP).
  • Battalion Orchestration: Multi-agent coordination with eight orchestration patterns.
  • Maneuver Flow DSL: String-based workflow orchestration with declarative syntax.
  • Herald Output Formatting: Pluggable formatters (JSON, Markdown, Table) with streaming support.

AI Agent System (Paladin)

Paladin provides a sophisticated AI agent framework with memory management and tool capabilities:

  • Paladins: Autonomous AI agents with configurable behaviors and tool access
  • Garrison Memory: Context-aware conversation history storage
    • InMemoryGarrison: Fast, ephemeral storage for development and testing
    • SqliteGarrison: Persistent storage with full-text search for production
  • Arsenal Tool System: External tool integration via MCP
    • STDIO Transport: Command-line tool execution (Python, Node.js, binaries)
    • SSE Transport: HTTP-based remote tool services
    • Tool Registry: Dynamic tool discovery and registration
    • Resource Controls: Timeout management and concurrency limiting
  • Sanctum Long-term Memory: Persistent, searchable vector memory for agents
    • InMemory Adapter: Fast, ephemeral storage for development (<10,000 entries)
    • Qdrant Adapter: Production-ready vector database (millions of entries, <500ms search)
    • Semantic Search: Find relevant memories using vector similarity
    • Rich Metadata: Filter by paladin ID, memory type, importance, timestamps
    • Memory Types: Episodic (events), Semantic (facts), Procedural (skills)
  • Circuit Breaker: Fault tolerance with automatic retry and backoff
  • Execution Service: Orchestrates agent execution with memory integration

See docs/GARRISON.md for detailed memory system documentation. See docs/ARSENAL.md for comprehensive tool system documentation. See docs/SANCTUM.md for long-term memory system documentation.

RAG (Retrieval-Augmented Generation)

New in Epic 12: Paladin now supports automatic RAG integration, enabling agents to retrieve relevant context from long-term memory and extract new memories after execution.

What is RAG?

  • Automatic Context Retrieval: Fetch relevant memories before generating responses
  • Smart Memory Extraction: Automatically store important facts after conversations
  • Knowledge Building: Accumulate wisdom across multiple sessions
  • Response Quality: Improve accuracy with historical context

Quick Start:

# config.yml
sanctum:
  provider: in_memory  # or 'qdrant' for production

rag:
  top_k: 5                    # Retrieve top 5 relevant memories
  min_similarity: 0.7          # 70% relevance threshold
  max_tokens: 2000             # Context budget
  timeout_seconds: 5           # Retrieval timeout

memory_extraction:
  enabled: true
  strategy: on_completion     # Extract after each conversation

Example Usage:

use paladin::application::use_cases::sanctum::{
    RagRetrievalService, MemoryExtractionService
};

// Create RAG services
let rag_service = Arc::new(RagRetrievalService::new(
    sanctum_port, embedding_port, rag_config
));

let extraction_service = Arc::new(MemoryExtractionService::new(
    llm_port, embedding_port, sanctum_port
));

// Configure Paladin with RAG
let execution_service = PaladinExecutionService::new(llm_port)
    .with_rag_retrieval(rag_service)
    .with_memory_extraction(extraction_service);

// Execute with automatic RAG
let result = execution_service.execute(&paladin, "user input").await?;
// ✓ Context automatically retrieved from Sanctum
// ✓ Response generated with historical context
// ✓ New memories extracted and stored

Benefits:

  • 🧠 Contextual Awareness: Agents remember previous conversations
  • 📈 Improved Accuracy: Responses reference historical knowledge
  • 🔄 Automatic: No manual memory management needed
  • ⚙️ Configurable: Tune retrieval and extraction parameters
  • 🚀 Scalable: Works with both in-memory and Qdrant storage

Learn More:

  • docs/SANCTUM.md#rag-integration - Complete RAG documentation
  • examples/paladin_with_rag.rs - Configuration guide and workflow
  • examples/cli_configs/paladin_rag.yaml - Full configuration example

Multi-Provider LLM Support

Paladin supports multiple LLM providers with a consistent interface, allowing you to choose the best provider for your needs:

  • OpenAI (GPT-4, GPT-3.5-turbo): Mature ecosystem, vision support, production-ready
  • DeepSeek: Cost-effective, strong reasoning capabilities, high throughput
  • Anthropic Claude: Safety-focused, long context (200K tokens), complex analysis

Key Features:

  • Unified LlmPort trait across all providers
  • Hot-swappable providers without code changes
  • Provider-specific capabilities detection
  • Automatic retry with exponential backoff
  • Comprehensive error handling and rate limiting

Configuration Example:

llm:
  default_provider: "openai"  # or "deepseek", "anthropic"

  openai:
    api_key: "${OPENAI_API_KEY}"
    model: "gpt-4"

  deepseek:
    api_key: "${DEEPSEEK_API_KEY}"
    model: "deepseek-chat"

  anthropic:
    api_key: "${ANTHROPIC_API_KEY}"
    model: "claude-3-5-sonnet-20241022"

Programmatic Usage:

// Create adapter
let config = DeepSeekConfig::from_env()?;
let llm_port = Arc::new(DeepSeekAdapter::new(config)?);

// Use with Paladin
let paladin = PaladinBuilder::new(llm_port)
    .system_prompt("You are a helpful assistant")
    .build()?;

See docs/PROVIDER_EXPANSION.md for detailed comparison and migration guide. See docs/CONTRIBUTING_PROVIDERS.md to add new providers.

Vision & Multi-Modal Processing (Sentinel)

New in Epic 13: Paladin now supports vision capabilities, enabling agents to analyze images and documents alongside text. The Sentinel Vision System provides seamless integration with vision-capable LLM providers.

Key Features:

  • 🖼️ Image Analysis: Process images from URLs, files, or base64-encoded data
  • 📄 Document Processing: Extract text from PDFs with intelligent chunking for RAG
  • 🎚️ Quality Control: Auto/Low/High detail levels for cost/accuracy trade-offs
  • 🔐 Secure: Built-in encryption (ChaCha20-Poly1305) and audit logging
  • 🏰 Battalion-Ready: Vision works seamlessly with all orchestration patterns
  • 🔌 Multi-Provider: OpenAI GPT-4o and Anthropic Claude 3 support

Quick Example:

use paladin::core::platform::container::vision::{VisionContent, ImageDetail};

// Create vision-enabled Paladin
let paladin = PaladinBuilder::new(llm_port)
    .system_prompt("You are a professional image analyst")
    .enable_vision(true)
    .build()?;

// Analyze an image
let image = VisionContent::ImageUrl {
    url: "https://example.com/photo.jpg".to_string(),
    detail: ImageDetail::High,
};

let result = execution_service
    .execute_with_vision(&paladin, "What's in this image?", vec![image])
    .await?;

Supported Vision Content:

  • ImageUrl: Reference publicly accessible images
  • ImageFile: Load images from local filesystem
  • ImageBase64: Embed encoded image data directly

Document Processing:

use paladin::application::ports::input::document_port::{DocumentPort, ChunkConfig};

// Extract text from PDF
let document = document_adapter
    .ingest(DocumentSource::File("paper.pdf".into()))
    .await?;

// Chunk for RAG (500 chars, 100 overlap)
let chunks = document_adapter.chunk(&document, ChunkConfig {
    chunk_size: 500,
    chunk_overlap: 100,
    separator: "\n\n".to_string(),
}).await?;

CLI Usage:

# Analyze single image
paladin vision analyze \
  --image photo.jpg \
  --prompt "Describe this image" \
  --detail high

# Process PDF document
paladin vision document \
  --file report.pdf \
  --chunk-size 1000 \
  --output chunks.json

Battalion Integration: Vision capabilities work with all Battalion patterns:

  • Formation: Sequential vision analysis pipeline
  • Phalanx: Parallel image processing (~3x speedup)
  • Campaign: Complex vision workflows with branching
  • Chain of Command: Hierarchical image review processes

Learn More:

  • docs/SENTINEL.md - Complete vision system documentation
  • docs/BATTALION_VISION_SUPPORT.md - Multi-agent vision patterns
  • examples/vision_analysis.rs - Single-image analysis walkthrough
  • examples/document_processing.rs - PDF extraction and chunking
  • examples/vision_battalion.rs - Formation and Phalanx patterns

Battalion Orchestration System

Battalion provides powerful multi-agent coordination capabilities with eight distinct orchestration patterns:

  • Formation (Sequential): Execute Paladins in sequence, passing output from one to the next
    • Perfect for multi-step pipelines and data transformation workflows
    • Linear execution with output chaining
  • Phalanx (Concurrent): Execute all Paladins simultaneously with result aggregation
    • Strategies: CollectAll, FirstSuccess, Majority, Custom
    • Ideal for parallel analysis and consensus building
  • Campaign (Graph/DAG): Conditional routing through a directed acyclic graph
    • Edge conditions: Always, Contains, Regex, Custom
    • Complex workflows with branching logic and fan-out/fan-in patterns
  • Chain of Command (Hierarchical): Commander analyzes input and delegates to specialists
    • Delegation strategies: Automatic (LLM-based), Broadcast, RoundRobin, Custom
    • Intelligent task routing and load distribution
  • Conclave (Multi-Expert Synthesis): Multiple experts analyze in parallel, aggregator synthesizes perspectives
    • Implements Mixture-of-Agents pattern for higher quality outputs
    • Perfect for expert panel decisions requiring multiple perspectives (technical, business, security)
    • Resilience: Continues even if some experts fail (partial success)
    • Configurable retry logic with exponential backoff
  • Council (Iterative Discussion): Iterative multi-round discussion pattern with turn-based dialogue
    • Enables debate, consensus building, and deliberative decision-making
    • Configurable turn limits, participation rules, and discussion strategies
    • Built-in conclusion detection and summary generation
  • Grove (Contextual Routing): Advanced routing with contextual analysis and LLM-based decision making
    • Semantic routing based on input content and historical performance
    • Fallback chains and multi-stage routing pipelines
    • Dynamic scoring and performance-based optimization
  • Maneuver (Flow DSL): String-based workflow orchestration with declarative syntax
    • Compact syntax: "a -> (b, c) -> d" for sequential and parallel flows
    • Error handling strategies: FailFast, ContinueParallel, IgnoreErrors
    • Built-in visualization (ASCII tree, Mermaid flowcharts) and CLI tools
    • See Flow DSL Guide for complete syntax and examples

Performance: Handles 100+ concurrent Battalions with <10ms orchestration overhead

Error Resilience: Three strategies (FailFast, ContinueOnError, RetryThenContinue) with exponential backoff

Testing: 218 comprehensive tests (85 unit + 133 integration) ensuring reliability

See docs/BATTALION.md for comprehensive orchestration documentation.

Herald Output Formatting System

Herald provides a powerful, pluggable output formatting system that transforms Paladin and Battalion execution results into human-readable formats:

  • JSON Herald: Structured JSON output for APIs and machine parsing
    • Pretty-printed or compact format
    • Optional timestamps
    • NDJSON streaming support
  • Markdown Herald: Beautiful, human-readable output with colors
    • Color-coded status badges (✅ ❌ ⏱️)
    • Configurable heading levels
    • Progressive text streaming
  • Table Herald: Compact ASCII/Unicode tables for dashboards
    • Multiple border styles (rounded, ascii, modern, none)
    • Automatic text truncation
    • Buffered rendering for consistency

Key Features:

  • ⚡ High Performance: <1ms for 10KB results (tested at 0.0095ms - 105x faster than target)
  • 🔌 Pluggable: Easy to implement custom formatters (XML, CSV, etc.)
  • 📡 Streaming Support: Three strategies (NDJSON, Progressive, Buffered)
  • ⚙️ Configurable: YAML-based config with runtime overrides
  • 🏗️ Type-Safe: Strong typing with comprehensive error handling

Quick Example:

use paladin::infrastructure::adapters::herald::{JsonHerald, MarkdownHerald};
use std::sync::Arc;

// Create Herald from config
let herald = settings.create_default_herald()?;

// Or create directly
let herald: Arc<dyn Herald> = Arc::new(MarkdownHerald::new());

// Use with Paladin
let service = PaladinExecutionService::new(llm_port, cb, None, None)
    .with_herald(herald);

let result = service.execute(&paladin, "input").await?;
if let Some(formatted) = service.format_result(&result, &paladin)? {
    println!("{}", formatted);
}

Custom Formatters: Implement the Herald trait to create custom output formats (XML, CSV, YAML, etc.)

See docs/HERALD.md for comprehensive formatting documentation.

Storage Solutions

  • SQL Store: Interfaces with relational databases for structured data storage and transactions.
  • NoSQL Store: Manages unstructured data with NoSQL databases.
  • File Store: Handles storage and retrieval of files.
  • Key and Key-Value Stores: Efficient storage and retrieval mechanisms for keys and values.

Getting Started

Prerequisites

  • Rust (latest stable version)
  • Cargo package manager

Installation

Clone the repository:

git clone <repository-url>
cd Paladin

Building

To build the project, run:

cargo build

Configuration

Paladin uses a dual-path configuration system:

  • YAML files (config.yml) for structural/behavioral settings
  • Environment variables for secrets and deployment-specific overrides

For detailed configuration instructions, see Configuration Guide.

Quick setup for development:

# 1. Copy the example environment file
cp .env.example .env

# 2. Edit .env and add your API keys
# OPENAI_API_KEY=sk-your-key-here
# DEEPSEEK_API_KEY=your-deepseek-key
# ANTHROPIC_API_KEY=your-anthropic-key

# 3. The .env file is automatically loaded in debug builds
cargo run

Configuration sources (in priority order):

  1. config.yml - Base configuration (committed to git)
  2. APP_* environment variables - Override any YAML value
  3. Direct environment variables - LLM API keys (never in YAML)

For production deployments, CI/CD, and advanced configuration patterns, see the Configuration Guide.

Running Tests

Run unit tests to ensure functionality:

cargo test

Live LLM API Tests In DevContainer

Use a workspace .env file as the single source of truth instead of one-off export commands.

cp .env.example .env

Set at least one provider key in .env:

OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=
ANTHROPIC_API_KEY=

Load .env in your current terminal session:

set -a
. /workspace/.env
set +a

Run live API tests (feature-gated and ignored by default):

cargo test --features live-api-tests -- --ignored --nocapture

Run one provider only:

cargo test --features live-api-tests test_openai -- --ignored --nocapture

CLI Tools (Armory)

Paladin includes a powerful command-line interface for managing agents, battalions, and tools without writing code.

Quick Start:

# Build the CLI
cargo build --release

# Create a new Paladin agent from template
./target/release/paladin agent new my-assistant --output agent.yaml

# Edit the configuration file (agent.yaml) with your settings
# Then execute the agent
./target/release/paladin agent run agent.yaml "What is Rust?"

# Create and run a Battalion (multi-agent workflow)
./target/release/paladin battalion new formation --output pipeline.yaml
./target/release/paladin battalion run pipeline.yaml "Analyze this text"

# List available tools
./target/release/paladin arsenal list

Features:

  • 🤖 Agent Management: Create, configure, and execute Paladins
  • 🏢 Battalion Operations: Orchestrate multi-agent workflows (Formation, Phalanx, Campaign, Chain of Command)
  • 🛠️ Arsenal Tools: List and test MCP-compatible tools
  • 📝 Template System: Quick-start YAML templates for all agent types
  • 🔧 Interactive Mode: Prompts for missing configuration
  • 📊 Multiple Output Formats: JSON, Markdown, or save to file

Comprehensive Documentation: See docs/CLI_USAGE.md for detailed usage guide, including:

  • Complete command reference with all flags and options
  • Configuration file schemas and examples
  • Troubleshooting guide for common errors
  • Environment variable setup
  • Advanced topics (streaming, custom formatters, arsenal integration)

Examples

Paladin Agent with Memory

use paladin::application::use_cases::paladin::{PaladinBuilder, PaladinExecutionService};
use paladin::infrastructure::resilience::circuit_breaker::CircuitBreaker;
use paladin::infrastructure::adapters::garrison::InMemoryGarrison;
use paladin::core::platform::container::garrison::GarrisonConfig;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create memory system
    let garrison = Arc::new(InMemoryGarrison::new(GarrisonConfig::default()));

    // Build agent
    let paladin = PaladinBuilder::new(llm_port)
        .name("Assistant")
        .system_prompt("You are a helpful AI assistant.")
        .with_garrison(garrison.clone())
        .build()?;

    // Execute with memory
    let circuit_breaker = Arc::new(CircuitBreaker::new(3, 2, 30000));
    let service = PaladinExecutionService::new(llm_port, circuit_breaker, Some(garrison));

    let result = service.execute(&paladin, "What is Rust?").await?;
    println!("Response: {}", result.content);

    Ok(())
}

See examples/ directory for more examples:

  • garrison_in_memory.rs - In-memory conversation history
  • garrison_persistent.rs - SQLite persistence example
  • garrison_semantic_search.rs - Future vector search demo
  • arsenal_stdio_tools.rs - STDIO MCP tool integration
  • arsenal_sse_tools.rs - SSE MCP tool integration
  • formation_sequential.rs - Sequential Paladin pipeline
  • phalanx_parallel.rs - Concurrent Paladin execution
  • campaign_workflow.rs - Graph-based conditional routing
  • chain_of_command_delegation.rs - Hierarchical task delegation

Battalion Formation Example

use paladin::application::use_cases::battalion::formation_service::FormationExecutionService;
use paladin::core::platform::container::battalion::formation::Formation;
use paladin::core::platform::container::battalion::BattalionConfig;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a sequential pipeline of Paladins
    let paladins = vec![
        create_paladin("analyzer", "Analyze the input data"),
        create_paladin("processor", "Process the analyzed data"),
        create_paladin("summarizer", "Create a summary"),
    ];

    let config = BattalionConfig::default();
    let formation = Formation::new(paladins, config)?;

    // Execute: output from each Paladin flows to the next
    let service = FormationExecutionService::new(llm_port);
    let result = service.execute(&formation, "Process this data").await?;

    println!("Final result: {:?}", result);
    Ok(())
}

See docs/BATTALION.md for comprehensive orchestration documentation.

Battalion Council Example

Council enables structured multi-agent discussions with turn-based dialogue, perfect for collaborative decision-making, debate, and consensus building:

use paladin::application::use_cases::battalion::council_service::CouncilExecutionService;
use paladin::core::platform::container::battalion::council::{
    CouncilBuilder, TerminationCondition, TurnStrategy
};
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create expert Paladins for discussion
    let security_expert = create_paladin("SecurityExpert",
        "You are a security expert focused on authentication best practices");
    let legal_expert = create_paladin("LegalExpert",
        "You are a legal expert focused on compliance and privacy regulations");
    let tech_lead = create_paladin("TechLead",
        "You are a technical lead focused on implementation feasibility");

    let paladins = vec![security_expert, legal_expert, tech_lead];

    // Build the Council with structured discussion rules
    let council = CouncilBuilder::new()
        .name("2FA Implementation Council")
        .participants(3)  // Number of participants in the discussion
        .turn_strategy(TurnStrategy::RoundRobin)  // Each expert takes turns
        .termination_condition(TerminationCondition::MaxRounds(3))  // 3 rounds of discussion
        .build()?;

    // Execute the discussion
    let council_service = CouncilExecutionService::new(llm_port);
    let result = council_service.execute(
        &council,
        &paladins,
        "Should we implement two-factor authentication for our application?"
    ).await?;

    // View the discussion transcript
    println!("📜 Discussion Summary:");
    println!("{}", result.summary);
    println!("\n🗣️ Total Turns: {}", result.total_turns);

    Ok(())
}

Use Cases:

  • Technical Decisions: Architecture reviews with security, performance, and maintainability experts
  • Policy Development: Multi-stakeholder discussions (legal, business, technical)
  • Code Review: Collaborative analysis with different expertise areas
  • Threat Modeling: Security experts discussing attack vectors and mitigations

See examples/council_discussion.rs for a complete working example with mock experts.

Battalion Grove Example

Grove provides intelligent routing to specialized agent trees based on task content, enabling dynamic expert selection:

use paladin::core::platform::container::battalion::grove::{
    GroveBuilder, GroveConfig, RoutingStrategy, Tree, TreeAgent
};
use paladin::application::use_cases::battalion::grove_service::GroveExecutionService;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create Security Experts Tree
    let security_tree = Tree::new("Security Experts")
        .add_agent(TreeAgent::new("SecurityAuditor")
            .with_keywords(vec!["security", "vulnerability", "authentication"]))
        .add_agent(TreeAgent::new("CryptoExpert")
            .with_keywords(vec!["encryption", "keys", "certificates"]))
        .add_agent(TreeAgent::new("AccessControlSpecialist")
            .with_keywords(vec!["authorization", "permissions", "rbac"]));

    // Create Performance Experts Tree
    let performance_tree = Tree::new("Performance Experts")
        .add_agent(TreeAgent::new("DatabaseOptimizer")
            .with_keywords(vec!["database", "query", "index", "sql"]))
        .add_agent(TreeAgent::new("CachingExpert")
            .with_keywords(vec!["cache", "redis", "latency"]))
        .add_agent(TreeAgent::new("LoadBalancer")
            .with_keywords(vec!["load", "scaling", "throughput"]));

    // Build the Grove with keyword-based routing
    let grove = GroveBuilder::new()
        .name("Expert Task Router")
        .add_tree(security_tree)
        .add_tree(performance_tree)
        .config(GroveConfig {
            routing_strategy: RoutingStrategy::KeywordMatch,
            fallback_tree: Some("Performance Experts".to_string()),
            confidence_threshold: 0.6,
        })
        .build()?;

    // Execute with automatic routing
    let grove_service = GroveExecutionService::new(llm_port);

    // Routes to Security Experts Tree → CryptoExpert
    let result1 = grove_service.execute(
        &grove,
        "How should we implement TLS certificate rotation?"
    ).await?;

    println!("✓ Routed to: {}", result1.selected_tree);
    println!("✓ Agent: {}", result1.selected_agent);
    println!("✓ Confidence: {:.2}%", result1.routing_confidence * 100.0);

    // Routes to Performance Experts Tree → CachingExpert
    let result2 = grove_service.execute(
        &grove,
        "What caching strategy should we use to reduce latency?"
    ).await?;

    Ok(())
}

Routing Strategies:

  • KeywordMatch: Match task keywords to agent expertise (fast, simple)
  • SemanticSimilarity: Use embeddings for context-aware routing (accurate, requires embedding model)
  • PerformanceBased: Route based on past agent success rates (adaptive, requires history)

Use Cases:

  • Help Desk Routing: Direct questions to specialized support teams
  • Code Analysis: Route to language-specific or domain experts
  • Multi-Domain Systems: Different expert trees for frontend, backend, DevOps, security
  • Customer Support: Route tickets based on product area or issue type

See examples/grove_routing.rs and examples/commander_grove.rs for complete working examples.

Arsenal Tool System Example

use paladin::application::use_cases::arsenal::ArsenalRegistryService;
use paladin::application::ports::output::arsenal_port::ArsenalRegistry;
use paladin::infrastructure::adapters::arsenal::Armament;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create tool registry
    let registry = Arc::new(ArsenalRegistryService::new());

    // Register a calculator tool
    let calculator = Armament {
        name: "calculator".to_string(),
        description: "Performs basic arithmetic operations".to_string(),
        parameters: serde_json::json!({
            "type": "object",
            "properties": {
                "operation": {"type": "string", "enum": ["add", "subtract", "multiply", "divide"]},
                "a": {"type": "number"},
                "b": {"type": "number"}
            },
            "required": ["operation", "a", "b"]
        }),
        required_params: vec!["operation".to_string(), "a".to_string(), "b".to_string()],
    };

    registry.register(calculator).await;

    // Paladin agents can now use the calculator tool via function calling
    Ok(())
}

See docs/ARSENAL.md for comprehensive tool system documentation.

Notification Example

let notification_request = NotificationRequest {
    recipient: NotificationRecipient::Email("user@example.com".to_string()),
    content: NotificationContent {
        title: "Welcome!".to_string(),
        body: "Thank you for joining Paladin.".to_string(),
        category: "info".to_string(),
        action_url: None,
        attachments: None,
        template_id: None,
        template_variables: None,
    },
    channel: NotificationChannel::Email,
    priority: NotificationPriority::Normal,
    scheduled_time: None,
    expiry_time: None,
    metadata: None,
};

let response = notification_service.send_notification(notification_request)?;

Content Delivery Example

let delivery_request = DeliveryRequest {
    recipient_id: "user123".to_string(),
    delivery_method: DeliveryMethod::Http {
        endpoint: "https://example.com/webhook".to_string(),
        headers: None,
    },
    content_payload: ContentPayload::Notification(NotificationContent {
        title: "Notification Title".to_string(),
        body: "Content body".to_string(),
        category: "update".to_string(),
        action_url: None,
        expires_at: None,
    }),
    priority: DeliveryPriority::Normal,
    scheduled_time: None,
    metadata: None,
};

let delivery_response = content_delivery_service.deliver_content(delivery_request)?;

Documentation

Comprehensive documentation is available in the docs/ directory:

Getting Started

User Guides

Architecture & Design

Deployment

Operations

  • Logging - Structured logging with tracing, log levels, and aggregation
  • Monitoring - Metrics collection with Prometheus and Grafana dashboards
  • Troubleshooting - Common issues and diagnostic procedures
  • Performance Tuning - Optimization strategies and benchmarking

Component Documentation

Contributing

API Documentation

Generate and view the Rust API documentation:

cargo doc --no-deps --open

Contributing

Contributions are welcome! Please read our Contributing Guide before submitting pull requests.

License

Distributed under the MIT License. See LICENSE for more information.