@aidex/providers

Installation

pnpm add @aidex/providers

npm install @aidex/providers

Concrete Provider implementations for the Aidex kernel (@aidex/core). Providers are application-land code per docs/architecture/provider-development-guide.md — this package supplies them so an app can new Aidex({ provider: new StubProvider() }) without hand-rolling a stub every time.

Contents

• stub/StubProvider — the reference Provider implementation: complete, deterministic, no AI SDK dependency. Default provider for unit tests and examples, and the model every real provider (GeminiProvider, OpenAIProvider, ClaudeProvider, ...) follows for how content, metadata, and raw are meant to be populated — see the doc comments in stub/StubProvider.ts for exactly what each future provider will replace: the content transform becomes the vendor's actual generated text, the metadata object becomes real provider diagnostics (model name, token usage) instead of just an identity tag, and raw becomes the vendor SDK's actual native response instead of an echo of the input.
• gemini/GeminiProvider — the first production Provider, backed by the official @google/genai SDK. Owns SDK client construction, API key/model configuration, and generate(); gemini/mapping.ts holds the pure Prompt→request / response→ProviderResponse translation, with no network logic of its own. No Gemini SDK type is exported outside this package — raw carries the native response typed as unknown from the outside.
• openai/OpenAIProvider — backed by the official openai SDK. Supports an optional baseURL config field for OpenAI-compatible third-party endpoints (Groq/Together/local-vLLM-style gateways) — this is the entire "OpenAI compatibility" story; there is no separate OpenAICompatibleProvider class. Pointing baseURL at a third party never causes actualProvider to be reported as "OpenAI" — see shared/ProviderResponseMetadata.ts's doc comment for why.
• claude/ClaudeProvider — backed by the official @anthropic-ai/sdk. maxOutputTokens config (default 1024) exists because Anthropic's API requires max_tokens on every request, unlike OpenAI/Gemini.
• openrouter/OpenRouterProvider — a gateway, not a vendor: routes a request to whichever upstream model/provider OpenRouter selects. Uses the openai SDK internally with baseURL pointed at OpenRouter (an implementation detail — it is its own standalone class, not a subclass of OpenAIProvider, since its capabilities and config surface are genuinely different). Configure via model (specific/auto/free convention strings) or the more explicit routing: RoutingStrategy (routing/RoutingStrategy.ts) — routing always wins when both are set; see routing/resolveRouting.ts's doc comment for the exact precedence rule. openrouter/API_CONTRACT.md is the verified source for every request/response field this provider reads or sends. Reports actualModel/actualProvider/routingMode on ProviderResponse.metadata — actualProvider only when OpenRouter's opt-in router-metadata response field identifies it, never guessed from the model name.
• shared/withAbort — reusable AidexOptions.signal/.timeout helpers. GeminiProvider.generate() uses all three: throwIfAborted as a pre-flight guard, withTimeoutSignal to merge options.timeout/options.signal into one signal (passed to the SDK's own config.abortSignal), and rejectOnAbort to guarantee generate() itself rejects on abort even if the SDK's internal abort handling doesn't (verified in tests via a mocked SDK call that never resolves).
• capabilities/ — the provider capability model: ProviderCapability (the fixed set of vendor-neutral capability identifiers), ProviderCapabilities (the total map every provider returns, so a lookup is never undefined), createProviderCapabilities (builds that map from a list of supported capabilities), and CapableProvider (a Provider that also implements getCapabilities()). Every provider in this package — StubProvider and GeminiProvider — implements CapableProvider and exposes getCapabilities().

Tool calling

ToolCallingProvider.generateWithTools(turns, tools, options) — implemented by GeminiProvider, OpenAIProvider, and ClaudeProvider — performs exactly one caller-driven round trip: declares tools, sends turns as conversation history, and returns whatever the model said (final text, or one or more tool_use ContentParts on ProviderResponse.toolCalls for the caller to resolve). It never executes a tool itself, never loops, and never decides when a conversation is "done" — the caller drives continuation by constructing the next ConversationTurn (an assistant tool_use turn plus a tool tool_result turn) and calling this again. This is deliberately a foundation, not an autonomous agent runtime.

toToolDeclarations(tools) / resolveToolCalls(registry, toolCalls) — the registry-integration half of that round trip, bridging @aidex/tools' Tool/ToolRegistry to this package's wire-level types. This integration requires @aidex/tools as a direct dependency (pnpm add @aidex/tools) — it's not pulled in by @aidex/providers itself:

import { ToolRegistry } from '@aidex/tools';
import { StubProvider, toToolDeclarations, resolveToolCalls } from '@aidex/providers';

const registry = new ToolRegistry();
registry.register(weatherTool);

const provider = new StubProvider();
const declarations = toToolDeclarations(registry.list());

// 1. Ask the model — it may request a tool call.
const first = await provider.generateWithTools([userTurn], declarations);

// 2. Resolve any tool_use calls against the real registry.
const toolUseCalls = (first.toolCalls ?? []).filter((p) => p.type === 'tool_use');
const results = await resolveToolCalls(registry, toolUseCalls);

// 3. Feed the results back for the next round trip.
const final = await provider.generateWithTools(
  [userTurn, { role: 'assistant', content: toolUseCalls }, { role: 'tool', content: results }],
  declarations
);

toToolDeclarations() declares each tool to the model under its id, not its name — id is the only field ToolRegistry guarantees is unique and resolvable via execute(). resolveToolCalls() never throws for a failed call (unregistered id, missing permission, or the tool's own execute() rejecting) — it returns a tool_result with isError: true instead, so the model can see and react to the failure. This integration lives here, and @aidex/providers depends on @aidex/tools (never the reverse), because @aidex/tools documents a deliberate "@aidex/core only" dependency boundary — see that package's own README, "Tool-calling foundation and the @aidex/mcp boundary," for the full rationale including why @aidex/mcp stays unconnected.

Rules this package follows

• Imports only the public contracts from @aidex/core (Provider, Prompt, ProviderResponse, AidexOptions) — never a kernel internal.
• No base Provider class, no inheritance, no provider registry, no singleton, no factory — each provider is a standalone class implementing Provider directly, per docs/architecture/design-principles.md's Composition over Inheritance principle.
• src/index.ts exports provider classes (and their config types), plus the capabilities/ module's public surface (ProviderCapability, ProviderCapabilities, createProviderCapabilities, CapableProvider) — internal mapping/translation helpers stay unexported.