Universal Adapter Matrix: 5 Providers, 1 Interface, BigInt Precision

2026-02-16

LOCKSTEP TRACEABILITY MATRIX --- api_endpoints: ["POST /v1/chat/completions", "GET /v1/models"] sdk_methods_updated: ["client.completions.create() (transparent — adapters are server-side)"] mcp_tools_updated: ["none"] ---

What We Built

The Model Executor (model-executor.ts, 2009 LOC) is BrainstormRouter's provider normalization layer. It implements the ProviderAdapter interface for 5 distinct providers — OpenAI, Anthropic, Google Generative AI, AWS Bedrock, and Ollama — presenting a single unified interface for request formatting, response parsing, stream chunk processing, and usage extraction.

Every adapter handles the idiosyncrasies of its provider: Anthropic's separate system parameter vs. OpenAI's system message in the messages array, Google's GenerateContent format, Bedrock's Converse API, Ollama's local REST API. The executor also detects and fixes parameter quirks automatically — max_tokens vs. maxTokens vs. max_completion_tokens — so the caller never needs to know which provider is being used.

Cost computation uses BigInt microcents (10^-9 USD per unit) throughout, avoiding floating-point rounding errors that accumulate at scale. A request that costs $0.000247 is stored as 247000n microcents, and aggregation across millions of requests remains exact.

Why It Matters

Building an AI application that works across providers is painful. Each provider has different authentication, request formats, response structures, streaming chunk formats, and parameter names. Developers waste weeks on adapter code that breaks when providers update their APIs.

BrainstormRouter's adapter matrix means developers write one API call and get access to 247 model endpoints across 5 providers. Provider-specific quirks, parameter fixes, streaming normalization, and cost computation are all handled transparently. When a new provider updates their API, we fix one adapter — not every customer's integration.

How It Works

Adapter Interface:

Each provider implements:

interface ProviderAdapter {
  allowedHeaders: Set<string>;
  formatRequest(req, endpoint): ProviderRequest;
  parseResponse(raw, endpoint): ModelExecutionResult;
  parseStreamChunk(line, endpoint): StreamItem | null;
  extractUsage(raw, endpoint): TokenUsage;
}

Capability Detection:

const caps = detectRequiredCapabilities(request);
// Returns: Set<'vision' | 'tool_use' | 'json_mode' | 'streaming' | ...>

The router uses these capabilities to filter eligible endpoints before the bandit selects a model.

Parameter Quirk Resolution:

const fix = detectParameterFix(request, endpoint);
// Returns: { field: 'max_tokens', from: 'max_tokens', to: 'max_completion_tokens' }

The executor auto-applies fixes so GPT-4o gets max_completion_tokens, Claude gets max_tokens, and Gemini gets maxOutputTokens — all from the same request.

Cost Computation (BigInt precision):

const cost = computeCost(usage, endpoint);
// Returns BigInt microcents: inputPerToken * inputTokens + outputPerToken * outputTokens
// Example: 247000n microcents = $0.000247

The Numbers

• 5 provider adapters: OpenAI (132 LOC), Anthropic (255 LOC), Google GenAI (198 LOC), Bedrock (204 LOC), Ollama (183 LOC)
• 2,009 total LOC — the largest single file in the router, and every line earns its keep
• BigInt microcents (10^-9 USD) for exact cost aggregation across millions of requests
• 247 model endpoints served through the unified interface
• Automatic parameter quirk detection — no manual mapping required per model

Competitive Edge

OpenRouter normalizes to an OpenAI-compatible interface but does not handle Bedrock, Ollama, or parameter quirk detection. Portkey supports multiple providers but requires per-provider configuration. BrainstormRouter's adapter matrix is the only implementation that auto-detects required capabilities, auto-fixes parameter mismatches, normalizes streaming chunks across all 5 providers, and computes costs with BigInt precision. The developer sees one interface; the router handles everything else.

Lockstep Checklist

• [x] API Routes: /v1/chat/completions and /v1/models consume the adapter matrix transparently.
• [x] TS SDK: client.completions.create() works identically regardless of which provider handles the request.
• [x] Python SDK: Same — provider normalization is server-side.
• [ ] MCP Schemas: Not applicable.
• [x] Master Record: Listed under "Core Engine & Routing" with all 6 adapter types in master-capability-record.md.