Configuration Reference

December 14, 2025 · View on GitHub

Complete reference for all configuration options in CHUK Tool Processor.

Table of Contents

ToolProcessor Configuration

All configuration options for the ToolProcessor class.

ParameterTypeDefaultDescription
strategyExecutionStrategyInProcessStrategy()Execution strategy (InProcess or Subprocess)
default_timeoutfloat30.0Default timeout for tool execution (seconds)
max_concurrencyint10Maximum concurrent tool executions
enable_cachingboolTrueEnable result caching
cache_ttlint300Cache time-to-live (seconds)
enable_rate_limitingboolFalseEnable rate limiting
global_rate_limitint | NoneNoneGlobal rate limit (requests/minute)
tool_rate_limitsdict[str, tuple[int, int]] | NoneNonePer-tool rate limits: {"tool_name": (max_requests, window_seconds)}
enable_retriesboolTrueEnable automatic retries on failure
max_retriesint3Maximum retry attempts
retry_delayfloat1.0Initial retry delay (seconds)
retry_backofffloat2.0Exponential backoff multiplier
enable_circuit_breakerboolFalseEnable circuit breaker pattern
circuit_breaker_thresholdint5Failures before circuit opens
circuit_breaker_timeoutfloat60.0Circuit reset timeout (seconds)

Example: Basic Configuration

from chuk_tool_processor.core.processor import ToolProcessor

processor = ToolProcessor(
    default_timeout=30.0,
    max_concurrency=20,
    enable_caching=True,
    cache_ttl=600
)

Example: Production Configuration

processor = ToolProcessor(
    # Execution
    default_timeout=30.0,
    max_concurrency=20,

    # Caching
    enable_caching=True,
    cache_ttl=600,  # 10 minutes

    # Rate Limiting
    enable_rate_limiting=True,
    global_rate_limit=100,  # 100 req/min globally
    tool_rate_limits={
        "expensive_api": (10, 60),  # 10 requests per minute
        "local_tool": (1000, 60)    # 1000 requests per minute
    },

    # Retries
    enable_retries=True,
    max_retries=3,
    retry_delay=1.0,
    retry_backoff=2.0,

    # Circuit Breaker
    enable_circuit_breaker=True,
    circuit_breaker_threshold=5,
    circuit_breaker_timeout=60.0
)

Timeout Configuration

Unified timeout configuration for MCP transports and StreamManager.

CategoryDefaultUsed For
connect30.0sConnection establishment, initialization, session discovery
operation30.0sNormal operations (tool calls, listing tools/resources/prompts)
quick5.0sFast health checks and pings
shutdown2.0sCleanup and shutdown operations

Example: TimeoutConfig

from chuk_tool_processor.mcp.transport import TimeoutConfig

timeout_config = TimeoutConfig(
    connect=60.0,     # Longer for slow initialization
    operation=45.0,   # Longer for heavy operations
    quick=3.0,        # Faster health checks
    shutdown=5.0      # More time for cleanup
)

Example: Using with StreamManager

from chuk_tool_processor.mcp.stream_manager import StreamManager

manager = StreamManager(timeout_config=timeout_config)

Example: Using with MCP Setup

from chuk_tool_processor.mcp import setup_mcp_stdio

processor, manager = await setup_mcp_stdio(
    config_file="mcp_config.json",
    servers=["sqlite"],
    namespace="db",
    initialization_timeout=120.0  # Separate init timeout
)

# Set custom timeouts on the manager
manager.timeout_config = timeout_config

Environment Variables

Core Configuration

VariableDefaultDescription
CHUK_DEFAULT_TIMEOUT10.0Default timeout for tool execution (seconds)
CHUK_MAX_CONCURRENCYNoneMaximum concurrent executions (None = unlimited)
CHUK_LOG_LEVELINFOLogging level (DEBUG, INFO, WARNING, ERROR)
CHUK_STRUCTURED_LOGGINGtrueEnable JSON logging (true/false)

Backend Selection

VariableDefaultDescription
CHUK_REGISTRY_BACKENDmemoryRegistry backend (memory or redis)
CHUK_RESILIENCE_BACKENDmemoryResilience backend (memory, redis, or auto)
CHUK_REDIS_URLredis://localhost:6379/0Redis connection URL
CHUK_REDIS_KEY_PREFIXchukKey prefix for Redis (multi-tenant isolation)

Circuit Breaker

VariableDefaultDescription
CHUK_CIRCUIT_BREAKER_ENABLEDfalseEnable circuit breaker (true/false)
CHUK_CIRCUIT_BREAKER_FAILURE_THRESHOLD5Failures before circuit opens
CHUK_CIRCUIT_BREAKER_SUCCESS_THRESHOLD2Successes in half-open to close
CHUK_CIRCUIT_BREAKER_RESET_TIMEOUT60.0Seconds before trying half-open
CHUK_CIRCUIT_BREAKER_FAILURE_WINDOW60.0Sliding window for counting failures (Redis only)

Rate Limiting

VariableDefaultDescription
CHUK_RATE_LIMIT_ENABLEDfalseEnable rate limiting (true/false)
CHUK_RATE_LIMIT_GLOBALNoneGlobal limit (requests per period)
CHUK_RATE_LIMIT_PERIOD60.0Rate limit period in seconds
CHUK_RATE_LIMIT_TOOLS""Per-tool limits: "tool1:10:60,tool2:5:30"

Caching

VariableDefaultDescription
CHUK_CACHE_ENABLEDtrueEnable result caching (true/false)
CHUK_CACHE_TTL300Cache time-to-live in seconds

Retries

VariableDefaultDescription
CHUK_RETRY_ENABLEDtrueEnable automatic retries (true/false)
CHUK_RETRY_MAX3Maximum retry attempts
CHUK_RETRY_BASE_DELAY1.0Initial retry delay in seconds
CHUK_RETRY_MAX_DELAY60.0Maximum retry delay in seconds

MCP & Observability

VariableDefaultDescription
MCP_BEARER_TOKEN-Bearer token for MCP SSE authentication
OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317OpenTelemetry collector endpoint
OTEL_SERVICE_NAMEchuk-tool-processorService name for traces/metrics
OTEL_TRACES_SAMPLERalways_onTrace sampling strategy
OTEL_TRACES_SAMPLER_ARG-Sampler argument (e.g., 0.1 for 10% sampling)

Example: Local Development

# In-memory backends (default)
export CHUK_LOG_LEVEL=DEBUG
export CHUK_DEFAULT_TIMEOUT=30.0
export CHUK_CACHE_ENABLED=true
export CHUK_RETRY_ENABLED=true

Example: Production with Redis

# Enable Redis for distributed deployments
export CHUK_REGISTRY_BACKEND=redis
export CHUK_RESILIENCE_BACKEND=redis
export CHUK_REDIS_URL=redis://redis-cluster:6379/0
export CHUK_REDIS_KEY_PREFIX=myapp

# Enable resilience features
export CHUK_CIRCUIT_BREAKER_ENABLED=true
export CHUK_CIRCUIT_BREAKER_FAILURE_THRESHOLD=5
export CHUK_RATE_LIMIT_ENABLED=true
export CHUK_RATE_LIMIT_GLOBAL=100
export CHUK_RATE_LIMIT_TOOLS="expensive_api:10:60,slow_api:5:30"

# Observability
export OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
export OTEL_SERVICE_NAME=production-api

ProcessorConfig (Programmatic Configuration)

The ProcessorConfig class provides a unified way to configure the processor, loading from environment variables or programmatically.

Loading from Environment

from chuk_tool_processor import ProcessorConfig

# Load all configuration from environment variables
config = ProcessorConfig.from_env()

# Create a fully-configured processor
processor = await config.create_processor()

async with processor:
    results = await processor.process(llm_output)

Programmatic Configuration

from chuk_tool_processor import ProcessorConfig, RegistryConfig, BackendType
from chuk_tool_processor.config import (
    CircuitBreakerConfig,
    RateLimitConfig,
    CacheConfig,
    RetryConfig,
)

config = ProcessorConfig(
    # Backend selection
    registry=RegistryConfig(backend=BackendType.REDIS),
    resilience_backend=BackendType.REDIS,
    redis_url="redis://localhost:6379/0",
    redis_key_prefix="myapp",

    # Execution
    default_timeout=30.0,
    max_concurrency=20,

    # Circuit breaker
    circuit_breaker=CircuitBreakerConfig(
        enabled=True,
        failure_threshold=5,
        success_threshold=2,
        reset_timeout=60.0,
        failure_window=60.0,
    ),

    # Rate limiting
    rate_limit=RateLimitConfig(
        enabled=True,
        global_limit=100,
        global_period=60.0,
        tool_limits={
            "expensive_api": (10, 60.0),
            "slow_api": (5, 30.0),
        },
    ),

    # Caching
    cache=CacheConfig(enabled=True, ttl=300),

    # Retries
    retry=RetryConfig(enabled=True, max_retries=3),
)

processor = await config.create_processor()

Configuration Methods

MethodDescription
ProcessorConfig.from_env()Load configuration from environment variables
config.create_processor()Create a fully-configured ToolProcessor
config.create_registry()Create just the registry
config.to_processor_kwargs()Get kwargs for ToolProcessor (in-memory only)
config.uses_redis()Check if resilience features use Redis
config.registry_uses_redis()Check if registry uses Redis

BackendType Options

ValueDescription
BackendType.MEMORYIn-memory backend (single instance)
BackendType.REDISRedis-backed backend (distributed)
BackendType.AUTOAuto-detect (prefers Redis if available)

Retry Policy Configuration

Retry behavior is controlled by three parameters:

ParameterDefaultDescription
max_retries3Maximum retry attempts (0 = no retries)
retry_delay1.0Initial delay between retries (seconds)
retry_backoff2.0Exponential backoff multiplier

Retry Delay Calculation

delay = retry_delay * (retry_backoff ** attempt)

Examples:

  • Attempt 1: 1.0 * (2.0 ** 0) = 1.0s
  • Attempt 2: 1.0 * (2.0 ** 1) = 2.0s
  • Attempt 3: 1.0 * (2.0 ** 2) = 4.0s

Example: Conservative Retry Policy

processor = ToolProcessor(
    enable_retries=True,
    max_retries=5,
    retry_delay=2.0,
    retry_backoff=1.5
)

Example: Aggressive Retry Policy

processor = ToolProcessor(
    enable_retries=True,
    max_retries=2,
    retry_delay=0.5,
    retry_backoff=3.0
)

Example: Disable Retries

processor = ToolProcessor(
    enable_retries=False
)

Rate Limiting Configuration

Rate limiting uses a sliding window algorithm.

ParameterDefaultDescription
enable_rate_limitingFalseEnable rate limiting
global_rate_limitNoneGlobal limit (requests/minute) across all tools
tool_rate_limitsNonePer-tool limits: {"tool_name": (max_requests, window_seconds)}

Rate Limit Priority

  1. Per-tool limits override global limits
  2. Global limit applies to tools without specific limits
  3. No limit if rate limiting is disabled or no limits configured

Example: Global Rate Limit

processor = ToolProcessor(
    enable_rate_limiting=True,
    global_rate_limit=100  # 100 requests/minute across all tools
)

Example: Per-Tool Rate Limits

processor = ToolProcessor(
    enable_rate_limiting=True,
    global_rate_limit=100,  # Default for all tools
    tool_rate_limits={
        "notion.search_pages": (10, 60),    # 10 per minute
        "expensive_api": (5, 60),           # 5 per minute
        "local_calculator": (1000, 60)      # 1000 per minute
    }
)

Example: Different Time Windows

processor = ToolProcessor(
    enable_rate_limiting=True,
    tool_rate_limits={
        "fast_api": (100, 10),    # 100 requests per 10 seconds
        "slow_api": (50, 300),    # 50 requests per 5 minutes
        "hourly_api": (1000, 3600)  # 1000 requests per hour
    }
)

Circuit Breaker Configuration

Circuit breaker prevents cascading failures by temporarily blocking requests to failing tools.

ParameterDefaultDescription
enable_circuit_breakerFalseEnable circuit breaker pattern
circuit_breaker_threshold5Number of failures before circuit opens
circuit_breaker_timeout60.0Time (seconds) before attempting recovery

Circuit States

  1. CLOSED: Normal operation, requests pass through
  2. OPEN: Too many failures, requests blocked immediately
  3. HALF_OPEN: Testing recovery with limited requests

State Transitions

CLOSED --[threshold failures]--> OPEN
OPEN --[timeout expires]--> HALF_OPEN
HALF_OPEN --[success]--> CLOSED
HALF_OPEN --[failure]--> OPEN

Example: Conservative Circuit Breaker

processor = ToolProcessor(
    enable_circuit_breaker=True,
    circuit_breaker_threshold=10,  # More tolerance
    circuit_breaker_timeout=120.0  # Longer recovery time
)

Example: Aggressive Circuit Breaker

processor = ToolProcessor(
    enable_circuit_breaker=True,
    circuit_breaker_threshold=3,   # Fail fast
    circuit_breaker_timeout=30.0   # Quick recovery attempts
)

Cache Configuration

Result caching with TTL and automatic idempotency key generation.

ParameterDefaultDescription
enable_cachingTrueEnable result caching
cache_ttl300Cache time-to-live (seconds)

Cache Key Generation

Cache keys are automatically generated from:

  1. Tool name
  2. Tool arguments (deterministic serialization)
  3. SHA256 hash

Example cache key:

ToolCall(tool="search", arguments={"query": "Python"})
# → idempotency_key: "e3b0c44298fc1c149afbf4c8996fb924..."

Example: Long-Lived Cache

processor = ToolProcessor(
    enable_caching=True,
    cache_ttl=3600  # 1 hour
)

Example: Short-Lived Cache

processor = ToolProcessor(
    enable_caching=True,
    cache_ttl=60  # 1 minute
)

Example: Disable Caching

processor = ToolProcessor(
    enable_caching=False
)

Performance Tuning Guide

High-Throughput Scenario

processor = ToolProcessor(
    max_concurrency=50,        # High concurrency
    default_timeout=10.0,      # Shorter timeouts
    enable_caching=True,       # Cache aggressively
    cache_ttl=300,
    enable_rate_limiting=True,
    global_rate_limit=500,     # High rate limit
    enable_retries=False       # Skip retries for speed
)

High-Reliability Scenario

processor = ToolProcessor(
    max_concurrency=10,            # Conservative concurrency
    default_timeout=60.0,          # Generous timeouts
    enable_caching=True,
    cache_ttl=600,
    enable_retries=True,
    max_retries=5,                 # More retries
    retry_delay=2.0,
    retry_backoff=1.5,
    enable_circuit_breaker=True,   # Prevent cascading failures
    circuit_breaker_threshold=10,
    circuit_breaker_timeout=120.0
)

Cost-Optimized Scenario

processor = ToolProcessor(
    enable_caching=True,
    cache_ttl=3600,            # Long cache for expensive calls
    enable_rate_limiting=True,
    global_rate_limit=50,      # Conservative rate limit
    enable_retries=True,
    max_retries=3,
    enable_circuit_breaker=True  # Avoid wasting credits
)

See Also