Paladin Documentation

Welcome to the Paladin documentation! Paladin is a Rust-based enterprise multi-agent orchestration framework built with Hexagonal Architecture and Domain-Driven Design principles.

🚀 Getting Started

New to Paladin? Start here:

1. Quickstart Guide - Get your first Paladin agent running in 15 minutes
2. Installation - Detailed setup instructions for all platforms
3. Examples Gallery - Working code examples for common use cases

📚 User Guides

Learn how to build with Paladin:

• Autonomous Agent Features - 🆕 Auto-planning, prompt generation, dynamic temperature, and agent handoffs (Epic 14)
• Battalion Orchestration - Multi-agent coordination with 8 orchestration patterns
• Maneuver Flow DSL - 🆕 Declarative workflows with Flow DSL syntax (Epic 17)
• Tool Integration (Arsenal) - Integrate external tools via MCP protocol
• Memory Management (Garrison) - Conversation context and persistence
• Output Formatting (Herald) - Format and stream agent responses
• CLI Usage Guide - Complete command-line interface reference

🏗️ Architecture

Understand Paladin's design:

• Architecture Overview - Three-layer hexagonal architecture
• Hexagonal Design - Port/adapter pattern implementation
• Domain Model - DDD entities and relationships
• Design Patterns - Patterns used throughout Paladin

🚢 Deployment

Deploy Paladin to production:

• Docker - Containerized deployment
• Kubernetes - Cloud-native orchestration
• CI/CD - Automated pipelines with GitHub Actions
• Production Best Practices - Security, scaling, and reliability
• Versioning Policy - Lockstep versioning rules and transition criteria
• Release Checklist - Dependency-aware release and publish workflow

🔧 Operations

Monitor and maintain Paladin:

• Logging - Structured logging configuration
• Monitoring - Metrics and dashboards
• Troubleshooting - Common issues and solutions
• Performance Tuning - Optimize for throughput and latency

🤝 Contributing

Extend and improve Paladin:

• Contribution Guide - How to contribute
• Adapter Development - Create custom adapters
• Testing Guide - Testing requirements and patterns

📖 API Reference

Comprehensive API documentation is available via rustdoc:

cargo doc --open

Or browse online at: https://docs.rs/paladin (when published)

🎯 Key Concepts

Medieval Military Theme

Paladin uses a consistent Medieval Military naming convention:

Architecture Layers

Paladin follows hexagonal (ports and adapters) architecture:

• Core Layer - Pure domain logic, no external dependencies
• Application Layer - Use cases and port definitions (interfaces)
• Infrastructure Layer - Adapter implementations for external systems

Dependencies flow inward only: Infrastructure → Application → Core

💡 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: You're reading it!

📄 License

See LICENSE for details.

Installation Guide

This guide provides detailed installation instructions for Paladin on Linux, macOS, and Windows.

Prerequisites

Required

• Rust 1.70 or later: https://rustup.rs/
• Cargo: Included with Rust installation
• LLM API Key: OpenAI, DeepSeek, or Anthropic account

Optional

• Docker: For containerized deployment (see Docker Guide)
• Redis: For async queue functionality (see Development Setup)
• MinIO: For file storage (see Development Setup)

Platform-Specific Setup

Linux

Ubuntu/Debian

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install system dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev

# Verify installation
rustc --version
cargo --version

Fedora/RHEL/CentOS

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install system dependencies
sudo dnf install -y gcc pkg-config openssl-devel

# Verify installation
rustc --version
cargo --version

Arch Linux

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install system dependencies
sudo pacman -S base-devel openssl pkg-config

# Verify installation
rustc --version
cargo --version

macOS

Using Homebrew

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install OpenSSL (if needed)
brew install openssl pkg-config

# Verify installation
rustc --version
cargo --version

Apple Silicon (M1/M2/M3)

Rust supports Apple Silicon natively. No additional steps required:

# Verify architecture
rustc --version --verbose | grep host
# Should show: host: aarch64-apple-darwin

Windows

Using rustup-init.exe

1. Download rustup-init.exe from https://rustup.rs/
2. Run the installer and follow prompts
3. Restart your terminal

# Verify installation
rustc --version
cargo --version

Using WSL2 (Recommended for Development)

# Inside WSL2 Ubuntu
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

# Install dependencies
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev

# Verify installation
rustc --version
cargo --version

Installing Paladin

Option 1: From Crates.io (Stable)

# Add Paladin to your project
cargo add paladin

# Or manually edit Cargo.toml

[dependencies]
paladin = "0.1"
tokio = { version = "1", features = ["full"] }

Option 2: From Source (Latest)

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

# Build the project
cargo build --release

# Run tests to verify
cargo test

# Optionally install CLI tools
cargo install --path .

Option 3: As a Dependency from Git

[dependencies]
paladin = { git = "https://github.com/DF3NDR/paladin-dev-env", branch = "main" }
tokio = { version = "1", features = ["full"] }

Feature Flags

Paladin supports optional features that can be enabled in Cargo.toml:

[dependencies.paladin]
version = "0.1"
features = [
    "redis-queue",      # Enable Redis queue adapter (default)
    "s3-storage",       # Enable MinIO/S3 storage (default)
    "anthropic",        # Enable Anthropic LLM provider
    "deepseek",         # Enable DeepSeek LLM provider
    "mcp",              # Enable MCP tool protocol
]

Default Features

Enabled by default:

• redis-queue - Redis-based async queue
• s3-storage - MinIO/S3 file storage

Optional Features

Not enabled by default:

• anthropic - Anthropic Claude integration
• deepseek - DeepSeek LLM integration
• mcp - Model Context Protocol for tools

Disable default features:

[dependencies.paladin]
version = "0.1"
default-features = false
features = ["mcp"]  # Only enable MCP

Environment Configuration

API Keys

Create a .env file in your project root:

# OpenAI (default provider)
OPENAI_API_KEY=sk-your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1  # Optional

# DeepSeek
DEEPSEEK_API_KEY=your-deepseek-key
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1  # Optional

# Anthropic
ANTHROPIC_API_KEY=your-anthropic-key
ANTHROPIC_BASE_URL=https://api.anthropic.com/v1  # Optional

Configuration File

Create config.yml (optional):

paladin:
  default_model: "gpt-4"
  default_temperature: 0.7
  default_max_loops: 3
  timeout_seconds: 300

garrison:
  type: "sqlite"  # or "in_memory"
  path: "./garrison.db"
  max_entries: 1000

llm:
  openai:
    api_key: "${OPENAI_API_KEY}"
    base_url: "https://api.openai.com/v1"

Development Setup

For local development with all features:

1. Clone the Repository

git clone https://github.com/DF3NDR/paladin-dev-env.git
cd paladin-dev-env

2. Install Development Dependencies

# Install additional cargo tools
cargo install cargo-watch      # Auto-rebuild on changes
cargo install cargo-edit        # cargo add/rm commands
cargo install cargo-audit       # Security vulnerability scanning
cargo install cargo-llvm-cov    # Code coverage
cargo install cargo-insta       # Snapshot testing (for CLI output tests)

cargo-insta is used for CLI snapshot testing. It allows you to capture and verify terminal output:

# Run snapshot tests
cargo test --test cli

# Review new snapshots
cargo insta review

# Accept all pending snapshots
cargo insta accept

See tests/cli/ for snapshot test examples.

3. Start Docker Services (Optional)

# Start Redis and MinIO
make dev

# Or manually with docker-compose
docker-compose -f docker/docker-compose.dev.yml up -d

4. Configure Environment

# Copy example environment
cp .env.example .env

# Edit with your API keys
vim .env

5. Build and Test

# Build the project
cargo build

# Run tests
cargo test

# Run with auto-reload
cargo watch -x run

Verification

Quick Test

Create test.rs:

use paladin::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    println!("Paladin version: {}", env!("CARGO_PKG_VERSION"));
    println!("Installation successful!");
    Ok(())
}

Run:

cargo run --example test

Full System Test

# Run all tests
cargo test

# Run integration tests (requires Docker services)
make test-integration-docker

# Run benchmarks
cargo bench

Troubleshooting

OpenSSL Errors (Linux)

# Ubuntu/Debian
sudo apt-get install pkg-config libssl-dev

# Fedora/RHEL
sudo dnf install pkgconfig openssl-devel

# Arch
sudo pacman -S openssl pkg-config

Linking Errors (Windows)

Install Visual Studio Build Tools:

• Download from https://visualstudio.microsoft.com/downloads/
• Select "Desktop development with C++"

Permission Errors (macOS)

# Fix cargo permissions
sudo chown -R $(whoami) ~/.cargo

Slow Compilation

Enable parallel compilation:

# Add to ~/.cargo/config.toml
[build]
jobs = 8  # Adjust based on CPU cores

Use sccache for caching:

cargo install sccache
export RUSTC_WRAPPER=sccache

Network Issues

Use a proxy:

# Set in ~/.cargo/config.toml
[http]
proxy = "http://proxy.example.com:8080"

[https]
proxy = "http://proxy.example.com:8080"

Or use a mirror:

[source.crates-io]
replace-with = "ustc"

[source.ustc]
registry = "https://mirrors.ustc.edu.cn/crates.io-index"

Next Steps

• Quickstart Guide - Build your first Paladin agent
• Configuration Guide - Advanced configuration
• Examples - Working code examples
• API Reference - Complete API documentation

Platform Support

Minimum System Requirements

• CPU: 2 cores (4+ recommended for parallel operations)
• RAM: 4 GB (8+ GB recommended)
• Disk: 2 GB for dependencies and builds
• Network: Internet connection for LLM API calls

Get Help

• Installation Issues: GitHub Issues
• General Questions: GitHub Discussions
• Documentation: docs/

Quickstart Guide

Get your first Paladin agent running in 15 minutes! This guide will walk you through creating a simple Paladin agent that can answer questions using an LLM.

Prerequisites

• Rust: 1.70 or later (installation guide)
• LLM API Key: OpenAI, DeepSeek, or Anthropic account
• Basic Rust knowledge: Understanding of cargo and async/await

Step 1: Installation

Add Paladin to your Cargo.toml:

[dependencies]
paladin = "0.1"
tokio = { version = "1", features = ["full"] }

Or create a new project:

cargo new my-paladin-agent
cd my-paladin-agent
cargo add paladin
cargo add tokio --features full

Step 2: Set Up Your Environment

Create a .env file in your project root:

# OpenAI
OPENAI_API_KEY=sk-your-api-key-here

# Or DeepSeek
DEEPSEEK_API_KEY=your-deepseek-key

# Or Anthropic
ANTHROPIC_API_KEY=your-anthropic-key

Security Note: Never commit API keys to version control. Add .env to your .gitignore.

Step 3: Create Your First Paladin

Create or edit src/main.rs:

use paladin::prelude::*;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load environment variables
    dotenv::dotenv().ok();

    // Create an LLM adapter (OpenAI in this example)
    let llm_adapter = Arc::new(
        OpenAiAdapter::new()
            .with_api_key(std::env::var("OPENAI_API_KEY")?)
            .with_model("gpt-4")
            .build()?
    );

    // Build a Paladin agent
    let paladin = PaladinBuilder::new(llm_adapter)
        .name("Assistant")
        .system_prompt("You are a helpful AI assistant. Be concise and accurate.")
        .temperature(0.7)
        .max_loops(3)
        .build()?;

    // Execute a query
    let response = paladin.execute("What is the capital of France?").await?;

    println!("Paladin: {}", response.content);

    Ok(())
}

Step 4: Run Your Agent

cargo run

Expected Output:

Paladin: The capital of France is Paris.

Next Steps

Congratulations! You've created your first Paladin agent. Here's what to explore next:

1. Add Memory (Garrison)

Enable conversation context:

#![allow(unused)]
fn main() {
let garrison = Arc::new(InMemoryGarrison::new());

let paladin = PaladinBuilder::new(llm_adapter)
    .name("Assistant")
    .system_prompt("You are a helpful assistant.")
    .with_garrison(garrison)
    .build()?;

// Now the Paladin remembers previous interactions
paladin.execute("My name is Alice").await?;
paladin.execute("What is my name?").await?; // "Your name is Alice"
}

2. Add Tools (Arsenal)

Give your Paladin capabilities:

#![allow(unused)]
fn main() {
use paladin::arsenal::*;

// Connect an MCP tool server
let web_search = MCPStdioAdapter::new("uvx", vec!["mcp-web-search"]).await?;

let paladin = PaladinBuilder::new(llm_adapter)
    .name("Research Assistant")
    .system_prompt("You can search the web to answer questions.")
    .add_armament(Arc::new(web_search))
    .build()?;

paladin.execute("What's the latest Rust release?").await?;
}

3. Multi-Agent Orchestration (Battalion)

Coordinate multiple Paladins:

#![allow(unused)]
fn main() {
use paladin::battalion::*;

// Sequential execution (Formation)
let analyst = /* create analyst Paladin */;
let writer = /* create writer Paladin */;

let formation = Formation::new()
    .add_paladin(analyst)
    .add_paladin(writer)
    .build()?;

let result = formation.execute("Analyze market trends and write a summary").await?;
}

4. Council Discussions

Enable multi-agent debate and consensus building:

#![allow(unused)]
fn main() {
use paladin::battalion::council::*;

// Create expert Paladins with different perspectives
let security_expert = PaladinBuilder::new(llm_adapter.clone())
    .name("SecurityExpert")
    .system_prompt("You are a security expert. Focus on authentication and data protection.")
    .build()?;

let legal_expert = PaladinBuilder::new(llm_adapter.clone())
    .name("LegalExpert")
    .system_prompt("You are a legal expert. Focus on compliance and privacy regulations.")
    .build()?;

let tech_lead = PaladinBuilder::new(llm_adapter.clone())
    .name("TechLead")
    .system_prompt("You are a technical lead. Focus on implementation feasibility.")
    .build()?;

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

// Build a Council for structured discussion
let council = CouncilBuilder::new()
    .name("Feature Discussion")
    .participants(3)
    .turn_strategy(TurnStrategy::RoundRobin)  // Each expert takes turns
    .termination_condition(TerminationCondition::MaxRounds(3))  // 3 rounds of debate
    .build()?;

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

println!("Discussion Summary: {}", result.summary);
println!("Total Turns: {}", result.total_turns);
}

Council Features:

• Turn-based dialogue: Structured conversations with round-robin or custom turn strategies
• Termination conditions: End after max rounds, consensus detection, or time limits
• Discussion transcript: Full conversation history with speaker attribution
• Summary generation: Automatic discussion summary and recommendation synthesis

Example CLI Command:

paladin council "Should we adopt microservices?" -n 5 --rounds 3

See examples/council_discussion.rs for a complete working example.

5. Grove Routing

Route tasks to specialized experts based on content:

#![allow(unused)]
fn main() {
use paladin::battalion::grove::*;

// Create specialized agent trees
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"]));

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

// Build the Grove with keyword-based routing
let grove = GroveBuilder::new()
    .name("Expert 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_adapter);

// Automatically routes to CryptoExpert
let result = grove_service.execute(
    &grove,
    "How should we implement TLS certificate rotation?"
).await?;

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

Grove Features:

• Intelligent routing: Keyword matching, semantic similarity, or performance-based selection
• Expert trees: Organize agents by domain (security, performance, frontend, backend)
• Fallback chains: Graceful degradation if no good match found
• Confidence scoring: Know how well the input matched the selected agent
• Dynamic learning: Performance-based routing improves over time

Routing Strategies:

• KeywordMatch: Fast, rule-based routing (best for well-defined domains)
• SemanticSimilarity: Embedding-based context-aware routing (requires embedding model)
• PerformanceBased: Adaptive routing based on historical success rates

See examples/grove_routing.rs for a complete working example.

6. Stream Responses

Get real-time output:

#![allow(unused)]
fn main() {
let mut stream = paladin.execute_stream("Tell me a story").await?;

while let Some(chunk) = stream.next().await {
    print!("{}", chunk?);
}
}

Common Patterns

Configuration from File

#![allow(unused)]
fn main() {
use paladin::config::ApplicationSettings;

let config = ApplicationSettings::load()?;
let paladin = PaladinBuilder::from_config(&config.paladin)?;
}

Error Handling

#![allow(unused)]
fn main() {
match paladin.execute(input).await {
    Ok(response) => println!("Success: {}", response.content),
    Err(PaladinError::Timeout(secs)) => {
        eprintln!("Timed out after {} seconds", secs);
    }
    Err(PaladinError::LlmError(msg)) => {
        eprintln!("LLM error: {}", msg);
    }
    Err(e) => eprintln!("Error: {}", e),
}
}

Testing CLI Output

Paladin provides snapshot testing for CLI output consistency using insta:

#![allow(unused)]
fn main() {
use paladin::application::cli::formatters::table::TableFormatter;

#[test]
fn test_result_table() {
    let mut table = TableFormatter::new();
    table
        .set_header(vec!["Agent", "Status", "Time"])
        .add_row(vec!["Analyzer", "Success", "1.2s"])
        .add_row(vec!["Generator", "Success", "0.8s"]);

    let output = table.render();
    insta::assert_snapshot!("result_table", output);
}
}

Run tests and review snapshots:

# Run all tests
cargo test

# Review new/changed snapshots
cargo insta review

# Accept all snapshots
cargo insta accept

Snapshot testing ensures CLI output remains consistent across changes. See tests/cli/ for examples.

Async Context

Always run Paladins in an async context:

#[tokio::main]
async fn main() {
    // Your Paladin code here
}

Troubleshooting

"API key not found"

Ensure your .env file is in the project root and contains the correct variable name:

OPENAI_API_KEY=sk-...

"Connection timeout"

Check your network connection and API endpoint:

#![allow(unused)]
fn main() {
let llm_adapter = OpenAiAdapter::new()
    .with_timeout(Duration::from_secs(60)) // Increase timeout
    .build()?;
}

"Rate limit exceeded"

Implement retry logic or use a rate limiter:

#![allow(unused)]
fn main() {
let config = PaladinConfig::default()
    .with_retry_attempts(3)
    .with_retry_delay(Duration::from_secs(5));
}

Example Projects

Check out complete examples in the examples/ directory:

• basic_paladin.rs - Simple question answering
• garrison_in_memory.rs - Conversation with memory
• arsenal_stdio_tools.rs - Tool integration
• formation_sequential.rs - Multi-agent workflows
• phalanx_parallel.rs - Concurrent processing

Learn More

• Installation Guide - Detailed setup for all platforms
• Configuration Guide - Advanced Paladin options
• Battalion Patterns - Multi-agent orchestration
• API Reference - Complete API documentation

Get Help

• Documentation: https://github.com/DF3NDR/paladin-dev-env/tree/main/docs
• Examples: https://github.com/DF3NDR/paladin-dev-env/tree/main/examples
• Issues: https://github.com/DF3NDR/paladin-dev-env/issues

Happy building with Paladin! 🏰

Paladin Configuration Guide

This guide explains how Paladin's configuration system works, best practices for different environments, and the clear separation of concerns between YAML files and environment variables.

Table of Contents

• Configuration Philosophy
• Quick Start
• Configuration Sources
• Environment Variables Reference
• Environment-Specific Setup
• Feature Flags
• Security Best Practices
• Advanced Topics

Configuration Philosophy

Paladin uses a dual-path configuration system with clear separation of concerns:

Why Both?

• YAML files are version-controlled, reviewed in PRs, and define the system's structure
• Environment variables are injected at deployment time and never committed to source control
• This separation enables security (secrets stay out of repos), flexibility (same code works in dev/staging/prod), and auditability (config changes are tracked in git)

Quick Start

Development (DevContainer)

1. Copy the example environment file:

   cp .env.example .env
   

2. Edit .env and add your API keys:

   # LLM Provider API Keys (choose one or more)
   OPENAI_API_KEY=sk-your-key-here
   DEEPSEEK_API_KEY=your-deepseek-key
   ANTHROPIC_API_KEY=your-anthropic-key
   

3. Load the environment file (automatic in DevContainer):

   # Manual loading if needed:
   set -a
   . /workspace/.env
   set +a
   

4. Run Paladin:

   cargo run
   

The .env file is automatically loaded by the application in debug builds.

CI/CD

Set secrets as environment variables in your CI system:

GitHub Actions:

env:
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}

GitLab CI:

variables:
  CONFIG_FILE: "config.test.yml"
script:
  - cargo test --features live-api-tests

Production

Use a secrets manager:

AWS Secrets Manager + ECS:

"secrets": [
  {
    "name": "OPENAI_API_KEY",
    "valueFrom": "arn:aws:secretsmanager:region:account:secret:paladin/openai"
  }
]

Kubernetes Secrets:

apiVersion: v1
kind: Secret
metadata:
  name: paladin-secrets
type: Opaque
data:
  OPENAI_API_KEY: <base64-encoded-key>
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: paladin
        envFrom:
        - secretRef:
            name: paladin-secrets

Configuration Sources

Paladin loads configuration in this priority order (later sources override earlier ones):

1. config.yml (or specified via --config flag) - Base configuration
2. Environment-specific file - config.{APP_ENV}.yml if APP_ENV is set
3. APP_* environment variables - Override any YAML value
4. Direct environment variables - LLM API keys bypass the config system

Example: Loading Sequence

Given this setup:

config.yml:

garrison:
  garrison_type: "in_memory"
  max_entries: 100

Environment:

APP_GARRISON_MAX_ENTRIES=500
OPENAI_API_KEY=sk-real-key

Result:

• Garrison type: in_memory (from config.yml)
• Max entries: 500 (overridden by APP_* env var)
• OpenAI key: sk-real-key (from direct env var, never in YAML)

Environment Variables Reference

LLM Provider API Keys (Direct Read)

These are NOT in config.yml — adapters read them directly from the environment:

APP_* Overrides (Settings System)

Override any YAML value using the APP_ prefix + uppercase path with underscores:

YAML path → Environment variable

garrison:
  max_entries: 100

→ APP_GARRISON_MAX_ENTRIES=500

llm:
  openai:
    default_model: "gpt-4"

→ APP_LLM_OPENAI_DEFAULT_MODEL="gpt-4-turbo"

Common Overrides

Garrison (Memory System)

APP_GARRISON_TYPE=sqlite
APP_GARRISON_PATH=./custom_garrison.db
APP_GARRISON_MAX_ENTRIES=200
APP_GARRISON_MAX_TOKENS=8000
APP_GARRISON_TOKENIZER=gpt-4
APP_GARRISON_EVICTION_STRATEGY=fifo
APP_GARRISON_PRESERVE_RECENT_COUNT=20

Sanctum (Long-term Memory)

APP_SANCTUM_ENABLED=true
APP_SANCTUM_ADAPTER_TYPE=qdrant
APP_SANCTUM_QDRANT_URL=http://qdrant-server:6334
APP_SANCTUM_QDRANT_COLLECTION_NAME=custom_memories
APP_SANCTUM_QDRANT_VECTOR_DIMENSION=3072

Arsenal (Tool System)

APP_ARSENAL_DEFAULT_TIMEOUT_SECONDS=60
APP_ARSENAL_MAX_CONCURRENT_TOOLS=10

Citadel (State Persistence)

APP_CITADEL_ENABLED=true
APP_CITADEL_STATE_DIR=./custom-states
APP_CITADEL_AUTOSAVE_ENABLED=true
APP_CITADEL_CLEANUP_ENABLED=true
APP_CITADEL_MAX_STATE_AGE_DAYS=60

Redis Queue

APP_REDIS_HOST=redis-prod.example.com
APP_REDIS_PORT=6379
APP_REDIS_PASSWORD=secure-password
APP_REDIS_DB=2
APP_REDIS_POOL_SIZE=20

MinIO File Storage

APP_MINIO_ENDPOINT=https://s3.amazonaws.com
APP_MINIO_BUCKET=paladin-prod
APP_MINIO_ACCESS_KEY=AKIAIOSFODNN7EXAMPLE
APP_MINIO_SECRET_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
APP_MINIO_REGION=us-west-2

Environment-Specific Setup

Development (DevContainer)

Config file: config.yml

Secrets source: .env file (auto-loaded in debug builds)

Setup:

# 1. Copy template
cp .env.example .env

# 2. Edit .env with your keys
vim .env

# 3. The DevContainer post-start.sh loads it automatically
# Or manually in new terminals:
set -a && . /workspace/.env && set +a

# 4. Run
cargo run

Benefits:

• ✅ Fast iteration with hot-reload
• ✅ No need to export vars in every terminal
• ✅ .env is gitignored, so secrets stay local

CI/CD (GitHub Actions, GitLab, etc.)

Config file: config.test.yml

Secrets source: CI secrets store

Setup (GitHub Actions example):

name: Test
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    env:
      # Use shorter timeouts and smaller limits for tests
      CONFIG_FILE: config.test.yml
    steps:
      - uses: actions/checkout@v4

      - name: Run tests with mocks
        run: cargo test

      - name: Run live API tests
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: cargo test --features live-api-tests -- --ignored

Benefits:

• ✅ Different config for test environment (faster timeouts, smaller limits)
• ✅ Secrets managed by CI platform (encrypted, audited, rotated)
• ✅ Mock tests run without API keys, live tests only with secrets present

Staging

Config file: config.staging.yml (set APP_ENV=staging)

Secrets source: Vault, AWS Secrets Manager, or K8s Secrets

Setup (Kubernetes example):

apiVersion: v1
kind: ConfigMap
metadata:
  name: paladin-config
data:
  config.staging.yml: |
    llm:
      default_provider: "deepseek"  # Use cheaper model in staging
    garrison:
      garrison_type: "sqlite"
      max_entries: 200
---
apiVersion: v1
kind: Secret
metadata:
  name: paladin-secrets
type: Opaque
stringData:
  OPENAI_API_KEY: "sk-staging-key"
  DEEPSEEK_API_KEY: "staging-key"
---
apiVersion: apps/v1
kind: Deployment
spec:
  template:
    spec:
      containers:
      - name: paladin
        env:
        - name: APP_ENV
          value: "staging"
        envFrom:
        - secretRef:
            name: paladin-secrets
        volumeMounts:
        - name: config
          mountPath: /etc/paladin/config.staging.yml
          subPath: config.staging.yml
      volumes:
      - name: config
        configMap:
          name: paladin-config

Production

Config file: config.production.yml (set APP_ENV=production)

Secrets source: Enterprise secrets manager (Vault, AWS SM, Azure Key Vault)

Setup (AWS ECS + Secrets Manager):

1. Store secrets:

   aws secretsmanager create-secret \
     --name paladin/prod/openai \
     --secret-string "sk-prod-key-..."
   

2. Task definition:

   {
     "family": "paladin-prod",
     "containerDefinitions": [{
       "name": "paladin",
       "image": "paladin:1.0.0",
       "command": ["--config", "/etc/paladin/config.production.yml"],
       "environment": [
         {"name": "APP_ENV", "value": "production"}
       ],
       "secrets": [
         {
           "name": "OPENAI_API_KEY",
           "valueFrom": "arn:aws:secretsmanager:region:account:secret:paladin/prod/openai"
         }
       ]
     }]
   }
   

Benefits:

• ✅ Secrets never touch disk or config files
• ✅ Automatic rotation with Secrets Manager
• ✅ Audit trail of all secret access
• ✅ Fine-grained IAM permissions

Feature Flags

Paladin uses Cargo feature flags to control which dependencies and subsystems are compiled into your application. This enables:

• Smaller binaries - Include only what you need
• Faster compilation - Skip unused dependencies
• Clear dependencies - Explicit about infrastructure requirements
• Provider choice - Select specific LLM providers (OpenAI, Anthropic, DeepSeek)

Quick Reference

Default build (minimal):

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

Full featured build (development):

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

Custom feature selection (production):

[dependencies]
paladin = { version = "0.1", features = [
    "llm-anthropic",      # Anthropic Claude provider
    "redis-queue",        # Redis queue adapter
    "s3-storage",         # S3/MinIO storage
    "web-server"          # REST API server
] }

Available Features

Configuration Integration

Feature flags affect which adapters are available at runtime. Your config.yml should only reference adapters enabled by your feature flags:

Example with llm-anthropic feature:

llm:
  default_provider: "anthropic"  # ✅ OK - anthropic adapter compiled
  anthropic:
    default_model: "claude-3-sonnet-20240229"

Example WITHOUT redis-queue feature:

redis:
  host: "localhost"
  port: 6379
  # ❌ Error at runtime - Redis adapter not compiled

Detailed Documentation

For complete feature flag documentation, see:

• Feature Flags Guide - Comprehensive reference
• Migration Guide - Breaking changes and migration help

Breaking Change Note

⚠️ Default features changed in v0.1.0

• Old default: redis-queue, s3-storage, openai-embeddings
• New default: llm-openai only

If you were relying on default features to provide Redis, S3, or embeddings, you must now explicitly add these features to your Cargo.toml. See MIGRATION.md for details.

Security Best Practices

✅ DO

1. Keep secrets in environment variables only

   export OPENAI_API_KEY="sk-..."
   

2. Use .env files for local development

   # .env (gitignored)
   OPENAI_API_KEY=sk-dev-key
   

3. Use secrets managers in production

   • AWS Secrets Manager
   • HashiCorp Vault
   • Kubernetes Secrets (with encryption at rest)
   • Azure Key Vault
   • GCP Secret Manager

4. Set restrictive file permissions on .env

   chmod 600 .env
   

5. Rotate API keys regularly

6. Use different keys per environment

   • Dev key: Limited quota, separate account
   • Staging key: Separate from prod
   • Prod key: High quota, monitored

❌ DON'T

1. Never commit secrets to git

   # ❌ BAD - Don't do this!
   api_key: "sk-real-key-here"
   

2. Never use production keys in development

3. Never share .env files via Slack/email

4. Never log API keys

   #![allow(unused)]
   fn main() {
   // ❌ BAD
   println!("API key: {}", api_key);
   }

5. Never put secrets in Docker images

   # ❌ BAD
   ENV OPENAI_API_KEY=sk-...
   

Advanced Topics

Custom Configuration Files

Specify a different config file:

cargo run -- --config my-custom-config.yml

Environment-Specific Configs

Set APP_ENV to automatically load environment-specific files:

export APP_ENV=staging
cargo run
# Loads config.yml first, then overrides with config.staging.yml

Configuration Validation

The application validates configuration on startup:

#![allow(unused)]
fn main() {
let settings = Settings::new()?; // Returns error if invalid
}

Common validation errors:

• Missing required fields
• Invalid enum values
• Out-of-range numbers
• Unreachable URLs (for live validation)

Programmatic Configuration

For tests or embedded usage:

#![allow(unused)]
fn main() {
use paladin::config::application_settings::Settings;

// Load from specific file
let settings = Settings::load_from_file("config.test.yml")?;

// Access config values
let garrison_config = settings.get_garrison_config()?;
assert_eq!(garrison_config.max_entries, 100);
}

MCP Server Configuration

MCP servers are defined in YAML but may reference env vars:

arsenal:
  mcp_servers:
    - name: "github"
      type: "stdio"
      command: "npx"
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "${GITHUB_TOKEN}"  # ❌ Won't interpolate!

    - name: "web-search"
      type: "sse"
      url: "http://localhost:8080/mcp"

Note: The ${VAR} syntax in YAML is not interpolated by the config crate. Set env vars directly:

export GITHUB_TOKEN="ghp_..."
cargo run

Debugging Configuration

Enable debug logging to see config loading:

RUST_LOG=debug cargo run

Check what config values are loaded:

#![allow(unused)]
fn main() {
use log::info;

let settings = Settings::new()?;
info!("Loaded config: {:?}", settings);
}

Configuration Schema

For IDE autocomplete and validation, generate a JSON schema:

# Future feature - not yet implemented
cargo run -- config schema > config-schema.json

Troubleshooting

"Missing API key" errors

Symptom: Error: Missing OPENAI_API_KEY environment variable

Solutions:

1. Check the variable is set: echo $OPENAI_API_KEY
2. Load .env file: set -a && . .env && set +a
3. Export manually: export OPENAI_API_KEY="sk-..."
4. In DevContainer, restart terminal or source ~/.bashrc

Config file not found

Symptom: Failed to load configuration: config.yml not found

Solutions:

1. Check current directory: pwd
2. Verify file exists: ls -la config.yml
3. Specify absolute path: --config /workspace/config.yml
4. Use correct filename: config.yml not config.yaml

APP_* overrides not working

Symptom: Environment variable set but value not changing

Solutions:

1. Check variable name matches YAML structure: garrison.max_entries → APP_GARRISON_MAX_ENTRIES
2. Use uppercase and underscores
3. Verify with: env | grep APP_
4. Check the getter method exists in application_settings.rs

Permissions errors on .env

Symptom: .env file readable by others

Solution:

chmod 600 .env
ls -la .env
# Should show: -rw------- (owner read/write only)

Further Reading

• Garrison (Memory) Documentation
• Sanctum (Long-term Memory) Documentation
• Arsenal (Tool System) Documentation
• CLI Usage Guide
• Deployment Guide
• Contributing Guide

Support

For configuration issues:

1. Check this guide first
2. Search existing issues
3. Ask in Discussions
4. Open a new issue with:
   • Your config.yml (redact secrets!)
   • Environment variables (redact secrets!)
   • Error messages
   • Rust version and OS

Autonomous Agent Features

Epic 14: Autonomous Agent Features - Advanced AI capabilities for intelligent task handling and agent collaboration

Table of Contents

1. Introduction
2. Autonomous Planning Mode
3. Auto-Generate System Prompts
4. Dynamic Temperature Adjustment
5. Agent Handoff Infrastructure
6. Handoff Tool
7. Configuration
8. Best Practices
9. Error Handling
10. Troubleshooting
11. Advanced Usage
12. API Reference

Introduction

Paladin's autonomous agent features enable AI agents to intelligently handle complex tasks with minimal human intervention. These features are designed to make agents more capable, adaptive, and collaborative.

Features Overview

Key Benefits

• Reduced Configuration Overhead: Less manual prompt engineering and parameter tuning
• Improved Task Handling: Automatic decomposition of complex tasks
• Adaptive Behavior: Temperature adjusts to task requirements
• Specialization: Delegate tasks to expert agents
• Opt-In Design: All features disabled by default for backward compatibility

Quick Start

#![allow(unused)]
fn main() {
use paladin::application::services::paladin::paladin_builder::PaladinBuilder;
use paladin::core::platform::container::paladin::MaxLoops;
use paladin::core::platform::container::autonomous_config::*;
use std::sync::Arc;

// Create autonomous configuration
let autonomous_config = AutonomousConfig {
    planning: PlanningConfig {
        enabled: true,
        max_subtasks: 15,
    },
    prompt_generation: PromptConfig {
        enabled: true,
        description: Some("Expert data analyst".to_string()),
    },
    dynamic_temperature: TemperatureConfig {
        enabled: true,
        min: 0.2,
        max: 0.85,
    },
    handoffs: HandoffConfig {
        enabled: true,
        strategy: HandoffStrategy::Automatic,
        max_depth: 5,
    },
};

// Build Paladin with autonomous features
let paladin = PaladinBuilder::new(llm_port)
    .name("data-analyst")
    .max_loops(MaxLoops::Auto) // Autonomous planning
    .agent_description("Expert data analyst specializing in financial reports")
    .auto_generate_prompt(true) // Auto-generate system prompt
    .dynamic_temperature(true)  // Adjust temperature dynamically
    .enable_handoffs()          // Enable delegation
    .build()
    .await?;
}

Autonomous Planning Mode

User Story US-14.1: Autonomous planning mode allows agents to decompose complex tasks into manageable subtasks automatically.

Concept

When MaxLoops::Auto is set, the Paladin uses an LLM-powered planning service to:

1. Analyze the input task
2. Decompose it into logical subtasks
3. Execute each subtask sequentially
4. Synthesize results into a final answer

This eliminates the need to manually determine iteration counts or break down complex workflows.

Use Cases

• Research Tasks: "Analyze competitor landscape and provide strategic recommendations"
• Data Analysis: "Load dataset, clean data, perform statistical analysis, and visualize results"
• Content Generation: "Research topic, create outline, write article, add citations"
• Code Development: "Design API, implement endpoints, write tests, document usage"

Configuration

#![allow(unused)]
fn main() {
use paladin::core::platform::container::paladin::MaxLoops;
use paladin::core::platform::container::autonomous_config::PlanningConfig;

// Enable autonomous planning
let paladin = PaladinBuilder::new(llm_port)
    .name("research-agent")
    .max_loops(MaxLoops::Auto) // Enables planning mode
    .build()
    .await?;

// Or configure via AutonomousConfig
let planning_config = PlanningConfig {
    enabled: true,
    max_subtasks: 15, // Maximum subtasks to create (1-100)
};
}

YAML Configuration:

autonomous:
  planning:
    enabled: true
    max_subtasks: 15

CLI Flag:

paladin agent run --config agent.yaml --input "Research topic" --auto-plan

How It Works

1. Planning Phase

The PlanningService sends a specialized prompt to the LLM:

You are a task planner. Decompose the following complex task into
logical subtasks that can be executed sequentially.

Task: [User input]

Provide a structured plan with:
- Clear subtask descriptions
- Expected outcomes
- Dependencies between subtasks

2. Decomposition

The LLM returns a TaskPlan structure:

#![allow(unused)]
fn main() {
pub struct TaskPlan {
    pub subtasks: Vec<Subtask>,
    pub estimated_loops: u32,
}

pub struct Subtask {
    pub id: String,
    pub description: String,
    pub expected_outcome: String,
    pub dependencies: Vec<String>,
}
}

3. Execution

Each subtask is executed in sequence:

• Previous subtask results are included in context
• Dependencies are resolved automatically
• Loop count is set to estimated_loops

4. Synthesis

Final loop synthesizes all subtask results into a cohesive answer.

Example Output

Input: "Analyze the performance of our web application"

Generated Plan:

1. Identify Metrics: Define key performance indicators (response time, throughput, error rate)
2. Collect Data: Gather performance logs and metrics from monitoring systems
3. Analyze Trends: Identify patterns, bottlenecks, and anomalies in the data
4. Generate Recommendations: Provide actionable suggestions for optimization
5. Summarize Findings: Create executive summary with key insights

Execution: Each subtask runs sequentially, final output synthesizes all results.

Auto-Generate System Prompts

User Story US-14.2: Automatically generate contextual system prompts based on agent description.

Concept

Instead of manually writing system prompts, provide a high-level description of the agent's role and capabilities. The PromptGenerationService uses an LLM to create an optimized system prompt.

Benefits

• Consistency: All agents have well-structured prompts
• Expertise: Leverage LLM's knowledge of effective prompt patterns
• Time Savings: No manual prompt engineering required
• Adaptability: Prompts optimized for specific agent roles

Configuration

#![allow(unused)]
fn main() {
// Enable auto-generation in builder
let paladin = PaladinBuilder::new(llm_port)
    .name("code-reviewer")
    .agent_description("Expert code reviewer specializing in Rust, security, and performance")
    .auto_generate_prompt(true) // Enable auto-generation
    .build()
    .await?;

// Manual system prompt takes precedence
let paladin_manual = PaladinBuilder::new(llm_port)
    .name("custom-agent")
    .system_prompt("Custom prompt...") // Manual override
    .agent_description("Description used only if prompt not set")
    .auto_generate_prompt(true)
    .build()
    .await?;
}

YAML Configuration:

autonomous:
  prompt_generation:
    enabled: true
    description: "Expert code reviewer specializing in Rust, security, and performance"

CLI Flag:

paladin agent run --config agent.yaml --input "Review this code" --auto-prompt

How It Works

1. Generation Request

The PromptGenerationService sends a meta-prompt:

Create an effective system prompt for an AI agent with the following role:

Agent Name: code-reviewer
Description: Expert code reviewer specializing in Rust, security, and performance

The prompt should:
- Clearly define the agent's expertise and responsibilities
- Establish appropriate tone and communication style
- Include relevant guidelines and best practices
- Be concise yet comprehensive (2-4 paragraphs)

2. LLM Response

The LLM generates a contextual system prompt:

You are an expert code reviewer with deep expertise in Rust programming,
security analysis, and performance optimization. Your role is to provide
thorough, constructive code reviews that identify issues and suggest
improvements.

When reviewing code:
1. Check for security vulnerabilities (unsafe code, input validation, etc.)
2. Analyze performance implications (algorithmic complexity, allocations)
3. Ensure idiomatic Rust patterns (ownership, borrowing, error handling)
4. Verify code clarity and maintainability

Provide specific, actionable feedback with code examples where helpful.

3. Caching

Generated prompts are cached using a deterministic hash:

#![allow(unused)]
fn main() {
let cache_key = format!("{}:{}", agent_name, description_hash);
}

This prevents redundant LLM calls for identical agent configurations.

Regeneration

#![allow(unused)]
fn main() {
// Clear cache and regenerate
let prompt_service = PromptGenerationService::new(llm_port);
prompt_service.invalidate_cache("agent-name", "description-hash").await?;

let new_prompt = prompt_service.generate_prompt("agent-name", "Updated description").await?;
}

Manual Override Pattern

#![allow(unused)]
fn main() {
// Provide fallback but allow override
let paladin = PaladinBuilder::new(llm_port)
    .name("analyst")
    .agent_description("Financial data analyst") // Used if no manual prompt
    .auto_generate_prompt(true)
    .build()
    .await?;

// Check if prompt was generated
if paladin.data().system_prompt.is_empty() {
    eprintln!("Warning: No system prompt generated or provided");
}
}

Dynamic Temperature Adjustment

User Story US-14.3: Automatically adjust LLM temperature based on task type (factual vs. creative).

Concept

Different tasks require different levels of creativity:

• Factual tasks (calculations, data retrieval) → Low temperature (0.1-0.3)
• Analytical tasks (analysis, reasoning) → Medium temperature (0.5-0.7)
• Creative tasks (writing, brainstorming) → High temperature (0.7-0.9)

The TemperatureService classifies tasks and recommends optimal temperature.

Task Type Classification

Configuration

#![allow(unused)]
fn main() {
// Enable dynamic temperature
let paladin = PaladinBuilder::new(llm_port)
    .name("versatile-agent")
    .agent_description("Multi-purpose agent for varied tasks")
    .dynamic_temperature(true) // Enable dynamic adjustment
    .temperature_bounds(0.2, 0.85) // Optional: set bounds
    .build()
    .await?;

// Or via AutonomousConfig
let temp_config = TemperatureConfig {
    enabled: true,
    min: 0.2,
    max: 0.85,
};
}

YAML Configuration:

autonomous:
  dynamic_temperature:
    enabled: true
    min: 0.2
    max: 0.85

CLI Flag:

paladin agent run --config agent.yaml --input "Task" --dynamic-temp

Classification Heuristics

The TemperatureService uses keyword analysis and LLM classification:

Keyword-Based (Fast)

#![allow(unused)]
fn main() {
// Factual indicators
if task.contains_any(&["calculate", "compute", "count", "sum"]) {
    return TaskType::Factual;
}

// Creative indicators
if task.contains_any(&["write", "create", "imagine", "design"]) {
    return TaskType::Creative;
}
}

LLM-Based (Accurate)

For ambiguous tasks, the service queries the LLM:

Classify this task as: Factual, Analytical, Conversational, or Creative

Task: [User input]

Consider:
- Does it require precise, deterministic output? (Factual)
- Does it involve reasoning and analysis? (Analytical)
- Is it general conversation? (Conversational)
- Does it benefit from creative variation? (Creative)

Respond with only the classification.

How It Works

1. Task Analysis

#![allow(unused)]
fn main() {
let task_type = temperature_service
    .detect_task_type_with_llm(task_description)
    .await?;
}

2. Temperature Calculation

#![allow(unused)]
fn main() {
let temperature = match task_type {
    TaskType::Factual => config.min.max(0.2),
    TaskType::Analytical => (config.min + config.max) / 2.0,
    TaskType::Conversational => (config.min + config.max) / 2.0 + 0.1,
    TaskType::Creative => config.max.min(0.85),
};
}

3. Application

Temperature is applied before LLM request:

#![allow(unused)]
fn main() {
let request = LlmRequest {
    model: "gpt-4",
    temperature, // Dynamically calculated
    messages: vec![...],
};
}

Example

Input: "Calculate the compound interest on $10,000 at 5% for 10 years"

• Classification: Factual
• Temperature: 0.2 (deterministic, precise)

Input: "Write a creative short story about a time traveler"

• Classification: Creative
• Temperature: 0.85 (varied, imaginative)

Agent Handoff Infrastructure

User Story US-14.4: Enable agents to delegate tasks to specialist agents.

Concept

A general-purpose agent can recognize when a task requires specialized expertise and hand it off to a specialist agent. The specialist executes the task and returns results to the original agent.

Delegation Patterns

1. Automatic: Agent decides when to delegate based on context
2. Explicit: Developer specifies handoff points programmatically
3. Threshold-Based: Delegate when confidence drops below threshold

Configuration

#![allow(unused)]
fn main() {
use paladin::core::platform::container::handoff::*;

// Build agent with handoff support
let main_agent = PaladinBuilder::new(llm_port)
    .name("general-assistant")
    .enable_handoffs() // Enable handoff infrastructure
    .handoff_strategy(HandoffStrategy::Automatic)
    .max_handoff_depth(5) // Prevent infinite delegation chains
    .build()
    .await?;

// Register specialist agents
let handoff_service = HandoffService::new(llm_port);
handoff_service.register_specialist(
    "code-expert",
    "Rust programming expert for code generation and debugging"
).await?;

handoff_service.register_specialist(
    "data-analyst",
    "Expert in data analysis, statistics, and visualization"
).await?;
}

YAML Configuration:

autonomous:
  handoffs:
    enabled: true
    strategy: "automatic"  # or "explicit" or {"threshold": 0.8}
    max_depth: 5

CLI Flag:

paladin agent run --config agent.yaml --input "Task" --enable-handoffs

HandoffStrategy Options

1. Automatic

Agent decides when to delegate based on task complexity and expertise:

#![allow(unused)]
fn main() {
HandoffStrategy::Automatic
}

2. Explicit

Developer controls handoffs programmatically:

#![allow(unused)]
fn main() {
HandoffStrategy::Explicit
}

3. Threshold

Delegate when confidence drops below threshold:

#![allow(unused)]
fn main() {
HandoffStrategy::threshold(0.75) // Delegate if confidence < 75%
}

Circular Handoff Prevention

The HandoffService prevents infinite delegation loops:

#![allow(unused)]
fn main() {
// Validation in should_handoff()
if handoff_chain.contains(&target_agent) {
    return Err(HandoffError::CircularHandoff {
        chain: handoff_chain.clone(),
        attempted_target: target_agent.to_string(),
    });
}
}

Example:

• Agent A → Agent B → Agent C ✅ Valid
• Agent A → Agent B → Agent A ❌ Circular (rejected)

Max Depth Configuration

Prevent unbounded delegation chains:

#![allow(unused)]
fn main() {
let handoff_config = HandoffConfig {
    enabled: true,
    strategy: HandoffStrategy::Automatic,
    max_depth: 5, // Maximum 5 hops
};
}

Example:

• A → B → C → D → E ✅ Depth 5 (allowed)
• A → B → C → D → E → F ❌ Depth 6 (rejected)

Context Transfer

When handing off, context is preserved and transferred:

#![allow(unused)]
fn main() {
pub struct HandoffContext {
    pub original_task: String,
    pub accumulated_results: Vec<String>,
    pub handoff_chain: Vec<String>,
    pub depth: u32,
    pub metadata: HashMap<String, String>,
}
}

The specialist receives:

• Original task description
• All previous agent outputs
• Current position in handoff chain
• Any custom metadata

Decision Process

#![allow(unused)]
fn main() {
// HandoffService determines if handoff is needed
let decision = handoff_service
    .should_handoff(task, current_agent, context)
    .await?;

match decision {
    HandoffDecision::Complete => {
        // Task can be completed by current agent
    }
    HandoffDecision::Handoff { target_agent, reason } => {
        // Delegate to specialist
        let result = execute_handoff(target_agent, task).await?;
    }
}
}

Handoff Tool

User Story US-14.5: Mid-execution agent delegation via LLM tool calls.

Concept

The handoff_to_agent tool is automatically registered with agents that have handoffs enabled. During execution, the LLM can invoke this tool to delegate tasks to specialists.

Tool Schema

{
  "name": "handoff_to_agent",
  "description": "Delegate the current task to a specialist agent when their expertise is needed",
  "parameters": {
    "type": "object",
    "properties": {
      "agent_name": {
        "type": "string",
        "enum": ["code-expert", "data-analyst", "security-specialist"],
        "description": "Name of the specialist agent to hand off to"
      },
      "message": {
        "type": "string",
        "description": "Clear task description for the specialist agent"
      }
    },
    "required": ["agent_name", "message"]
  }
}

Note: The enum values for agent_name are dynamically populated based on registered specialists.

Example LLM Tool Call

When the LLM recognizes specialized expertise is needed:

{
  "tool_calls": [
    {
      "id": "call_abc123",
      "type": "function",
      "function": {
        "name": "handoff_to_agent",
        "arguments": "{\"agent_name\": \"code-expert\", \"message\": \"Review this Rust function for memory safety issues: fn process_data(data: Vec<u8>) { ... }\"}"
      }
    }
  ]
}

Auto-Registration

The HandoffTool is automatically registered when handoffs are enabled:

#![allow(unused)]
fn main() {
// Automatic registration in PaladinBuilder
if self.handoffs_enabled {
    let handoff_tool = HandoffTool::new(
        self.specialist_list.clone(),
        self.handoff_service.clone()
    );
    arsenal.register_tool(Arc::new(handoff_tool)).await?;
}
}

No manual tool registration required!

Error Scenarios

1. Invalid Agent

{"agent_name": "nonexistent-agent", "message": "..."}

Error: HandoffError::InvalidAgent

Error: Agent 'nonexistent-agent' is not registered as a specialist.
Available agents: code-expert, data-analyst, security-specialist

2. Circular Handoff

general-agent → code-expert → general-agent (attempt)

Error: HandoffError::CircularHandoff

Error: Circular handoff detected.
Chain: general-agent → code-expert → general-agent
Cannot hand back to an agent already in the chain.

3. Max Depth Exceeded

A → B → C → D → E → F (max_depth = 5)

Error: HandoffError::MaxDepthExceeded

Error: Maximum handoff depth (5) exceeded.
Current chain: A → B → C → D → E → F

Execution Flow

1. LLM invokes tool: handoff_to_agent(agent_name="code-expert", message="...")
2. Validation: Check agent exists, no circular handoff, depth OK
3. Context preparation: Build HandoffContext with chain history
4. Specialist execution: Target agent receives task and context
5. Result return: Specialist output returned to original agent
6. Continuation: Original agent incorporates result and continues

Configuration

Autonomous features can be configured via YAML files, CLI flags, or the Builder API.

YAML Configuration

Complete example (config.yml):

autonomous:
  # Autonomous Planning (US-14.1)
  planning:
    enabled: true
    max_subtasks: 15

  # Auto-Generate System Prompt (US-14.2)
  prompt_generation:
    enabled: true
    description: "Expert data analyst specializing in financial reports"

  # Dynamic Temperature Adjustment (US-14.3)
  dynamic_temperature:
    enabled: true
    min: 0.2
    max: 0.85

  # Agent Handoff (US-14.4 & US-14.5)
  handoffs:
    enabled: true
    strategy: "automatic"  # Options: "automatic", "explicit", {"threshold": 0.8}
    max_depth: 5

CLI Flags

# Enable all autonomous features
paladin agent run \
  --config agent.yaml \
  --input "Complex task" \
  --auto-plan \
  --auto-prompt \
  --dynamic-temp \
  --enable-handoffs

# Enable specific features
paladin agent run \
  --config agent.yaml \
  --input "Calculate compound interest" \
  --dynamic-temp  # Only dynamic temperature

Builder API

#![allow(unused)]
fn main() {
use paladin::application::services::paladin::paladin_builder::PaladinBuilder;
use paladin::core::platform::container::paladin::MaxLoops;
use paladin::core::platform::container::autonomous_config::*;

let autonomous_config = AutonomousConfig {
    planning: PlanningConfig {
        enabled: true,
        max_subtasks: 15,
    },
    prompt_generation: PromptConfig {
        enabled: true,
        description: Some("Financial analyst".to_string()),
    },
    dynamic_temperature: TemperatureConfig {
        enabled: true,
        min: 0.2,
        max: 0.85,
    },
    handoffs: HandoffConfig {
        enabled: true,
        strategy: HandoffStrategy::Automatic,
        max_depth: 5,
    },
};

let paladin = PaladinBuilder::new(llm_port)
    .name("analyst")

    // Method 1: Individual feature methods
    .max_loops(MaxLoops::Auto)
    .agent_description("Financial analyst")
    .auto_generate_prompt(true)
    .dynamic_temperature(true)
    .temperature_bounds(0.2, 0.85)
    .enable_handoffs()
    .handoff_strategy(HandoffStrategy::Automatic)
    .max_handoff_depth(5)

    // Method 2: Configuration object
    // .with_autonomous_config(autonomous_config)

    .build()
    .await?;
}

Configuration Precedence

When multiple configuration sources are present:

Precedence Order (highest to lowest):

1. CLI Flags: --auto-plan, --auto-prompt, etc.
2. Builder API: Explicit method calls
3. YAML Configuration: config.yml file
4. Defaults: All features disabled

Example:

#![allow(unused)]
fn main() {
// YAML says planning disabled
// Builder says planning enabled
let paladin = PaladinBuilder::new(llm_port)
    .load_config_from_yaml("config.yml")  // planning: enabled: false
    .max_loops(MaxLoops::Auto)            // Builder overrides YAML
    .build().await?;
// Result: Planning is ENABLED (builder takes precedence)
}

Environment Variables

Override configuration via environment variables:

# Planning
export APP_AUTONOMOUS_PLANNING_ENABLED=true
export APP_AUTONOMOUS_PLANNING_MAX_SUBTASKS=20

# Prompt Generation
export APP_AUTONOMOUS_PROMPT_GENERATION_ENABLED=true
export APP_AUTONOMOUS_PROMPT_GENERATION_DESCRIPTION="Expert coder"

# Dynamic Temperature
export APP_AUTONOMOUS_DYNAMIC_TEMPERATURE_ENABLED=true
export APP_AUTONOMOUS_DYNAMIC_TEMPERATURE_MIN=0.2
export APP_AUTONOMOUS_DYNAMIC_TEMPERATURE_MAX=0.8

# Handoffs
export APP_AUTONOMOUS_HANDOFFS_ENABLED=true
export APP_AUTONOMOUS_HANDOFFS_STRATEGY=explicit
export APP_AUTONOMOUS_HANDOFFS_MAX_DEPTH=10

Best Practices

When to Use Each Feature

Autonomous Planning

✅ Use when:

• Task is complex and multi-step
• Breaking down manually is time-consuming
• Workflow is exploratory (research, analysis)

❌ Avoid when:

• Task is simple and single-step
• Exact workflow is known and fixed
• Real-time performance is critical (adds planning overhead)

Auto-Generate Prompts

✅ Use when:

• Creating many agents with similar roles
• Standardizing prompt quality across agents
• Experimenting with new agent configurations

❌ Avoid when:

• Highly specialized prompts requiring domain expertise
• Production agents where prompt is carefully tuned
• Prompt generation costs are a concern

Dynamic Temperature

✅ Use when:

• Agent handles diverse task types
• Task type varies per execution
• Optimal temperature is unknown

❌ Avoid when:

• Agent has single, consistent task type
• Temperature is already well-tuned
• Task classification overhead is unacceptable

Agent Handoffs

✅ Use when:

• Multiple specialized agents exist
• Tasks require varied expertise
• Collaboration improves outcomes

❌ Avoid when:

• Single agent can handle all tasks
• Handoff overhead exceeds benefits
• Linear workflow is more efficient

Performance Considerations

Token Usage

• Planning: Adds ~500-1500 tokens for plan generation
• Prompt Generation: One-time cost of ~300-800 tokens (cached)
• Temperature Classification: ~200-400 tokens per classification
• Handoffs: ~200 tokens per handoff decision + specialist execution

Optimization:

#![allow(unused)]
fn main() {
// Use planning selectively
let use_planning = task_length > 100 || task_complexity > 0.7;
let max_loops = if use_planning {
    MaxLoops::Auto
} else {
    MaxLoops::Fixed(3)
};
}

Latency

• Planning: +1-3 seconds for plan generation
• Prompt Generation: +0.5-2 seconds (only on first execution)
• Temperature Classification: +0.3-1 second per task
• Handoffs: +LLM latency per hop (2-5 seconds typical)

Optimization:

#![allow(unused)]
fn main() {
// Disable features for latency-sensitive tasks
if real_time_required {
    builder.dynamic_temperature(false);
    builder.max_loops(MaxLoops::Fixed(1));
}
}

Cost Management

• Estimate costs: Calculate token usage for budget planning
• Cache prompts: Prompt generation is cached automatically
• Limit depth: Set reasonable max_handoff_depth (3-5)
• Monitor usage: Track autonomous feature LLM calls

Token Budget Management

#![allow(unused)]
fn main() {
// Calculate estimated token usage
let base_tokens = 1000; // Task input + output
let planning_tokens = planning_enabled ? 1000 : 0;
let prompt_gen_tokens = prompt_gen_enabled && !cached ? 500 : 0;
let temp_tokens = dynamic_temp_enabled ? 300 : 0;
let handoff_tokens = handoffs_enabled ? 200 * max_depth : 0;

let estimated_total = base_tokens + planning_tokens
                    + prompt_gen_tokens + temp_tokens
                    + handoff_tokens;

if estimated_total > budget {
    // Disable or reduce features
}
}

Combining Features Effectively

Recommended Combinations

Research Agent (Exploration & Analysis):

#![allow(unused)]
fn main() {
.max_loops(MaxLoops::Auto)         // Plan research steps
.dynamic_temperature(true)          // Adapt to analysis vs. writing
.enable_handoffs()                  // Delegate to specialists
}

Code Generation Agent (Precision & Expertise):

#![allow(unused)]
fn main() {
.auto_generate_prompt(true)         // Standard prompt template
.dynamic_temperature(true)          // Low temp for code, high for docs
.enable_handoffs()                  // Delegate to security expert
}

Customer Support Agent (Conversational & Adaptive):

#![allow(unused)]
fn main() {
.dynamic_temperature(true)          // Conversational tone
.enable_handoffs()                  // Escalate to specialists
}

Data Analysis Agent (Structured & Methodical):

#![allow(unused)]
fn main() {
.max_loops(MaxLoops::Auto)         // Break down analysis steps
.auto_generate_prompt(true)         // Role-based prompt
.dynamic_temperature(true)          // Analytical temperature
}

Avoid Over-Configuration

❌ Too much:

#![allow(unused)]
fn main() {
.max_loops(MaxLoops::Auto)         // Planning
.auto_generate_prompt(true)         // Auto prompt
.dynamic_temperature(true)          // Dynamic temp
.enable_handoffs()                  // Handoffs
.max_handoff_depth(10)              // Deep chains
// Result: Slow, expensive, complex debugging
}

✅ Balanced:

#![allow(unused)]
fn main() {
.max_loops(MaxLoops::Fixed(5))     // Fixed loops
.system_prompt("...")               // Manual prompt (tuned)
.dynamic_temperature(true)          // Only dynamic temp
// Result: Fast, cost-effective, predictable
}

Error Handling

Autonomous features have specific error types for different failure modes.

PlanningError

#![allow(unused)]
fn main() {
pub enum PlanningError {
    /// LLM failed to generate a valid plan
    PlanGenerationFailed(String),

    /// Generated plan has no subtasks
    EmptyPlan,

    /// Subtask dependencies are circular
    CircularDependencies(Vec<String>),

    /// LLM provider error during planning
    LlmError(LlmError),
}
}

Handling:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::planning::PlanningError;

match paladin.execute(input).await {
    Err(PaladinError::Planning(PlanningError::PlanGenerationFailed(msg))) => {
        eprintln!("Failed to generate plan: {}", msg);
        // Fallback: Use fixed loop count
        paladin.config_mut().max_loops = MaxLoops::Fixed(5);
        paladin.execute(input).await?
    }
    Err(PaladinError::Planning(PlanningError::EmptyPlan)) => {
        eprintln!("LLM returned empty plan, using default execution");
        // Fallback: Single execution
        paladin.config_mut().max_loops = MaxLoops::Fixed(1);
        paladin.execute(input).await?
    }
    Ok(result) => result,
    Err(e) => return Err(e),
}
}

PromptError

#![allow(unused)]
fn main() {
pub enum PromptError {
    /// LLM failed to generate a valid prompt
    GenerationFailed(String),

    /// Agent description is missing or empty
    MissingDescription,

    /// Generated prompt is too short/long
    InvalidLength { length: usize, min: usize, max: usize },

    /// LLM provider error during generation
    LlmError(LlmError),
}
}

Handling:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::prompt::PromptError;

let builder = PaladinBuilder::new(llm_port)
    .agent_description("Analyst")
    .auto_generate_prompt(true);

match builder.build().await {
    Err(PaladinError::Prompt(PromptError::MissingDescription)) => {
        eprintln!("Agent description required for auto-prompt");
        // Fallback: Use default prompt
        PaladinBuilder::new(llm_port)
            .system_prompt("You are a helpful AI assistant.")
            .build().await?
    }
    Err(PaladinError::Prompt(PromptError::GenerationFailed(msg))) => {
        eprintln!("Prompt generation failed: {}", msg);
        // Fallback: Manual prompt
        PaladinBuilder::new(llm_port)
            .system_prompt("You are an analyst.")
            .build().await?
    }
    Ok(paladin) => paladin,
    Err(e) => return Err(e),
}
}

HandoffError

#![allow(unused)]
fn main() {
pub enum HandoffError {
    /// Target agent not found in registry
    InvalidAgent(String),

    /// Circular handoff detected
    CircularHandoff { chain: Vec<String>, attempted_target: String },

    /// Maximum handoff depth exceeded
    MaxDepthExceeded { current_depth: u32, max_depth: u32 },

    /// Specialist execution failed
    ExecutionFailed { agent: String, error: String },

    /// LLM provider error during handoff
    LlmError(LlmError),
}
}

Handling:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::handoff::{HandoffError, HandoffDecision};

match handoff_service.should_handoff(task, agent, context).await {
    Ok(HandoffDecision::Handoff { target_agent, .. }) => {
        match execute_handoff(&target_agent, task).await {
            Ok(result) => result,
            Err(HandoffError::InvalidAgent(name)) => {
                eprintln!("Agent '{}' not found, continuing with current agent", name);
                // Fallback: Current agent completes task
                current_agent.execute(task).await?
            }
            Err(HandoffError::CircularHandoff { chain, attempted_target }) => {
                eprintln!("Circular handoff detected: {:?} -> {}", chain, attempted_target);
                // Fallback: Break chain, current agent completes
                current_agent.execute(task).await?
            }
            Err(HandoffError::MaxDepthExceeded { current_depth, max_depth }) => {
                eprintln!("Max depth {} exceeded (current: {})", max_depth, current_depth);
                // Fallback: No more handoffs, finish with current agent
                current_agent.execute(task).await?
            }
            Err(e) => return Err(e),
        }
    }
    Ok(HandoffDecision::Complete) => {
        // No handoff needed
        current_agent.execute(task).await?
    }
    Err(e) => return Err(e.into()),
}
}

Graceful Degradation

Pattern: Disable feature on error, continue execution

#![allow(unused)]
fn main() {
async fn execute_with_fallback(paladin: &Paladin, input: &str) -> Result<String> {
    // Try with autonomous features
    match paladin.execute(input).await {
        Ok(result) => Ok(result.output),

        // Planning failed: retry with fixed loops
        Err(PaladinError::Planning(_)) => {
            eprintln!("Planning failed, using fixed execution");
            let mut config = paladin.config().clone();
            config.max_loops = MaxLoops::Fixed(3);
            paladin.execute_with_config(input, config).await
                .map(|r| r.output)
        }

        // Handoff failed: continue without delegation
        Err(PaladinError::Handoff(_)) => {
            eprintln!("Handoff failed, completing task without delegation");
            let mut config = paladin.config().clone();
            config.handoffs_enabled = false;
            paladin.execute_with_config(input, config).await
                .map(|r| r.output)
        }

        // Other errors: propagate
        Err(e) => Err(e),
    }
}
}

Troubleshooting

Common Issues and Solutions

Issue: Planning generates too many subtasks

Symptom: Plans have 20+ subtasks, execution is slow

Solution:

autonomous:
  planning:
    max_subtasks: 10  # Reduce limit

Or provide more focused input:

#![allow(unused)]
fn main() {
// ❌ Too broad
"Analyze the company's performance"

// ✅ More focused
"Analyze Q4 2025 revenue trends and identify top 3 growth drivers"
}

Issue: Generated prompts are too generic

Symptom: Auto-generated prompts lack specificity

Solution: Provide detailed agent descriptions

#![allow(unused)]
fn main() {
// ❌ Too vague
.agent_description("Analyst")

// ✅ Specific
.agent_description(
    "Senior financial analyst specializing in SaaS companies, \
     with expertise in revenue forecasting, churn analysis, and \
     unit economics. Focus on actionable insights and data-driven \
     recommendations."
)
}

Issue: Wrong temperature for task

Symptom: Factual tasks get creative outputs, or vice versa

Solution: Check classification logic or override manually

#![allow(unused)]
fn main() {
// Option 1: Provide clearer task description
// ❌ Ambiguous
"Tell me about quantum computing"

// ✅ Clear intent
"Calculate the energy levels of a hydrogen atom" // → Factual

// Option 2: Manual override
.temperature(0.2)  // Force low temperature
.dynamic_temperature(false)  // Disable auto-adjustment
}

Issue: Circular handoff errors

Symptom: HandoffError::CircularHandoff errors

Solution: Review agent configurations and handoff logic

#![allow(unused)]
fn main() {
// Check specialist capabilities don't overlap
handoff_service.register_specialist(
    "code-expert",
    "Rust code generation and debugging (does NOT do security audits)"
);

handoff_service.register_specialist(
    "security-expert",
    "Security audits and vulnerability analysis (does NOT write code)"
);
}

Issue: Max depth exceeded

Symptom: HandoffError::MaxDepthExceeded errors

Solution: Increase max_depth or simplify task delegation

autonomous:
  handoffs:
    max_depth: 10  # Increase limit

Or break complex delegation into separate Paladin executions.

Issue: Features not activating

Symptom: Autonomous features appear disabled despite configuration

Solution: Verify configuration precedence

#![allow(unused)]
fn main() {
// Check 1: Configuration loaded?
println!("Config: {:?}", paladin.config());

// Check 2: Builder methods called?
let paladin = PaladinBuilder::new(llm_port)
    .auto_generate_prompt(true)  // Must be true
    .agent_description("...")     // Must be provided
    .build().await?;

// Check 3: CLI flags passed?
// paladin agent run --auto-prompt  (must include flag)
}

Debugging Tips

Enable Logging

export RUST_LOG=paladin=debug,paladin::application::services::paladin=trace

# Run with verbose output
paladin agent run --config agent.yaml --input "Task" --verbose

Output:

DEBUG paladin::planning: Generating plan for task: "Analyze data"
DEBUG paladin::planning: Plan generated with 5 subtasks
TRACE paladin::planning: Subtask 1: Load dataset
TRACE paladin::planning: Subtask 2: Clean data
...

Tracing

Use OpenTelemetry for distributed tracing:

#![allow(unused)]
fn main() {
use tracing::{info, debug, span, Level};

let span = span!(Level::INFO, "autonomous_execution");
let _enter = span.enter();

info!("Starting execution with planning enabled");
debug!(max_subtasks = config.planning.max_subtasks, "Planning configuration");

// Execution...
}

Inspect Intermediate Results

#![allow(unused)]
fn main() {
// Enable detailed output
let result = paladin.execute(input).await?;

println!("Execution time: {}ms", result.execution_time_ms);
println!("Loops completed: {}", result.loop_count);
println!("Stop reason: {:?}", result.stop_reason);

// Access plan (if available)
if let Some(plan) = result.plan {
    println!("Generated plan:");
    for subtask in plan.subtasks {
        println!("  - {}: {}", subtask.id, subtask.description);
    }
}

// Access handoff history
for handoff in result.handoff_history {
    println!("Handoff: {} -> {} ({})",
             handoff.from_agent,
             handoff.to_agent,
             handoff.reason);
}
}

Performance Optimization Tips

Reduce Token Usage

#![allow(unused)]
fn main() {
// Disable expensive features for simple tasks
if task.len() < 50 {
    builder
        .max_loops(MaxLoops::Fixed(1))
        .dynamic_temperature(false);
}
}

Cache Aggressively

#![allow(unused)]
fn main() {
// Prompt generation caches automatically
// For other expensive operations, implement caching:
use std::collections::HashMap;
use std::sync::Arc;
use tokio::sync::RwLock;

let task_type_cache: Arc<RwLock<HashMap<String, TaskType>>> =
    Arc::new(RwLock::new(HashMap::new()));

// Check cache before classification
if let Some(cached_type) = task_type_cache.read().await.get(task) {
    return Ok(*cached_type);
}
}

Parallel Execution

#![allow(unused)]
fn main() {
// For independent tasks, use Phalanx (parallel execution)
let phalanx = Phalanx::new(vec![paladin1, paladin2, paladin3]);
let results = phalanx.execute(inputs).await?;
}

Optimize Handoff Strategy

#![allow(unused)]
fn main() {
// Use explicit handoffs for predictable workflows
builder.handoff_strategy(HandoffStrategy::Explicit);

// Implement custom decision logic
if task_requires_specialist(&task) {
    execute_handoff("specialist", &task).await?
} else {
    current_agent.execute(&task).await?
}
}

Advanced Usage

Combining Autonomous Features

Example: Research & Analysis Agent

#![allow(unused)]
fn main() {
let research_agent = PaladinBuilder::new(llm_port)
    .name("research-analyst")
    .max_loops(MaxLoops::Auto)  // Plan research steps
    .agent_description(
        "Expert research analyst with skills in literature review, \
         data synthesis, and academic writing"
    )
    .auto_generate_prompt(true)  // Generate researcher prompt
    .dynamic_temperature(true)   // Analytical + creative
    .temperature_bounds(0.3, 0.8)
    .enable_handoffs()           // Delegate to specialists
    .handoff_strategy(HandoffStrategy::threshold(0.7))
    .build()
    .await?;

// Register specialists
handoff_service.register_specialist(
    "statistics-expert",
    "Statistical analysis and data interpretation"
).await?;

handoff_service.register_specialist(
    "writer",
    "Academic and technical writing"
).await?;

// Execute complex research task
let result = research_agent
    .execute("Research the impact of AI on software development productivity")
    .await?;
}

Example: Code Generation Agent

#![allow(unused)]
fn main() {
let code_agent = PaladinBuilder::new(llm_port)
    .name("code-generator")
    .agent_description(
        "Expert Rust developer specializing in safe, idiomatic code \
         with comprehensive error handling and documentation"
    )
    .auto_generate_prompt(true)  // Generate coder prompt
    .dynamic_temperature(true)   // Low for code, higher for docs
    .temperature_bounds(0.1, 0.6)
    .enable_handoffs()           // Delegate testing & review
    .build()
    .await?;

// Register specialists
handoff_service.register_specialist(
    "test-engineer",
    "Unit and integration test generation"
).await?;

handoff_service.register_specialist(
    "security-auditor",
    "Security review and vulnerability scanning"
).await?;

// Generate with automatic testing and review
let result = code_agent
    .execute("Create a secure REST API endpoint for user authentication")
    .await?;
}

Custom Agent Configurations

Multi-Stage Pipeline

#![allow(unused)]
fn main() {
// Stage 1: Planning
let planner = PaladinBuilder::new(llm_port)
    .name("planner")
    .max_loops(MaxLoops::Auto)
    .auto_generate_prompt(true)
    .agent_description("Task decomposition specialist")
    .build()
    .await?;

// Stage 2: Execution
let executor = PaladinBuilder::new(llm_port)
    .name("executor")
    .max_loops(MaxLoops::Fixed(1))
    .dynamic_temperature(true)
    .enable_handoffs()
    .build()
    .await?;

// Stage 3: Review
let reviewer = PaladinBuilder::new(llm_port)
    .name("reviewer")
    .max_loops(MaxLoops::Fixed(1))
    .temperature(0.3)  // Analytical
    .system_prompt("Review the output for completeness and accuracy")
    .build()
    .await?;

// Execute pipeline
let plan_result = planner.execute(task).await?;
let exec_result = executor.execute(&plan_result.output).await?;
let final_result = reviewer.execute(&exec_result.output).await?;
}

Adaptive Agent

#![allow(unused)]
fn main() {
// Agent that adjusts its configuration based on feedback
struct AdaptiveAgent {
    paladin: Paladin,
    performance_history: Vec<f32>,
}

impl AdaptiveAgent {
    async fn execute_adaptive(&mut self, task: &str) -> Result<String> {
        // Adjust based on historical performance
        let avg_performance = self.performance_history.iter().sum::<f32>()
                            / self.performance_history.len() as f32;

        if avg_performance < 0.7 {
            // Performance is low, enable more features
            self.paladin.config_mut().max_loops = MaxLoops::Auto;
            self.paladin.config_mut().enable_handoffs = true;
        } else {
            // Performance is good, optimize for speed
            self.paladin.config_mut().max_loops = MaxLoops::Fixed(3);
            self.paladin.config_mut().enable_handoffs = false;
        }

        let result = self.paladin.execute(task).await?;

        // Record performance
        let performance = self.calculate_performance(&result);
        self.performance_history.push(performance);

        Ok(result.output)
    }
}
}

Integration with Battalion Patterns

Formation with Autonomous Agents

#![allow(unused)]
fn main() {
use paladin::application::services::battalion::formation_service::FormationService;

// Create autonomous agents
let agent1 = PaladinBuilder::new(llm_port.clone())
    .name("researcher")
    .max_loops(MaxLoops::Auto)
    .auto_generate_prompt(true)
    .agent_description("Research and data gathering specialist")
    .build().await?;

let agent2 = PaladinBuilder::new(llm_port.clone())
    .name("analyst")
    .dynamic_temperature(true)
    .auto_generate_prompt(true)
    .agent_description("Data analysis and insights expert")
    .build().await?;

let agent3 = PaladinBuilder::new(llm_port.clone())
    .name("writer")
    .temperature(0.7)
    .auto_generate_prompt(true)
    .agent_description("Report writing and documentation specialist")
    .build().await?;

// Formation: Sequential execution (output N → input N+1)
let formation = FormationService::new();
let result = formation.execute(
    vec![agent1, agent2, agent3],
    "Analyze market trends in AI industry"
).await?;
}

Phalanx with Handoffs

#![allow(unused)]
fn main() {
use paladin::application::services::battalion::phalanx_service::PhalanxService;

// Create agents with handoff capabilities
let agents: Vec<Paladin> = vec![
    PaladinBuilder::new(llm_port.clone())
        .name("competitor-analyzer")
        .enable_handoffs()
        .build().await?,
    PaladinBuilder::new(llm_port.clone())
        .name("market-researcher")
        .enable_handoffs()
        .build().await?,
    PaladinBuilder::new(llm_port.clone())
        .name("trend-analyst")
        .enable_handoffs()
        .build().await?,
];

// Register shared specialists
for agent in &agents {
    handoff_service.register_specialist(
        "data-expert",
        "Statistical analysis and data interpretation"
    ).await?;
}

// Phalanx: Parallel execution
let phalanx = PhalanxService::new();
let results = phalanx.execute(
    agents,
    vec!["Analyze competitor X", "Research market Y", "Identify trend Z"]
).await?;
}

API Reference

PaladinBuilder Methods

Autonomous Planning

#![allow(unused)]
fn main() {
/// Enable autonomous planning mode
pub fn max_loops(mut self, loops: MaxLoops) -> Self

// MaxLoops variants
pub enum MaxLoops {
    Fixed(u32),  // Manual loop count
    Auto,        // Autonomous planning
}
}

Prompt Generation

#![allow(unused)]
fn main() {
/// Enable automatic prompt generation
pub fn auto_generate_prompt(mut self, enabled: bool) -> Self

/// Set agent description (required for auto-prompt)
pub fn agent_description(mut self, description: impl Into<String>) -> Self

/// Manual system prompt (overrides auto-generation)
pub fn system_prompt(mut self, prompt: impl Into<String>) -> Self
}

Dynamic Temperature

#![allow(unused)]
fn main() {
/// Enable dynamic temperature adjustment
pub fn dynamic_temperature(mut self, enabled: bool) -> Self

/// Set temperature bounds (min, max)
pub fn temperature_bounds(mut self, min: f32, max: f32) -> Self

/// Manual temperature (overrides dynamic)
pub fn temperature(mut self, temp: f32) -> Self
}

Agent Handoffs

#![allow(unused)]
fn main() {
/// Enable agent handoff capabilities
pub fn enable_handoffs(mut self) -> Self

/// Set handoff strategy
pub fn handoff_strategy(mut self, strategy: HandoffStrategy) -> Self

/// Set maximum handoff depth
pub fn max_handoff_depth(mut self, depth: u32) -> Self
}

Configuration Types

AutonomousConfig

#![allow(unused)]
fn main() {
pub struct AutonomousConfig {
    pub planning: PlanningConfig,
    pub prompt_generation: PromptConfig,
    pub dynamic_temperature: TemperatureConfig,
    pub handoffs: HandoffConfig,
}

impl AutonomousConfig {
    pub fn new() -> Self;
    pub fn validate(&self) -> Result<(), String>;
}
}

PlanningConfig

#![allow(unused)]
fn main() {
pub struct PlanningConfig {
    pub enabled: bool,
    pub max_subtasks: u32,
}

impl PlanningConfig {
    pub fn new(max_subtasks: u32) -> Self;
    pub fn enabled() -> Self;
}
}

PromptConfig

#![allow(unused)]
fn main() {
pub struct PromptConfig {
    pub enabled: bool,
    pub description: Option<String>,
}

impl PromptConfig {
    pub fn new(description: String) -> Self;
    pub fn enabled() -> Self;
    pub fn with_description(self, description: String) -> Self;
}
}

TemperatureConfig

#![allow(unused)]
fn main() {
pub struct TemperatureConfig {
    pub enabled: bool,
    pub min: f32,
    pub max: f32,
}

impl TemperatureConfig {
    pub fn new(min: f32, max: f32) -> Self;
    pub fn enabled() -> Self;
    pub fn with_bounds(self, min: f32, max: f32) -> Self;
}
}

HandoffConfig

#![allow(unused)]
fn main() {
pub struct HandoffConfig {
    pub enabled: bool,
    pub strategy: HandoffStrategy,
    pub max_depth: u32,
}

impl HandoffConfig {
    pub fn new(strategy: HandoffStrategy, max_depth: u32) -> Self;
    pub fn enabled() -> Self;
    pub fn with_strategy(self, strategy: HandoffStrategy) -> Self;
    pub fn with_max_depth(self, max_depth: u32) -> Self;
}
}

Services

PlanningService

#![allow(unused)]
fn main() {
pub struct PlanningService {
    llm_port: Arc<dyn LlmPort>,
}

impl PlanningService {
    pub fn new(llm_port: Arc<dyn LlmPort>) -> Self;

    pub async fn generate_plan(
        &self,
        task: &str,
        max_subtasks: u32
    ) -> Result<TaskPlan, PlanningError>;
}
}

PromptGenerationService

#![allow(unused)]
fn main() {
pub struct PromptGenerationService {
    llm_port: Arc<dyn LlmPort>,
    cache: Arc<RwLock<HashMap<String, String>>>,
}

impl PromptGenerationService {
    pub fn new(llm_port: Arc<dyn LlmPort>) -> Self;

    pub async fn generate_prompt(
        &self,
        agent_name: &str,
        description: &str
    ) -> Result<String, PromptError>;

    pub async fn clear_cache(&self);

    pub async fn invalidate_cache(&self, agent_name: &str, description: &str);
}
}

TemperatureService

#![allow(unused)]
fn main() {
pub struct TemperatureService {
    llm_port: Arc<dyn LlmPort>,
}

impl TemperatureService {
    pub fn new(llm_port: Arc<dyn LlmPort>) -> Self;

    pub async fn calculate_optimal_temperature(
        &self,
        task: &str,
        config: Option<&TemperatureConfig>
    ) -> Result<f32, TemperatureError>;

    pub async fn detect_task_type_with_llm(
        &self,
        task: &str
    ) -> Result<TaskType, TemperatureError>;
}
}

HandoffService

#![allow(unused)]
fn main() {
pub struct HandoffService {
    llm_port: Arc<dyn LlmPort>,
    specialists: Arc<RwLock<HashMap<String, String>>>,
}

impl HandoffService {
    pub fn new(llm_port: Arc<dyn LlmPort>) -> Self;

    pub async fn register_specialist(
        &self,
        name: &str,
        description: &str
    ) -> Result<(), HandoffError>;

    pub async fn should_handoff(
        &self,
        task: &str,
        current_agent: &str,
        context: &HandoffContext
    ) -> Result<HandoffDecision, HandoffError>;

    pub fn get_specialists(&self) -> Vec<String>;
}
}

Error Types

#![allow(unused)]
fn main() {
pub enum PlanningError {
    PlanGenerationFailed(String),
    EmptyPlan,
    CircularDependencies(Vec<String>),
    LlmError(LlmError),
}

pub enum PromptError {
    GenerationFailed(String),
    MissingDescription,
    InvalidLength { length: usize, min: usize, max: usize },
    LlmError(LlmError),
}

pub enum TemperatureError {
    ClassificationFailed(String),
    InvalidBounds { min: f32, max: f32 },
    LlmError(LlmError),
}

pub enum HandoffError {
    InvalidAgent(String),
    CircularHandoff { chain: Vec<String>, attempted_target: String },
    MaxDepthExceeded { current_depth: u32, max_depth: u32 },
    ExecutionFailed { agent: String, error: String },
    LlmError(LlmError),
}
}

Examples

See the examples/ directory for complete working examples:

• autonomous_planning.rs - Autonomous planning mode
• autonomous_prompt_generation.rs - Auto-generated prompts
• autonomous_temperature.rs - Dynamic temperature
• autonomous_handoffs.rs - Agent delegation
• autonomous_complete.rs - All features combined

Run examples:

# Autonomous planning
cargo run --example autonomous_planning

# Auto-generate prompts
cargo run --example autonomous_prompt_generation

# Dynamic temperature
cargo run --example autonomous_temperature

# Agent handoffs
cargo run --example autonomous_handoffs

# All features
cargo run --example autonomous_complete

Further Reading

• Paladin Overview
• Battalion Orchestration
• Arsenal Tool System
• Garrison Memory System
• Configuration Guide
• API Documentation

Version: 0.1.0
Last Updated: February 1, 2026
Status: ✅ Stable (Epic 14 Complete)

Battalion Orchestration System

Multi-Paladin coordination framework with eight orchestration patterns

Table of Contents

1. Overview
2. Quick Start
3. Orchestration Patterns
4. Commander Strategy Router
5. Configuration
6. Error Handling
7. Performance
8. Best Practices
9. API Reference

Overview

The Battalion system enables coordination of multiple Paladin agents through eight distinct orchestration patterns:

Key Features

• Hexagonal Architecture: Clean separation of domain, application, and infrastructure layers
• Error Resilience: Three strategies (FailFast, ContinueOnError, RetryThenContinue)
• High Performance: <1s orchestration overhead, tested with 100+ concurrent Battalions
• Type Safety: Full Rust type system guarantees, compile-time validation
• Async/Await: Built on tokio for efficient concurrent execution

Quick Start

Installation

Add to Cargo.toml:

[dependencies]
paladin = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

Basic Formation Example

use paladin::application::services::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 Paladins
    let paladins = vec![
        create_paladin("analyzer", "Analyze the input data"),
        create_paladin("processor", "Process the analyzed data"),
        create_paladin("summarizer", "Create a summary"),
    ];

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

    // Execute
    let service = FormationExecutionService::new(Arc::new(llm_port));
    let result = service.execute(&formation, "Initial input").await?;

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

Orchestration Patterns

1. Formation (Sequential Pipeline)

Purpose: Execute Paladins sequentially, passing output from each to the next.

Architecture:

Input → Paladin₁ → Paladin₂ → Paladin₃ → Output

When to Use:

• Data transformation pipelines
• Multi-step analysis workflows
• Iterative refinement tasks

Example:

#![allow(unused)]
fn main() {
let paladins = vec![
    create_paladin("extractor", "Extract key information"),
    create_paladin("validator", "Validate the extracted data"),
    create_paladin("formatter", "Format as JSON"),
];

let formation = Formation::new(paladins, config)?;
let result = formation_service.execute(&formation, text_input).await?;
}

Performance: Linear time complexity O(n), where n = number of Paladins.

2. Phalanx (Concurrent Execution)

Purpose: Execute all Paladins concurrently and aggregate results.

Architecture:

Input → ┌─ Paladin₁ ─┐
        ├─ Paladin₂ ─┤ → Aggregation → Output
        └─ Paladin₃ ─┘

Aggregation Strategies:

Example:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::phalanx::{Phalanx, AggregationStrategy};

let paladins = vec![
    create_paladin("gpt4", "Expert analyst"),
    create_paladin("claude", "Critical reviewer"),
    create_paladin("gemini", "Creative thinker"),
];

let phalanx = Phalanx::new(paladins, config)?
    .with_aggregation(AggregationStrategy::Majority);

let result = phalanx_service.execute(&phalanx, question).await?;
}

Per-Paladin Metrics:

Phalanx provides detailed execution metrics for each Paladin, enabling fine-grained performance analysis:

#![allow(unused)]
fn main() {
let result = phalanx_service.execute(&phalanx, question).await?;

// Access execution times per Paladin by name
println!("Execution Times:");
for (paladin_name, time_ms) in &result.per_paladin_times {
    println!("  {}: {}ms", paladin_name, time_ms);
}

// Access token usage per Paladin
println!("\nToken Usage:");
for (paladin_name, tokens) in &result.per_paladin_tokens {
    println!("  {}: {} tokens (prompt: {}, completion: {})",
        paladin_name,
        tokens.total_tokens,
        tokens.prompt_tokens,
        tokens.completion_tokens
    );
}

// Calculate metrics
let avg_time: u64 = result.per_paladin_times.values().sum::<u64>()
    / result.per_paladin_times.len() as u64;
let max_time = result.per_paladin_times.values().max().unwrap_or(&0);
let total_tokens: usize = result.per_paladin_tokens.values()
    .map(|t| t.total_tokens)
    .sum();

println!("\nAggregate Metrics:");
println!("  Average time: {}ms", avg_time);
println!("  Slowest Paladin: {}ms", max_time);
println!("  Total tokens: {}", total_tokens);
}

Metrics Use Cases:

• Performance Profiling: Identify slow Paladins for optimization
• Cost Analysis: Track token consumption per model/Paladin
• Load Balancing: Adjust Paladin assignments based on execution patterns
• SLA Monitoring: Verify all Paladins meet latency requirements

Performance: Constant time O(1) with respect to Paladin count (concurrent execution).

3. Campaign (Graph Orchestration)

Purpose: Execute Paladins based on a directed acyclic graph (DAG) with conditional routing.

Architecture:

        ┌─ Paladin₂ ─┐
Input → Paladin₁      ├→ Paladin₄ → Output
        └─ Paladin₃ ─┘

Edge Conditions:

• Always: Unconditional edge
• Contains(String): Route if output contains text
• Regex(String): Route if regex matches
• Custom(String): User-defined condition logic

Example:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::campaign::{Campaign, EdgeCondition};

let mut campaign = Campaign::new(config)?;

// Add Paladins
campaign.add_paladin("classifier", create_paladin("classifier", "Classify input"));
campaign.add_paladin("technical", create_paladin("technical", "Handle technical"));
campaign.add_paladin("general", create_paladin("general", "Handle general"));

// Add conditional edges
campaign.add_edge(
    "classifier",
    "technical",
    EdgeCondition::Contains("technical".into()),
    None // No transformation
)?;

campaign.add_edge(
    "classifier",
    "general",
    EdgeCondition::Always,
    None
)?;

campaign.set_entry_points(vec!["classifier".into()])?;

let result = campaign_service.execute(&campaign, user_input).await?;
}

Performance: Depends on graph structure; worst-case O(V + E) where V = vertices, E = edges.

4. Chain of Command (Hierarchical Delegation)

Purpose: Commander Paladin analyzes input and delegates to appropriate specialist Paladin(s).

Architecture:

                Commander (analyzes + routes)
                     ↓
        ┌────────────┼────────────┐
        ↓            ↓            ↓
   Specialist₁   Specialist₂  Specialist₃

Delegation Strategies:

Example - Automatic Delegation:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::chain_of_command::{
    ChainOfCommand, DelegationStrategy
};

let commander = create_paladin("commander",
    "You are a task router. Analyze the input and select specialists.");

let specialists = vec![
    create_paladin("database", "Database specialist"),
    create_paladin("api", "API integration specialist"),
    create_paladin("analytics", "Data analytics specialist"),
];

let chain = ChainOfCommand::new(commander, specialists, config)?
    .with_strategy(DelegationStrategy::Automatic);

// Commander will analyze "Query user database" and select database specialist
let result = chain_service.execute(&chain, "Query user database").await?;
}

Performance: O(1) for delegation decision + O(k) for executing k selected specialists.

5. Conclave (Multi-Expert Synthesis)

Purpose: Multiple specialized Paladins (experts) analyze input in parallel, then an aggregator synthesizes their diverse perspectives into a comprehensive response. Implements the Mixture-of-Agents pattern.

Architecture:

                    ┌──────────────┐
                    │   Input      │
                    └──────┬───────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
         ▼                 ▼                 ▼
  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐
  │  Expert 1   │   │  Expert 2   │   │  Expert 3   │
  │ (Technical) │   │ (Business)  │   │ (Security)  │
  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘
         │                 │                 │
         └─────────────────┼─────────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │ Aggregator  │
                    │  Synthesis  │
                    └──────┬──────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   Final     │
                    │  Response   │
                    └─────────────┘

When to Use:

• Decisions benefit from multiple expert perspectives (technical, business, security, etc.)
• Diverse viewpoints must be intelligently synthesized
• Quality improves through multi-perspective analysis
• Different stakeholder concerns must all be addressed

Key Features:

• Parallel Expert Execution: All experts analyze concurrently
• Intelligent Synthesis: Aggregator combines perspectives (not simple concatenation)
• Resilience: Continues even if some experts fail (partial success)
• Retry Logic: Exponential backoff with jitter for failed experts
• Token Management: Optional truncation to prevent context overflow
• Observability: Three levels (Minimal, Standard, Verbose)

Example:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::conclave::{Conclave, ConclaveConfig};

// Create 3 experts with different perspectives
let technical = create_paladin("TechnicalExpert",
    "Analyze from a technical architecture perspective");
let business = create_paladin("BusinessExpert",
    "Analyze from a business strategy perspective");
let security = create_paladin("SecurityExpert",
    "Analyze from a security and compliance perspective");

// Create aggregator to synthesize expert outputs
let aggregator = create_paladin("Aggregator",
    "Synthesize the expert analyses into a comprehensive recommendation");

// Configure Conclave
let config = ConclaveConfig::new("expert-panel", BattalionConfig::default())
    .with_timeout(300)
    .with_retry_attempts(2)
    .with_observability(ObservabilityLevel::Standard);

// Build and execute
let conclave = Conclave::new(
    vec![technical, business, security],
    aggregator,
    config
)?;

let result = conclave_service.execute(&conclave,
    "Should we migrate to microservices?"
).await?;

println!("Final Recommendation:\n{}", result.aggregated_output.output);
}

Performance: O(1) with respect to expert count (concurrent execution) + O(1) for aggregation.

Learn More: See Conclave Pattern Guide for comprehensive documentation including configuration options, YAML setup, CLI usage, best practices, and troubleshooting.

6. Council (Deliberative Discussion)

Purpose: Enable multi-agent deliberation with structured turn-taking and conversation flow.

Architecture:

Topic: "Should we implement feature X?"

Round 1:  [Expert1] → [Expert2] → [Expert3]
Round 2:  [Expert1] → [Expert2] → [Expert3]
Round 3:  [Expert1] → [Expert2] → [Expert3]

→ Final Output: Synthesized recommendations

Turn-Taking Strategies:

• RoundRobin: Participants speak in order, cycling through the list
• ModeratorDirected: Moderator controls discussion flow, calls on relevant experts

Termination Conditions:

• MaxRounds: Fixed number of discussion rounds
• Consensus: Stops when agreement detected (keyword-based)
• ModeratorDecision: Moderator decides when sufficient deliberation
• Keyword: Specific keyword triggers termination (e.g., "APPROVED")

When to Use:

• Collaborative decision-making requiring discussion
• Consensus building among stakeholders
• Expert panel deliberations
• Structured debate with turn-taking

Example:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::council::{
    CouncilBuilder, TurnStrategy, TerminationCondition
};

let council = CouncilBuilder::new()
    .name("Security Review Council")
    .add_participant(security_expert)
    .add_participant(legal_expert)
    .add_participant(technical_expert)
    .turn_strategy(TurnStrategy::RoundRobin)
    .termination_condition(TerminationCondition::MaxRounds(3))
    .build()?;

let topic = "Should we implement two-factor authentication?";
let result = council_service.convene(&council, topic).await?;
}

Performance: O(P × R) where P = participants, R = rounds.

Learn More: See Council Pattern Documentation for comprehensive guide including moderated discussions, consensus building, and conversation history storage.

7. Grove (Intelligent Agent Routing)

Purpose: Route tasks to specialized agents based on expertise matching.

Architecture:

Task: "Optimize database queries"
         │
         ▼
   [Routing Engine]
         │
    ┌────┴────┐
    ▼         ▼
[Backend]  [Frontend]
[Tree]     [Tree]
│          │
├─ DB Expert ✓ (87% match)
├─ API Expert
└─ Service Expert

Routing Strategies:

When to Use:

• Specialized task distribution
• Domain expert selection
• Load balancing across specialists
• Hierarchical agent organization

Example:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::grove::{
    GroveBuilder, Tree, TreeAgent, RoutingStrategy
};

let backend_tree = Tree::new("Backend Specialists")
    .add_agent(TreeAgent::new("DatabaseExpert")
        .with_keywords(vec!["database", "sql", "query", "schema"]))
    .add_agent(TreeAgent::new("ApiExpert")
        .with_keywords(vec!["api", "rest", "graphql", "endpoint"]));

let grove = GroveBuilder::new()
    .name("Tech Support Grove")
    .add_tree(backend_tree)
    .config(GroveConfig {
        routing_strategy: RoutingStrategy::KeywordMatch,
        similarity_threshold: 0.6,
        ..Default::default()
    })
    .build()?;

let result = grove_service.execute(&grove,
    "Optimize database query performance").await?;
}

Performance: Routing time varies by strategy (10ms-300ms) + agent execution time.

Learn More: See Grove Pattern Documentation for complete guide including semantic routing, LLM-powered routing, and expertise definition strategies.

8. Maneuver (Flow DSL Orchestration)

Purpose: Define complex agent workflows declaratively using a simple text-based DSL.

Architecture:

Flow DSL: "analyzer -> (summarizer, translator) -> reviewer"

Execution:
Input → analyzer → ┌─ summarizer ─┐
                   └─ translator ─┘ → reviewer → Output

Flow Operators:

• Sequential (->): Execute agents in order, passing output as next input
• Parallel (,): Execute agents concurrently with same input
• Nested (()): Group agents for precedence and mixed patterns

When to Use:

• Complex workflows requiring both sequential and parallel execution
• Dynamic workflow generation from configuration
• Rapid prototyping of multi-agent patterns
• Visual workflow documentation needs

Key Features:

• Declarative Syntax: Define entire workflow as text expression
• Mixed Patterns: Combine sequential and parallel in single flow
• Visual Feedback: ASCII tree and Mermaid flowchart generation
• Compile-Time Validation: Flow expression parsing with error reporting
• Commander Integration: Auto-detected via "flow" keywords or ->/, operators

Example:

#![allow(unused)]
fn main() {
use paladin::application::services::battalion::maneuver_service::ManeuverExecutionService;
use paladin::core::platform::container::battalion::maneuver::{Maneuver, ManeuverConfig};
use paladin::core::platform::container::battalion::parser::FlowParser;

// Parse flow expression
let flow = FlowParser::parse("intake -> (technical, business, security) -> synthesis")?;

// Create Paladins matching flow agent names
let mut agents = HashMap::new();
agents.insert("intake", create_paladin("intake", "Initial processing"));
agents.insert("technical", create_paladin("technical", "Technical analysis"));
agents.insert("business", create_paladin("business", "Business perspective"));
agents.insert("security", create_paladin("security", "Security review"));
agents.insert("synthesis", create_paladin("synthesis", "Combine perspectives"));

// Create Maneuver
let maneuver = Maneuver::new(
    "review-workflow",
    agents,
    flow,
    ManeuverConfig::default()
)?;

// Execute
let result = maneuver_service.execute(&maneuver, "Proposal document").await?;
}

CLI Visualization:

# Visualize flow structure
paladin maneuver visualize -c workflow.yaml --format ascii

# Output:
# └─> intake
#     ├─> [PARALLEL]
#     │   ├─> technical
#     │   ├─> business
#     │   └─> security
#     └─> synthesis

# Generate Mermaid flowchart
paladin maneuver visualize -c workflow.yaml --format mermaid

Performance: Parsing overhead <1ms, execution time depends on flow structure (sequential = O(n), parallel = O(1) per stage).

Learn More: See Maneuver Pattern Documentation for complete guide including Flow DSL syntax reference, configuration options, error handling, visualization formats, and troubleshooting.

Commander Strategy Router

Unified interface for intelligent Battalion orchestration

Overview

The Commander is a high-level abstraction that simplifies Battalion usage by:

1. Auto Mode: Automatically selecting the optimal strategy based on input analysis
2. Unified API: Single interface for all five Battalion patterns
3. Simplified Configuration: Smart defaults with optional customization
4. Enhanced Telemetry: Strategy selection reasoning and detailed timing metadata

Quick Start with Commander

use paladin::application::services::battalion::commander::CommanderBuilder;
use paladin::core::platform::container::battalion::BattalionStrategy;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Auto mode - Commander selects best strategy
    let commander = CommanderBuilder::new(paladin_port)
        .strategy(BattalionStrategy::Auto)
        .paladins(vec![paladin1, paladin2, paladin3])
        .build()?; // Uses smart defaults

    let result = commander.execute("Analyze this data in parallel").await?;

    // See what strategy was selected
    println!("Strategy: {:?}", result.strategy_used);
    if let Some(reasoning) = &result.strategy_selection_reasoning {
        println!("Because: {}", reasoning);
    }

    Ok(())
}

Auto Mode Strategy Selection

When using BattalionStrategy::Auto, the Commander analyzes:

1. Input Keywords

• Maneuver: "flow", "dynamic flow", "->", "," (DSL operators in input) [Highest Priority]
• Formation: "sequential", "pipeline", "step by step", "one after", "first then"
• Phalanx: "parallel", "concurrent", "all at once", "simultaneously"
• Campaign: "workflow", "graph", "conditional", "if-then", "depends on"
• ChainOfCommand: "delegate", "hierarchy", "specialist", "expert"

2. Paladin Count Heuristics

• 1-3 Paladins: Defaults to Formation (sequential)
• 4+ Paladins: Analyzes for parallelism or specialization
• Many similar Paladins: Prefers Phalanx (parallel)
• Mixed specialist Paladins: Considers ChainOfCommand

3. Fallback Logic

• If no clear indicators: Formation (safe default)
• Strategy selection takes 0-5ms typically
• Selection reasoning included in result metadata

Examples by Strategy

Explicit Formation

#![allow(unused)]
fn main() {
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Formation)
    .paladins(vec![analyzer, enhancer, reviewer])
    .config(BattalionConfig::new("review_pipeline").with_timeout(60))
    .build()?;

let result = commander.execute("Review this document").await?;
}

Auto Mode with Telemetry

#![allow(unused)]
fn main() {
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Auto)
    .paladins(workers)
    .build()?;

let result = commander.execute("Process these items in parallel").await?;

println!("Selected: {:?} in {}ms",
    result.strategy_used,
    result.strategy_selection_time_ms);
println!("Executed in {}ms",
    result.completed_at.signed_duration_since(result.started_at)
        .num_milliseconds());
}

Production Configuration

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::{ErrorStrategy, RetryPolicy};
use std::path::PathBuf;

let config = BattalionConfig::new("production_battalion")
    .with_description("Critical data processing pipeline")
    .with_timeout(300) // 5 minutes
    .with_error_strategy(ErrorStrategy::RetryThenContinue)
    .with_retry_policy(RetryPolicy {
        max_attempts: 3,
        ..Default::default()
    })
    .with_metadata_dir(PathBuf::from("./checkpoints"));

let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Formation)
    .paladins(critical_paladins)
    .config(config)
    .build()?;

match commander.execute("Critical task").await {
    Ok(result) => println!("Success: {} succeeded, {} failed",
        result.paladin_success_count,
        result.paladin_failure_count),
    Err(e) => eprintln!("Failed: {}", e),
}
}

Configuration Options

Required Fields

• strategy: BattalionStrategy (Formation, Phalanx, Campaign, ChainOfCommand, Auto)
• paladins: Vec (must contain at least 1 Paladin)

Optional Fields (with defaults)

• config: BattalionConfig (default: 300s timeout, FailFast, 3 retries)
  • name: Battalion identifier (default: "default_commander_battalion")
  • timeout_seconds: Max execution time (default: 300)
  • error_strategy: How to handle failures (default: FailFast)
  • retry_policy: Retry configuration (default: 3 attempts with backoff)
  • metadata_output_dir: Checkpoint directory (default: None)

Error Handling Strategies

FailFast (Default)

Stops execution immediately on first Paladin failure.

Use When:

• All Paladins must succeed for valid result
• Failures indicate fundamental issues
• Want fast failure feedback

#![allow(unused)]
fn main() {
.with_error_strategy(ErrorStrategy::FailFast)
}

ContinueOnError

Continues executing remaining Paladins despite failures, collects all errors.

Use When:

• Partial results are valuable
• Independent tasks where some failures acceptable
• Need complete execution report

#![allow(unused)]
fn main() {
.with_error_strategy(ErrorStrategy::ContinueOnError)
}

RetryThenContinue (Recommended for Production)

Retries failed Paladins up to max_attempts, then continues with remaining Paladins.

Use When:

• Transient failures are possible (network, rate limits)
• Want resilience without blocking entire workflow
• Production environments

#![allow(unused)]
fn main() {
.with_error_strategy(ErrorStrategy::RetryThenContinue)
.with_retry_policy(RetryPolicy {
    max_attempts: 3,
    ..Default::default()
})
}

Telemetry & Metadata

Commander results include comprehensive metadata:

#![allow(unused)]
fn main() {
pub struct BattalionResult {
    pub battalion_id: Uuid,
    pub battalion_name: String,
    pub started_at: DateTime<Utc>,
    pub completed_at: DateTime<Utc>,
    pub status: BattalionStatus,
    pub strategy_used: BattalionStrategy,         // Actual strategy executed
    pub strategy_selection_reasoning: Option<String>, // Auto mode explanation
    pub strategy_selection_time_ms: u64,          // Selection overhead
    pub final_output: String,
    pub paladin_success_count: usize,
    pub paladin_failure_count: usize,
    pub per_paladin_times: Vec<u64>,              // Individual timing
    // ... additional fields
}
}

Key Metrics:

• strategy_selection_time_ms: Overhead for Auto mode (typically 0-5ms)
• paladin_success_count / paladin_failure_count: Execution statistics
• per_paladin_times: Individual Paladin execution times for each Paladin by name
• per_paladin_tokens: Token usage breakdown (prompt_tokens, completion_tokens, total_tokens) per Paladin
• strategy_selection_reasoning: Transparency for Auto mode decisions

Metadata Export (JSON Files)

Commander can automatically export comprehensive execution metadata to JSON files for:

• Performance Analysis: Track execution times, token usage, and bottlenecks
• Audit Trails: Complete execution history for compliance and debugging
• Cost Tracking: Per-Paladin token consumption for billing and optimization
• Troubleshooting: Detailed error context and failure analysis

Enable Metadata Export:

#![allow(unused)]
fn main() {
use std::path::PathBuf;

let config = BattalionConfig::new("audited_battalion")
    .with_metadata_dir(PathBuf::from("./battalion_metadata"));

let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Auto)
    .paladins(paladins)
    .config(config)
    .build()?;

let result = commander.execute(input).await?;
// Metadata automatically written to: ./battalion_metadata/{strategy}_{timestamp}_{uuid}.json
}

Metadata File Naming Convention:

• Format: {strategy}_{timestamp}_{uuid}.json
• Example: Formation_20240315_143022_a1b2c3d4.json
• Components:
  • strategy: Battalion strategy used (Formation, Phalanx, Campaign, etc.)
  • timestamp: ISO 8601 format (YYYYMMDD_HHMMSS)
  • uuid: Unique identifier (first 8 characters of Battalion ID)

JSON Structure:

{
  "battalion_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "battalion_name": "audited_battalion",
  "strategy_used": "Formation",
  "started_at": "2024-03-15T14:30:22.123Z",
  "completed_at": "2024-03-15T14:31:15.456Z",
  "duration_ms": 53333,
  "status": "Completed",
  "paladin_success_count": 3,
  "paladin_failure_count": 0,
  "total_tokens": 1520,
  "paladin_results": [
    {
      "paladin_name": "Analyzer",
      "status": "Success",
      "output": "Analysis complete: ...",
      "execution_time_ms": 1500,
      "token_count": 450,
      "loop_count": 1
    }
  ],
  "per_paladin_times": {
    "Analyzer": 1500,
    "Enhancer": 1800,
    "Reviewer": 1200
  },
  "per_paladin_tokens": {
    "Analyzer": {
      "prompt_tokens": 150,
      "completion_tokens": 300,
      "total_tokens": 450
    }
  },
  "strategy_selection_reasoning": "Input contains 'sequential' keyword",
  "strategy_selection_time_ms": 2
}

Field Descriptions:

Use Cases:

#![allow(unused)]
fn main() {
// Production audit trail
let config = BattalionConfig::new("production_api_handler")
    .with_metadata_dir(PathBuf::from("/var/log/battalion"))
    .with_timeout(60);

// Cost optimization analysis
let config = BattalionConfig::new("cost_tracking")
    .with_metadata_dir(PathBuf::from("./cost_analysis"));

// Performance profiling
let config = BattalionConfig::new("profiling_run")
    .with_metadata_dir(PathBuf::from("./performance_data"));
}

Configuration via YAML:

battalion:
  metadata_output_dir: "./battalion_metadata"
  default_timeout: 300
  error_strategy: "RetryThenContinue"

Benefits:

• ✅ Zero Performance Impact: Async file I/O, non-blocking
• ✅ Complete Audit Trail: Every execution fully documented
• ✅ Cost Transparency: Per-Paladin token tracking for billing
• ✅ Debugging Aid: Capture execution state before failures
• ✅ Compliance Ready: Tamper-evident JSON with timestamps

Best Practices

Use Auto Mode for Flexibility

#![allow(unused)]
fn main() {
// Good: Let Commander optimize
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Auto)
    .paladins(paladins)
    .build()?;
}

Use Explicit Strategies for Predictability

#![allow(unused)]
fn main() {
// Good: Known pattern, explicit selection
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Formation)
    .paladins(pipeline_paladins)
    .build()?;
}

Configure Timeouts Appropriately

#![allow(unused)]
fn main() {
// Good: Realistic timeout with buffer
let config = BattalionConfig::new("batch_job")
    .with_timeout(600); // 10 minutes for batch processing
}

Use RetryThenContinue in Production

#![allow(unused)]
fn main() {
// Best for production
let config = BattalionConfig::new("production")
    .with_error_strategy(ErrorStrategy::RetryThenContinue)
    .with_retry_policy(RetryPolicy { max_attempts: 3, ..Default::default() });
}

Monitor Telemetry

#![allow(unused)]
fn main() {
let result = commander.execute(input).await?;
metrics.record_execution_time(
    result.completed_at.signed_duration_since(result.started_at).num_milliseconds()
);
metrics.record_success_rate(
    result.paladin_success_count,
    result.paladin_failure_count
);
}

Performance Characteristics

• Auto Mode Overhead: 0-5ms for strategy selection
• Timeout Enforcement: Tokio-based, minimal overhead
• Telemetry Collection: <1ms overhead
• Builder Validation: Compile-time + runtime validation
• Strategy Delegation: Zero-cost abstraction after selection

Configuration

BattalionConfig

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::{BattalionConfig, ErrorStrategy, RetryPolicy};

let config = BattalionConfig {
    name: "research_battalion".to_string(),
    description: Some("Research and analysis workflow".to_string()),
    timeout_seconds: 300, // 5 minute timeout
    error_strategy: ErrorStrategy::RetryThenContinue,
    retry_policy: RetryPolicy {
        max_attempts: 3,
        exponential_backoff: true,
        jitter: true,
        base_delay: Duration::from_millis(100),
        max_delay: Duration::from_secs(10),
    },
    metadata_output_dir: Some(PathBuf::from("./battalion_metadata")),
};
}

Configuration Options

Error Handling

Error Strategies

1. FailFast (Default)

• Stop execution on first Paladin failure
• Return error immediately
• Use when: Each step is critical, failures are unacceptable

#![allow(unused)]
fn main() {
let config = BattalionConfig {
    error_strategy: ErrorStrategy::FailFast,
    ..Default::default()
};
}

2. ContinueOnError

• Continue executing even if some Paladins fail
• Collect all errors, return at end
• Use when: Partial results are valuable

#![allow(unused)]
fn main() {
let config = BattalionConfig {
    error_strategy: ErrorStrategy::ContinueOnError,
    ..Default::default()
};
}

3. RetryThenContinue

• Retry failed Paladin up to max_attempts
• If still fails, continue to next
• Use when: Transient failures expected (network issues, API rate limits)

#![allow(unused)]
fn main() {
let config = BattalionConfig {
    error_strategy: ErrorStrategy::RetryThenContinue,
    retry_policy: RetryPolicy {
        max_attempts: 3,
        exponential_backoff: true,
        jitter: true,
        base_delay: Duration::from_millis(100),
        max_delay: Duration::from_secs(10),
    },
    ..Default::default()
};
}

Retry Policy

Exponential Backoff Formula:

delay = min(base_delay * 2^attempt, max_delay)

With Jitter (recommended to prevent thundering herd):

actual_delay = random(0.5 * delay, delay)

Example Retry Sequence:

Attempt 1: 100ms
Attempt 2: 200ms
Attempt 3: 400ms (with jitter: 200-400ms)

Performance

Benchmarks

Tested on: Intel i7, 32GB RAM, Rust 1.93

Performance Tips

1. Use Phalanx for Independent Tasks: 10x speedup vs Formation for parallelizable work
2. Limit Concurrency: Default semaphore allows 10 concurrent Paladins in Phalanx
3. Tune Timeouts: Set realistic timeouts based on LLM latency (typically 1-10s per call)
4. Batch Processing: Process multiple inputs with same Battalion configuration
5. Monitor Token Usage: Track PaladinResult.token_count to manage LLM costs

Scaling Limits

• Formation: Tested up to 100 Paladins sequentially
• Phalanx: Tested up to 50 concurrent Paladins
• Campaign: Tested graphs with 20 nodes, 30 edges
• Chain of Command: Tested 1 commander + 10 specialists

Best Practices

1. Choose the Right Pattern

┌─────────────────────────────────────────────────────────────┐
│ Decision Tree                                                │
├─────────────────────────────────────────────────────────────┤
│ Need sequential processing?                                 │
│   → Yes: Formation                                           │
│   → No: Continue...                                          │
│                                                              │
│ Tasks independent and parallelizable?                       │
│   → Yes: Phalanx                                             │
│   → No: Continue...                                          │
│                                                              │
│ Need conditional routing/branching?                         │
│   → Yes: Campaign                                            │
│   → No: Continue...                                          │
│                                                              │
│ Need intelligent task delegation?                           │
│   → Yes: Chain of Command                                    │
└─────────────────────────────────────────────────────────────┘

2. Design Paladin System Prompts

Formation: Make each Paladin aware it's in a pipeline

#![allow(unused)]
fn main() {
create_paladin("step2",
    "You are step 2 in a 3-step pipeline. \
     Input is from step 1 (data extractor). \
     Your output goes to step 3 (summarizer).")
}

Phalanx: Ensure consistent output format for aggregation

#![allow(unused)]
fn main() {
create_paladin("analyst1",
    "Provide your analysis in format: VERDICT: [approve|reject], REASON: [text]")
}

Campaign: Include routing hints in prompts

#![allow(unused)]
fn main() {
create_paladin("classifier",
    "Classify input as 'technical' or 'general'. \
     Output ONLY the classification word.")
}

Chain of Command: Train commander to output specialist names

#![allow(unused)]
fn main() {
create_paladin("commander",
    "Available specialists: database_expert, api_specialist, analytics_pro. \
     Output format: SELECT: [specialist_name(s)], REASON: [why]")
}

3. Error Handling Strategy

#![allow(unused)]
fn main() {
// Critical pipeline - fail fast
let critical_formation = Formation::new(paladins, BattalionConfig {
    error_strategy: ErrorStrategy::FailFast,
    ..Default::default()
})?;

// Research task - collect all perspectives
let research_phalanx = Phalanx::new(paladins, BattalionConfig {
    error_strategy: ErrorStrategy::ContinueOnError,
    ..Default::default()
})?;

// External API calls - retry transient failures
let api_campaign = Campaign::new(BattalionConfig {
    error_strategy: ErrorStrategy::RetryThenContinue,
    retry_policy: RetryPolicy {
        max_attempts: 3,
        exponential_backoff: true,
        jitter: true,
        base_delay: Duration::from_millis(500),
        max_delay: Duration::from_secs(5),
    },
    ..Default::default()
})?;
}

4. Testing

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;
    use paladin::paladin_ports::output::paladin_port::PaladinPort;

    // Create mock PaladinPort for testing
    struct MockPort;

    #[async_trait]
    impl PaladinPort for MockPort {
        async fn execute(&self, paladin: &Paladin, input: &str)
            -> Result<PaladinResult, PaladinError>
        {
            Ok(PaladinResult {
                output: format!("Mock: {}", input),
                token_count: 10,
                execution_time_ms: 5,
                loop_count: 1,
                stop_reason: StopReason::Completed,
            })
        }

        // ... implement other required methods
    }

    #[tokio::test]
    async fn test_formation_pipeline() {
        let mock_port = Arc::new(MockPort);
        let service = FormationExecutionService::new(mock_port);

        // Test your Battalion logic
    }
}
}

API Reference

Core Types

#![allow(unused)]
fn main() {
// Domain layer (src/core/platform/container/battalion/)
pub struct Formation { /* ... */ }
pub struct Phalanx { /* ... */ }
pub struct Campaign { /* ... */ }
pub struct ChainOfCommand { /* ... */ }

pub struct BattalionConfig { /* ... */ }
pub enum ErrorStrategy { FailFast, ContinueOnError, RetryThenContinue }
pub struct RetryPolicy { /* ... */ }
pub enum BattalionStatus { Idle, Running, Paused, Completed, Failed, Cancelled }
pub struct BattalionResult { /* ... */ }
pub enum BattalionError { /* ... */ }

// Application layer (src/application/services/battalion/)
pub struct FormationExecutionService { /* ... */ }
pub struct PhalanxExecutionService { /* ... */ }
pub struct CampaignExecutionService { /* ... */ }
pub struct ChainOfCommandExecutionService { /* ... */ }
}

Key Methods

Formation

#![allow(unused)]
fn main() {
impl Formation {
    pub fn new(paladins: Vec<Paladin>, config: BattalionConfig) -> Result<Self, BattalionError>;
    pub fn validate(&self) -> Result<(), BattalionError>;
}

impl FormationExecutionService {
    pub fn new(paladin_port: Arc<dyn PaladinPort>) -> Self;
    pub async fn execute(&self, formation: &Formation, input: &str) -> Result<BattalionResult, BattalionError>;
}
}

Phalanx

#![allow(unused)]
fn main() {
impl Phalanx {
    pub fn new(paladins: Vec<Paladin>, config: BattalionConfig) -> Result<Self, BattalionError>;
    pub fn with_aggregation(self, strategy: AggregationStrategy) -> Self;
}

impl PhalanxExecutionService {
    pub fn new(paladin_port: Arc<dyn PaladinPort>) -> Self;
    pub async fn execute(&self, phalanx: &Phalanx, input: &str) -> Result<BattalionResult, BattalionError>;
}
}

Campaign

#![allow(unused)]
fn main() {
impl Campaign {
    pub fn new(config: BattalionConfig) -> Result<Self, BattalionError>;
    pub fn add_paladin(&mut self, name: impl Into<String>, paladin: Paladin) -> Result<(), BattalionError>;
    pub fn add_edge(&mut self, from: impl Into<String>, to: impl Into<String>, condition: EdgeCondition, transform: Option<String>) -> Result<(), BattalionError>;
    pub fn set_entry_points(&mut self, entry_points: Vec<String>) -> Result<(), BattalionError>;
    pub fn validate(&self) -> Result<(), BattalionError>;
}
}

Chain of Command

#![allow(unused)]
fn main() {
impl ChainOfCommand {
    pub fn new(commander: Paladin, specialists: Vec<Paladin>, config: BattalionConfig) -> Result<Self, BattalionError>;
    pub fn with_strategy(self, strategy: DelegationStrategy) -> Self;
}
}

Examples

See the examples/ directory for complete runnable examples:

• examples/formation_sequential.rs - Multi-step analysis pipeline
• examples/phalanx_parallel.rs - Concurrent analysis with majority voting
• examples/campaign_workflow.rs - Complex conditional routing DAG
• examples/chain_of_command_delegation.rs - All 4 delegation strategies

Run examples:

cargo run --example formation_sequential
cargo run --example phalanx_parallel
cargo run --example campaign_workflow
cargo run --example chain_of_command_delegation

Troubleshooting

Common Issues

1. "Formation requires at least 2 Paladins"

• Solution: Add more Paladins to your Formation

2. "Cycle detected in Campaign graph"

• Solution: Use campaign.validate() to check for cycles before execution
• Campaigns must be DAGs (directed acyclic graphs)

3. "Phalanx majority requires ≥3 Paladins"

• Solution: Use AggregationStrategy::CollectAll or add more Paladins

4. "Timeout exceeded"

• Solution: Increase timeout_seconds in BattalionConfig or optimize Paladin prompts

5. "No entry points defined for Campaign"

• Solution: Call campaign.set_entry_points(vec!["start_node"])? before execution

Architecture Notes

Hexagonal Architecture Layers

┌──────────────────────────────────────────────┐
│ Infrastructure Layer (Adapters)              │
│ - LLM adapters (OpenAI, DeepSeek, Anthropic) │
│ - Garrison (memory) adapters                 │
│ - Arsenal (tool) adapters                    │
└─────────────────┬────────────────────────────┘
                  │
┌─────────────────┴────────────────────────────┐
│ Application Layer (Ports & Services)         │
│ - BattalionPort trait                        │
│ - *ExecutionService implementations          │
│ - Retry logic, error aggregation utilities   │
└─────────────────┬────────────────────────────┘
                  │
┌─────────────────┴────────────────────────────┐
│ Core Domain Layer (Pure Business Logic)     │
│ - Formation, Phalanx, Campaign, Chain types  │
│ - BattalionConfig, Error types               │
│ - No external dependencies                   │
└──────────────────────────────────────────────┘

Dependency Rule: Dependencies point inward only. Domain has zero external deps.

Contributing

When adding new Battalion patterns:

1. Domain Layer: Define entity in src/core/platform/container/battalion/
2. Application Layer: Create service in src/application/services/battalion/
3. Tests: Write unit tests (TDD), integration tests, examples
4. Documentation: Update this file, add rustdoc
5. Performance: Add load test, verify <1s overhead

License

Same as Paladin project license.

Support

• GitHub Issues: paladin/issues
• Documentation: docs/
• Examples: examples/

Version: 0.1.0
Last Updated: January 2026
Maintainers: Paladin Core Team

Commander Strategy Router

Unified interface for intelligent Battalion orchestration with automatic strategy selection

Table of Contents

• Overview
• Quick Start
• Strategy Selection
  • Auto Mode
  • Explicit Strategy Selection
• Metadata Export
  • Enabling Metadata Export
  • JSON Structure
  • Use Cases
• Configuration
  • BattalionConfig
  • Error Handling Strategies
  • Retry Policies
• Telemetry & Monitoring
• Best Practices
• Troubleshooting

Overview

The Commander is a high-level abstraction that simplifies Battalion usage by providing:

1. Auto Mode: Automatically selects the optimal orchestration strategy based on input analysis
2. Unified API: Single interface for all Battalion patterns (Formation, Phalanx, Campaign, ChainOfCommand, Maneuver)
3. Simplified Configuration: Smart defaults with comprehensive customization options
4. Enhanced Telemetry: Strategy selection reasoning, detailed timing, and metadata export

When to Use Commander

• Auto Mode: When strategy may vary per request (e.g., user-driven workflows)
• Explicit Mode: When strategy is known and fixed (e.g., production pipelines)
• Metadata Export: When audit trails, cost tracking, or performance analysis needed

Architecture

┌──────────────────────────────────────────────────────────────┐
│                      Commander                                 │
├──────────────────────────────────────────────────────────────┤
│  Strategy Selection Logic (Auto Mode)                        │
│    ↓                                                          │
│  ┌─────────┬─────────┬──────────┬───────────┬─────────┐    │
│  │Formation│ Phalanx │ Campaign │ChainOfCmd │ Maneuver│    │
│  └─────────┴─────────┴──────────┴───────────┴─────────┘    │
├──────────────────────────────────────────────────────────────┤
│  Telemetry & Metadata Collection                             │
│  - Execution times per Paladin                               │
│  - Token usage breakdown                                     │
│  - Strategy selection reasoning                              │
│  - Optional JSON export                                      │
└──────────────────────────────────────────────────────────────┘

Quick Start

Auto Mode (Recommended for Dynamic Workflows)

use paladin::application::services::battalion::commander::CommanderBuilder;
use paladin::core::platform::container::battalion::BattalionStrategy;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let paladin_port = Arc::new(/* your PaladinPort implementation */);

    let paladins = vec![
        create_paladin("Analyzer", "data analysis"),
        create_paladin("Processor", "data processing"),
        create_paladin("Synthesizer", "report generation"),
    ];

    // Commander automatically selects best strategy
    let commander = CommanderBuilder::new(paladin_port)
        .strategy(BattalionStrategy::Auto)
        .paladins(paladins)
        .build()?;

    let result = commander.execute("Analyze this data").await?;

    println!("Strategy Selected: {:?}", result.strategy_used);
    if let Some(reasoning) = &result.strategy_selection_reasoning {
        println!("Reasoning: {}", reasoning);
    }

    Ok(())
}

Explicit Strategy (Recommended for Production Pipelines)

#![allow(unused)]
fn main() {
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Formation)  // Explicit strategy
    .paladins(pipeline_paladins)
    .build()?;

let result = commander.execute(input).await?;
}

Strategy Selection

Auto Mode

Commander analyzes input and Paladin configuration to select the optimal strategy.

Selection Logic

Commander evaluates multiple factors:

1. Input Keyword Analysis:

   • Maneuver (highest priority): "flow", "dynamic flow", "->", "," (DSL operators)
   • Formation: "sequential", "pipeline", "step by step", "one after", "first then"
   • Phalanx: "parallel", "concurrent", "all at once", "simultaneously"
   • Campaign: "workflow", "graph", "conditional", "if-then", "depends on"
   • ChainOfCommand: "delegate", "hierarchy", "specialist", "expert"

2. Paladin Count Heuristics:

   • 1-3 Paladins: Formation (sequential) by default
   • 4+ Paladins: Analyzes for parallelism indicators
   • Many similar Paladins: Prefers Phalanx (parallel execution)
   • Mixed specialist Paladins: Considers ChainOfCommand (delegation)

3. Fallback Logic:

   • If no clear indicators: Formation (safest default)
   • Selection typically completes in 0-5ms
   • Reasoning explanation included in result metadata

Example: Auto Mode with Analysis

#![allow(unused)]
fn main() {
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Auto)
    .paladins(vec![
        create_paladin("Worker1", "analysis"),
        create_paladin("Worker2", "analysis"),
        create_paladin("Worker3", "analysis"),
    ])
    .build()?;

// Input suggests parallel execution
let result = commander.execute("Process all items in parallel").await?;

assert_eq!(result.strategy_used, BattalionStrategy::Phalanx);
assert!(result.strategy_selection_reasoning.is_some());
println!("Selected: {:?} because {}",
    result.strategy_used,
    result.strategy_selection_reasoning.unwrap()
);
}

Explicit Strategy Selection

When the orchestration pattern is known, use explicit strategy:

#![allow(unused)]
fn main() {
// Sequential processing pipeline
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Formation)
    .paladins(vec![analyzer, enhancer, reviewer])
    .build()?;

// Parallel batch processing
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Phalanx)
    .paladins(parallel_workers)
    .build()?;

// Conditional routing
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Campaign)
    .paladins(workflow_paladins)
    .build()?;
}

Metadata Export

Commander can export comprehensive execution metadata to JSON files for audit trails, performance analysis, and cost tracking.

Enabling Metadata Export

#![allow(unused)]
fn main() {
use std::path::PathBuf;
use paladin::core::platform::container::battalion::BattalionConfig;

let config = BattalionConfig::new("audited_battalion")
    .with_metadata_dir(PathBuf::from("./battalion_metadata"));

let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Auto)
    .paladins(paladins)
    .config(config)
    .build()?;

let result = commander.execute(input).await?;

// Metadata automatically written to:
// ./battalion_metadata/{strategy}_{timestamp}_{uuid}.json
}

File Naming Convention

Metadata files are named using a consistent pattern:

{strategy}_{timestamp}_{uuid}.json

Components:

• strategy: Battalion strategy executed (Formation, Phalanx, Campaign, etc.)
• timestamp: ISO 8601 format without separators (YYYYMMDD_HHMMSS)
• uuid: First 8 characters of the Battalion execution UUID

Examples:

Formation_20240315_143022_a1b2c3d4.json
Phalanx_20240315_150815_f5e6d7c8.json
Campaign_20240315_162341_9a8b7c6d.json

JSON Structure

The metadata JSON file contains comprehensive execution information:

{
  "battalion_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "battalion_name": "audited_battalion",
  "strategy_used": "Formation",
  "started_at": "2024-03-15T14:30:22.123456Z",
  "completed_at": "2024-03-15T14:31:15.789012Z",
  "duration_ms": 53666,
  "status": "Completed",
  "paladin_success_count": 3,
  "paladin_failure_count": 0,
  "total_tokens": 1520,
  "paladin_results": [
    {
      "paladin_name": "Analyzer",
      "status": "Success",
      "output": "Analysis complete: 15 insights identified",
      "execution_time_ms": 1500,
      "token_count": 450,
      "loop_count": 1,
      "stop_reason": "Completed"
    },
    {
      "paladin_name": "Enhancer",
      "status": "Success",
      "output": "Enhanced analysis with 8 recommendations",
      "execution_time_ms": 1800,
      "token_count": 620,
      "loop_count": 1,
      "stop_reason": "Completed"
    },
    {
      "paladin_name": "Reviewer",
      "status": "Success",
      "output": "Final review: High quality, approved",
      "execution_time_ms": 1200,
      "token_count": 450,
      "loop_count": 1,
      "stop_reason": "Completed"
    }
  ],
  "per_paladin_times": {
    "Analyzer": 1500,
    "Enhancer": 1800,
    "Reviewer": 1200
  },
  "per_paladin_tokens": {
    "Analyzer": {
      "prompt_tokens": 150,
      "completion_tokens": 300,
      "total_tokens": 450
    },
    "Enhancer": {
      "prompt_tokens": 220,
      "completion_tokens": 400,
      "total_tokens": 620
    },
    "Reviewer": {
      "prompt_tokens": 150,
      "completion_tokens": 300,
      "total_tokens": 450
    }
  },
  "strategy_selection_reasoning": "Input contains 'sequential' keyword",
  "strategy_selection_time_ms": 2,
  "final_output": "Complete analysis with recommendations and review",
  "errors": []
}

Field Reference

Use Cases

1. Performance Analysis

#![allow(unused)]
fn main() {
let config = BattalionConfig::new("performance_profiling")
    .with_metadata_dir(PathBuf::from("./profiling_data"));

let result = commander.execute(input).await?;

// Analyze metadata to identify bottlenecks
// Find slow Paladins: Check per_paladin_times
// Optimize token usage: Review per_paladin_tokens
}

2. Cost Tracking

#![allow(unused)]
fn main() {
let config = BattalionConfig::new("cost_tracking")
    .with_metadata_dir(PathBuf::from("./billing_data"));

// Parse metadata files to calculate costs
// Cost = total_tokens * model_cost_per_token
// Per-Paladin cost breakdown available
}

3. Audit Trails & Compliance

#![allow(unused)]
fn main() {
let config = BattalionConfig::new("production_api_handler")
    .with_metadata_dir(PathBuf::from("/var/log/battalion"));

// Every execution fully documented
// Tamper-evident JSON with timestamps
// Track who executed what and when
}

4. Debugging & Troubleshooting

#![allow(unused)]
fn main() {
let config = BattalionConfig::new("debug_session")
    .with_metadata_dir(PathBuf::from("./debug_logs"));

// Capture execution state before failures
// Per-Paladin outputs for inspection
// Strategy selection reasoning for unexpected results
}

Configuration via YAML

# config.yml
battalion:
  metadata_output_dir: "./battalion_metadata"
  default_timeout: 300
  error_strategy: "RetryThenContinue"

#![allow(unused)]
fn main() {
use config::Config;

let settings = Config::builder()
    .add_source(config::File::with_name("config.yml"))
    .build()?;

let metadata_dir = settings.get_string("battalion.metadata_output_dir")?;
let config = BattalionConfig::new("from_config")
    .with_metadata_dir(PathBuf::from(metadata_dir));
}

Performance Impact

• File I/O: Asynchronous, non-blocking
• Overhead: <1ms for typical payloads
• Disk Usage: ~1-5KB per execution (depends on Paladin count and output size)
• Production Ready: Zero performance impact on critical path

Configuration

BattalionConfig

Comprehensive configuration for Commander behavior:

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::{
    BattalionConfig, ErrorStrategy, RetryPolicy
};
use std::path::PathBuf;

let config = BattalionConfig::new("my_battalion")
    .with_description("Processes critical data pipeline")
    .with_timeout(300)  // 5 minutes
    .with_error_strategy(ErrorStrategy::RetryThenContinue)
    .with_retry_policy(RetryPolicy {
        max_attempts: 3,
        initial_delay_ms: 1000,
        max_delay_ms: 30000,
        backoff_multiplier: 2.0,
    })
    .with_metadata_dir(PathBuf::from("./checkpoints"));
}

Configuration Fields

Error Handling Strategies

FailFast (Default)

Stops execution immediately on first Paladin failure.

#![allow(unused)]
fn main() {
let config = BattalionConfig::new("fail_fast")
    .with_error_strategy(ErrorStrategy::FailFast);
}

When to Use:

• All Paladins must succeed for valid result
• Failures indicate fundamental issues (bad input, configuration errors)
• Want fast failure feedback for debugging

ContinueOnError

Continues executing remaining Paladins despite failures.

#![allow(unused)]
fn main() {
let config = BattalionConfig::new("continue_on_error")
    .with_error_strategy(ErrorStrategy::ContinueOnError);
}

When to Use:

• Partial results are valuable (e.g., batch processing)
• Independent tasks where some failures acceptable
• Need complete execution report for analysis

RetryThenContinue (Recommended for Production)

Retries failed Paladins up to max_attempts, then continues with remaining Paladins.

#![allow(unused)]
fn main() {
let config = BattalionConfig::new("production")
    .with_error_strategy(ErrorStrategy::RetryThenContinue)
    .with_retry_policy(RetryPolicy {
        max_attempts: 3,
        initial_delay_ms: 1000,
        max_delay_ms: 30000,
        backoff_multiplier: 2.0,
    });
}

When to Use:

• Transient failures possible (network issues, rate limits, temporary unavailability)
• Production environments requiring resilience
• Want to maximize success rate without blocking entire workflow

Retry Policies

#![allow(unused)]
fn main() {
pub struct RetryPolicy {
    pub max_attempts: u32,        // Total attempts (including initial)
    pub initial_delay_ms: u64,    // First retry delay
    pub max_delay_ms: u64,        // Cap on delay
    pub backoff_multiplier: f64,  // Exponential backoff factor
}
}

Default Retry Policy:

#![allow(unused)]
fn main() {
RetryPolicy {
    max_attempts: 3,          // 3 total attempts
    initial_delay_ms: 1000,   // 1 second first retry
    max_delay_ms: 30000,      // 30 second cap
    backoff_multiplier: 2.0,  // Double delay each retry
}
}

Retry Timing Example:

• Attempt 1: Immediate
• Attempt 2: After 1 second
• Attempt 3: After 2 seconds
• If max_attempts = 4, Attempt 4: After 4 seconds

Telemetry & Monitoring

BattalionResult Telemetry

#![allow(unused)]
fn main() {
pub struct BattalionResult {
    pub battalion_id: Uuid,
    pub battalion_name: String,
    pub started_at: DateTime<Utc>,
    pub completed_at: DateTime<Utc>,
    pub status: BattalionStatus,
    pub strategy_used: BattalionStrategy,
    pub strategy_selection_reasoning: Option<String>,
    pub strategy_selection_time_ms: u64,
    pub final_output: String,
    pub paladin_success_count: usize,
    pub paladin_failure_count: usize,
    pub total_tokens: usize,
    pub per_paladin_times: HashMap<String, u64>,
    pub per_paladin_tokens: HashMap<String, TokenUsage>,
    // ... additional fields
}
}

Monitoring Examples

Execution Duration

#![allow(unused)]
fn main() {
let result = commander.execute(input).await?;

let duration = result.completed_at
    .signed_duration_since(result.started_at)
    .num_milliseconds();

println!("Execution time: {}ms", duration);
}

Success Rate

#![allow(unused)]
fn main() {
let success_rate = result.paladin_success_count as f64
    / (result.paladin_success_count + result.paladin_failure_count) as f64
    * 100.0;

println!("Success rate: {:.1}%", success_rate);
}

Per-Paladin Metrics

#![allow(unused)]
fn main() {
for (name, time_ms) in &result.per_paladin_times {
    let tokens = result.per_paladin_tokens
        .get(name)
        .map(|t| t.total_tokens)
        .unwrap_or(0);

    println!("{}: {}ms, {} tokens", name, time_ms, tokens);
}
}

Integration with Metrics Systems

#![allow(unused)]
fn main() {
// Prometheus-style metrics
metrics.record_battalion_duration(
    result.battalion_name.as_str(),
    duration as f64
);

metrics.record_strategy_selection(
    result.strategy_used,
    result.strategy_selection_time_ms
);

metrics.record_paladin_counts(
    result.paladin_success_count,
    result.paladin_failure_count
);
}

Best Practices

1. Use Auto Mode for User-Driven Workflows

#![allow(unused)]
fn main() {
// Good: Flexibility for unpredictable inputs
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Auto)
    .paladins(general_purpose_paladins)
    .build()?;
}

2. Use Explicit Strategies for Production Pipelines

#![allow(unused)]
fn main() {
// Good: Predictability and performance
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Formation)  // Known pattern
    .paladins(pipeline_paladins)
    .build()?;
}

3. Configure Appropriate Timeouts

#![allow(unused)]
fn main() {
// Good: Realistic timeout with buffer
let config = BattalionConfig::new("batch_processing")
    .with_timeout(600);  // 10 minutes for batch job
}

Consider:

• LLM response times (typically 1-30 seconds per request)
• Number of Paladins and strategy (sequential vs. parallel)
• Network latency and retries
• Add 20-30% buffer for safety

4. Use RetryThenContinue in Production

#![allow(unused)]
fn main() {
// Best practice for production
let config = BattalionConfig::new("production")
    .with_error_strategy(ErrorStrategy::RetryThenContinue)
    .with_retry_policy(RetryPolicy {
        max_attempts: 3,
        initial_delay_ms: 1000,
        max_delay_ms: 30000,
        backoff_multiplier: 2.0,
    });
}

5. Enable Metadata Export for Critical Systems

#![allow(unused)]
fn main() {
// Good: Audit trail for compliance
let config = BattalionConfig::new("critical_system")
    .with_metadata_dir(PathBuf::from("/var/log/battalion"));
}

6. Monitor Telemetry Regularly

#![allow(unused)]
fn main() {
let result = commander.execute(input).await?;

// Log key metrics
log::info!(
    "Battalion {} completed in {}ms ({} success, {} failed)",
    result.battalion_name,
    result.completed_at.signed_duration_since(result.started_at).num_milliseconds(),
    result.paladin_success_count,
    result.paladin_failure_count
);
}

7. Handle Errors Gracefully

#![allow(unused)]
fn main() {
match commander.execute(input).await {
    Ok(result) => {
        if result.paladin_failure_count > 0 {
            log::warn!(
                "Completed with {} failures",
                result.paladin_failure_count
            );
        }
        process_result(result);
    }
    Err(e) => {
        log::error!("Battalion execution failed: {}", e);
        handle_failure(e);
    }
}
}

Troubleshooting

Issue: Strategy Selection Takes Too Long

Symptoms: High strategy_selection_time_ms (>10ms)

Solutions:

1. Use explicit strategy instead of Auto mode
2. Simplify input (avoid very long strings in keyword analysis)
3. Consider caching strategy decisions for similar inputs

#![allow(unused)]
fn main() {
// If Auto mode adds too much overhead:
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Formation)  // Explicit, 0ms overhead
    .paladins(paladins)
    .build()?;
}

Issue: Metadata Files Not Created

Possible Causes:

1. Directory doesn't exist or lacks write permissions
2. metadata_output_dir not set in configuration
3. Execution failed before metadata write

Solutions:

#![allow(unused)]
fn main() {
use std::fs;

// Ensure directory exists with correct permissions
let metadata_dir = PathBuf::from("./battalion_metadata");
fs::create_dir_all(&metadata_dir)?;

let config = BattalionConfig::new("battalion")
    .with_metadata_dir(metadata_dir);

// Verify after execution
let result = commander.execute(input).await?;
println!("Battalion ID: {}", result.battalion_id);
// Look for: {strategy}_{timestamp}_{first_8_chars_of_uuid}.json
}

Issue: Unexpected Strategy Selected

Symptoms: Auto mode selects different strategy than expected

Diagnosis:

#![allow(unused)]
fn main() {
let result = commander.execute(input).await?;

println!("Expected: X, Got: {:?}", result.strategy_used);
if let Some(reasoning) = &result.strategy_selection_reasoning {
    println!("Reasoning: {}", reasoning);
}
}

Solutions:

1. Review input for keyword conflicts
2. Use explicit strategy if behavior must be deterministic
3. Check Paladin count (affects heuristics)

Issue: High Token Usage

Symptoms: total_tokens higher than expected

Diagnosis:

#![allow(unused)]
fn main() {
let result = commander.execute(input).await?;

println!("Total tokens: {}", result.total_tokens);
for (name, tokens) in &result.per_paladin_tokens {
    println!("  {}: {} tokens", name, tokens.total_tokens);
}

// Check for surprisingly high token usage
let max_tokens = result.per_paladin_tokens.values()
    .map(|t| t.total_tokens)
    .max()
    .unwrap_or(0);

if max_tokens > expected_threshold {
    println!("WARNING: High token usage detected");
}
}

Solutions:

1. Optimize Paladin system prompts (reduce verbosity)
2. Trim input context before passing to Paladins
3. Use smaller models for simple tasks
4. Consider token limits in Paladin configuration

Issue: Timeouts

Symptoms: BattalionStatus::Timeout in result

Diagnosis:

#![allow(unused)]
fn main() {
let result = commander.execute(input).await;

if let Ok(r) = result {
    if r.status == BattalionStatus::Timeout {
        println!("Timeout after {}s", config.timeout_seconds);

        // Check which Paladins completed
        println!("Completed: {}", r.paladin_success_count);
        println!("Failed: {}", r.paladin_failure_count);
    }
}
}

Solutions:

1. Increase timeout appropriately
2. Check per-Paladin execution times for bottlenecks
3. Consider using Phalanx (parallel) instead of Formation (sequential)
4. Optimize slow Paladins

#![allow(unused)]
fn main() {
// Increase timeout
let config = BattalionConfig::new("battalion")
    .with_timeout(600);  // 10 minutes instead of 5

// Or switch to parallel execution
let commander = CommanderBuilder::new(paladin_port)
    .strategy(BattalionStrategy::Phalanx)  // Parallel = faster
    .paladins(paladins)
    .build()?;
}

Issue: Partial Failures

Symptoms: paladin_failure_count > 0 but execution completes

This is expected behavior with:

• ErrorStrategy::ContinueOnError
• ErrorStrategy::RetryThenContinue (after retries exhausted)

Handling:

#![allow(unused)]
fn main() {
let result = commander.execute(input).await?;

if result.paladin_failure_count > 0 {
    log::warn!(
        "Partial success: {} of {} Paladins failed",
        result.paladin_failure_count,
        result.paladin_success_count + result.paladin_failure_count
    );

    // Check metadata for detailed error information
    if let Some(metadata_dir) = config.metadata_output_dir {
        println!("See metadata in: {}", metadata_dir.display());
    }
}
}

See Also

• Battalion Documentation - Detailed orchestration pattern documentation
• Paladin - Individual agent configuration
• Configuration Guide - System-wide configuration
• Examples - Runnable code examples

Version: 0.1.0
Last Updated: 2024-03-15

Arsenal Tool System

Overview

The Arsenal Tool System enables Paladins (AI agents) to interact with external tools and services through the Model Context Protocol (MCP). This hexagonal architecture implementation provides a clean separation between tool definitions, execution logic, and transport mechanisms.

Key Concepts

• Armament: A single tool or capability (e.g., calculator, file reader, web search)
• Arsenal: The collection of available tools and the infrastructure to execute them
• MCP (Model Context Protocol): JSON-RPC 2.0 based protocol for tool communication
• Transport: The mechanism for tool invocation (STDIO or SSE)

Architecture Layers

┌─────────────────────────────────────────────────────────┐
│                    Paladin (Agent)                       │
│  - Receives tool calls from LLM                         │
│  - Invokes arsenal                                      │
│  - Injects results back into conversation               │
└─────────────────┬───────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│           Application Layer (Ports)                      │
│  - ArsenalPort: Tool execution interface                │
│  - ArsenalRegistry: Tool registration interface         │
│  - ArsenalExecutionService: Orchestration logic         │
└─────────────────┬───────────────────────────────────────┘
                  │
┌─────────────────▼───────────────────────────────────────┐
│        Infrastructure Layer (Adapters)                   │
│  - MCPStdioAdapter: Command-line tool execution         │
│  - MCPSseAdapter: HTTP/SSE tool execution               │
│  - TimeoutWrapper: Execution time limits                │
│  - ConcurrencyLimiter: Parallel execution control       │
└──────────────────────────────────────────────────────────┘

Quick Start

Basic Usage

use paladin::application::services::paladin::PaladinBuilder;
use paladin::paladin_ports::output::llm_port::LlmPort;
use paladin::infrastructure::adapters::llm::MockLlmAdapter;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create LLM adapter
    let llm_port: Arc<dyn LlmPort> = Arc::new(
        MockLlmAdapter::new()
            .with_responses(vec![
                "I'll help you calculate that.".to_string(),
            ])
    );

    // Build Paladin with tool support
    let paladin = PaladinBuilder::new(llm_port)
        .system_prompt("You are a helpful assistant with calculator capabilities.")
        .name("Calculator Agent")
        .build()?;

    // Execute with tool support
    let result = paladin.execute("What is 12 * 8?").await?;
    println!("Result: {}", result);

    Ok(())
}

With STDIO MCP Server

use paladin::application::services::arsenal::ArsenalRegistryService;
use paladin::paladin_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 arsenal registry
    let registry = Arc::new(ArsenalRegistryService::new());

    // Register STDIO tool (conceptual - requires actual MCP server)
    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;

    Ok(())
}

With SSE MCP Server

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

    // Register SSE-based remote tool
    let web_search = Armament {
        name: "web_search".to_string(),
        description: "Search the web for information".to_string(),
        parameters: serde_json::json!({
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "max_results": {"type": "integer", "default": 10}
            },
            "required": ["query"]
        }),
        required_params: vec!["query".to_string()],
    };

    registry.register(web_search).await;

    Ok(())
}

Model Context Protocol (MCP)

Protocol Overview

The Arsenal Tool System implements the Model Context Protocol specification, a standardized way for AI agents to interact with external tools and data sources.

Key Features:

• JSON-RPC 2.0 message format
• Structured tool discovery via tools/list
• Tool invocation via tools/call
• Support for both STDIO and SSE transports
• Server capability negotiation

Message Format

Tool Discovery Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Tool Discovery Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "calculator",
        "description": "Performs basic arithmetic operations",
        "inputSchema": {
          "type": "object",
          "properties": {
            "operation": {"type": "string", "enum": ["add", "subtract", "multiply", "divide"]},
            "a": {"type": "number"},
            "b": {"type": "number"}
          },
          "required": ["operation", "a", "b"]
        }
      }
    ]
  }
}

Tool Invocation Request

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calculator",
    "arguments": {
      "operation": "multiply",
      "a": 12,
      "b": 8
    }
  }
}

Tool Invocation Response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "96"
      }
    ]
  }
}

Transport Mechanisms

STDIO Transport

Use Case: Local command-line tools, scripts, binaries

Characteristics:

• Spawns subprocess using tokio::process::Command
• Communicates via stdin/stdout
• Ideal for local development and testing
• Lower latency than network-based transports

Configuration Example:

arsenal:
  default_timeout_seconds: 30
  max_concurrent_tools: 5
  mcp_servers:
    - name: "calculator"
      type: "stdio"
      command: "python"
      args: ["-m", "calculator_mcp_server"]

Rust Implementation:

#![allow(unused)]
fn main() {
use paladin::infrastructure::adapters::arsenal::MCPStdioAdapter;

let adapter = MCPStdioAdapter::new(
    "python".to_string(),
    vec!["-m".to_string(), "calculator_mcp_server".to_string()]
);
}

SSE (Server-Sent Events) Transport

Use Case: Remote web services, cloud-hosted tools, scalable deployments

Characteristics:

• HTTP-based communication with SSE streaming
• Supports automatic reconnection
• Works with load balancers and proxies
• Cloud-native architecture

Configuration Example:

arsenal:
  mcp_servers:
    - name: "web_search"
      type: "sse"
      endpoint: "https://mcp.example.com/search"

Rust Implementation:

#![allow(unused)]
fn main() {
use paladin::infrastructure::adapters::arsenal::MCPSseAdapter;

let adapter = MCPSseAdapter::new("https://mcp.example.com/search".to_string());
}

Configuration

Application Settings

The Arsenal system is configured via config.yml (or config.test.yml for testing):

arsenal:
  # Global timeout for all tool invocations (seconds)
  default_timeout_seconds: 30

  # Maximum number of concurrent tool executions
  max_concurrent_tools: 5

  # MCP server configurations
  mcp_servers:
    # STDIO-based local tool
    - name: "calculator"
      type: "stdio"
      command: "uvx"
      args: ["mcp-calculator"]

    # Another STDIO tool with Python
    - name: "file_reader"
      type: "stdio"
      command: "python"
      args: ["-m", "mcp_file_reader"]

    # SSE-based remote tool
    - name: "web_search"
      type: "sse"
      endpoint: "https://api.example.com/mcp/search"

    # Another SSE tool
    - name: "weather_api"
      type: "sse"
      endpoint: "https://api.weather.com/mcp"

Environment Variables

Some MCP servers may require authentication:

# For OpenAI function calling
export OPENAI_API_KEY="sk-..."

# For custom MCP servers
export MCP_AUTH_TOKEN="..."

# For debugging MCP communication
export RUST_LOG="paladin::infrastructure::adapters::arsenal=debug"

Tool Development

Creating MCP-Compatible Tools

To create a tool that works with the Arsenal system, implement an MCP server that responds to tools/list and tools/call methods.

Python Example (STDIO)

#!/usr/bin/env python3
import json
import sys

def handle_request(request):
    method = request.get("method")

    if method == "tools/list":
        return {
            "jsonrpc": "2.0",
            "id": request["id"],
            "result": {
                "tools": [
                    {
                        "name": "calculator",
                        "description": "Basic arithmetic operations",
                        "inputSchema": {
                            "type": "object",
                            "properties": {
                                "operation": {"type": "string"},
                                "a": {"type": "number"},
                                "b": {"type": "number"}
                            },
                            "required": ["operation", "a", "b"]
                        }
                    }
                ]
            }
        }

    elif method == "tools/call":
        args = request["params"]["arguments"]
        op = args["operation"]
        a, b = args["a"], args["b"]

        if op == "add":
            result = a + b
        elif op == "multiply":
            result = a * b
        # ... other operations

        return {
            "jsonrpc": "2.0",
            "id": request["id"],
            "result": {
                "content": [{"type": "text", "text": str(result)}]
            }
        }

if __name__ == "__main__":
    for line in sys.stdin:
        request = json.loads(line)
        response = handle_request(request)
        print(json.dumps(response), flush=True)

Node.js Example (SSE)

const express = require('express');
const app = express();

app.use(express.json());

// Tool list endpoint
app.post('/mcp', (req, res) => {
  const { method, id } = req.body;

  if (method === 'tools/list') {
    res.json({
      jsonrpc: '2.0',
      id,
      result: {
        tools: [
          {
            name: 'web_search',
            description: 'Search the web',
            inputSchema: {
              type: 'object',
              properties: {
                query: { type: 'string' }
              },
              required: ['query']
            }
          }
        ]
      }
    });
  } else if (method === 'tools/call') {
    // Perform search and return results
    const { query } = req.body.params.arguments;
    res.json({
      jsonrpc: '2.0',
      id,
      result: {
        content: [{ type: 'text', text: `Results for: ${query}` }]
      }
    });
  }
});

app.listen(3000);

Best Practices

1. Schema Validation: Always provide complete JSON Schema for tool parameters
2. Error Handling: Return proper JSON-RPC error responses (codes -32xxx)
3. Timeouts: Implement internal timeouts shorter than Arsenal's global timeout
4. Idempotency: Tools should be idempotent when possible
5. Documentation: Provide clear descriptions for tool purpose and parameters

Resource Controls

Timeout Management

The Arsenal system enforces execution timeouts to prevent hung tool calls:

#![allow(unused)]
fn main() {
use std::time::Duration;
use paladin::infrastructure::adapters::arsenal::TimeoutWrapper;

let timeout = TimeoutWrapper::new(Duration::from_secs(30));
let result = timeout.execute(async {
    // Tool execution code
}).await?;
}

Behavior:

• Default timeout: 30 seconds (configurable via config.yml)
• Timeout errors return ArsenalError::Timeout
• Execution time is tracked and included in results

Concurrency Limiting

To prevent resource exhaustion, concurrent tool executions are limited:

#![allow(unused)]
fn main() {
use paladin::infrastructure::adapters::arsenal::ConcurrencyLimiter;

let limiter = ConcurrencyLimiter::new(5); // Max 5 concurrent executions
let permit = limiter.acquire().await?;

// Execute tool with permit held
let result = execute_tool().await?;

drop(permit); // Release permit
}

Behavior:

• Default limit: 5 concurrent tools (configurable)
• Requests queue when limit reached
• Fair FIFO ordering for permits

Error Handling

Error Types

#![allow(unused)]
fn main() {
pub enum ArsenalError {
    /// Tool not found in registry
    ToolNotFound(String),

    /// Invalid arguments provided to tool
    InvalidArguments(String),

    /// Tool execution exceeded timeout
    Timeout { tool_name: String, timeout_secs: u64 },

    /// MCP protocol error (invalid JSON-RPC)
    ProtocolError(String),

    /// Transport-level error (network, process spawn)
    TransportError(String),
}
}

Error Propagation

Errors are handled gracefully and injected back into the Paladin's context:

Tool Call → Arsenal Invocation → Error → Formatted Message → LLM Context

Example formatted error message:

Tool Execution Failed
Tool: calculator
Arguments: {"operation": "divide", "a": 10, "b": 0}
Error: Division by zero
Execution Time: 5ms

Please try again with valid arguments.

Integration with Paladins

Automatic Tool Detection

Paladins automatically detect tool calls in LLM responses using function calling format:

{
  "function_call": {
    "name": "calculator",
    "arguments": "{\"operation\": \"multiply\", \"a\": 12, \"b\": 8}"
  }
}

Execution Flow

1. LLM generates response with tool call
2. Paladin detects function_call field
3. Arsenal validates tool exists
4. Tool arguments validated against schema
5. Tool executed via appropriate transport
6. Result formatted and injected into context
7. LLM continues with tool results

Context Injection Format

Successful tool executions are formatted as:

Tool Execution Result
Tool: calculator
Arguments: {"operation": "multiply", "a": 12, "b": 8}
Output: 96
Execution Time: 12ms

Testing

Unit Tests

Test domain types and logic:

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_armament_creation() {
        let armament = Armament {
            name: "test_tool".to_string(),
            description: "A test tool".to_string(),
            parameters: serde_json::json!({}),
            required_params: vec![],
        };

        assert_eq!(armament.name, "test_tool");
    }
}
}

Integration Tests

Test MCP adapters with mock servers:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn test_stdio_adapter_discovery() {
    let adapter = MCPStdioAdapter::new(
        "python".to_string(),
        vec!["-m".to_string(), "test_mcp_server".to_string()]
    );

    let tools = adapter.discover_tools().await?;
    assert!(!tools.is_empty());
}
}

Functional Tests

End-to-end tests with Paladin integration:

#![allow(unused)]
fn main() {
#[tokio::test]
async fn test_paladin_tool_execution() {
    let paladin = PaladinBuilder::new(mock_llm())
        .system_prompt("Use calculator tool")
        .build()?;

    let result = paladin.execute("What is 5 + 3?").await?;
    assert!(result.contains("8"));
}
}

Troubleshooting

Common Issues

Tool Not Found

Symptom: ArsenalError::ToolNotFound

Solutions:

1. Verify tool is registered in Arsenal registry
2. Check tool name matches exactly (case-sensitive)
3. Ensure MCP server is running and responsive
4. Check logs for discovery errors

Timeout Errors

Symptom: ArsenalError::Timeout

Solutions:

1. Increase default_timeout_seconds in config
2. Optimize tool implementation for faster execution
3. Check for network latency (SSE transport)
4. Verify tool isn't hanging indefinitely

Invalid Arguments

Symptom: ArsenalError::InvalidArguments

Solutions:

1. Check JSON Schema matches tool expectations
2. Ensure LLM is providing all required parameters
3. Validate parameter types (string, number, boolean)
4. Review tool's parameter documentation

Protocol Errors

Symptom: ArsenalError::ProtocolError

Solutions:

1. Verify MCP server implements JSON-RPC 2.0 correctly
2. Check for malformed JSON in responses
3. Ensure proper jsonrpc, id, method fields
4. Test MCP server independently with curl/httpie

Transport Errors

Symptom: ArsenalError::TransportError

Solutions:

1. STDIO: Check command path and permissions
2. STDIO: Verify all arguments are correct
3. SSE: Test endpoint URL accessibility
4. SSE: Check network connectivity and firewalls
5. Review error logs for specific failure details

Debugging

Enable debug logging:

export RUST_LOG="paladin::infrastructure::adapters::arsenal=debug"
cargo run

Inspect MCP communication:

#![allow(unused)]
fn main() {
// Add to adapter implementations
tracing::debug!("MCP Request: {:?}", request);
tracing::debug!("MCP Response: {:?}", response);
}

Test MCP server independently:

# STDIO server
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python -m my_mcp_server

# SSE server
curl -X POST https://mcp.example.com/tools \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Examples

See the examples/ directory for complete working examples:

• examples/arsenal_stdio_tools.rs - STDIO MCP server usage
• examples/arsenal_sse_tools.rs - SSE MCP server usage

Run examples:

cargo run --example arsenal_stdio_tools
cargo run --example arsenal_sse_tools

API Documentation

Generate and browse complete API documentation:

cargo doc --no-deps --open

Key modules:

• paladin::core::platform::container::arsenal - Domain types
• paladin::paladin_ports::output::arsenal_port - Port traits
• paladin::application::services::arsenal - Use case services
• paladin::infrastructure::adapters::arsenal - MCP adapters

Contributing

When contributing Arsenal-related changes:

1. Follow TDD: Write tests first
2. Maintain hexagonal architecture boundaries
3. Document all public APIs with rustdoc
4. Run full test suite: cargo test
5. Pass clippy: cargo clippy -- -D warnings
6. Format code: cargo fmt

License

See LICENSE for details.

See Also

• Model Context Protocol Specification
• Paladin Design Documentation
• Hexagonal Architecture Guide
• Garrison Memory System

Garrison Memory System

The Garrison is Paladin's memory and context management system, enabling AI agents to maintain conversation history, search previous interactions, and persist knowledge across sessions.

Table of Contents

• Overview
• Architecture
• Configuration
• Usage Patterns
• Implementations
• Troubleshooting
• Performance Considerations

Overview

What is a Garrison?

In medieval times, a garrison was a fortified location where troops stored supplies and maintained strategic resources. Similarly, Paladin's Garrison system stores and manages conversation context—the essential "supplies" an AI agent needs to maintain coherent, contextual interactions.

Key Features

• Conversation History: Store and retrieve user-assistant interactions
• Automatic Windowing: Manage context size with configurable eviction strategies
• Full-Text Search: Find relevant conversations using keyword or phrase queries
• Persistence: Optional SQLite storage for durability across restarts
• Multi-Paladin Isolation: Multiple agents can share a database with isolated data
• Extensible: Pluggable architecture supports custom storage backends

Architecture

The Garrison system follows Hexagonal Architecture (Ports & Adapters):

┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │           GarrisonPort (Interface)                    │  │
│  │  - remember(entry)                                    │  │
│  │  - recall_recent(limit)                               │  │
│  │  - search(query, limit)                               │  │
│  │  - forget_all()                                       │  │
│  │  - stats()                                            │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┴─────────────────┐
        │                                   │
┌───────▼─────────┐               ┌─────────▼────────┐
│ InMemoryGarrison│               │ SqliteGarrison   │
│  (Ephemeral)    │               │  (Persistent)    │
│                 │               │                  │
│  Storage:       │               │  Storage:        │
│  - VecDeque     │               │  - SQLite DB     │
│  - RwLock       │               │  - Connection    │
│                 │               │    Pool          │
│  Use Cases:     │               │  - FTS5 Index    │
│  - Testing      │               │                  │
│  - Dev          │               │  Use Cases:      │
│  - Short-lived  │               │  - Production    │
│    sessions     │               │  - Multi-session │
│                 │               │  - Analytics     │
└─────────────────┘               └──────────────────┘

Core Components

Domain Layer (src/core/platform/container/garrison.rs)

• GarrisonEntry: Individual conversation message
• ConversationRole: System, User, Assistant, Tool
• GarrisonConfig: Windowing and eviction configuration
• EvictionStrategy: FIFO, ImportanceBased, SlidingWindow

Application Layer (src/application/ports/output/garrison_port.rs)

• GarrisonPort: Core interface for memory operations
• LongTermGarrisonPort: Extended interface for vector search (future)
• GarrisonStats: Statistics and metrics
• GarrisonError: Comprehensive error types

Infrastructure Layer (src/infrastructure/adapters/garrison/)

• InMemoryGarrison: Fast, ephemeral implementation
• SqliteGarrison: Persistent, production-ready implementation

Configuration

GarrisonConfig

#![allow(unused)]
fn main() {
use paladin::core::platform::container::garrison::{
    GarrisonConfig, EvictionStrategy
};

// Default configuration
let config = GarrisonConfig::default();
// max_entries: 100
// max_tokens: Some(4000)
// eviction_strategy: ImportanceBased
// preserve_recent_count: 10

// Custom configuration
let config = GarrisonConfig::new(50, Some(2000))
    .with_eviction_strategy(EvictionStrategy::SlidingWindow)
    .with_preserve_recent(5);
}

Configuration Options

Eviction Strategies

FIFO (First In, First Out)

#![allow(unused)]
fn main() {
.with_eviction_strategy(EvictionStrategy::FIFO)
}

• Behavior: Remove the oldest entry when limits are exceeded
• Use Case: Simple, predictable behavior for chat applications
• Pros: Consistent, easy to understand
• Cons: May lose important context like system prompts

ImportanceBased

#![allow(unused)]
fn main() {
.with_eviction_strategy(EvictionStrategy::ImportanceBased)
}

• Behavior: Preserve system prompts and recent messages, evict middle entries
• Use Case: Multi-turn conversations where instructions matter
• Pros: Maintains critical context (system prompt) and recent flow
• Cons: More complex logic

SlidingWindow

#![allow(unused)]
fn main() {
.with_eviction_strategy(EvictionStrategy::SlidingWindow)
}

• Behavior: Always keep the N most recent entries
• Use Case: Short-term context without historical baggage
• Pros: Predictable memory usage, fresh context
• Cons: Loses all historical context

Usage Patterns

Pattern 1: Simple In-Memory Conversation

use paladin::infrastructure::adapters::garrison::InMemoryGarrison;
use paladin::paladin_ports::output::garrison_port::GarrisonPort;
use paladin::core::platform::container::garrison::{
    GarrisonConfig, GarrisonEntry, ConversationRole
};

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

    // Store system prompt
    let system = GarrisonEntry::new(
        ConversationRole::System,
        "You are a helpful assistant.".into()
    );
    garrison.remember(system).await?;

    // Store conversation
    let user_msg = GarrisonEntry::new(
        ConversationRole::User,
        "What is Rust?".into()
    );
    garrison.remember(user_msg).await?;

    let assistant_msg = GarrisonEntry::new(
        ConversationRole::Assistant,
        "Rust is a systems programming language...".into()
    );
    garrison.remember(assistant_msg).await?;

    // Retrieve recent context
    let recent = garrison.recall_recent(10).await?;
    println!("Context has {} entries", recent.len());

    Ok(())
}

Pattern 2: Persistent Conversation with SQLite

use paladin::infrastructure::adapters::garrison::sqlite_garrison::SqliteGarrison;
use paladin::paladin_ports::output::garrison_port::GarrisonPort;
use paladin::core::platform::container::garrison::GarrisonConfig;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = GarrisonConfig::default();

    // Connect to database (creates if doesn't exist)
    let garrison = SqliteGarrison::connect(
        "./data/garrison.db",
        config,
        "assistant-001"  // Unique paladin ID
    ).await?;

    // Data persists across restarts!
    let previous_history = garrison.recall_recent(100).await?;
    println!("Loaded {} previous entries", previous_history.len());

    // ... store new entries ...

    Ok(())
}

Pattern 3: Context-Aware Search

#![allow(unused)]
fn main() {
// Search for specific topics in conversation history
let results = garrison.search("error handling", 10).await?;

for entry in results {
    println!("[{}] {}",
        match entry.role {
            ConversationRole::User => "User",
            ConversationRole::Assistant => "Assistant",
            _ => "Other",
        },
        entry.content
    );
}

// Phrase search (exact match) for SQLite
let exact_results = garrison.search("\"memory safety\"", 5).await?;
}

Pattern 4: Integrating with PaladinExecutionService

#![allow(unused)]
fn main() {
use paladin::application::services::paladin::{
    PaladinBuilder, PaladinExecutionService, CircuitBreaker
};
use std::sync::Arc;

// Create garrison
let garrison = Arc::new(SqliteGarrison::connect(
    "./garrison.db",
    config,
    "my-paladin"
).await?);

// Create execution service with garrison
let circuit_breaker = Arc::new(CircuitBreaker::new(3, 2, 30000));
let service = PaladinExecutionService::new(
    llm_port,
    circuit_breaker,
    Some(garrison.clone())  // Enable memory!
);

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

// Execute - conversation history is automatically managed
let result = service.execute(&paladin, "Hello!").await?;
}

Pattern 5: Manual Context Window Management

#![allow(unused)]
fn main() {
use paladin::core::platform::container::garrison::ConversationHistory;

// For advanced use cases
let mut history = ConversationHistory::new(config);

history.add(system_entry);
history.add(user_entry);
history.add(assistant_entry);

// Automatic eviction when limits reached
let context_for_llm = history.to_entries();
}

Implementations

InMemoryGarrison

When to use:

• Development and testing
• Short-lived sessions (< 1 hour)
• Prototyping
• When persistence isn't needed

Characteristics:

• Storage: In-process memory (VecDeque + RwLock)
• Performance: Fastest (microsecond operations)
• Persistence: None (data lost on shutdown)
• Concurrency: Thread-safe read-write locking
• Search: O(N) substring matching

Example:

#![allow(unused)]
fn main() {
let garrison = InMemoryGarrison::new(GarrisonConfig::default());
}

SqliteGarrison

When to use:

• Production deployments
• Multi-session conversations
• When you need data recovery
• Analytics and conversation history
• Multiple paladins sharing infrastructure

Characteristics:

• Storage: SQLite database file
• Performance: Fast (connection pooling, indexed searches)
• Persistence: Durable across restarts
• Concurrency: Connection pool (up to 5 concurrent)
• Search: FTS5 full-text search (very fast)
• Isolation: Per-paladin data isolation via paladin_id

Example:

#![allow(unused)]
fn main() {
let garrison = SqliteGarrison::connect(
    "./garrison.db",
    config,
    "paladin-001"
).await?;
}

Database Schema:

CREATE TABLE garrison_entries (
    id TEXT PRIMARY KEY,
    paladin_id TEXT NOT NULL,
    role TEXT NOT NULL,
    content TEXT NOT NULL,
    timestamp TEXT NOT NULL,
    token_count INTEGER,
    metadata TEXT,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

CREATE INDEX idx_paladin_timestamp ON garrison_entries(paladin_id, timestamp DESC);

CREATE VIRTUAL TABLE garrison_fts USING fts5(content, paladin_id);

Troubleshooting

Issue: "Out of memory" with InMemoryGarrison

Cause: No eviction configured or limits too high

Solution:

#![allow(unused)]
fn main() {
// Set reasonable limits
let config = GarrisonConfig::new(50, Some(2000))
    .with_eviction_strategy(EvictionStrategy::SlidingWindow);
}

Issue: "Database is locked" with SqliteGarrison

Cause: Exceeding connection pool limits or long-running transactions

Solution:

• Ensure async operations complete promptly
• Check connection pool size (default: 5)
• Avoid holding database locks during slow operations (LLM calls)

Issue: Search returns no results

Cause: FTS5 tokenization or query syntax

Solution:

#![allow(unused)]
fn main() {
// Use phrase search for exact matches
let results = garrison.search("\"exact phrase\"", 10).await?;

// For partial matches, use wildcards (SQLite only)
let results = garrison.search("rust*", 10).await?;
}

Issue: Entries not appearing after restart

Cause: Using InMemoryGarrison instead of SqliteGarrison

Solution:

#![allow(unused)]
fn main() {
// Switch to persistent storage
let garrison = SqliteGarrison::connect(
    "./persistent_garrison.db",
    config,
    "my-paladin"
).await?;
}

Issue: Wrong paladin seeing another's conversation

Cause: Using same paladin_id for different instances

Solution:

#![allow(unused)]
fn main() {
// Use unique IDs per paladin
let garrison1 = SqliteGarrison::connect(db, config, "alice").await?;
let garrison2 = SqliteGarrison::connect(db, config, "bob").await?;
}

Issue: High memory usage even with eviction

Cause: Large content per entry or token counting disabled

Solution:

#![allow(unused)]
fn main() {
// Enable token counting (requires tiktoken)
use paladin::infrastructure::adapters::garrison::token_counter::TokenCounterFactory;

let counter = TokenCounterFactory::for_model("gpt-4");

// Manually set token counts
let mut entry = GarrisonEntry::new(role, content);
entry.token_count = Some(counter.count_tokens(&content));
garrison.remember(entry).await?;
}

Performance Considerations

Benchmarks (Approximate)

Optimization Tips

For InMemoryGarrison

1. Use appropriate config: Don't store more than needed

   #![allow(unused)]
   fn main() {
   GarrisonConfig::new(20, Some(1500))  // Small window for recent context
   }

2. Periodic cleanup: Call forget_all() after long-running sessions

   #![allow(unused)]
   fn main() {
   if session_count > 100 {
       garrison.forget_all().await?;
   }
   }

For SqliteGarrison

1. Batch operations: Group multiple remembers if possible (future enhancement)

2. Optimize searches:

   #![allow(unused)]
   fn main() {
   // Good: Specific phrase search
   garrison.search("\"memory management\"", 5).await?
   
   // Avoid: Very broad searches with high limits
   // garrison.search("the", 1000).await?  // Slow!
   }

3. Use appropriate limits: Don't recall more than needed

   #![allow(unused)]
   fn main() {
   // Good: Only what you need
   let context = garrison.recall_recent(10).await?;
   
   // Avoid: Retrieving everything unnecessarily
   // let all = garrison.recall_recent(100000).await?;
   }

4. Regular VACUUM: Reclaim space periodically

   #![allow(unused)]
   fn main() {
   // Run VACUUM on SQLite database file periodically
   // (requires manual SQL execution)
   }

Memory Footprint

InMemoryGarrison:

• Base: ~200 bytes
• Per entry: ~300-500 bytes (depending on content length)
• Example: 100 entries ≈ 30-50 KB

SqliteGarrison:

• Base: ~1 MB (connection pool)
• Per entry: Disk storage only
• Example: 10,000 entries ≈ 5-10 MB database file

Next Steps

• See examples/garrison_in_memory.rs for basic usage
• See examples/garrison_persistent.rs for SQLite usage
• See examples/garrison_semantic_search.rs for future vector search
• Review API documentation for detailed type information

Future Enhancements

• Vector embeddings: Semantic similarity search via LongTermGarrisonPort
• Batch operations: Efficient multi-entry storage
• Compression: Automatic content compression for old entries
• Export/import: Conversation backup and restore
• Analytics: Conversation statistics and insights
• Redis adapter: Distributed garrison for multi-node deployments

Sanctum: Long-term Memory System

Sanctum is Paladin's long-term memory system that enables AI agents to store, retrieve, and learn from historical interactions using vector embeddings and semantic search.

Table of Contents

• Overview
• Architecture
• Adapters
• Configuration
• Usage Examples
• RAG Integration
• Performance
• Deployment
• Migration Guide
• API Reference

Overview

Sanctum provides persistent, searchable memory for Paladin agents through a flexible adapter system that supports both development and production scenarios.

Key Features

• Vector-based semantic search: Find relevant memories using embedding similarity
• Flexible storage adapters: Choose between in-memory (dev) and Qdrant (production)
• Rich metadata filtering: Filter by paladin ID, memory type, importance, timestamps
• Memory types: Episodic (events), Semantic (facts), Procedural (skills)
• Importance scoring: Prioritize critical memories (0.0-1.0 scale)
• Access tracking: Monitor memory usage patterns
• Batch operations: Efficiently store multiple memories

Use Cases

1. Conversation History: Remember past interactions with users
2. Knowledge Accumulation: Build long-term knowledge bases
3. Context Retrieval: Pull relevant context for current tasks
4. Learning from Experience: Improve responses based on historical data
5. Multi-session Continuity: Maintain state across agent restarts

Architecture

Sanctum follows the Hexagonal Architecture pattern with clear separation between domain, application, and infrastructure layers:

┌─────────────────────────────────────────────────────────────┐
│                     Application Layer                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │              SanctumPort (Trait)                      │  │
│  │  - store()                                            │  │
│  │  - store_batch()                                      │  │
│  │  - search()                                           │  │
│  │  - delete()                                           │  │
│  │  - update()                                           │  │
│  │  - count()                                            │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┴───────────────────┐
        │                                       │
        ▼                                       ▼
┌────────────────────┐              ┌────────────────────┐
│ InMemorySanctum    │              │ QdrantSanctumAdapter│
│ (Development)      │              │ (Production)       │
│                    │              │                    │
│ - HashMap storage  │              │ - Vector database  │
│ - Fast startup     │              │ - Persistent       │
│ - No setup needed  │              │ - Scalable         │
└────────────────────┘              └────────────────────┘

Domain Types

Memory

Represents a single memory entry with metadata:

#![allow(unused)]
fn main() {
pub struct Memory {
    pub id: Uuid,
    pub paladin_id: String,
    pub content: String,
    pub memory_type: MemoryType,
    pub importance: f32,
    pub access_count: u32,
    pub created_at: DateTime<Utc>,
    pub last_accessed: DateTime<Utc>,
    pub metadata: HashMap<String, Value>,
}
}

MemoryType

Categories for different types of memories:

• Episodic: Specific events and experiences ("User asked about Rust")
• Semantic: General facts and knowledge ("Rust is a systems programming language")
• Procedural: How-to knowledge and skills ("To compile Rust, run cargo build")

SanctumEntry

Memory paired with its vector embedding:

#![allow(unused)]
fn main() {
pub struct SanctumEntry {
    pub memory: Memory,
    pub embedding: Vec<f32>,
}
}

Adapters

Sanctum supports multiple storage adapters through the SanctumPort trait.

InMemory Adapter

Best for:

• Development and testing
• Prototyping
• Small-scale deployments (<10,000 memories)
• Fast iteration without infrastructure

Characteristics:

• ✅ Zero setup required
• ✅ Lightning-fast operations (<1ms)
• ✅ Simple debugging
• ❌ Data lost on restart
• ❌ Limited to single machine
• ❌ Memory constrained by RAM

Configuration:

sanctum:
  enabled: true
  adapter_type: "in_memory"

Qdrant Adapter

Best for:

• Production deployments
• Large-scale applications (>10,000 memories)
• Distributed systems
• Data persistence requirements

Characteristics:

• ✅ Persistent storage
• ✅ Scalable to millions of vectors
• ✅ Fast semantic search (<500ms for 100K vectors)
• ✅ Distributed deployment support
• ✅ HNSW indexing for performance
• ❌ Requires Qdrant infrastructure
• ❌ Slightly higher latency than in-memory

Configuration:

sanctum:
  enabled: true
  adapter_type: "qdrant"
  qdrant:
    url: "http://localhost:6334"
    collection_name: "paladin_memories"
    vector_dimension: 1536  # Must match embedding model

Adapter Comparison

Configuration

Basic Configuration

# Minimal development configuration
sanctum:
  enabled: true
  adapter_type: "in_memory"

Production Configuration

# Production Qdrant configuration
sanctum:
  enabled: true
  adapter_type: "qdrant"
  qdrant:
    url: "http://qdrant:6334"
    collection_name: "paladin_production_memories"
    vector_dimension: 1536  # OpenAI text-embedding-3-small

Environment Variable Overrides

All configuration can be overridden via environment variables:

# Enable/disable Sanctum
export APP_SANCTUM_ENABLED=true

# Select adapter
export APP_SANCTUM_ADAPTER_TYPE=qdrant

# Qdrant configuration
export APP_SANCTUM_QDRANT_URL=http://qdrant-cluster:6334
export APP_SANCTUM_QDRANT_COLLECTION_NAME=custom_memories
export APP_SANCTUM_QDRANT_VECTOR_DIMENSION=3072

Vector Dimensions by Model

Choose the dimension that matches your embedding model:

Usage Examples

Creating a Sanctum Adapter

Development (InMemory)

use paladin::infrastructure::adapters::sanctum::InMemorySanctum;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // No configuration needed for in-memory
    let sanctum = InMemorySanctum::new();

    println!("InMemory Sanctum ready!");
    Ok(())
}

Production (Qdrant)

use paladin::infrastructure::adapters::sanctum::QdrantSanctumAdapter;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to Qdrant
    let sanctum = QdrantSanctumAdapter::new(
        "http://localhost:6334",  // Qdrant gRPC endpoint
        "paladin_memories",        // Collection name
        1536,                      // Vector dimension
    ).await?;

    println!("Qdrant Sanctum connected!");
    Ok(())
}

Storing Memories

#![allow(unused)]
fn main() {
use paladin::core::platform::container::sanctum::{MemoryBuilder, MemoryType, SanctumEntry};
use paladin::paladin_ports::output::sanctum_port::SanctumPort;

async fn store_memory(
    sanctum: &dyn SanctumPort,
    embedding_vector: Vec<f32>,
) -> Result<(), Box<dyn std::error::Error>> {
    // Build a memory
    let memory = MemoryBuilder::new(
        "paladin-123".to_string(),
        "User asked about Rust programming".to_string(),
    )
    .memory_type(MemoryType::Episodic)
    .importance(0.8)
    .build()?;

    // Create entry with embedding
    let entry = SanctumEntry::new(memory, embedding_vector)?;

    // Store in Sanctum
    sanctum.store(entry).await?;

    Ok(())
}
}

Batch Storing

#![allow(unused)]
fn main() {
async fn store_batch(
    sanctum: &dyn SanctumPort,
) -> Result<(), Box<dyn std::error::Error>> {
    let entries: Vec<SanctumEntry> = vec![
        // ... create multiple entries
    ];

    // Efficient batch storage
    sanctum.store_batch(entries).await?;

    Ok(())
}
}

Semantic Search

#![allow(unused)]
fn main() {
use paladin::paladin_ports::output::sanctum_port::SanctumQuery;

async fn search_memories(
    sanctum: &dyn SanctumPort,
    query_embedding: Vec<f32>,
) -> Result<(), Box<dyn std::error::Error>> {
    // Create search query
    let query = SanctumQuery::new(query_embedding, 5)  // Top 5 results
        .min_score(0.7);  // Minimum similarity threshold

    // Execute search
    let results = sanctum.search(query).await?;

    for result in results {
        println!("Score: {:.3} - {}", result.score, result.entry.memory.content);
    }

    Ok(())
}
}

Filtered Search

#![allow(unused)]
fn main() {
use paladin::paladin_ports::output::sanctum_port::SanctumFilter;

async fn filtered_search(
    sanctum: &dyn SanctumPort,
    query_embedding: Vec<f32>,
) -> Result<(), Box<dyn std::error::Error>> {
    // Build filter
    let filter = SanctumFilter::new()
        .paladin_id("paladin-123".to_string())
        .memory_type(MemoryType::Episodic)
        .min_importance(0.5);

    // Search with filter
    let query = SanctumQuery::new(query_embedding, 10)
        .filter(filter);

    let results = sanctum.search(query).await?;

    Ok(())
}
}

Updating and Deleting

#![allow(unused)]
fn main() {
async fn update_memory(
    sanctum: &dyn SanctumPort,
    entry: SanctumEntry,
) -> Result<(), Box<dyn std::error::Error>> {
    // Update entry (upsert)
    sanctum.update(entry).await?;

    Ok(())
}

async fn delete_memory(
    sanctum: &dyn SanctumPort,
    memory_id: &str,
) -> Result<(), Box<dyn std::error::Error>> {
    // Delete by ID
    let deleted = sanctum.delete(memory_id).await?;

    if deleted {
        println!("Memory deleted successfully");
    } else {
        println!("Memory not found");
    }

    Ok(())
}
}

Performance

Benchmarks

Performance characteristics based on testing:

InMemory Adapter

Qdrant Adapter

Performance Recommendations

1. Use batch operations: 10-100x faster than individual stores
2. Set appropriate top_k: Lower values = faster searches
3. Use min_score: Filter low-quality results early
4. Index design: HNSW indexing in Qdrant provides sub-linear search time
5. Monitor memory: InMemory adapter consumes ~1KB per entry with 1536-dim vectors

Scaling Guidelines

InMemory

• Comfortable: Up to 10,000 entries
• Maximum: 100,000 entries (requires ~150MB RAM with 1536-dim vectors)
• Beyond: Switch to Qdrant

Qdrant

• Single node: 1-10 million entries
• Cluster: 10M+ entries with horizontal scaling
• Performance target: <500ms search on 100K entries maintained

Deployment

See DEPLOYMENT.md for detailed deployment guides including:

• Docker Compose setup
• Kubernetes deployment
• Cloud provider configurations (AWS, GCP, Azure)
• Production best practices
• Monitoring and observability

Quick Docker Setup

# docker-compose.yml
services:
  qdrant:
    image: qdrant/qdrant:latest
    ports:
      - "6333:6333"  # HTTP API
      - "6334:6334"  # gRPC API
    volumes:
      - qdrant_data:/qdrant/storage
    environment:
      - QDRANT__SERVICE__HTTP_PORT=6333
      - QDRANT__SERVICE__GRPC_PORT=6334

volumes:
  qdrant_data:

Start with:

docker-compose up -d qdrant

Migration Guide

See MIGRATION.md for detailed migration guides including:

• Migrating from InMemory to Qdrant
• Exporting and importing memories
• Zero-downtime migration strategies
• Rollback procedures

Quick Migration Overview

1. Export memories from InMemory adapter
2. Start Qdrant infrastructure
3. Configure Paladin with Qdrant adapter
4. Import memories into Qdrant
5. Validate data integrity
6. Switch to Qdrant adapter

API Reference

SanctumPort Trait

The main interface for all Sanctum adapters:

#![allow(unused)]
fn main() {
#[async_trait]
pub trait SanctumPort: Send + Sync {
    /// Store a single memory entry
    async fn store(&self, entry: SanctumEntry) -> Result<(), SanctumError>;

    /// Store multiple entries in batch (more efficient)
    async fn store_batch(&self, entries: Vec<SanctumEntry>) -> Result<(), SanctumError>;

    /// Search for similar memories using vector similarity
    async fn search(&self, query: SanctumQuery) -> Result<Vec<SanctumSearchResult>, SanctumError>;

    /// Delete a memory by ID
    async fn delete(&self, id: &str) -> Result<bool, SanctumError>;

    /// Update an existing memory (upsert)
    async fn update(&self, entry: SanctumEntry) -> Result<(), SanctumError>;

    /// Count memories matching optional filter
    async fn count(&self, filter: Option<SanctumFilter>) -> Result<usize, SanctumError>;
}
}

Memory Builder

Fluent API for creating memories:

#![allow(unused)]
fn main() {
let memory = MemoryBuilder::new(paladin_id, content)
    .memory_type(MemoryType::Semantic)
    .importance(0.9)
    .with_metadata("key", json!("value"))
    .build()?;
}

Query Builder

Build semantic search queries:

#![allow(unused)]
fn main() {
let query = SanctumQuery::new(embedding, top_k)
    .min_score(0.7)
    .filter(filter);
}

Filter Builder

Build complex filters:

#![allow(unused)]
fn main() {
let filter = SanctumFilter::new()
    .paladin_id("paladin-123")
    .memory_type(MemoryType::Episodic)
    .min_importance(0.5)
    .created_after(start_time)
    .created_before(end_time)
    .with_metadata("category", json!("technical"));
}

Error Handling

Sanctum operations return Result<T, SanctumError>:

#![allow(unused)]
fn main() {
#[derive(Debug, thiserror::Error)]
pub enum SanctumError {
    #[error("Storage error: {0}")]
    StorageError(String),

    #[error("Search error: {0}")]
    SearchError(String),

    #[error("Memory not found: {0}")]
    NotFound(String),

    #[error("Invalid dimension: {0}")]
    InvalidDimension(String),

    #[error("Configuration error: {0}")]
    ConfigError(String),
}
}

Handle errors appropriately:

#![allow(unused)]
fn main() {
match sanctum.store(entry).await {
    Ok(()) => println!("Memory stored successfully"),
    Err(SanctumError::StorageError(msg)) => eprintln!("Storage failed: {}", msg),
    Err(e) => eprintln!("Unexpected error: {}", e),
}
}

RAG Integration (Retrieval-Augmented Generation)

New in Epic 12: Automatic memory retrieval and extraction for Paladin agents

Sanctum now supports seamless RAG integration, enabling Paladin agents to automatically retrieve relevant context before execution and extract memories after completion.

Overview

RAG (Retrieval-Augmented Generation) enhances Paladin responses by:

1. Auto-Retrieval: Fetch relevant memories before LLM calls
2. Context Injection: Insert historical context into prompts
3. Auto-Extraction: Store important facts after execution
4. Knowledge Building: Accumulate wisdom across sessions

Architecture

User Input
    ↓
┌─────────────────────────────┐
│  RagRetrievalService        │
│  • Embed query              │
│  • Search Sanctum (top-k)   │
│  • Filter by similarity     │
│  • Format as context        │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│  PaladinExecutionService    │
│  • Inject context to prompt │
│  • Execute LLM with context │
│  • Return enriched response │
└─────────────┬───────────────┘
              ↓
┌─────────────────────────────┐
│  MemoryExtractionService    │
│  • Parse response           │
│  • Identify key facts       │
│  • Generate embeddings      │
│  • Store in Sanctum         │
└─────────────────────────────┘
    ↓
Response

Configuration

Add RAG configuration to your config.yml:

# Sanctum configuration (required for RAG)
sanctum:
  provider: qdrant  # or 'in_memory'
  qdrant:
    url: http://localhost:6333
    collection_name: paladin_memories
    vector_dimension: 1536  # Match embedding model
    distance: cosine

# RAG Retrieval settings
rag:
  top_k: 5                  # Number of memories to retrieve
  min_similarity: 0.7        # Minimum similarity score (0.0-1.0)
  max_tokens: 2000           # Max tokens for context
  timeout_seconds: 5         # Retrieval timeout

# Memory Extraction settings
memory_extraction:
  enabled: true
  strategy: on_completion    # Options: on_completion, every_turn, manual, threshold

RAG Retrieval Service

Basic Usage

#![allow(unused)]
fn main() {
use paladin::application::services::sanctum::rag_retrieval_service::{
    RagRetrievalService, RagConfig
};

let rag_service = RagRetrievalService::new(
    Arc::clone(&sanctum_port),
    Arc::clone(&embedding_port),
    RagConfig::default(),
);

// Retrieve relevant context
let memories = rag_service
    .retrieve_context("paladin-id", "user query")
    .await?;

// Format for prompt injection
let context_text = rag_service.format_for_prompt(&memories);
}

Configuration Options

#![allow(unused)]
fn main() {
let rag_config = RagConfig {
    top_k: 5,                              // Retrieve top 5 memories
    min_similarity: 0.7,                   // Only >= 70% match
    max_tokens: 2000,                      // Budget limit
    retrieval_trigger: RetrievalTrigger::Always,  // When to retrieve
};
}

Retrieval Triggers:

• Always: Retrieve for every query (recommended)
• KeywordBased: Retrieve only if keywords detected
• SemanticThreshold: Retrieve if query similarity exceeds threshold

Advanced Features

Deduplication: Automatically removes near-identical memories (>0.95 similarity)

Ranking: Sorts memories by relevance score (descending)

Token Budget: Truncates context to fit within max_tokens limit

Timeout Handling: Gracefully handles retrieval timeouts (returns empty context)

Memory Extraction Service

Basic Usage

#![allow(unused)]
fn main() {
use paladin::application::services::sanctum::memory_extraction_service::{
    MemoryExtractionService, MemoryExtractionStrategy
};

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

// Extract memories from conversation
let conversation = vec![
    garrison_entry_1,
    garrison_entry_2,
];

let extracted = extraction_service
    .extract_memories("paladin-id", &conversation)
    .await?;
}

Extraction Strategies

#![allow(unused)]
fn main() {
pub enum MemoryExtractionStrategy {
    EveryTurn,                    // Extract after each interaction
    OnCompletion,                 // Extract when conversation ends
    Manual,                       // Explicit extraction calls
    Threshold { importance: f32 },  // Extract if importance >= threshold
}
}

Strategy Recommendations:

• OnCompletion: Best for most use cases (default)
• EveryTurn: For critical interactions needing immediate storage
• Threshold: For filtering low-importance content
• Manual: For custom extraction logic

Memory Quality

The extraction service uses LLM-based analysis to:

• Identify key facts and insights
• Categorize by memory type (Episodic/Semantic/Procedural)
• Assign importance scores (0.0-1.0)
• Add contextual metadata

Paladin Integration

Programmatic Setup

#![allow(unused)]
fn main() {
use paladin::application::services::paladin::paladin_execution_service::PaladinExecutionService;

// Create 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 execution service 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
// ✓ Response generated with historical context
// ✓ New memories extracted and stored
}

Configuration-based Setup

When using config.yml, RAG happens automatically:

#![allow(unused)]
fn main() {
// No code changes required!
// RAG is configured via config.yml and happens transparently
let result = paladin.execute("user input").await?;
}

Performance Tuning

Retrieval Optimization

Trade-offs:

• ↑ top_k → More context but slower and more expensive
• ↓ min_similarity → More memories but less relevant
• ↑ max_tokens → Better context but higher token costs

Extraction Optimization

Batch Operations: Extract memories in batches to reduce API calls

#![allow(unused)]
fn main() {
// Batch extract from multiple conversations
let all_conversations = vec![conv1, conv2, conv3];
for conversation in all_conversations {
    extraction_service.extract_memories(paladin_id, &conversation).await?;
}
}

Duplicate Detection: Automatic deduplication prevents redundant storage

Importance Filtering: Set minimum importance thresholds to reduce noise

Example Workflow

Session 1: Building Knowledge Base

#![allow(unused)]
fn main() {
// First interaction - no prior context
let result1 = execution_service.execute(&paladin, "What is Rust?").await?;
// Output: "Rust is a systems programming language..."
// Memory stored: "Rust is a systems language focused on safety"

// Second interaction - retrieves first memory
let result2 = execution_service.execute(&paladin, "Tell me about ownership").await?;
// Context injected: Previous Rust definition
// Output: "Building on Rust's focus on safety, ownership is..."
// Memory stored: "Ownership prevents memory bugs"
}

Session 2: Using Knowledge

#![allow(unused)]
fn main() {
// New session - agent remembers previous learnings
let result3 = execution_service.execute(&paladin, "Explain memory management").await?;
// Context retrieved: Rust definition + ownership explanation
// Output: "Based on our earlier discussion about Rust's ownership..."
// ✓ Response quality improved with historical context
}

Monitoring & Debugging

Enable Debug Logging

#![allow(unused)]
fn main() {
env_logger::init();  // Set RUST_LOG=debug
}

Logs include:

• Retrieval latency and result counts
• Memory extraction statistics
• Context injection details
• Error conditions and fallbacks

Metrics

Track these metrics for production:

#![allow(unused)]
fn main() {
// Retrieval metrics
- retrieval_latency_ms
- memories_retrieved_count
- similarity_scores_distribution

// Extraction metrics
- extraction_latency_ms
- memories_stored_count
- importance_scores_distribution

// Quality metrics
- context_injection_rate
- response_improvement_score
}

Troubleshooting

No memories retrieved

Causes:

• Empty Sanctum (first interaction)
• Similarity threshold too high
• Embeddings not generated correctly

Solutions:

rag:
  min_similarity: 0.5  # Lower threshold
  top_k: 10            # Increase candidates

Irrelevant context

Causes:

• Similarity threshold too low
• Poor embedding quality
• Noisy memory storage

Solutions:

rag:
  min_similarity: 0.8  # Stricter threshold
  top_k: 3             # Fewer, better matches

Slow execution

Causes:

• Large top_k value
• Sanctum query latency
• Embedding generation delay

Solutions:

rag:
  top_k: 3             # Reduce candidates
  timeout_seconds: 3   # Stricter timeout

Best Practices

1. Start Simple: Use default configuration and adjust based on results
2. Monitor Quality: Track retrieval relevance and response improvement
3. Tune Gradually: Adjust one parameter at a time
4. Test Thresholds: Experiment with similarity values for your use case
5. Production Setup: Use Qdrant for scalability, in-memory for dev
6. Error Handling: RAG degrades gracefully if Sanctum unavailable
7. Cost Management: Balance top_k and max_tokens against API costs

Example Code

See working examples:

• examples/paladin_with_rag.rs - RAG configuration demonstration
• examples/paladin_with_sanctum.rs - Memory operations
• examples/cli_configs/paladin_rag.yaml - Full configuration
• tests/integration/rag_integration_tests.rs - Configuration validation

Best Practices

1. Memory Management

• Set appropriate importance scores (0.0-1.0)
• Use memory types correctly (Episodic/Semantic/Procedural)
• Add meaningful metadata for filtering
• Implement cleanup strategies for old memories

2. Embedding Quality

• Use consistent embedding models
• Ensure vector dimensions match configuration
• Normalize embeddings for better similarity scores
• Consider embedding model costs vs. quality trade-offs

3. Search Optimization

• Use filters to reduce search space
• Set reasonable top_k values (5-20 typical)
• Apply min_score thresholds (0.7+ for high relevance)
• Batch operations when possible

4. Production Deployment

• Use Qdrant for production workloads
• Monitor search latencies
• Implement proper backup strategies
• Use separate collections for different use cases
• Configure appropriate resource limits

5. Development Workflow

• Use InMemory for development
• Test with realistic data volumes
• Validate configuration before production
• Implement graceful degradation if Sanctum unavailable

Troubleshooting

Common Issues

1. Dimension Mismatch

Error: InvalidDimension: Expected 1536 dimensions, got 768

Solution: Ensure embedding model matches configured dimension:

qdrant:
  vector_dimension: 768  # Match your model's output

2. Qdrant Connection Failed

Error: StorageError: Failed to connect to Qdrant

Solution: Verify Qdrant is running and accessible:

curl http://localhost:6333/health

3. Slow Search Performance

Symptom: Search takes >1 second

Solutions:

• Reduce top_k value
• Add filters to narrow search space
• Check Qdrant resource allocation
• Consider upgrading to Qdrant cluster

4. Memory Not Found After Insert

Issue: Inserted memory not immediately searchable

Solution: Qdrant indexes asynchronously. Add small delay:

#![allow(unused)]
fn main() {
sanctum.store(entry).await?;
tokio::time::sleep(Duration::from_millis(100)).await;
// Now searchable
}

Additional Resources

• Sanctum Architecture
• Qdrant Documentation
• OpenAI Embeddings
• Vector Search Tutorial

Support

For issues, questions, or contributions:

• GitHub Issues: paladin-dev-env/issues
• Discussions: paladin-dev-env/discussions

Next Steps:

• Review Configuration Examples
• Explore Deployment Guide
• Read Migration Guide

Herald Output Formatting System

The Herald is Paladin's pluggable output formatting system that transforms Paladin and Battalion execution results into human-readable formats. It provides multiple built-in formatters (JSON, Markdown, Table) and supports custom formatters through a simple trait-based interface.

Table of Contents

• Overview
• Quick Start
• Built-in Formatters
  • JSON Herald
  • Markdown Herald
  • Table Herald
• Configuration
• Usage Patterns
  • Paladin Execution
  • Battalion Execution
  • Runtime Override
• Streaming Support
• Custom Formatters
• Performance
• API Reference

Overview

The Herald system follows the Hexagonal Architecture pattern:

Core (Domain)                   Application (Ports)              Infrastructure (Adapters)
┌─────────────────┐            ┌──────────────────┐            ┌─────────────────────┐
│ Herald Trait    │────────────│ Herald Port      │────────────│ JsonHerald          │
│ PaladinResult   │            │ HeraldRegistry   │            │ MarkdownHerald      │
│ BattalionResult │            │                  │            │ TableHerald         │
│ StreamChunk     │            │                  │            │ (Your Custom Herald)│
└─────────────────┘            └──────────────────┘            └─────────────────────┘

Key Features:

• 🎨 Multiple Formats: JSON, Markdown, and Table formatters included
• ⚡ High Performance: <1ms for 10KB results (tested at 0.0095ms)
• 🔌 Pluggable: Easy to add custom formatters
• 📡 Streaming Support: Progressive output for long-running tasks
• ⚙️ Configurable: YAML-based configuration with runtime overrides
• 🏗️ Type-Safe: Strong typing with comprehensive error handling

Quick Start

1. Configure Herald in config.yml

herald:
  default_formatter: "json"  # or "markdown", "table"
  include_metadata: true

  # JSON-specific options
  json:
    pretty_print: true
    include_timestamps: true

  # Markdown-specific options
  markdown:
    use_colors: true
    heading_level: 2

  # Table-specific options
  table:
    max_column_width: 60
    border_style: "rounded"  # or "ascii", "modern", "none"

2. Use Herald with Paladin

use paladin::application::services::paladin::paladin_builder::PaladinBuilder;
use paladin::application::services::paladin::paladin_execution_service::PaladinExecutionService;
use paladin::config::Settings;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load settings
    let settings = Settings::new()?;

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

    // Create LLM port (example with OpenAI)
    let config = OpenAIConfig::from_env()?;
    let llm_port = Arc::new(OpenAIAdapter::new(config)?);

    // Build Paladin
    let paladin = PaladinBuilder::new(llm_port.clone())
        .system_prompt("You are a helpful assistant")
        .name("MyPaladin")
        .build()?;

    // Create execution service with Herald
    let service = PaladinExecutionService::new(
        llm_port,
        circuit_breaker,
        None,  // garrison
        None,  // arsenal
    ).with_herald(herald);

    // Execute and format
    let result = service.execute(&paladin, "Hello!").await?;
    if let Some(formatted) = service.format_result(&result, &paladin)? {
        println!("{}", formatted);
    }

    Ok(())
}

Built-in Formatters

JSON Herald

Best for: API integrations, structured logging, machine parsing

Format: Pretty-printed JSON with full metadata

{
  "paladin_id": "paladin-123",
  "paladin_name": "DataAnalyst",
  "status": "completed",
  "output": "Analysis results here...",
  "metadata": {
    "execution_time_ms": 1245,
    "total_tokens": 523,
    "timestamp": "2026-01-26T10:30:45Z"
  }
}

Features:

• Pretty-printed by default (configurable)
• Optional timestamps
• NDJSON streaming (newline-delimited JSON)
• Metadata in separate object

Usage:

#![allow(unused)]
fn main() {
use paladin::infrastructure::adapters::herald::JsonHerald;

let herald = Arc::new(JsonHerald::new());
// or with custom config
let herald = Arc::new(JsonHerald::new().with_config(JsonHeraldConfig {
    pretty_print: false,
    include_timestamps: true,
}));
}

Markdown Herald

Best for: Human-readable reports, documentation, CLI output

Format: Structured Markdown with colors and formatting

## ✅ Paladin: DataAnalyst

**Status:** completed
**Output:**
Analysis results here...

---
*Execution Time: 1.25s | Tokens: 523 | Timestamp: 2026-01-26 10:30:45*

Features:

• Color-coded status badges (✅ ❌ ⏱️)
• Configurable heading levels
• Progressive streaming (immediate text output)
• Optional ANSI colors

Usage:

#![allow(unused)]
fn main() {
use paladin::infrastructure::adapters::herald::MarkdownHerald;

let herald = Arc::new(MarkdownHerald::new());
// or with custom config
let herald = Arc::new(MarkdownHerald::new().with_config(MarkdownHeraldConfig {
    use_colors: true,
    heading_level: 3,
}));
}

Table Herald

Best for: Terminal dashboards, side-by-side comparisons, compact summaries

Format: ASCII/Unicode tables with borders

┌────────────┬───────────┬──────────────────────┐
│ Field      │ Value     │ Details              │
├────────────┼───────────┼──────────────────────┤
│ Paladin    │ DataAna…  │ Status: completed    │
│ Output     │ Analysis… │ (truncated to 60ch)  │
│ Time       │ 1.25s     │ Tokens: 523          │
└────────────┴───────────┴──────────────────────┘

Features:

• Multiple border styles (rounded, ascii, modern, none)
• Automatic text truncation (configurable)
• Buffered streaming (renders complete table at end)
• Compact representation

Usage:

#![allow(unused)]
fn main() {
use paladin::infrastructure::adapters::herald::TableHerald;

let herald = Arc::new(TableHerald::default());
// or with custom config
let herald = Arc::new(TableHerald::new().with_config(TableHeraldConfig {
    max_column_width: 80,
    border_style: "modern".to_string(),
}));
}

Configuration

YAML Configuration

All Herald settings are defined in config.yml:

herald:
  # Global settings
  default_formatter: "json"        # Default formatter to use
  include_metadata: true            # Include execution metadata

  # JSON formatter configuration
  json:
    pretty_print: true              # Pretty-print JSON (vs compact)
    include_timestamps: true        # Add ISO 8601 timestamps

  # Markdown formatter configuration
  markdown:
    use_colors: true                # Use ANSI colors in output
    heading_level: 2                # Heading level (1-6)

  # Table formatter configuration
  table:
    max_column_width: 60            # Max chars per column
    border_style: "rounded"         # rounded|ascii|modern|none

Environment Variable Overrides

# Override default formatter
export PALADIN_HERALD__DEFAULT_FORMATTER=markdown

# Override JSON settings
export PALADIN_HERALD__JSON__PRETTY_PRINT=false

# Override table settings
export PALADIN_HERALD__TABLE__MAX_COLUMN_WIDTH=100

Validation Rules

• default_formatter: Must be "json", "markdown", or "table"
• heading_level: Must be 1-6
• max_column_width: Must be > 0
• border_style: Must be "rounded", "ascii", "modern", or "none"

Invalid configurations will return a HeraldError::ConfigurationError.

Usage Patterns

Paladin Execution

#![allow(unused)]
fn main() {
use paladin::application::services::paladin::paladin_execution_service::PaladinExecutionService;

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

// Execute
let result = service.execute(&paladin, "input").await?;

// Format result
match service.format_result(&result, &paladin)? {
    Some(formatted) => println!("{}", formatted),
    None => println!("No Herald configured"),
}
}

Battalion Execution

Formation (Sequential):

#![allow(unused)]
fn main() {
use paladin::application::services::battalion::formation_service::FormationExecutionService;

let service = FormationExecutionService::new(llm_port, cb, None, None)
    .with_herald(herald);

let result = service.execute(&formation, "input").await?;

// Format all Paladin results with enumeration
if let Some(formatted) = service.format_result(&result)? {
    println!("{}", formatted);
}
}

Phalanx (Concurrent):

#![allow(unused)]
fn main() {
use paladin::application::services::battalion::phalanx_service::PhalanxExecutionService;

let service = PhalanxExecutionService::new(
    llm_port,
    cb,
    aggregation_strategy,
    None,
    None,
).with_herald(herald);

let result = service.execute(&phalanx, "input").await?;

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

Runtime Override

Override the Herald at runtime without changing configuration:

#![allow(unused)]
fn main() {
// Load default Herald from config
let default_herald = settings.create_default_herald()?;

// Create service with default
let mut service = PaladinExecutionService::new(llm_port, cb, None, None)
    .with_herald(default_herald);

// Execute with JSON
let result1 = service.execute(&paladin, "task1").await?;
let json_output = service.format_result(&result1, &paladin)?;

// Override to Markdown for specific task
let markdown_herald = Arc::new(MarkdownHerald::new());
service = service.with_herald(markdown_herald);

let result2 = service.execute(&paladin, "task2").await?;
let markdown_output = service.format_result(&result2, &paladin)?;

// Override to Table
let table_herald = Arc::new(TableHerald::default());
service = service.with_herald(table_herald);

let result3 = service.execute(&paladin, "task3").await?;
let table_output = service.format_result(&result3, &paladin)?;
}

Streaming Support

Herald supports progressive output for long-running tasks through streaming:

Streaming Architecture

#![allow(unused)]
fn main() {
pub struct StreamChunk {
    pub content: String,
    pub is_final: bool,
}

pub struct ExecutionMetadata {
    pub execution_time_ms: u64,
    pub total_tokens: u32,
}

pub trait Herald: Send + Sync {
    fn format_stream_chunk(&self, chunk: &StreamChunk) -> Result<Option<String>>;
    fn finalize_stream(&self, metadata: &ExecutionMetadata) -> Result<String>;
}
}

Streaming Strategies

JSON Herald (NDJSON):

• Each chunk is a separate JSON object on its own line
• Newline-delimited JSON (NDJSON) format
• Can be parsed line-by-line as it streams

{"content":"First chunk","is_final":false}
{"content":"Second chunk","is_final":false}
{"content":"Final chunk","is_final":true}
{"type":"metadata","execution_time_ms":1000,"total_tokens":500}

Markdown Herald (Progressive):

• Chunks append directly to output as text
• Immediate visibility for users
• Metadata added as footer section when finalized

First chunk Second chunk Final chunk
---
*Execution Time: 1.00s | Tokens: 500*

Table Herald (Buffered):

• All chunks return None (buffered internally)
• Complete table rendered only in finalize_stream()
• Ensures proper table formatting

(nothing until finalize)
┌────────────┬──────────────────┐
│ Field      │ Value            │
├────────────┼──────────────────┤
│ Output     │ Complete content │
│ Time       │ 1.00s            │
└────────────┴──────────────────┘

Streaming Example

#![allow(unused)]
fn main() {
// Create Herald
let herald = Arc::new(JsonHerald::new());

// Process stream
let mut output = String::new();

for chunk in stream {
    if let Some(formatted) = herald.format_stream_chunk(&chunk)? {
        output.push_str(&formatted);
        print!("{}", formatted);  // Progressive output
    }
}

// Finalize
let metadata = ExecutionMetadata {
    execution_time_ms: 1000,
    total_tokens: 500,
};
let final_line = herald.finalize_stream(&metadata)?;
output.push_str(&final_line);
println!("{}", final_line);
}

Custom Formatters

Implement the Herald trait to create custom formatters:

Example: XML Herald

#![allow(unused)]
fn main() {
use paladin::core::platform::container::herald::{
    Herald, PaladinResult, BattalionResult, StreamChunk, ExecutionMetadata, HeraldError,
};
use async_trait::async_trait;

pub struct XmlHerald;

impl Herald for XmlHerald {
    fn name(&self) -> &str {
        "xml"
    }

    fn mime_type(&self) -> &str {
        "application/xml"
    }

    fn format_paladin_result(&self, result: &PaladinResult) -> Result<String, HeraldError> {
        Ok(format!(
            r#"<?xml version="1.0" encoding="UTF-8"?>
<paladin_result>
    <paladin_id>{}</paladin_id>
    <paladin_name>{}</paladin_name>
    <status>{}</status>
    <output>{}</output>
</paladin_result>"#,
            result.paladin_id,
            result.paladin_name,
            result.status,
            xml_escape(&result.output),
        ))
    }

    fn format_battalion_result(&self, result: &BattalionResult) -> Result<String, HeraldError> {
        let mut xml = format!(
            r#"<?xml version="1.0" encoding="UTF-8"?>
<battalion_result>
    <battalion_id>{}</battalion_id>
    <battalion_name>{}</battalion_name>
    <status>{}</status>
    <paladins>"#,
            result.battalion_id,
            result.battalion_name,
            result.status,
        );

        for paladin in &result.results {
            xml.push_str(&format!(
                r#"
        <paladin id="{}">
            <name>{}</name>
            <status>{}</status>
            <output>{}</output>
        </paladin>"#,
                paladin.paladin_id,
                paladin.paladin_name,
                paladin.status,
                xml_escape(&paladin.output),
            ));
        }

        xml.push_str("\n    </paladins>\n</battalion_result>");
        Ok(xml)
    }

    fn format_error(&self, error: &str) -> Result<String, HeraldError> {
        Ok(format!(
            r#"<?xml version="1.0" encoding="UTF-8"?>
<error>{}</error>"#,
            xml_escape(error)
        ))
    }

    fn format_stream_chunk(&self, chunk: &StreamChunk) -> Result<Option<String>, HeraldError> {
        // XML streaming: wrap each chunk
        Ok(Some(format!(
            r#"<chunk is_final="{}">{}</chunk>"#,
            chunk.is_final,
            xml_escape(&chunk.content)
        )))
    }

    fn finalize_stream(&self, metadata: &ExecutionMetadata) -> Result<String, HeraldError> {
        Ok(format!(
            r#"<metadata execution_time_ms="{}" total_tokens="{}"/>"#,
            metadata.execution_time_ms,
            metadata.total_tokens
        ))
    }
}

fn xml_escape(s: &str) -> String {
    s.replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
        .replace('"', "&quot;")
        .replace('\'', "&apos;")
}
}

Register Custom Herald

#![allow(unused)]
fn main() {
use paladin::application::services::herald::herald_registry::HeraldRegistry;

// Create registry
let mut registry = HeraldRegistry::default();

// Register custom herald
let xml_herald = Arc::new(XmlHerald);
registry.register("xml".to_string(), xml_herald);

// Get when needed
let herald = registry.get("xml").expect("Herald not found");
}

Performance

Herald formatters are designed for minimal overhead:

Benchmark Results

Key Takeaways:

• All formatters process 10KB results in under 10 microseconds
• Performance exceeds requirements by orders of magnitude
• Zero-copy operations where possible
• Efficient string building with pre-allocation

Performance Tips

1. Use appropriate formatter: JSON for APIs, Markdown for humans, Table for dashboards
2. Disable pretty-printing: Set pretty_print: false for JSON in production
3. Limit output size: Truncate large outputs before formatting
4. Buffer streaming: Use Table Herald's buffering for UI consistency

API Reference

Core Types

#![allow(unused)]
fn main() {
/// Main Herald trait for output formatting
pub trait Herald: Send + Sync {
    fn name(&self) -> &str;
    fn mime_type(&self) -> &str;
    fn format_paladin_result(&self, result: &PaladinResult) -> Result<String, HeraldError>;
    fn format_battalion_result(&self, result: &BattalionResult) -> Result<String, HeraldError>;
    fn format_error(&self, error: &str) -> Result<String, HeraldError>;
    fn format_stream_chunk(&self, chunk: &StreamChunk) -> Result<Option<String>, HeraldError>;
    fn finalize_stream(&self, metadata: &ExecutionMetadata) -> Result<String, HeraldError>;
}

/// Paladin execution result
pub struct PaladinResult {
    pub paladin_id: String,
    pub paladin_name: String,
    pub status: String,
    pub output: String,
}

/// Battalion execution result
pub struct BattalionResult {
    pub battalion_id: String,
    pub battalion_name: String,
    pub status: String,
    pub results: Vec<PaladinResult>,
}

/// Stream chunk for progressive output
pub struct StreamChunk {
    pub content: String,
    pub is_final: bool,
}

/// Execution metadata for stream finalization
pub struct ExecutionMetadata {
    pub execution_time_ms: u64,
    pub total_tokens: u32,
}
}

Error Types

#![allow(unused)]
fn main() {
#[derive(Debug, thiserror::Error)]
pub enum HeraldError {
    #[error("Configuration error: {0}")]
    ConfigurationError(String),

    #[error("Formatting error: {0}")]
    FormattingError(String),

    #[error("Invalid result: {0}")]
    InvalidResult(String),

    #[error("Serialization error: {0}")]
    SerializationError(String),
}
}

Configuration Types

#![allow(unused)]
fn main() {
/// JSON Herald configuration
pub struct JsonHeraldConfig {
    pub pretty_print: bool,
    pub include_timestamps: bool,
}

/// Markdown Herald configuration
pub struct MarkdownHeraldConfig {
    pub use_colors: bool,
    pub heading_level: u8,
}

/// Table Herald configuration
pub struct TableHeraldConfig {
    pub max_column_width: usize,
    pub border_style: String,
}
}

Best Practices

1. Choose the Right Formatter

• JSON: APIs, logging systems, structured data stores
• Markdown: Human-readable reports, CLI tools, documentation
• Table: Terminal dashboards, comparison views, compact summaries

2. Configure Appropriately

# Development: Pretty and colorful
herald:
  default_formatter: "markdown"
  markdown:
    use_colors: true

# Production: Compact and structured
herald:
  default_formatter: "json"
  json:
    pretty_print: false

3. Handle Errors Gracefully

#![allow(unused)]
fn main() {
match service.format_result(&result, &paladin) {
    Ok(Some(formatted)) => println!("{}", formatted),
    Ok(None) => println!("Raw output: {}", result.output),
    Err(e) => eprintln!("Formatting error: {}", e),
}
}

4. Use Runtime Overrides Sparingly

#![allow(unused)]
fn main() {
// Good: Configure once
let herald = settings.create_default_herald()?;
let service = PaladinExecutionService::new(...).with_herald(herald);

// Avoid: Changing formatter for every request
// (unless truly needed for different output destinations)
}

5. Test Custom Formatters

#![allow(unused)]
fn main() {
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_custom_formatter() {
        let herald = XmlHerald;
        let result = PaladinResult {
            paladin_id: "test-1".to_string(),
            paladin_name: "TestPaladin".to_string(),
            status: "completed".to_string(),
            output: "Test output".to_string(),
        };

        let formatted = herald.format_paladin_result(&result).unwrap();
        assert!(formatted.contains("<paladin_result>"));
        assert!(formatted.contains("test-1"));
    }
}
}

Troubleshooting

Issue: Herald not formatting output

Symptoms: format_result() returns None

Solutions:

1. Verify Herald is configured: service.with_herald(herald)
2. Check that Herald is Some, not None
3. Ensure configuration is valid

Issue: Formatting fails with error

Symptoms: HeraldError::FormattingError

Solutions:

1. Check result data is valid (no null/empty required fields)
2. Verify custom formatter implementation handles edge cases
3. Review error message for specific cause

Issue: Colors not showing in Markdown

Symptoms: ANSI codes visible as text

Solutions:

1. Ensure terminal supports ANSI colors
2. Check use_colors is set to true in config
3. Use a color-capable terminal emulator

Issue: Table borders not displaying correctly

Symptoms: Broken box characters

Solutions:

1. Use UTF-8 compatible terminal
2. Switch to border_style: "ascii" for compatibility
3. Set border_style: "none" to disable borders

Examples

See the examples/ directory for complete working examples:

• herald_json_output.rs - JSON formatting
• herald_markdown_output.rs - Markdown formatting
• herald_custom_formatter.rs - XML/CSV custom formatters
• herald_streaming.rs - Streaming formatters
• basic_paladin.rs - Updated with Herald usage

Further Reading

• Design and Architecture - Overall system architecture
• Battalion Documentation - Multi-agent orchestration
• Garrison Documentation - Memory system
• Arsenal Documentation - Tool integration
• Hexagonal Architecture - Architectural pattern

Questions or Issues? See CONTRIBUTING.md or open an issue on GitHub.

Maneuver: Flow DSL Orchestration

Declarative multi-agent workflows with dynamic execution patterns

Table of Contents

1. Overview
2. Quick Start
3. Flow DSL Syntax
4. Execution Patterns
5. Configuration
6. CLI Commands
7. Visualization
8. Error Handling
9. Performance
10. Best Practices
11. API Reference
12. Troubleshooting

Overview

Maneuver is a declarative Battalion orchestration pattern that uses a Flow DSL (Domain-Specific Language) to define complex agent execution patterns. Unlike other Battalion patterns that require explicit code, Maneuver allows you to express workflows as simple text expressions.

Key Features

• Declarative Syntax: Define workflows as text expressions (agent1 -> agent2)
• Mixed Patterns: Combine sequential and parallel execution in a single flow
• Visual Feedback: ASCII and Mermaid.js visualization of flow graphs
• Type-Safe Parsing: Compile-time validation of flow expressions
• Commander Integration: Automatic pattern detection for "flow" keywords

Comparison with Other Patterns

Quick Start

Installation

Maneuver is included in Paladin core. Ensure you have version 0.1.0+:

[dependencies]
paladin = "0.1.0"
tokio = { version = "1.0", features = ["full"] }

Basic Example

use paladin::application::services::battalion::maneuver_service::ManeuverExecutionService;
use paladin::core::platform::container::battalion::maneuver::Maneuver;
use paladin::core::platform::container::battalion::parser::FlowParser;
use std::collections::HashMap;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Define flow using DSL
    let flow = FlowParser::parse("analyzer -> summarizer -> reviewer")?;

    // Create Paladins
    let mut agents = HashMap::new();
    agents.insert("analyzer".to_string(), create_paladin("analyzer", "Analyze input"));
    agents.insert("summarizer".to_string(), create_paladin("summarizer", "Summarize"));
    agents.insert("reviewer".to_string(), create_paladin("reviewer", "Final review"));

    // Create Maneuver
    let maneuver = Maneuver::new("doc-workflow", agents, flow, Default::default())?;

    // Execute
    let service = ManeuverExecutionService::new(Arc::new(paladin_port));
    let result = service.execute(&maneuver, "Document to process").await?;

    println!("Final output: {}", result.final_output);
    Ok(())
}

CLI Quick Start

# Create a Maneuver configuration
paladin battalion new my-workflow --type maneuver -o workflow.yaml

# Visualize the flow
paladin maneuver visualize -c workflow.yaml --format ascii

# Validate configuration
paladin maneuver validate -c workflow.yaml --verbose

# Execute the workflow
paladin battalion run -c workflow.yaml -t maneuver -i "Process this input"

Flow DSL Syntax

The Flow DSL uses a simple, intuitive syntax for defining agent execution patterns.

Basic Syntax

Sequential Execution

agent1 -> agent2 -> agent3

Output from agent1 flows as input to agent2, then to agent3.

Parallel Execution

(agent1, agent2)

Both agent1 and agent2 execute concurrently with the same input.

Note: Use commas (,) for parallel, not pipes (|).

Nested Patterns

agent1 -> (agent2, agent3) -> agent4

1. agent1 executes first
2. Output flows to both agent2 and agent3 (parallel)
3. Combined output flows to agent4

Syntax Rules

Valid Examples

# Simple sequential
agent1 -> agent2

# Simple parallel
(agent1, agent2)

# Mixed nested
start -> (analyzer, reviewer) -> end

# Complex workflow
intake -> (technical, business, security) -> synthesis -> review

# Deep nesting
a -> (b -> (c, d), e) -> f

Invalid Syntax

# ❌ Pipe operator (use comma instead)
(agent1 | agent2)

# ❌ Missing parentheses for parallel
agent1 -> agent2, agent3

# ❌ Spaces in agent names
my agent -> another agent

# ❌ Empty groups
() -> agent1

# ❌ Trailing operators
agent1 ->

Execution Patterns

Sequential Pattern

Flow: agent1 -> agent2 -> agent3

Behavior:

1. Execute agent1 with initial input
2. Pass agent1 output to agent2 as input
3. Pass agent2 output to agent3 as input
4. Return agent3 output as final result

Use Cases:

• Data transformation pipelines
• Multi-stage analysis
• Progressive refinement

Example:

#![allow(unused)]
fn main() {
// Flow: "extractor -> translator -> formatter"
let flow = FlowParser::parse("extractor -> translator -> formatter")?;

// Input: "Extract data from: <raw_text>"
// extractor output: "Data: {...}"
// translator output: "Translated: {...}"  
// formatter output: "Formatted report: {...}" (final)
}

Parallel Pattern

Flow: (agent1, agent2, agent3)

Behavior:

1. Execute all agents concurrently with same input
2. Wait for all to complete
3. Combine outputs (concatenation or custom logic)
4. Return combined result

Use Cases:

• Multi-perspective analysis
• Expert panel reviews
• Parallel processing

Example:

#![allow(unused)]
fn main() {
// Flow: "(tech_reviewer, business_reviewer, security_reviewer)"
let flow = FlowParser::parse("(tech_reviewer, business_reviewer, security_reviewer)")?;

// All receive: "Review this proposal: {...}"
// Output combines all three perspectives
}

Nested Pattern

Flow: agent1 -> (agent2, agent3) -> agent4

Behavior:

1. Execute agent1 with initial input
2. Pass output to both agent2 and agent3 (parallel)
3. Wait for both to complete
4. Combine their outputs
5. Pass combined result to agent4
6. Return agent4 output as final result

Use Cases:

• Divide-and-conquer workflows
• Multi-faceted analysis with synthesis
• Complex decision trees

Example:

#![allow(unused)]
fn main() {
// Flow: "analyzer -> (summarizer, translator) -> reviewer"
let flow = FlowParser::parse("analyzer -> (summarizer, translator) -> reviewer")?;

// 1. analyzer processes input
// 2. summarizer + translator work in parallel on analysis
// 3. reviewer synthesizes both outputs into final result
}

Execution Order Visualization

Sequential: agent1 → agent2 → agent3
           t₀      t₁      t₂

Parallel:   agent1
           ↙      ↘
       agent2    agent3
           ↘      ↙
         (combine)

Nested:     agent1
              ↓
          ┌───┴───┐
      agent2   agent3
          └───┬───┘
           agent4

Configuration

Maneuver Configuration

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::maneuver::{
    ManeuverConfig, ErrorStrategy, OutputFormat
};
use std::time::Duration;

let config = ManeuverConfig::new()
    .with_error_strategy(ErrorStrategy::ContinueOnError)
    .with_output_format(OutputFormat::Concatenate)
    .with_pass_output_as_input(true)
    .with_timeout(Duration::from_secs(300))
    .with_collect_timing_metrics(true);

let maneuver = Maneuver::new("workflow", agents, flow, config)?;
}

Error Strategies

#![allow(unused)]
fn main() {
pub enum ErrorStrategy {
    /// Stop immediately on first error
    FailFast,

    /// Continue executing remaining agents despite errors
    ContinueOnError,

    /// Continue on error in parallel branches only
    ContinueParallel,
}
}

When to Use:

• FailFast: Critical workflows where any failure invalidates the result
• ContinueOnError: Best-effort workflows, collect partial results
• ContinueParallel: Parallel sections can fail independently

Output Formats

#![allow(unused)]
fn main() {
pub enum OutputFormat {
    /// Concatenate all outputs with newlines
    Concatenate,

    /// JSON object with agent names as keys
    Json,

    /// Last agent's output only
    LastOnly,
}
}

Example Outputs:

#![allow(unused)]
fn main() {
// Concatenate (default)
"Output from agent1\n---\nOutput from agent2\n---\nOutput from agent3"

// Json
r#"{"agent1": "...", "agent2": "...", "agent3": "..."}"#

// LastOnly
"Output from agent3"  // Only the final agent
}

YAML Configuration

type: maneuver
name: "document-workflow"

# Flow expression using DSL
flow: "analyzer -> (summarizer, translator) -> reviewer"

# Available Paladins (must match names in flow)
paladins:
  - inline:
      name: "analyzer"
      system_prompt: "Analyze the input document"
      model: "gpt-4"
      temperature: 0.7
      provider:
        type: openai

  - inline:
      name: "summarizer"
      system_prompt: "Create a concise summary"
      model: "gpt-4"
      temperature: 0.5
      provider:
        type: openai

  - inline:
      name: "translator"
      system_prompt: "Translate to simple language"
      model: "gpt-4"
      temperature: 0.5
      provider:
        type: openai

  - inline:
      name: "reviewer"
      system_prompt: "Final review and synthesis"
      model: "gpt-4"
      temperature: 0.6
      provider:
        type: openai

# Optional: visualize before execution
visualize: "ascii"

CLI Commands

Create Maneuver Configuration

paladin battalion new my-workflow --type maneuver --output workflow.yaml

Creates a template YAML file with example flow and agents.

Visualize Flow

# ASCII tree visualization
paladin maneuver visualize -c workflow.yaml --format ascii

# Mermaid flowchart (for documentation)
paladin maneuver visualize -c workflow.yaml --format mermaid

# Save to file
paladin maneuver visualize -c workflow.yaml --format ascii -o flow.txt

Output Example (ASCII):

└─> analyzer
    ├─> [PARALLEL]
    │   ├─> summarizer
    │   └─> translator
    └─> reviewer

Output Example (Mermaid):

flowchart LR
    agent_analyzer
    agent_analyzer --> parallel_1[Parallel]
    parallel_1 --> agent_summarizer
    parallel_1 --> agent_translator
    parallel_1 --> agent_reviewer

Validate Configuration

# Basic validation
paladin maneuver validate -c workflow.yaml

# Verbose validation with detailed output
paladin maneuver validate -c workflow.yaml --verbose

Validates:

• Flow expression syntax
• All agents referenced in flow exist in config
• Paladin configuration structure
• Provider settings

Execute Maneuver

# Interactive execution
paladin battalion run -c workflow.yaml -t maneuver

# With input provided
paladin battalion run -c workflow.yaml -t maneuver -i "Process this text"

# Save output to file
paladin battalion run -c workflow.yaml -t maneuver -i "Input" -o result.json

# Verbose execution
paladin battalion run -c workflow.yaml -t maneuver -v

Visualization

ASCII Tree Format

Perfect for terminal output and debugging:

└─> intake
    ├─> [PARALLEL]
    │   ├─> technical
    │   ├─> business
    │   └─> security
    └─> synthesis
        └─> review

Features:

• Box-drawing characters (├─>, └─>, │)
• Clear hierarchy visualization
• Sequential and parallel markers
• Nested structure representation

Mermaid Flowchart Format

Ideal for documentation and presentations:

flowchart LR
    agent_intake
    agent_intake --> parallel_1[Parallel]
    parallel_1 --> agent_technical
    parallel_1 --> agent_business
    parallel_1 --> agent_security
    parallel_1 --> agent_synthesis
    agent_synthesis --> agent_review

Features:

• Web-ready visualization
• Integrates with GitHub/GitLab/documentation tools
• Professional diagram quality
• Exportable to SVG/PNG

Programmatic Visualization

#![allow(unused)]
fn main() {
use paladin::application::services::battalion::flow_visualizer::{
    FlowVisualizer, VisualizationFormat
};

let flow = FlowParser::parse("a -> (b, c) -> d")?;

// ASCII visualization
let ascii = FlowVisualizer::to_ascii(&flow);
println!("{}", ascii);

// Mermaid visualization
let mermaid = FlowVisualizer::to_mermaid(&flow);
println!("{}", mermaid);

// Using format parameter
let viz = FlowVisualizer::visualize(&flow, VisualizationFormat::Ascii);
}

Error Handling

Validation Errors

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::parser::FlowParseError;

match FlowParser::parse("agent1 -> (agent2 | agent3)") {
    Ok(flow) => { /* Success */ },
    Err(FlowParseError::InvalidCharacter { position, character }) => {
        eprintln!("Invalid character '{}' at position {}", character, position);
        // Error: Invalid character '|' at position 17
    },
    Err(e) => eprintln!("Parse error: {}", e),
}
}

Execution Errors

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::maneuver::ManeuverError;

match service.execute(&maneuver, input).await {
    Ok(result) => println!("Success: {}", result.final_output),
    Err(ManeuverError::AgentNotFound(name)) => {
        eprintln!("Agent '{}' not found in configuration", name);
    },
    Err(ManeuverError::ExecutionError(msg)) => {
        eprintln!("Execution failed: {}", msg);
    },
    Err(e) => eprintln!("Error: {}", e),
}
}

Error Recovery

#![allow(unused)]
fn main() {
// Configure error handling strategy
let config = ManeuverConfig::new()
    .with_error_strategy(ErrorStrategy::ContinueOnError);

// Execution continues despite failures
let result = service.execute(&maneuver, input).await?;

// Check status
match result.status {
    ExecutionStatus::Success => println!("All agents succeeded"),
    ExecutionStatus::PartialSuccess => println!("Some agents failed"),
    ExecutionStatus::Failed => println!("Execution failed"),
}

// Inspect individual outputs
for (agent, output) in result.step_outputs {
    if output.is_empty() {
        println!("Agent {} failed", agent);
    }
}
}

Performance

Benchmarks

Based on battalion_benchmarks.rs:

Optimization Tips

1. Minimize Sequential Chains

❌ Slow: a -> b -> c -> d -> e -> f (6 sequential calls)

✅ Fast: a -> (b, c, d) -> e (3 stages total)

2. Use Parallel Where Possible

#![allow(unused)]
fn main() {
// Slow: Sequential when order doesn't matter
"tech_review -> security_review -> legal_review"

// Fast: Parallel independent reviews
"(tech_review, security_review, legal_review)"
}

3. Configure Timeouts

#![allow(unused)]
fn main() {
let config = ManeuverConfig::new()
    .with_timeout(Duration::from_secs(120))  // Per-agent timeout
    .with_error_strategy(ErrorStrategy::ContinueParallel);  // Don't wait for failures
}

4. Optimize Agent Prompts

• Keep system prompts concise
• Use lower max_loops values when possible
• Set appropriate temperature values

5. Monitor Timing Metrics

#![allow(unused)]
fn main() {
let config = ManeuverConfig::new()
    .with_collect_timing_metrics(true);

let result = service.execute(&maneuver, input).await?;

if let Some(metrics) = result.timing_metrics {
    for (agent, duration) in metrics {
        println!("{}: {}ms", agent, duration.as_millis());
    }
}
}

Best Practices

1. Flow Design

Keep Flows Simple

#![allow(unused)]
fn main() {
// ✅ Good: Clear, easy to understand
"intake -> analyze -> decide"

// ❌ Bad: Too complex, hard to debug
"a -> (b -> (c, d -> (e, f)), g -> (h, i)) -> j"
}

Use Descriptive Names

#![allow(unused)]
fn main() {
// ✅ Good: Clear purpose
"document_analyzer -> sentiment_classifier -> report_generator"

// ❌ Bad: Cryptic names
"agent1 -> agent2 -> agent3"
}

2. Agent Configuration

Specialize Agents

Each agent should have a clear, focused responsibility:

- name: "analyzer"
  system_prompt: "Analyze technical feasibility only. Focus on implementation challenges."

- name: "risk_assessor"  
  system_prompt: "Assess security and privacy risks only."

- name: "synthesizer"
  system_prompt: "Combine technical analysis and risk assessment into recommendation."

Use Consistent Naming

Match agent names in flow expression exactly:

#![allow(unused)]
fn main() {
// Flow uses: analyzer, summarizer, reviewer
flow: "analyzer -> summarizer -> reviewer"

// Paladins must use same names:
agents.insert("analyzer", ...);
agents.insert("summarizer", ...);
agents.insert("reviewer", ...);
}

3. Error Handling

Always Handle Errors

#![allow(unused)]
fn main() {
// ✅ Good: Explicit error handling
match service.execute(&maneuver, input).await {
    Ok(result) => process_result(result),
    Err(ManeuverError::AgentNotFound(name)) => {
        log_error!("Missing agent: {}", name);
        return default_result();
    },
    Err(e) => {
        log_error!("Execution failed: {}", e);
        retry_with_fallback();
    },
}

// ❌ Bad: Unwrapping
let result = service.execute(&maneuver, input).await.unwrap();
}

Choose Appropriate Strategy

#![allow(unused)]
fn main() {
// Critical workflows: fail fast
let config = ManeuverConfig::new()
    .with_error_strategy(ErrorStrategy::FailFast);

// Best-effort workflows: collect partial results
let config = ManeuverConfig::new()
    .with_error_strategy(ErrorStrategy::ContinueOnError);
}

4. Testing

Validate Flows Early

#![allow(unused)]
fn main() {
#[test]
fn test_workflow_validation() {
    let flow = FlowParser::parse("analyzer -> summarizer").unwrap();

    let mut agents = HashMap::new();
    agents.insert("analyzer".to_string(), create_test_agent("analyzer"));
    agents.insert("summarizer".to_string(), create_test_agent("summarizer"));

    let result = Maneuver::new("test", agents, flow, Default::default());
    assert!(result.is_ok());
}
}

Test Visualizations

#![allow(unused)]
fn main() {
#[test]
fn test_flow_visualization() {
    let flow = FlowParser::parse("a -> (b, c)").unwrap();
    let ascii = FlowVisualizer::to_ascii(&flow);

    assert!(ascii.contains("PARALLEL"));
    assert!(ascii.contains("a"));
    assert!(ascii.contains("b"));
    assert!(ascii.contains("c"));
}
}

5. Documentation

Document Complex Flows

# Flow explanation:
# 1. Intake agent validates and normalizes input
# 2. Three specialists analyze in parallel:
#    - Technical feasibility
#    - Business value
#    - Security implications
# 3. Synthesis agent combines all perspectives
# 4. Final review for quality assurance
flow: "intake -> (technical, business, security) -> synthesis -> review"

API Reference

Core Types

FlowParser

#![allow(unused)]
fn main() {
pub struct FlowParser;

impl FlowParser {
    /// Parse a flow expression from text
    pub fn parse(input: &str) -> Result<FlowExpression, FlowParseError>
}
}

FlowExpression

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FlowExpression {
    /// Single agent execution
    Agent(String),

    /// Sequential execution (agent₁ → agent₂ → ...)
    Sequential(Vec<FlowExpression>),

    /// Parallel execution (agent₁, agent₂, ...)
    Parallel(Vec<FlowExpression>),
}

impl FlowExpression {
    /// Get all agent names referenced in this expression
    pub fn agent_names(&self) -> Vec<String>
}
}

Maneuver

#![allow(unused)]
fn main() {
pub struct Maneuver {
    pub name: String,
    pub agents: HashMap<String, Paladin>,
    pub flow: FlowExpression,
    pub config: ManeuverConfig,
}

impl Maneuver {
    /// Create a new Maneuver with validation
    pub fn new(
        name: impl Into<String>,
        agents: HashMap<String, Paladin>,
        flow: FlowExpression,
        config: ManeuverConfig,
    ) -> Result<Self, ManeuverError>

    /// Validate that all flow agents exist
    pub fn validate(&self) -> Result<(), ManeuverError>
}
}

ManeuverConfig

#![allow(unused)]
fn main() {
pub struct ManeuverConfig {
    pub error_strategy: ErrorStrategy,
    pub output_format: OutputFormat,
    pub pass_output_as_input: bool,
    pub timeout: Option<Duration>,
    pub collect_timing_metrics: bool,
    pub detailed_observability: bool,
}

impl ManeuverConfig {
    pub fn new() -> Self
    pub fn with_error_strategy(self, strategy: ErrorStrategy) -> Self
    pub fn with_output_format(self, format: OutputFormat) -> Self
    pub fn with_timeout(self, timeout: Duration) -> Self
}
}

ManeuverResult

#![allow(unused)]
fn main() {
pub struct ManeuverResult {
    /// Final aggregated output
    pub final_output: String,

    /// Individual agent outputs
    pub step_outputs: HashMap<String, String>,

    /// Execution order
    pub execution_order: Vec<String>,

    /// Per-agent timing (if enabled)
    pub timing_metrics: Option<HashMap<String, Duration>>,

    /// Execution status
    pub status: ExecutionStatus,
}
}

ManeuverExecutionService

#![allow(unused)]
fn main() {
pub struct ManeuverExecutionService {
    paladin_port: Arc<dyn PaladinPort>,
}

impl ManeuverExecutionService {
    pub fn new(paladin_port: Arc<dyn PaladinPort>) -> Self

    pub async fn execute(
        &self,
        maneuver: &Maneuver,
        input: &str,
    ) -> Result<ManeuverResult, ManeuverError>
}
}

Visualization

FlowVisualizer

#![allow(unused)]
fn main() {
pub struct FlowVisualizer;

impl FlowVisualizer {
    /// Generate ASCII tree visualization
    pub fn to_ascii(flow: &FlowExpression) -> String

    /// Generate Mermaid flowchart
    pub fn to_mermaid(flow: &FlowExpression) -> String

    /// Generate visualization in specified format
    pub fn visualize(flow: &FlowExpression, format: VisualizationFormat) -> String
}

pub enum VisualizationFormat {
    Ascii,
    Mermaid,
}
}

Troubleshooting

Common Issues

1. Parse Error: Invalid Character '|'

Problem: Using pipe operator for parallel execution

#![allow(unused)]
fn main() {
// ❌ Wrong
let flow = FlowParser::parse("(agent1 | agent2)")?;
}

Solution: Use comma instead

#![allow(unused)]
fn main() {
// ✅ Correct
let flow = FlowParser::parse("(agent1, agent2)")?;
}

2. AgentNotFound Error

Problem: Agent name in flow doesn't match configured agents

#![allow(unused)]
fn main() {
// Flow references "analyzer"
let flow = FlowParser::parse("analyzer -> summarizer")?;

// But agent is named "Analyzer" (different case)
agents.insert("Analyzer".to_string(), paladin);
}

Solution: Use exact same names

#![allow(unused)]
fn main() {
// ✅ Correct - exact match
agents.insert("analyzer".to_string(), paladin);
}

3. Missing Parentheses for Parallel

Problem: Forgetting parentheses around parallel agents

#![allow(unused)]
fn main() {
// ❌ Wrong - will be parsed as "agent1 -> agent2", "agent3"
let flow = FlowParser::parse("agent1 -> agent2, agent3")?;
}

Solution: Always use parentheses for parallel

#![allow(unused)]
fn main() {
// ✅ Correct
let flow = FlowParser::parse("agent1 -> (agent2, agent3)")?;
}

4. Timeout Errors

Problem: Agents taking too long to execute

#![allow(unused)]
fn main() {
// Default timeout may be too short
let config = ManeuverConfig::default();  // 300s default
}

Solution: Increase timeout for slow workflows

#![allow(unused)]
fn main() {
// ✅ Longer timeout
let config = ManeuverConfig::new()
    .with_timeout(Duration::from_secs(600));  // 10 minutes
}

5. Partial Results from Parallel Execution

Problem: Some agents fail in parallel execution

Solution: Use appropriate error strategy

#![allow(unused)]
fn main() {
// Continue despite failures
let config = ManeuverConfig::new()
    .with_error_strategy(ErrorStrategy::ContinueParallel);

let result = service.execute(&maneuver, input).await?;

// Check which agents succeeded
for (agent, output) in result.step_outputs {
    if !output.is_empty() {
        println!("{} succeeded: {}", agent, output);
    }
}
}

Debugging Tips

1. Enable Verbose Logging

#![allow(unused)]
fn main() {
env_logger::init();  // In main()

// Set RUST_LOG=debug
// Will show detailed execution trace
}

2. Visualize Before Executing

paladin maneuver visualize -c config.yaml --format ascii

Visual inspection often reveals flow logic issues.

3. Validate Configuration

paladin maneuver validate -c config.yaml --verbose

Catches configuration mismatches before execution.

4. Check Timing Metrics

#![allow(unused)]
fn main() {
let config = ManeuverConfig::new()
    .with_collect_timing_metrics(true);

let result = service.execute(&maneuver, input).await?;

if let Some(metrics) = result.timing_metrics {
    for (agent, duration) in metrics {
        if duration > Duration::from_secs(60) {
            println!("⚠️  {} took {}s", agent, duration.as_secs());
        }
    }
}
}

5. Inspect Individual Outputs

#![allow(unused)]
fn main() {
let result = service.execute(&maneuver, input).await?;

// Check each agent's output
for agent in result.execution_order {
    if let Some(output) = result.step_outputs.get(&agent) {
        println!("\n=== {} ===", agent);
        println!("{}", output);
    }
}
}

Getting Help

• Documentation: https://github.com/DF3NDR/paladin-dev-env/docs
• Issues: https://github.com/DF3NDR/paladin-dev-env/issues
• Discussions: https://github.com/DF3NDR/paladin-dev-env/discussions
• Examples: examples/ directory in repository

Advanced Topics

Custom Output Formatting

#![allow(unused)]
fn main() {
use paladin::core::platform::container::battalion::maneuver::OutputFormat;

// Implement custom aggregation logic
let config = ManeuverConfig::new()
    .with_output_format(OutputFormat::Json);

// Result will be JSON:
// {"agent1": "output1", "agent2": "output2"}
}

Integration with Commander

Commander automatically detects Maneuver patterns:

#![allow(unused)]
fn main() {
use paladin::application::services::battalion::commander::Commander;

let commander = Commander::new(paladin_port)
    .with_strategy(BattalionStrategy::Auto)
    .with_paladins(paladins)
    .build()?;

// These inputs trigger Maneuver:
// - "Create a flow for..."
// - "Execute: agent1 -> agent2"
// - "Dynamic flow orchestration"
// - Any input containing "->" or "," operators
}

Performance Tuning

For high-throughput systems:

#![allow(unused)]
fn main() {
// Minimize overhead
let config = ManeuverConfig::new()
    .with_collect_timing_metrics(false)  // Disable if not needed
    .with_detailed_observability(false)  // Reduce logging
    .with_error_strategy(ErrorStrategy::FailFast);  // Fast failure

// Use connection pooling for LLM providers
// Pre-validate flows at startup
// Cache parsed flow expressions
}

Last Updated: February 2026
Version: 0.1.0
Status: Production Ready

Paladin Configuration Guide

This guide covers how to configure Paladin agents for optimal performance, from basic setup to advanced tuning.

Table of Contents

• Basic Configuration
• System Prompt Best Practices
• Model Selection
• Temperature and Sampling
• Stop Words and Termination
• Timeout and Retry Settings
• Advanced Configuration

Basic Configuration

Minimal Setup

#![allow(unused)]
fn main() {
use paladin::prelude::*;

let paladin = PaladinBuilder::new(llm_adapter)
    .name("Assistant")
    .system_prompt("You are a helpful assistant.")
    .build()?;
}

Common Configuration

#![allow(unused)]
fn main() {
let paladin = PaladinBuilder::new(llm_adapter)
    .name("DataAnalyst")
    .system_prompt("You are an expert data analyst. Provide clear, data-driven insights.")
    .model("gpt-4")
    .temperature(0.7)
    .max_loops(5)
    .timeout(Duration::from_secs(120))
    .build()?;
}

Full Configuration

#![allow(unused)]
fn main() {
let paladin = PaladinBuilder::new(llm_adapter)
    .name("ResearchAssistant")
    .system_prompt("You are a research assistant specializing in academic papers.")
    .user_name("Researcher")
    .model("gpt-4-turbo")
    .temperature(0.8)
    .max_loops(10)
    .stop_words(vec!["END", "STOP", "FINAL_ANSWER"])
    .timeout(Duration::from_secs(300))
    .retry_attempts(3)
    .retry_delay(Duration::from_secs(5))
    .with_garrison(garrison)
    .add_armament(search_tool)
    .add_armament(calculator_tool)
    .build()?;
}

System Prompt Best Practices

The system prompt defines your Paladin's behavior and capabilities. Follow these best practices:

1. Be Specific About Role

❌ Vague:

#![allow(unused)]
fn main() {
.system_prompt("You are helpful.")
}

✅ Specific:

#![allow(unused)]
fn main() {
.system_prompt("You are a senior software engineer specializing in Rust. \
                You provide code reviews focused on safety, performance, and idiomatic patterns.")
}

2. Define Output Format

#![allow(unused)]
fn main() {
.system_prompt("You are a JSON API. Always respond with valid JSON. \
                Structure: {\"status\": \"success|error\", \"data\": {...}, \"message\": \"...\"}  \
                Never include markdown code blocks or explanations outside the JSON.")
}

3. Set Boundaries

#![allow(unused)]
fn main() {
.system_prompt("You are a customer support agent for TechCorp. \
                - Only answer questions about our products and services \
                - Escalate billing questions to the finance team \
                - Do not provide medical, legal, or financial advice \
                - Be polite and professional at all times")
}

4. Include Examples (Few-Shot)

#![allow(unused)]
fn main() {
.system_prompt("You categorize customer feedback as: FEATURE_REQUEST, BUG_REPORT, or PRAISE. \
                \
                Examples: \
                Input: 'The app crashes when I upload large files' \
                Output: BUG_REPORT \
                \
                Input: 'It would be great to have dark mode' \
                Output: FEATURE_REQUEST \
                \
                Input: 'Love the new design!' \
                Output: PRAISE")
}

5. Specify Tone and Style

#![allow(unused)]
fn main() {
.system_prompt("You are a technical writer creating documentation for developers. \
                - Use clear, concise language \
                - Prefer active voice \
                - Include code examples \
                - Target audience: junior to mid-level developers \
                - Avoid jargon unless necessary")
}

Model Selection

Choose the right model for your use case:

OpenAI Models

#![allow(unused)]
fn main() {
// GPT-4 Turbo - Best for complex reasoning
.model("gpt-4-turbo")  // Latest turbo model
.model("gpt-4")        // Standard GPT-4

// GPT-3.5 - Fast and cost-effective
.model("gpt-3.5-turbo")  // Recommended for most tasks
}

When to use:

• GPT-4: Complex reasoning, code generation, detailed analysis
• GPT-3.5: Simple queries, classification, summarization

DeepSeek Models

#![allow(unused)]
fn main() {
// DeepSeek Chat - Strong coding capabilities
.model("deepseek-chat")

// DeepSeek Coder - Specialized for code
.model("deepseek-coder")
}

When to use:

• deepseek-chat: General purpose, good for multi-turn conversations
• deepseek-coder: Code generation, technical documentation

Anthropic Models

#![allow(unused)]
fn main() {
// Claude 3 Family
.model("claude-3-opus")    // Most capable
.model("claude-3-sonnet")  // Balanced
.model("claude-3-haiku")   // Fastest
}

When to use:

• Opus: Complex analysis, long documents, creative writing
• Sonnet: General purpose, good balance of speed and quality
• Haiku: Fast responses, simple queries, high throughput

Model Comparison

Temperature and Sampling

Temperature controls randomness in responses:

Temperature Scale

#![allow(unused)]
fn main() {
// 0.0 - Deterministic, focused (best for factual tasks)
.temperature(0.0)

// 0.3-0.5 - Slightly varied (good for classification)
.temperature(0.4)

// 0.7 - Balanced (general purpose)
.temperature(0.7)

// 0.9-1.0 - Creative, diverse (brainstorming, creative writing)
.temperature(0.9)

// >1.0 - Very random (experimental, not recommended)
.temperature(1.2)
}

Use Cases by Temperature

Example: Task-Specific Configuration

#![allow(unused)]
fn main() {
// Code Review - Deterministic
let code_reviewer = PaladinBuilder::new(llm_adapter)
    .system_prompt("Review Rust code for safety and best practices.")
    .temperature(0.2)
    .build()?;

// Content Writer - Creative
let writer = PaladinBuilder::new(llm_adapter)
    .system_prompt("Write engaging blog posts about technology.")
    .temperature(0.9)
    .build()?;

// Customer Support - Balanced
let support = PaladinBuilder::new(llm_adapter)
    .system_prompt("Help customers with product questions.")
    .temperature(0.7)
    .build()?;
}

Stop Words and Termination

Control when a Paladin stops generating:

Basic Stop Words

#![allow(unused)]
fn main() {
let paladin = PaladinBuilder::new(llm_adapter)
    .stop_words(vec!["END", "STOP", "###"])
    .build()?;
}

Use Cases

1. Structured Output

#![allow(unused)]
fn main() {
// Stop at delimiter for parsing
.system_prompt("Generate a list of items. End with '---'")
.stop_words(vec!["---"])
}

2. Multi-Step Reasoning

#![allow(unused)]
fn main() {
// Stop when final answer is reached
.system_prompt("Think step by step. When done, output FINAL_ANSWER: <answer>")
.stop_words(vec!["FINAL_ANSWER:"])
}

3. Dialog Systems

#![allow(unused)]
fn main() {
// Stop at turn boundaries
.system_prompt("You are user A in a conversation. End each turn with [END_TURN]")
.stop_words(vec!["[END_TURN]"])
}

Max Loops

Prevent infinite reasoning loops:

#![allow(unused)]
fn main() {
// Default: 3 loops
.max_loops(3)

// For simple tasks: 1 loop
.max_loops(1)

// For complex reasoning: 10+ loops
.max_loops(15)
}

What is a loop? A loop is one reasoning cycle: prompt → LLM → response → (optional tool calls) → repeat.