} catch (error) {
  const elapsed = performance.now() - startTime;
  this.recordMetric(requestId, 'primary_failure', elapsed);

  // Fallback chain with cost awareness
  const fallbackResult = await this.executeWithFallbackChain(
    prompt,
    outputSchema,
    this.config.maxRetries
  );

  return outputSchema.parse(fallbackResult);
}

}

private async executeWithTimeout<T>(promise: Promise<T>, timeoutMs: number): Promise<T> { return Promise.race([ promise, new Promise<never>((_, reject) => setTimeout(() => reject(new Error('LATENCY_TIMEOUT')), timeoutMs) ) ]); }

private async executeWithFallbackChain( prompt: string, schema: z.ZodTypeAny, retriesLeft: number ): Promise<unknown> { if (retriesLeft <= 0) throw new Error('FALLBACK_CHAIN_EXHAUSTED');

// Select fallback based on cost/latency telemetry
const provider = this.config.edgeFallback || this.config.fallback;
const estimatedCost = prompt.length * 0.001 * provider.costPerToken;

if (estimatedCost > this.config.costBudgetPerRequest) {
  throw new Error('COST_BUDGET_EXCEEDED');
}

try {
  return await provider.generate(prompt, schema);
} catch {
  return this.executeWithFallbackChain(prompt, schema, retriesLeft - 1);
}

}

private recordMetric(requestId: string, event: string, duration: number) { if (!this.metrics.has(requestId)) this.metrics.set(requestId, []); this.metrics.get(requestId)!.push(duration); // Emit to OpenTelemetry / Datadog / custom collector } }

### Architecture Decisions & Rationale

- **Schema-First Validation:** Zod enforcement at the routing layer prevents malformed outputs from propagating to business logic. This shifts failure detection left and enables contract testing.
- **Provider Abstraction:** Decoupling from vendor SDKs allows zero-downtime provider swaps and prevents lock-in. The `AIProvider` interface standardizes cost, latency, and generation contracts.
- **Cost-Aware Routing:** Budget enforcement prevents runaway token consumption during retry storms. The router evaluates estimated cost before fallback execution.
- **Timeout & Circuit Breaking:** Latency budgets prevent cascading delays. The `executeWithTimeout` wrapper enforces SLAs independently of provider behavior.
- **Observability Integration:** Metric collection is built into the router lifecycle. Tags include `requestId`, `event`, and `duration` for downstream tracing.

## Pitfall Guide

### Common Mistakes in Production AI Systems

1. **Treating LLMs as Deterministic Functions**
   LLMs are probabilistic systems. Assuming consistent outputs for identical prompts breaks idempotency, caching, and testing strategies. Always seed requests, enforce schemas, and design for variance.

2. **Ignoring Token Budgeting**
   Unbounded retry loops and verbose prompts compound costs exponentially. Implement per-request cost ceilings, prompt compression, and token counting before generation.

3. **Hardcoding System Prompts**
   Static prompts degrade as models update and user inputs drift. Externalize prompts to version-controlled configuration, implement A/B testing pipelines, and monitor prompt drift metrics.

4. **Skipping Structured Output Validation**
   Raw text outputs require fragile regex or LLM-as-judge parsing. Schema validation at the routing layer eliminates 60%+ of downstream parsing failures and enables automated contract testing.

5. **Single-Provider Dependency**
   Vendor outages, rate limits, and pricing changes directly impact SLAs. Abstract providers, maintain fallback chains, and implement provider health checks with automatic traffic shifting.

6. **Neglecting Circuit Breakers for AI Workloads**
   Traditional circuit breakers monitor HTTP status codes. AI failures manifest as timeouts, validation errors, or cost breaches. Implement AI-specific circuit breakers that track schema failures, latency percentiles, and token spend.

### Production Best Practices

- Enforce schema contracts at the edge of the AI subsystem, not in business logic.
- Implement cost-aware routing with dynamic provider selection based on real-time telemetry.
- Use prompt versioning and automated drift detection to maintain output quality.
- Deploy fallback chains with explicit cost/latency thresholds, not arbitrary retry counts.
- Integrate AI metrics into existing observability stacks using standardized spans and attributes.
- Test AI systems with contract tests, chaos engineering for provider failures, and cost simulation workloads.

## Production Bundle

### Action Checklist
- [ ] Define output schemas with Zod/TypeBox before implementation: enforce deterministic contracts at the routing layer.
- [ ] Implement provider abstraction interface: decouple business logic from vendor SDKs.
- [ ] Add cost budgeting per request: prevent runaway token consumption during fallbacks.
- [ ] Configure latency SLAs and timeout wrappers: enforce p95 targets independently of provider behavior.
- [ ] Deploy schema validation at the routing boundary: catch malformed outputs before business logic.
- [ ] Integrate AI metrics into observability stack: track latency, cost, validation success, and fallback triggers.
- [ ] Establish prompt versioning and drift monitoring: detect degradation before user impact.
- [ ] Implement AI-specific circuit breakers: monitor schema failures, cost breaches, and timeout rates.

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| High-throughput chatbot with strict latency SLA | Cost-Aware Router with Edge Fallback | Edge models reduce p95 latency to <200ms; routing prevents cloud cost spikes | -45% infrastructure cost |
| Compliance-critical document extraction | Schema-First Router with Structured Validation | Zod enforcement guarantees parseable output; audit trails meet regulatory requirements | +12% dev overhead, -68% parsing failures |
| Multi-modal pipeline (text + vision) | Agentic Orchestrator with Task Decomposition | Decouples modalities, routes to specialized models, prevents cross-modal latency cascades | +20% architecture complexity, -33% end-to-end latency |
| Budget-constrained MVP deployment | Static Fallback Chain with Prompt Compression | Minimal infrastructure; compression reduces token spend by 40-60% | -55% token cost, moderate latency variance |

### Configuration Template

```yaml
# ai-router-config.yaml
router:
  version: "2.0"
  defaults:
    max_retries: 2
    latency_budget_ms: 800
    cost_budget_per_request_usd: 0.05
    output_validation: true
    observability:
      enabled: true
      metrics_prefix: "ai.router"
      trace_spans: true

providers:
  primary:
    name: "cloud-advanced"
    endpoint: "https://api.provider.com/v1/chat"
    cost_per_token: 0.000015
    latency_budget_ms: 600
    fallback_priority: 1

  fallback:
    name: "cloud-standard"
    endpoint: "https://api.provider.com/v1/chat"
    cost_per_token: 0.000005
    latency_budget_ms: 400
    fallback_priority: 2

  edge:
    name: "edge-quantized"
    endpoint: "http://localhost:8080/generate"
    cost_per_token: 0.000001
    latency_budget_ms: 150
    fallback_priority: 3

circuit_breaker:
  failure_threshold: 5
  reset_timeout_seconds: 30
  monitoring_metrics:
    - "schema_validation_failure_rate"
    - "latency_p95_ms"
    - "cost_breach_count"

prompts:
  versioning:
    enabled: true
    storage: "s3://prompt-configs"
    drift_detection:
      enabled: true
      threshold: 0.15
      check_interval_hours: 6

Quick Start Guide

1. Install dependencies: npm install zod @opentelemetry/api @opentelemetry/sdk-node
2. Initialize router: Copy the configuration template to ai-router-config.yaml, replace provider endpoints with your credentials, and instantiate AILifecycleRouter with the parsed config.
3. Define your schema: Create a Zod schema matching your expected output structure. Pass it to router.route() alongside your prompt.
4. Deploy observability: Attach OpenTelemetry exporters to the router's recordMetric method. Verify spans, latency percentiles, and cost metrics in your dashboard.
5. Test fallback behavior: Simulate provider timeouts and cost breaches using a mock provider. Confirm circuit breaker activation and fallback chain execution.

Production AI in 2026 is no longer about chasing model benchmarks. It is about engineering deterministic, cost-governed, and observable subsystems that treat probabilistic generation as a managed resource. Implement routing contracts, enforce schema validation, and measure everything. The architecture will outperform the model.