> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cascadeflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> TypeScript configuration types — AgentConfig, QualityConfig, CascadeConfig, RunOptions, and presets.

# Configuration

Full reference for `@cascadeflow/core` configuration types.

## AgentConfig

Passed to `new CascadeAgent(config)`.

```typescript theme={null}
interface AgentConfig {
  models: ModelConfig[];                    // Required — sorted by cost
  quality?: QualityConfig;                  // Quality validation
  cascade?: CascadeConfig;                  // Cascade behavior
  toolExecutor?: ToolExecutor;              // Tool execution
  callbacks?: CallbackManager;              // Lifecycle callbacks
  domainConfigs?: DomainConfigMap;          // Per-domain routing
  enableDomainDetection?: boolean;          // Auto-detect domain (default: true)
  tiers?: Record<string, TierRouterConfig>; // User tier definitions
  workflows?: Record<string, WorkflowProfile>; // Workflow profiles
  tenantRules?: Record<string, Record<string, unknown>>; // Per-tenant overrides
  channelModels?: Record<string, string[]>; // Channel → allowed models
  channelFailover?: Record<string, string>; // Channel failover map
  ruleEngineConfig?: RuleEngineConfig;      // Rule engine config
}
```

## QualityConfig

```typescript theme={null}
interface QualityConfig {
  threshold?: number;                  // Min confidence (default: 0.7)
  confidenceThresholds?: {             // By complexity level
    trivial?: number;
    simple?: number;
    moderate?: number;
    hard?: number;
    expert?: number;
  };
  requireMinimumTokens?: number;       // Min response length (default: 10)
  requireValidation?: boolean;         // Enable validation (default: true)
  useSemanticValidation?: boolean;     // ML-based validation
  semanticThreshold?: number;          // Semantic similarity threshold
  enableAdaptive?: boolean;            // Adaptive thresholds (default: false)
}
```

## CascadeConfig

```typescript theme={null}
interface CascadeConfig {
  quality?: QualityConfig;             // Quality settings
  maxBudget?: number;                  // Max budget per query (USD)
  trackCosts?: boolean;                // Cost tracking (default: true)
  maxRetries?: number;                 // Max retries per model (default: 0)
  timeout?: number;                    // Timeout in seconds (default: 60)
  routingStrategy?: 'cost' | 'quality' | 'speed'; // Routing strategy
  useSpeculative?: boolean;            // Speculative execution (default: false)
  verbose?: boolean;                   // Verbose logging
  trackMetrics?: boolean;              // Performance metrics (default: true)
}
```

## RunOptions

Passed to `agent.run(input, options)`.

```typescript theme={null}
interface RunOptions {
  maxTokens?: number;                  // Max tokens to generate
  temperature?: number;                // Temperature (0-2)
  systemPrompt?: string;               // System prompt
  tools?: Tool[];                      // Available tools
  toolExecutor?: ToolExecutor;         // Tool executor
  maxSteps?: number;                   // Max tool loop steps
  extra?: Record<string, any>;         // Provider-specific options
  forceDirect?: boolean;               // Skip cascade
  userTier?: string;                   // User tier
  workflow?: string;                   // Workflow profile
  kpiFlags?: Record<string, any>;      // KPI flags
  tenantId?: string;                   // Tenant ID
  channel?: string;                    // Channel
}
```

## Presets

```typescript theme={null}
import {
  PRESET_BEST_OVERALL,
  PRESET_ULTRA_FAST,
  PRESET_ULTRA_CHEAP,
  PRESET_OPENAI_ONLY,
  PRESET_ANTHROPIC_ONLY,
  PRESET_FREE_LOCAL,
  DEFAULT_QUALITY_CONFIG,
  DEFAULT_CASCADE_CONFIG,
} from '@cascadeflow/core';

// Use a preset
const agent = new CascadeAgent(PRESET_BEST_OVERALL);
```

| Preset                  | Description                |
| ----------------------- | -------------------------- |
| `PRESET_BEST_OVERALL`   | Claude Haiku + GPT-5       |
| `PRESET_ULTRA_FAST`     | Fastest cascade pair       |
| `PRESET_ULTRA_CHEAP`    | Cheapest cascade pair      |
| `PRESET_OPENAI_ONLY`    | OpenAI models only         |
| `PRESET_ANTHROPIC_ONLY` | Anthropic models only      |
| `PRESET_FREE_LOCAL`     | Free local models (Ollama) |

## Error Classes

```typescript theme={null}
import {
  cascadeflowError,
  ConfigurationError,
  ProviderError,
  AuthenticationError,
  RateLimitError,
  QualityValidationError,
  TimeoutError,
  ToolExecutionError,
} from '@cascadeflow/core';

try {
  const result = await agent.run('Query');
} catch (e) {
  if (e instanceof RateLimitError) {
    // Wait and retry
  } else if (e instanceof QualityValidationError) {
    // No model met the quality threshold
  }
}
```