Paladin Feature Flags

Paladin uses Cargo feature flags to enable fine-grained control over compiled dependencies and functionality. This allows you to build minimal, focused binaries for specific use cases while reducing compile times and binary sizes.

See also the Crate Map & Feature Flags reference for per-crate flag tables, the crate dependency graph, and copy-paste consumer profiles.

Table of Contents

• Overview
• Available Feature Flags
• Default Configuration
• Usage Examples
• Build Comparison
• Feature Dependencies
• Best Practices

Overview

Philosophy

Feature flags in Paladin follow these principles:

1. Core Framework Always Available - Paladin agents, Battalion orchestration, Garrison memory, Arsenal tools, and Herald formatters are always compiled
2. Provider Choice - Choose which of the nine LLM providers to support (OpenAI, Anthropic, DeepSeek, Kimi, Qwen, Grok, Ollama, Gemini, or the generic OpenAI-compatible adapter)
3. Subsystem Opt-In - Enable only the subsystems you need (web servers, content processing, notifications)
4. Infrastructure Selection - Pick storage/queue adapters (Redis, S3/MinIO, Qdrant)
5. Testing Flexibility - Enable integration tests only when needed

Default vs. Full

This default has not changed. The llm-* flags were rewired (see below) so each one now actually gates its adapter instead of being an inert stub, but the compiled default provider set is deliberately unchanged from before that fix — openai + anthropic + deepseek. See the [Unreleased] section of CHANGELOG.md for the fix this note refers to. No consumer action is required.

Available Feature Flags

LLM Provider Flags

Vendor base URLs and default model IDs for Kimi/Qwen/Grok/Gemini were recorded from vendor documentation but have not been verified against a live endpoint in this environment.

Subsystem Flags

Storage & Queue Flags

paladin-storage's SQLite adapters are always compiled — the facade depends on paladin-storage unconditionally with its sqlite feature enabled, so there is no storage-sqlite facade flag to opt into.

Observability & Admin Flags

Special Build Flags

CLI Flags

Build the paladin-cli binary with:

cargo build --bin paladin-cli --features cli

Testing Flags

Convenience Flags

Default Configuration

Current Default:

[dependencies]
paladin-ai = "0.10.0"

This enables:

• ✅ llm-openai - OpenAI LLM provider
• ✅ llm-anthropic - Anthropic LLM provider
• ✅ llm-deepseek - DeepSeek LLM provider
• ✅ Core framework (always available)

The six providers Phase 17 added (llm-kimi, llm-qwen, llm-grok, llm-ollama, llm-gemini, llm-openai-compatible) are not in the default set — opt in explicitly per-provider or via llm-all. See CHANGELOG.md's [Unreleased] entry: the llm-* flags were rewired to actually gate their adapters, but the compiled default provider set is unchanged from before that fix.

See migration-guide.md for migration guidance.

Usage Examples

Minimal Build (Core Only)

No external LLM providers, storage, or queues:

[dependencies]
paladin-ai = { version = "0.10.0", default-features = false }

Use case: Custom LLM integrations, library embedding, edge deployments

Single Provider Builds

OpenAI Only (default):

[dependencies]
paladin-ai = "0.10.0"
# Or explicitly:
paladin-ai = { version = "0.10.0", features = ["llm-openai"] }

Anthropic Only:

[dependencies]
paladin-ai = { version = "0.10.0", default-features = false, features = ["llm-anthropic"] }

DeepSeek Only:

[dependencies]
paladin-ai = { version = "0.10.0", default-features = false, features = ["llm-deepseek"] }

Multi-Provider Builds

All LLM Providers:

[dependencies]
paladin-ai = { version = "0.10.0", default-features = false, features = ["llm-all"] }

OpenAI + Anthropic:

[dependencies]
paladin-ai = { version = "0.10.0", default-features = false, features = ["llm-openai", "llm-anthropic"] }

Orchestration Platform Build

Agents + web API + Redis queue + S3 storage:

[dependencies]
paladin-ai = { version = "0.10.0", features = ["web-server", "redis-queue", "s3-storage"] }

Content Processing Build

Content ingestion + processing + all providers:

[dependencies]
paladin-ai = { version = "0.10.0", features = ["llm-all", "content-processing", "qdrant", "s3-storage"] }

Full Development Build

All features enabled:

[dependencies]
paladin-ai = { version = "0.10.0", features = ["full"] }

Or use the CLI:

cargo build --features full
cargo test --features full

Production API Server

Web server + notifications + OpenAI + storage:

[dependencies]
paladin-ai = { version = "0.10.0", features = ["web-server", "notifications", "redis-queue", "s3-storage"] }

Build Comparison

Binary Size Comparison

*Approximate values for release builds on x86_64 Linux. Actual values vary by system.

Compile Time Optimization

Fast iteration (core only):

cargo build --no-default-features
cargo test --lib --no-default-features

Full testing (all features):

cargo test --features full

Feature Dependencies

Dependency Tree

full
├── llm-all
│   ├── llm-openai
│   ├── llm-anthropic
│   ├── llm-deepseek
│   ├── llm-kimi
│   ├── llm-qwen
│   ├── llm-grok
│   ├── llm-ollama
│   ├── llm-gemini
│   └── llm-openai-compatible
├── content-processing
│   ├── pdf-extract
│   ├── scraper
│   ├── tiktoken-rs
│   └── rss
├── web-server
│   ├── actix-web
│   └── axum
├── notifications
│   ├── lettre
│   └── handlebars
├── vision
├── redis-queue
│   └── redis
├── s3-storage
│   └── rust-s3
├── openai-embeddings
└── qdrant
    └── qdrant-client

Conditional Compilation Examples

In Your Code:

// Always available (core framework)
use paladin::core::platform::container::paladin::Paladin;
use paladin::application::services::paladin::paladin_builder::PaladinBuilder;

// Conditionally compiled — the LLM adapters live in the paladin_llm crate;
// the facade kept no shim for the old, now-removed infrastructure-adapter module path.
#[cfg(feature = "llm-openai")]
use paladin_llm::openai::OpenAIAdapter;

#[cfg(feature = "redis-queue")]
use paladin::infrastructure::adapters::queue::redis::RedisQueueAdapter;

#[cfg(feature = "web-server")]
use paladin::infrastructure::web::server::start_web_server;

Best Practices

1. Start Minimal, Add as Needed

Begin with default features, add others only when required:

# Start here
[dependencies]
paladin-ai = "0.10.0"

# Add features as needed
paladin-ai = { version = "0.10.0", features = ["redis-queue"] }

2. Use full for Development Only

Enable all features during development, but specify exact features for production:

[dependencies]
# Production - explicit features
paladin-ai = { version = "0.10.0", features = ["llm-anthropic", "s3-storage"] }

[dev-dependencies]
# Development - all features
paladin-ai = { version = "0.10.0", features = ["full"] }

3. Document Feature Requirements

If your application requires specific features, document them:

//! # Example Application
//!
//! **Required Features:**
//! ```toml
//! paladin-ai = { version = "0.10.0", features = ["llm-openai", "redis-queue", "s3-storage"] }
//! ```

4. Test with Multiple Feature Combinations

Use CI to test critical combinations:

# .github/workflows/ci.yml
strategy:
  matrix:
    features:
      - "--no-default-features"
      - ""  # default
      - "--features full"

See .github/workflows/ for Paladin's complete feature matrix testing.

5. Feature-Gate Examples

Add feature requirements to example documentation:

//! # Redis Queue Example
//!
//! **Required Cargo Features:**
//! ```toml
//! paladin-ai = { version = "0.10.0", features = ["redis-queue"] }
//! ```
//!
//! Run with: `cargo run --example redis_queue --features redis-queue`

Migration Guide

If you're upgrading from a version before the feature flag reorganization, see migration-guide.md for detailed migration instructions.

CI/CD Integration

GitHub Actions

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        features:
          - ""                              # default
          - "--no-default-features"         # core only
          - "--features full"               # all features
          - "--features llm-anthropic"      # specific provider
    steps:
      - uses: actions/checkout@v4
      - uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Test
        run: cargo test ${{ matrix.features }}

Docker Multi-Stage Builds

# Builder with only needed features. Base image kept in sync with the real
# builder stage in `Dockerfile` — see that file for the authoritative pin.
FROM rust:1.93-slim-bookworm as builder
WORKDIR /app
COPY . .
RUN cargo build --release --features "llm-openai,redis-queue,s3-storage"

# Runtime image
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/paladin /usr/local/bin/
CMD ["paladin"]

Support

For issues or questions about feature flags:

• Documentation: Configuration Guide
• Migration: Migration Guide
• Issues: GitHub Issues
• Discussions: GitHub Discussions