@fenixforce/kernel 0.1.0

package/dist/providers/anthropic.d.ts

@@ -0,0 +1,24 @@
+import type { LLMProvider, CompletionParams, CompletionResult, ProviderCapabilities } from "./interface.js";
+import type { ChatCompletionChunk } from "./stream-wrapper.js";
+export interface AnthropicConfig {
+    id?: string;
+    apiKey: string;
+    model: string;
+    baseUrl?: string;
+    maxTokens?: number;
+}
+export declare class AnthropicProvider implements LLMProvider {
+    readonly id: string;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly maxTokens;
+    constructor(config: AnthropicConfig);
+    capabilities(): ProviderCapabilities;
+    complete(params: CompletionParams): Promise<CompletionResult>;
+    stream(params: CompletionParams): AsyncIterable<ChatCompletionChunk>;
+    private headers;
+    private buildRequestBody;
+    private convertContent;
+    private mapStopReason;
+}

package/dist/providers/auto-detect.d.ts

@@ -0,0 +1,16 @@
+import type { ProviderSlot } from "./interface.js";
+export interface DetectedProvider {
+    id: string;
+    slot: ProviderSlot;
+    apiKeyEnv?: string;
+    baseUrl?: string;
+}
+export interface AutoDetectResult {
+    chat: DetectedProvider | null;
+    tts: DetectedProvider | null;
+    stt: DetectedProvider | null;
+    reusedKeys: string[];
+}
+export declare function autoDetectProviders(): Promise<AutoDetectResult>;
+/** List all supported provider IDs for documentation/diagnostics. */
+export declare function listSupportedProviders(): string[];

package/dist/providers/auto-discover.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Model Auto-Discovery — at startup, probe configured providers for
+ * available models and populate the ModelRegistry.
+ *
+ * - Ollama: GET /api/tags
+ * - OpenRouter: known model list (no probe needed)
+ * - Custom/OpenAI-compatible endpoints: GET /v1/models
+ *
+ * ~60 lines of logic.
+ */
+import type { ModelRegistry } from "./model-registry.js";
+export interface DiscoveryTarget {
+    /** Provider identifier. */
+    provider: string;
+    /** Base URL of the provider API. */
+    baseUrl: string;
+    /** API key for authenticated endpoints. */
+    apiKey?: string;
+    /** Provider type hint for choosing the right probe strategy. */
+    type?: "ollama" | "openrouter" | "openai-compatible";
+}
+export interface DiscoveryResult {
+    provider: string;
+    models: string[];
+    registered: number;
+    error?: string;
+}
+export declare function discoverModels(targets: DiscoveryTarget[], registry: ModelRegistry): Promise<DiscoveryResult[]>;

package/dist/providers/bedrock.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Bedrock Provider — AWS Bedrock Converse API adapter.
+ *
+ * Features:
+ * - SigV4 request signing (AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY)
+ * - Region-based endpoints (https://bedrock-runtime.{region}.amazonaws.com)
+ * - Model IDs prefixed with provider (anthropic.claude-*, meta.llama-*)
+ * - Streaming via event stream encoding
+ * - Multi-region support with region variants in model registry
+ */
+import type { LLMProvider, CompletionParams, CompletionResult, ProviderCapabilities } from "./interface.js";
+import type { ChatCompletionChunk } from "./stream-wrapper.js";
+export interface BedrockConfig {
+    id?: string;
+    model: string;
+    region?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+    maxTokens?: number;
+}
+export declare class BedrockProvider implements LLMProvider {
+    readonly id: string;
+    private readonly model;
+    private readonly region;
+    private readonly accessKeyId;
+    private readonly secretAccessKey;
+    private readonly sessionToken?;
+    private readonly maxTokens;
+    constructor(config: BedrockConfig);
+    capabilities(): ProviderCapabilities;
+    complete(params: CompletionParams): Promise<CompletionResult>;
+    stream(params: CompletionParams): AsyncIterable<ChatCompletionChunk>;
+    private buildRequest;
+    private convertContent;
+    private parseResponse;
+    private mapStopReason;
+}

package/dist/providers/cache-strategy.d.ts

@@ -0,0 +1,58 @@
+export interface CacheableMessage {
+    role: string;
+    content: string;
+    name?: string;
+    /** Provider-specific cache control annotation */
+    cacheControl?: {
+        type: "ephemeral";
+    };
+}
+export interface ToolDefinitionEntry {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+export interface CacheStrategyConfig {
+    /** System identity + steering rules — computed once at session start */
+    systemMessage: string;
+    /** Tool definitions — sorted by name for deterministic ordering */
+    toolDefinitions: ToolDefinitionEntry[];
+    /** Workspace steering rules — loaded at session start */
+    developerInstructions: string;
+}
+export interface OrderedRequest {
+    messages: CacheableMessage[];
+    /** Index of the last static message (cache breakpoint) */
+    cacheBreakpointIndex: number;
+    /** SHA-256 hash of the static prefix */
+    prefixHash: string;
+}
+export interface CacheMetrics {
+    sessionId: string;
+    totalCalls: number;
+    cacheHits: number;
+    estimatedTokensSaved: number;
+    hitRate: number;
+}
+export type CacheEventEmitter = (event: string, payload: Record<string, unknown>) => void;
+export declare class CacheStrategy {
+    private config;
+    private prefixHash;
+    private metrics;
+    private emitEvent;
+    constructor(config: CacheStrategyConfig, emitEvent?: CacheEventEmitter);
+    /**
+     * Build an ordered request with cache-optimized message ordering.
+     * Pipeline: system → tool defs → dev instructions → history → current message.
+     */
+    buildOrderedRequest(sessionId: string, history: CacheableMessage[], currentMessage: CacheableMessage): OrderedRequest;
+    /**
+     * Record cache hit/miss from provider response metadata.
+     */
+    recordCacheResult(sessionId: string, cachedTokens: number, totalInputTokens: number): void;
+    /** Get cache metrics for a session. */
+    getMetrics(sessionId: string): CacheMetrics | null;
+    /** Update static config (triggers cache-bust on next call). */
+    updateConfig(partial: Partial<CacheStrategyConfig>): void;
+    private computePrefixHash;
+}

package/dist/providers/circuit-breaker.d.ts

@@ -0,0 +1,33 @@
+export type CircuitState = "closed" | "open" | "half-open";
+export interface CircuitBreakerConfig {
+    /** Failures before opening the circuit (default: 5) */
+    failureThreshold?: number;
+    /** Base reset timeout in ms (default: 60_000 = 60s) */
+    resetTimeoutMs?: number;
+    /** Max reset timeout after backoff in ms (default: 3_600_000 = 1hr) */
+    maxResetTimeoutMs?: number;
+    /** Base timeout for billing/quota errors in ms (default: 18_000_000 = 5hr) */
+    billingResetTimeoutMs?: number;
+    /** Max timeout for billing/quota errors in ms (default: 86_400_000 = 24hr) */
+    billingMaxResetTimeoutMs?: number;
+}
+export declare function isBillingError(error: unknown): boolean;
+export declare class ProviderCircuitBreaker {
+    private state;
+    private failureCount;
+    private consecutiveResets;
+    private lastFailureTime;
+    private isBillingFailure;
+    private readonly config;
+    private keyBreakers;
+    constructor(config?: CircuitBreakerConfig);
+    getState(): CircuitState;
+    canAttempt(): boolean;
+    recordSuccess(): void;
+    recordFailure(error?: unknown): void;
+    /** Get or create a per-key sub-breaker (G14 multi-key support) */
+    getKeyBreaker(key: string): ProviderCircuitBreaker;
+    /** Find a healthy key from the list, or null if all are tripped */
+    getHealthyKey(keys: string[]): string | null;
+    private currentTimeout;
+}

package/dist/providers/cost-meter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * CostMeter — budget enforcement layer that checks spending limits
+ * before LLM calls, persists cost logs, and computes usage summaries.
+ *
+ * Yields quota:warning at 80% and quota:exceeded at budget limit.
+ */
+import type { StorageAdapter } from "../storage/interface.js";
+import type { BudgetsConfig } from "../config/schema.js";
+import type { AgentEvent } from "../events/types.js";
+export interface ModelPricing {
+    inputCostPer1k: number;
+    outputCostPer1k: number;
+}
+export type BudgetPeriod = "hourly" | "daily" | "monthly";
+/** Input to track() — what happened during an LLM call */
+export interface CostEntry {
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+}
+export interface UsageSummary {
+    period: BudgetPeriod;
+    costUsd: number;
+    totalTokens: number;
+    entries: number;
+}
+export interface BudgetStatus {
+    allowed: boolean;
+    reason?: string;
+    usage: {
+        hourly: UsageSummary;
+        daily: UsageSummary;
+        monthly: UsageSummary;
+    };
+}
+export declare function calculateCost(model: string, inputTokens: number, outputTokens: number, pricingTable?: Record<string, ModelPricing>): number;
+export interface CostMeterOptions {
+    userId: string;
+    storage: StorageAdapter;
+    budgets: BudgetsConfig;
+    pricingTable?: Record<string, ModelPricing>;
+}
+export declare class CostMeter {
+    private userId;
+    private storage;
+    private budgets;
+    private pricingTable;
+    constructor(options: CostMeterOptions);
+    /**
+     * Record token usage after an LLM call. Persists to cost_logs table.
+     */
+    track(entry: CostEntry): Promise<void>;
+    /**
+     * Track usage and yield quota events if thresholds are crossed.
+     * Call this as an async generator to receive quota:warning / quota:exceeded.
+     */
+    trackWithEvents(entry: CostEntry, sessionId?: string): AsyncGenerator<AgentEvent, void>;
+    /**
+     * Check whether the user is within budget across all configured periods.
+     */
+    checkBudget(userId?: string): Promise<BudgetStatus>;
+    /**
+     * Get usage summary for a specific period.
+     */
+    getUsage(userId?: string, period?: BudgetPeriod, now?: Date): Promise<UsageSummary>;
+    /**
+     * Compute the usage percentage for the tightest configured budget.
+     * Returns null if no budgets are configured.
+     */
+    usagePercent(userId?: string): Promise<number | null>;
+    /** Get the tightest (smallest) configured budget limit in USD. */
+    private tightestLimit;
+}

package/dist/providers/cost-tracking.d.ts

@@ -0,0 +1,36 @@
+import type { LLMProvider, CompletionParams, CompletionResult, EmbeddingResult, ProviderCapabilities, GenerateObjectParams, StreamObjectChunk } from "./interface.js";
+import type { ChatCompletionChunk } from "./stream-wrapper.js";
+export interface CostRecord {
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    estimatedCost: number;
+    timestamp: number;
+}
+export interface CostSummary {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalEstimatedCost: number;
+    recordCount: number;
+}
+export declare class CostTrackingProvider implements LLMProvider {
+    private readonly inner;
+    private readonly inputCostPerM;
+    private readonly outputCostPerM;
+    readonly id: string;
+    private readonly records;
+    private model;
+    stream?: (params: CompletionParams) => AsyncIterable<ChatCompletionChunk>;
+    generateObject?: <T = unknown>(params: GenerateObjectParams) => Promise<T>;
+    streamObject?: <T = unknown>(params: GenerateObjectParams) => AsyncIterable<StreamObjectChunk<T>>;
+    constructor(inner: LLMProvider, inputCostPerM?: number, outputCostPerM?: number);
+    capabilities(): ProviderCapabilities;
+    complete(params: CompletionParams): Promise<CompletionResult>;
+    embed(input: string | string[]): Promise<EmbeddingResult>;
+    getRecords(): readonly CostRecord[];
+    getSummary(): CostSummary;
+    private record;
+    private wrapStream;
+    private wrapObjectStream;
+}

package/dist/providers/google.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Google Provider — Google Generative AI (Gemini) API adapter.
+ *
+ * Supports the generateContent endpoint with:
+ * - contents array with "model"/"user" roles (not "assistant")
+ * - Inline tool declarations (Google format, not OpenAI)
+ * - Streaming via SSE
+ * - Vertex AI support via baseUrl override + service account auth
+ * - GOOGLE_API_KEY env var
+ */
+import type { LLMProvider, CompletionParams, CompletionResult, ProviderCapabilities } from "./interface.js";
+import type { ChatCompletionChunk } from "./stream-wrapper.js";
+export interface GoogleProviderConfig {
+    id?: string;
+    apiKey: string;
+    model: string;
+    /** Override for Vertex AI: e.g. https://{region}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/google */
+    baseUrl?: string;
+    maxOutputTokens?: number;
+}
+export declare class GoogleProvider implements LLMProvider {
+    readonly id: string;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly maxOutputTokens;
+    constructor(config: GoogleProviderConfig);
+    capabilities(): ProviderCapabilities;
+    complete(params: CompletionParams): Promise<CompletionResult>;
+    stream(params: CompletionParams): AsyncIterable<ChatCompletionChunk>;
+    private buildRequest;
+    private convertContent;
+    private parseResponse;
+    private mapFinishReason;
+}

package/dist/providers/index.d.ts

@@ -0,0 +1,32 @@
+export * from "./interface.js";
+export * from "./circuit-breaker.js";
+export * from "./cost-tracking.js";
+export * from "./manager.js";
+export * from "./cost-meter.js";
+export { AnthropicProvider } from "./anthropic.js";
+export { GoogleProvider } from "./google.js";
+export { BedrockProvider } from "./bedrock.js";
+export { ModelRegistry, loadDefaultRegistry, createRegistry } from "./model-registry.js";
+export { discoverModels } from "./auto-discover.js";
+export type { DiscoveryTarget, DiscoveryResult } from "./auto-discover.js";
+export { rankModels, pickBestModel, resolveMode, createOptimizationConfig } from "./optimization-modes.js";
+export type { OptimizationMode, OptimizationConfig, RankedModel } from "./optimization-modes.js";
+export { checkCompatibility } from "./versioning.js";
+export type { VersionCompat, VersionCheckResult } from "./versioning.js";
+export { OpenAICompatibleProvider } from "./openai-compatible.js";
+export type { OpenAICompatibleConfig } from "./openai-compatible.js";
+export { repairJson, parsePartialJson } from "./json-repair.js";
+export { verifiedGenerateObject, StructuredOutputError } from "./structured-verify.js";
+export type { VerifyOptions, VerifyResult } from "./structured-verify.js";
+export { SidecarLifecycle } from "./sidecar-lifecycle.js";
+export type { SidecarConfig as SidecarLifecycleConfig, SidecarState as SidecarLifecycleState, StartFn as SidecarStartFn, HealthCheckFn as SidecarHealthCheckFn, } from "./sidecar-lifecycle.js";
+export { createOpenAICompatibleStream } from "./stream-wrapper.js";
+export type { ChatCompletionChunk, TokenUsage } from "./stream-wrapper.js";
+export { createKeyRotator } from "./key-rotation.js";
+export type { KeyRotationConfig, KeyRotator } from "./key-rotation.js";
+export { createRuntimeProviderCRUD, _resetProviderIds } from "./runtime-crud.js";
+export type { ProviderEntry, CreateProviderInput, UpdateProviderInput, TestResult, ProviderFactory, RuntimeProviderCRUDConfig, RuntimeProviderCRUD, } from "./runtime-crud.js";
+export { autoDetectProviders, listSupportedProviders } from "./auto-detect.js";
+export type { DetectedProvider, AutoDetectResult } from "./auto-detect.js";
+export { CacheStrategy } from "./cache-strategy.js";
+export type { CacheableMessage, ToolDefinitionEntry, CacheStrategyConfig, OrderedRequest, CacheMetrics, CacheEventEmitter, } from "./cache-strategy.js";

package/dist/providers/interface.d.ts

@@ -0,0 +1,98 @@
+import type { ChatCompletionChunk } from "./stream-wrapper.js";
+export type ProviderSlot = "chat" | "utility" | "embedding" | "vision" | "stt" | "tts";
+export interface ProviderCapabilities {
+    nativeToolCalling: boolean;
+    vision: boolean;
+    streaming: boolean;
+    structuredOutput: boolean;
+    maxContextTokens: number;
+}
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ContentPart {
+    type: "text" | "image_url";
+    text?: string;
+    image_url?: {
+        url: string;
+        detail?: "low" | "high" | "auto";
+    };
+}
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | ContentPart[] | null;
+    tool_call_id?: string;
+    tool_calls?: ToolCall[];
+}
+export interface ToolDefinition {
+    type: "function";
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface CompletionParams {
+    model?: string;
+    messages: Message[];
+    temperature?: number;
+    maxTokens?: number;
+    tools?: ToolDefinition[];
+    stop?: string | string[];
+}
+export interface CompletionResult {
+    content: string;
+    toolCalls?: ToolCall[];
+    finishReason: "stop" | "tool_calls" | "length" | "content_filter" | null;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface EmbeddingResult {
+    embeddings: number[][];
+    usage?: {
+        totalTokens: number;
+    };
+}
+export interface JsonSchema {
+    type: string;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    description?: string;
+    enum?: unknown[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+}
+export interface GenerateObjectParams {
+    model?: string;
+    messages: Message[];
+    schema: JsonSchema;
+    schemaName?: string;
+    schemaDescription?: string;
+    temperature?: number;
+    maxTokens?: number;
+}
+export interface StreamObjectChunk<T = unknown> {
+    partial: Partial<T>;
+    done: boolean;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface LLMProvider {
+    readonly id: string;
+    complete(params: CompletionParams): Promise<CompletionResult>;
+    stream?(params: CompletionParams): AsyncIterable<ChatCompletionChunk>;
+    embed?(input: string | string[]): Promise<EmbeddingResult>;
+    generateObject?<T = unknown>(params: GenerateObjectParams): Promise<T>;
+    streamObject?<T = unknown>(params: GenerateObjectParams): AsyncIterable<StreamObjectChunk<T>>;
+    capabilities(): ProviderCapabilities;
+}

package/dist/providers/json-repair.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Attempt to parse JSON, repairing common LLM output issues.
+ * Returns the parsed value, or throws if repair is impossible.
+ */
+export declare function repairJson<T = unknown>(input: string): T;
+/**
+ * Parse partial/streaming JSON, returning the best partial result.
+ * Unlike repairJson, this never throws — it returns undefined on failure.
+ */
+export declare function parsePartialJson<T = unknown>(input: string): Partial<T> | undefined;

package/dist/providers/key-rotation.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Key Rotation — round-robin between multiple API keys for a provider.
+ * Ties into ProviderCircuitBreaker per-key mode (G14): each key gets
+ * its own sub-breaker. When a key hits rate limits, the breaker opens
+ * and rotation skips to the next healthy key.
+ *
+ * ~50 lines of logic.
+ */
+import { ProviderCircuitBreaker } from "./circuit-breaker.js";
+export interface KeyRotationConfig {
+    /** Provider name (for identification). */
+    provider: string;
+    /** API keys to rotate between. */
+    keys: string[];
+    /** Circuit breaker config passed to per-key sub-breakers. */
+    breakerConfig?: ConstructorParameters<typeof ProviderCircuitBreaker>[0];
+}
+export interface KeyRotator {
+    /** Get the next healthy key via round-robin. Returns null if all tripped. */
+    next(): string | null;
+    /** Record success for the last-selected key's breaker. */
+    recordSuccess(): void;
+    /** Record failure for the last-selected key's breaker (opens after threshold). */
+    recordFailure(error?: unknown): void;
+    /** Snapshot of each key's circuit state. */
+    health(): Array<{
+        key: string;
+        state: string;
+        canAttempt: boolean;
+    }>;
+    /** Number of keys that can currently be used. */
+    healthyCount(): number;
+    /** The underlying per-key circuit breaker. */
+    readonly breaker: ProviderCircuitBreaker;
+}
+export declare function createKeyRotator(config: KeyRotationConfig): KeyRotator;

package/dist/providers/manager.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ProviderManager — holds providers by slot, wraps with circuit breakers
+ * and cost tracking, and provides capability-based dispatch.
+ */
+import type { LLMProvider, ProviderCapabilities, ProviderSlot } from "./interface.js";
+import { ProviderCircuitBreaker } from "./circuit-breaker.js";
+import { type AutoDetectResult } from "./auto-detect.js";
+export interface ManagedProvider {
+    provider: LLMProvider;
+    breaker: ProviderCircuitBreaker;
+    slot: ProviderSlot;
+}
+export interface ProviderManagerOptions {
+    /** Wrap providers with CostTrackingProvider. */
+    enableCostTracking?: boolean;
+    sessionId?: string;
+}
+export declare class ProviderManager {
+    private slots;
+    private enableCostTracking;
+    constructor(options?: ProviderManagerOptions);
+    /**
+     * Register a provider for a slot. Wraps in CostTrackingProvider if
+     * cost tracking is enabled, and creates a circuit breaker.
+     */
+    register(slot: ProviderSlot, provider: LLMProvider): void;
+    /**
+     * Get a healthy (closed or half-open) provider for a given slot.
+     * Returns null if no healthy provider is available.
+     */
+    getHealthy(slot: ProviderSlot): LLMProvider | null;
+    /**
+     * Get the circuit breaker for a slot, for recording success/failure.
+     */
+    getBreaker(slot: ProviderSlot): ProviderCircuitBreaker | null;
+    /**
+     * Capability-based dispatch: returns a healthy provider that satisfies
+     * the requested capability. Falls back across slots in order:
+     * - For vision: try vision slot, then chat slot
+     * - For other capabilities: try the requested slot, then chat, then utility
+     */
+    getByCapability(capability: keyof ProviderCapabilities, preferredSlot?: ProviderSlot): LLMProvider | null;
+    /**
+     * List all registered slots.
+     */
+    listSlots(): ProviderSlot[];
+    /**
+     * Get the managed entry (provider + breaker) for a slot.
+     */
+    get(slot: ProviderSlot): ManagedProvider | undefined;
+    /**
+     * Check whether any provider slots are configured.
+     */
+    hasSlots(): boolean;
+    /**
+     * Auto-detect and populate provider slots from environment when
+     * no explicit configuration exists. Uses the G15 cascade:
+     * LLM → TTS → STT, with multi-modal key reuse.
+     *
+     * Callers must create LLMProvider instances from the detection
+     * result and register them via register().
+     */
+    static autoDetect(): Promise<AutoDetectResult>;
+}

package/dist/providers/model-registry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Model Registry — central catalog of known LLM models with capabilities,
+ * pricing, and alias resolution. Loaded at startup from data/models.json,
+ * extensible at runtime via register().
+ */
+export interface ModelCapabilities {
+    nativeToolCalling: boolean;
+    vision: boolean;
+    streaming: boolean;
+    reasoning: boolean;
+    maxContextTokens: number;
+    maxOutputTokens: number;
+}
+export interface ModelPricing {
+    inputPer1MTokens: number;
+    outputPer1MTokens: number;
+    cachedInputPer1MTokens: number;
+}
+export interface ModelEntry {
+    id: string;
+    provider: string;
+    model: string;
+    displayName: string;
+    capabilities: ModelCapabilities;
+    pricing: ModelPricing;
+    aliases: string[];
+}
+export declare class ModelRegistry {
+    private readonly models;
+    private readonly aliasIndex;
+    constructor(entries?: ModelEntry[]);
+    /** Register a model entry, indexing by ID and all aliases. */
+    register(entry: ModelEntry): void;
+    /** Look up a model by full ID or any alias. Returns undefined if not found. */
+    lookup(idOrAlias: string): ModelEntry | undefined;
+    /** List all models for a given provider name. */
+    listByProvider(provider: string): ModelEntry[];
+    /** Filter models by a capability key (e.g. "vision", "reasoning"). */
+    listByCapability(cap: keyof ModelCapabilities): ModelEntry[];
+    /** Estimate cost in USD for a given model and token counts. */
+    estimateCost(modelIdOrAlias: string, inputTokens: number, outputTokens: number, cachedInputTokens?: number): number;
+    /** Return all registered entries. */
+    listAll(): ModelEntry[];
+    /** Number of registered models. */
+    get size(): number;
+}
+/** Load the default registry from data/models.json. */
+export declare function loadDefaultRegistry(): ModelRegistry;
+/** Create a fresh registry (useful for testing). */
+export declare function createRegistry(entries?: ModelEntry[]): ModelRegistry;

package/dist/providers/openai-compatible.d.ts

@@ -0,0 +1,26 @@
+import type { LLMProvider, CompletionParams, CompletionResult, EmbeddingResult, ProviderCapabilities, GenerateObjectParams, StreamObjectChunk } from "./interface.js";
+import type { ChatCompletionChunk } from "./stream-wrapper.js";
+export interface OpenAICompatibleConfig {
+    id?: string;
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    capabilities?: Partial<ProviderCapabilities>;
+}
+export declare class OpenAICompatibleProvider implements LLMProvider {
+    readonly id: string;
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly model;
+    private readonly caps;
+    constructor(config: OpenAICompatibleConfig);
+    capabilities(): ProviderCapabilities;
+    complete(params: CompletionParams): Promise<CompletionResult>;
+    stream(params: CompletionParams): AsyncIterable<ChatCompletionChunk>;
+    embed(input: string | string[]): Promise<EmbeddingResult>;
+    generateObject<T = unknown>(params: GenerateObjectParams): Promise<T>;
+    streamObject<T = unknown>(params: GenerateObjectParams): AsyncIterable<StreamObjectChunk<T>>;
+    private headers;
+    private buildRequestBody;
+    private mapFinishReason;
+}