ai-runtime-engine 1.1.0

package/dist/types.d.ts

@@ -0,0 +1,460 @@
+/**
+ * Public, cross-cutting contracts for the AI Router. These are provider-agnostic on purpose:
+ * nothing here names a vendor. Provider adapters and the vendor catalog translate their reality
+ * into these shapes; `core/` only ever sees these.
+ */
+import type { AgentCapability, BooleanCapabilityGroup, InputModality, IntelligenceSkill, OutputModality } from './core/capabilities/taxonomy.js';
+/**
+ * How sure are we that a capability is real? Ordered from least to most trustworthy.
+ * INVARIANT: `unknown` and `unsupported` never satisfy a requirement, and nothing in the system
+ * may silently promote a lower rank to a higher one (see evidence.ts).
+ */
+export type Evidence = 'unsupported' | 'unknown' | 'inferred' | 'documented' | 'verified';
+export declare const EVIDENCE_RANK: Record<Evidence, number>;
+export interface Capability<V = boolean> {
+    value: V;
+    evidence: Evidence;
+    note?: string;
+}
+export interface CapabilityProfile {
+    input: Partial<Record<InputModality, Capability>>;
+    output: Partial<Record<OutputModality, Capability>>;
+    intelligence: Partial<Record<IntelligenceSkill, Capability>>;
+    agent: Partial<Record<AgentCapability, Capability>>;
+    context: {
+        contextWindow: Capability<number>;
+        maxOutputTokens?: Capability<number>;
+    };
+}
+/** A single required capability, addressed by (group, key). Context is expressed via minContextWindow. */
+export interface CapabilityRequirement {
+    group: BooleanCapabilityGroup;
+    key: string;
+    /** Minimum evidence rank that counts as "supported". Defaults to `documented`. */
+    minEvidence?: Evidence;
+    /** Optional per-requirement weight used by capabilityFit scoring. */
+    weight?: number;
+}
+export type OutputFormat = 'text' | 'json' | 'structured_output' | 'code';
+export type InputPart = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'image' | 'audio' | 'video' | 'file' | 'pdf';
+    mime: string;
+    data: string;
+};
+export interface ToolSpec {
+    name: string;
+    description?: string;
+    parameters?: unknown;
+}
+export interface ToolCall {
+    id?: string;
+    name: string;
+    arguments: unknown;
+}
+/** Declared sensitivity of the input. `unknown` is treated as most-restrictive (fail-closed). */
+export type Sensitivity = 'low' | 'high' | 'unknown';
+/** What a provider adapter receives. `model` is filled in by the selector. */
+export interface AIRequest {
+    taskId: string;
+    model: string;
+    input: {
+        text?: string;
+        parts?: InputPart[];
+    };
+    system?: string;
+    output?: {
+        format: OutputFormat;
+        schema?: unknown;
+    };
+    tools?: ToolSpec[];
+    params?: {
+        temperature?: number;
+        maxTokens?: number;
+        topP?: number;
+        stop?: string[];
+    };
+    timeoutMs: number;
+    signal?: AbortSignal;
+    sensitivity: Sensitivity;
+    metadata?: Record<string, unknown>;
+}
+export type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'error';
+/** What every provider adapter returns — normalized so callers never parse vendor JSON. */
+export interface AIResponse {
+    text?: string;
+    json?: unknown;
+    toolCalls?: ToolCall[];
+    finishReason: FinishReason;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    providerId: string;
+    model: string;
+    latencyMs: number;
+    /** Raw provider payload — OFF by default and redacted when on. */
+    raw?: unknown;
+}
+export type ErrorCategory = 'AUTHENTICATION' | 'AUTHORIZATION' | 'RATE_LIMIT' | 'QUOTA' | 'MODEL_NOT_FOUND' | 'CAPABILITY' | 'INVALID_REQUEST' | 'TIMEOUT' | 'NETWORK' | 'PROVIDER' | 'RESPONSE_VALIDATION' | 'BUDGET' | 'PRIVACY_VIOLATION' | 'NO_CAPABLE_PROVIDER' | 'ALL_PROVIDERS_FAILED' | 'CONFIG' | 'UNKNOWN';
+export interface RouterErrorInfo {
+    category: ErrorCategory;
+    message: string;
+    retryable: boolean;
+    providerId?: string;
+    model?: string;
+}
+export type HealthState = 'NOT_CONFIGURED' | 'CONFIGURED' | 'AVAILABLE' | 'DEGRADED' | 'RATE_LIMITED' | 'QUOTA_EXCEEDED' | 'AUTH_FAILED' | 'NETWORK_ERROR' | 'MODEL_UNAVAILABLE' | 'CAPABILITY_MISMATCH' | 'DISABLED' | 'UNKNOWN';
+export interface HealthStatus {
+    providerId: string;
+    state: HealthState;
+    routable: boolean;
+    checkedAt: number;
+    latencyMs?: number;
+    cooldownUntil?: number;
+    /** Human-readable detail — always redacted before it is stored or emitted. */
+    detail?: string;
+}
+export interface Pricing {
+    inputPerMTok?: number;
+    outputPerMTok?: number;
+    currency?: string;
+}
+export type QualityTier = 'frontier' | 'strong' | 'mid' | 'small';
+export interface ModelMetadata {
+    providerId: string;
+    id: string;
+    family?: string;
+    displayName?: string;
+    capabilities: CapabilityProfile;
+    contextWindow?: number;
+    maxOutputTokens?: number;
+    pricing?: Pricing;
+    quality?: {
+        tier?: QualityTier;
+        score?: number;
+        evidence: Evidence;
+    };
+    /** Observed/assumed reliability 0..1 with its evidence. */
+    reliability?: {
+        successRate: number;
+        evidence: Evidence;
+    };
+    /** Observed/assumed latency in ms with its evidence. */
+    latency?: {
+        p50Ms?: number;
+        p95Ms?: number;
+        evidence: Evidence;
+    };
+    enabled: boolean;
+    source: Evidence;
+}
+export type ProviderKind = 'openai-compatible' | 'gemini' | 'groq' | 'anthropic' | 'ollama' | 'custom' | 'mock';
+export interface ProviderMetadata {
+    id: string;
+    name: string;
+    kind: ProviderKind;
+    /** baseUrl ORIGIN only — never a full request URL, never a key-in-query. */
+    baseOrigin?: string;
+    authMode: 'env' | 'os-store' | 'none';
+    supportsModelListing: boolean;
+    defaultModel?: string;
+    models: ModelMetadata[];
+    privacyClass: PrivacyClass;
+}
+export interface ExecutionEstimate {
+    providerId: string;
+    model: string;
+    estInputTokens?: number;
+    estOutputTokens?: number;
+    estCost?: {
+        amount: number;
+        currency: string;
+        evidence: Evidence;
+    };
+    estLatencyMs?: {
+        p50?: number;
+        p95?: number;
+        evidence: Evidence;
+    };
+    contextFits: boolean;
+}
+/** `local` may receive high-sensitivity input; `cloud` is untrusted/external (the fail-closed default). */
+export type PrivacyClass = 'local' | 'cloud';
+export interface PrivacyRequirement {
+    /** Force a floor regardless of task input, e.g. a task that must stay local. */
+    requireLocal?: boolean;
+}
+export interface TaskDefinition {
+    id: string;
+    aliases?: string[];
+    description?: string;
+    required: CapabilityRequirement[];
+    preferred?: CapabilityRequirement[];
+    minContextWindow?: number;
+    output?: {
+        format: OutputFormat;
+        schema?: unknown;
+    };
+    defaultStrategy?: Strategy;
+    privacy?: PrivacyRequirement;
+    qualityFloor?: QualityTier;
+}
+export interface NormalizedTask {
+    id: string;
+    required: CapabilityRequirement[];
+    preferred: CapabilityRequirement[];
+    minContextWindow?: number;
+    output?: {
+        format: OutputFormat;
+        schema?: unknown;
+    };
+    strategy: Strategy;
+    sensitivity: Sensitivity;
+    requireLocal: boolean;
+    /** Low when the task was unknown and requirements had to be inferred. */
+    confidence: number;
+}
+export type Strategy = 'best' | 'fastest' | 'cheapest' | 'highest-quality' | 'local-only' | 'cloud-only' | 'privacy-first' | 'provider-specific' | 'fallback-only';
+export interface ScoreWeights {
+    capabilityFit: number;
+    quality: number;
+    reliability: number;
+    historicalSuccess: number;
+    latency: number;
+    cost: number;
+    userPreference: number;
+}
+export type ScoreBreakdown = Record<keyof ScoreWeights, number>;
+/** A (provider, model) pair under consideration, carrying everything the scorer needs. */
+export interface Candidate {
+    providerId: string;
+    model: ModelMetadata;
+}
+export interface ExclusionReason {
+    providerId: string;
+    model: string;
+    reason: string;
+}
+export interface RankedCandidate {
+    providerId: string;
+    model: string;
+    score: number;
+    breakdown: ScoreBreakdown;
+}
+export interface AttemptRecord {
+    providerId: string;
+    model: string;
+    outcome: 'success' | 'retryable' | 'non-retryable';
+    category?: ErrorCategory;
+    latencyMs: number;
+}
+export interface ValidationReport {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        why?: string;
+    }>;
+}
+export interface RoutingReport {
+    taskId: string;
+    strategy: Strategy;
+    weights: ScoreWeights;
+    requiredCapabilities: CapabilityRequirement[];
+    consideredCount: number;
+    filteredOut: ExclusionReason[];
+    ranked: RankedCandidate[];
+    selected?: {
+        providerId: string;
+        model: string;
+    };
+    attempts: AttemptRecord[];
+    validation?: ValidationReport;
+    /** True when the winning result's confidence fell below the configured minConfidence. */
+    belowConfidenceThreshold?: boolean;
+    /** Present when multi-model verification ran (config or per-run `verification`). */
+    verification?: VerificationReport;
+}
+export interface VerificationReport {
+    verifierProviderId: string;
+    verifierModel: string;
+    agreement: 'agree' | 'disagree' | 'inconclusive';
+    reason?: string;
+}
+export interface RunResult<T = AIResponse> {
+    ok: boolean;
+    response?: T;
+    error?: RouterErrorInfo;
+    confidence: number;
+    routing: RoutingReport;
+}
+export interface RunRequest {
+    task: string;
+    input: string | {
+        text?: string;
+        parts?: InputPart[];
+    };
+    system?: string;
+    requirements?: Partial<{
+        input: string[];
+        output: string[];
+        intelligence: string[];
+        agent: string[];
+        minContextWindow: number;
+    }>;
+    constraints?: {
+        maxCostUsd?: number;
+        maxLatencyMs?: number;
+        minimumConfidence?: number;
+        allowProviders?: string[];
+        denyProviders?: string[];
+    };
+    strategy?: Strategy;
+    /** Explicit override: pin a provider (and optionally model). Still passes through all filters. */
+    provider?: string;
+    model?: string;
+    /** User exclude/prefer routing controls. EXCLUDE is a hard filter; PREFER is a soft scoring nudge. */
+    routing?: RoutingPreferences;
+    sensitivity?: Sensitivity;
+    output?: {
+        format: OutputFormat;
+        schema?: unknown;
+    };
+    tools?: ToolSpec[];
+    params?: AIRequest['params'];
+    /** Per-run spend guardrail (overrides config.budget). */
+    budget?: {
+        maxCostUsd?: number;
+        maxCalls?: number;
+    };
+    /** Run a second model to verify the result before returning (overrides config.verification). */
+    verification?: boolean;
+    /** Attach tools from registered MCP sources to this run (requires a tool-calling model). */
+    mcp?: boolean;
+}
+/**
+ * User exclude/prefer routing (all optional). EXCLUDE is a HARD filter — an excluded candidate is never
+ * selected but stays visible in the routing trace (`⊘ excluded by user configuration`). PREFER is a SOFT
+ * scoring preference — a preferred-but-incapable/unhealthy/inaccessible candidate still loses. Model
+ * entries accept `provider:model` (exact) or a bare `model` id (any provider). Learning can never
+ * override an exclusion.
+ */
+export interface RoutingPreferences {
+    excludeProviders?: string[];
+    excludeModels?: string[];
+    preferProviders?: string[];
+    preferModels?: string[];
+}
+export interface DeclaredCapabilities {
+    input?: string[];
+    output?: string[];
+    intelligence?: string[];
+    agent?: string[];
+    contextWindow?: number;
+}
+export interface ProviderConfig {
+    id: string;
+    kind: ProviderKind;
+    baseUrl?: string;
+    /** NAME of the environment variable that holds the key — never the value itself. */
+    apiKeyEnv?: string;
+    enabled?: boolean;
+    models?: string[] | 'auto';
+    defaultModel?: string;
+    /** Operator-asserted capabilities for providers not in the catalog (tagged `documented`). */
+    capabilities?: DeclaredCapabilities;
+    privacyClass?: PrivacyClass;
+    wireShape?: 'openai' | 'anthropic';
+    /** Non-secret headers only. */
+    headers?: Record<string, string>;
+    weightOverrides?: Partial<ScoreWeights>;
+}
+export interface TelemetryConfig {
+    enabled: boolean;
+    sink: 'memory' | 'file';
+    storePrompts: false;
+    path?: string;
+}
+export interface RouterConfig {
+    providers: ProviderConfig[];
+    strategy?: Strategy;
+    weights?: Partial<ScoreWeights>;
+    defaults?: {
+        timeoutMs?: number;
+        maxFallbacks?: number;
+        minEvidence?: Evidence;
+        minConfidence?: number;
+    };
+    privacy?: {
+        /** Cloud providers allowed at all (default true — keeps a single cloud provider working). */
+        allowCloud?: boolean;
+        allowLocal?: boolean;
+        /** May HIGH-sensitivity input go to cloud? Default false — the core "never silently leak" guarantee. */
+        sensitiveDataAllowedOnCloud?: boolean;
+        /** Strict opt-in: treat undeclared (`unknown`) sensitivity as sensitive (fail-closed). Default false. */
+        treatUnknownAsSensitive?: boolean;
+        defaultSensitivity?: Sensitivity;
+    };
+    telemetry?: Partial<TelemetryConfig>;
+    /** Learning-based routing: feed observed success/latency into scoring (default enabled). */
+    learning?: {
+        enabled?: boolean;
+    };
+    /** Multi-model verification default for high-risk tasks (per-run `verification` overrides). */
+    verification?: {
+        enabled?: boolean;
+    };
+    /** Spend guardrails applied per `run()` across primary + fallbacks + verification. */
+    budget?: {
+        maxCostUsd?: number;
+        maxCalls?: number;
+    };
+    /** Team policy: org-level guardrails enforced on EVERY run (merged with per-run constraints). */
+    policy?: {
+        allowProviders?: string[];
+        denyProviders?: string[];
+        requireLocal?: boolean;
+        maxCostUsd?: number;
+        strategy?: Strategy;
+    };
+    tasks?: TaskDefinition[];
+}
+export type TelemetryEvent = {
+    type: 'route.decision';
+    ts: number;
+    taskId: string;
+    strategy: Strategy;
+    considered: number;
+    selected?: {
+        providerId: string;
+        model: string;
+    };
+    topScore?: number;
+} | {
+    type: 'route.attempt';
+    ts: number;
+    taskId: string;
+    providerId: string;
+    model: string;
+    outcome: 'success' | 'retryable' | 'non-retryable';
+    category?: ErrorCategory;
+    latencyMs: number;
+} | {
+    type: 'route.result';
+    ts: number;
+    taskId: string;
+    ok: boolean;
+    confidence: number;
+    totalLatencyMs: number;
+    fallbackCount: number;
+} | {
+    type: 'health.transition';
+    ts: number;
+    providerId: string;
+    from: HealthState;
+    to: HealthState;
+};

package/dist/types.js

@@ -0,0 +1,12 @@
+/**
+ * Public, cross-cutting contracts for the AI Router. These are provider-agnostic on purpose:
+ * nothing here names a vendor. Provider adapters and the vendor catalog translate their reality
+ * into these shapes; `core/` only ever sees these.
+ */
+export const EVIDENCE_RANK = {
+    unsupported: 0,
+    unknown: 1,
+    inferred: 2,
+    documented: 3,
+    verified: 4,
+};

package/dist/util/clock.d.ts

@@ -0,0 +1,6 @@
+/** An injectable clock so timing-dependent logic (cooldowns, latency, backoff) is deterministic in tests. */
+export interface Clock {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+export declare const systemClock: Clock;

package/dist/util/clock.js

@@ -0,0 +1,4 @@
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+};

package/dist/util/extractJson.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Pull the first balanced JSON object out of a model response.
+ *
+ * Models wrap JSON in prose or ``` fences often enough that failing on it would be a self-inflicted
+ * flake; anything beyond a single balanced top-level object is a hard error, not a heuristic guess.
+ * Pure and dependency-free, so it is trivially unit-testable.
+ */
+export declare function extractJson(text: unknown): unknown;

package/dist/util/extractJson.js

@@ -0,0 +1,54 @@
+/**
+ * Pull the first balanced JSON object out of a model response.
+ *
+ * Models wrap JSON in prose or ``` fences often enough that failing on it would be a self-inflicted
+ * flake; anything beyond a single balanced top-level object is a hard error, not a heuristic guess.
+ * Pure and dependency-free, so it is trivially unit-testable.
+ */
+import { AIError } from '../core/fallback/errors.js';
+export function extractJson(text) {
+    const raw = String(text ?? '').trim();
+    if (!raw)
+        throw new AIError('model returned an empty response', { category: 'RESPONSE_VALIDATION' });
+    const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const body = (fenced ? fenced[1] : raw).trim();
+    const start = body.indexOf('{');
+    if (start === -1) {
+        throw new AIError('model response contained no JSON object', { category: 'RESPONSE_VALIDATION' });
+    }
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < body.length; i += 1) {
+        const ch = body[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === '\\')
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === '{')
+            depth += 1;
+        else if (ch === '}') {
+            depth -= 1;
+            if (depth === 0) {
+                const slice = body.slice(start, i + 1);
+                try {
+                    return JSON.parse(slice);
+                }
+                catch (e) {
+                    const why = e instanceof Error ? e.message : String(e);
+                    throw new AIError(`model response was not valid JSON (${why})`, { category: 'RESPONSE_VALIDATION' });
+                }
+            }
+        }
+    }
+    throw new AIError('model response ended mid-JSON (likely truncated by max_tokens)', {
+        category: 'RESPONSE_VALIDATION',
+    });
+}

package/dist/verification/verify.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Multi-model verification. After a primary result, a SECOND model — preferably from a
+ * different provider — judges the answer and returns a structured verdict. Opt-in, because it at least
+ * doubles cost. The judge is provider-agnostic: it receives the task and the candidate answer and must
+ * reply with JSON `{ "valid": boolean, "reason": string }`. A parse failure or no distinct verifier is
+ * reported as `inconclusive` rather than blocking the result.
+ */
+import type { AIResponse, NormalizedTask, VerificationReport } from '../types.js';
+import type { ScoredCandidate } from '../core/router/scorer.js';
+import type { RequestTemplate } from '../core/router/normalize.js';
+import type { AIProvider } from '../providers/provider.js';
+import type { BudgetTracker } from '../core/policies/budget.js';
+export interface VerifyInput {
+    task: NormalizedTask;
+    template: RequestTemplate;
+    primary: {
+        providerId: string;
+        model: string;
+        response: AIResponse;
+    };
+    ranked: ScoredCandidate[];
+    getProvider: (id: string) => AIProvider | undefined;
+    budget?: BudgetTracker;
+    costOf?: (providerId: string, model: string) => Promise<number>;
+}
+export declare function runVerification(input: VerifyInput): Promise<VerificationReport | undefined>;

package/dist/verification/verify.js

@@ -0,0 +1,67 @@
+/**
+ * Multi-model verification. After a primary result, a SECOND model — preferably from a
+ * different provider — judges the answer and returns a structured verdict. Opt-in, because it at least
+ * doubles cost. The judge is provider-agnostic: it receives the task and the candidate answer and must
+ * reply with JSON `{ "valid": boolean, "reason": string }`. A parse failure or no distinct verifier is
+ * reported as `inconclusive` rather than blocking the result.
+ */
+import { buildRequest } from '../core/router/request.js';
+import { executeOnce } from '../core/router/executor.js';
+import { extractJson } from '../util/extractJson.js';
+function pickVerifier(ranked, primaryProviderId, primaryModel) {
+    // Prefer a different provider; otherwise a different model on the same provider.
+    return (ranked.find((c) => c.candidate.providerId !== primaryProviderId) ??
+        ranked.find((c) => !(c.candidate.providerId === primaryProviderId && c.candidate.model.id === primaryModel)));
+}
+function candidateAnswer(response) {
+    if (response.text)
+        return response.text;
+    if (response.json !== undefined)
+        return JSON.stringify(response.json);
+    return '(no answer)';
+}
+export async function runVerification(input) {
+    const verifier = pickVerifier(input.ranked, input.primary.providerId, input.primary.model);
+    if (!verifier || (verifier.candidate.providerId === input.primary.providerId && verifier.candidate.model.id === input.primary.model)) {
+        return { verifierProviderId: input.primary.providerId, verifierModel: input.primary.model, agreement: 'inconclusive', reason: 'no distinct verifier available' };
+    }
+    const provider = input.getProvider(verifier.candidate.providerId);
+    if (!provider)
+        return undefined;
+    const estCost = input.budget?.active && input.costOf ? await input.costOf(verifier.candidate.providerId, verifier.candidate.model.id) : 0;
+    if (input.budget && !input.budget.canSpend(estCost)) {
+        return { verifierProviderId: verifier.candidate.providerId, verifierModel: verifier.candidate.model.id, agreement: 'inconclusive', reason: 'budget exhausted before verification' };
+    }
+    const original = input.template.input.text ?? '(non-text input)';
+    const answer = candidateAnswer(input.primary.response);
+    const verifyTemplate = {
+        taskId: `${input.template.taskId}:verify`,
+        input: {
+            text: `You are a strict verifier. TASK "${input.task.id}":\n${original}\n\nCANDIDATE ANSWER:\n${answer}\n\nReply ONLY with JSON: {"valid": true|false, "reason": "<short>"}.`,
+        },
+        system: 'You verify whether a candidate answer correctly and completely satisfies the task. Respond only with the requested JSON.',
+        output: { format: 'json' },
+        timeoutMs: input.template.timeoutMs,
+        sensitivity: input.template.sensitivity,
+    };
+    const request = buildRequest(verifyTemplate, verifier.candidate.model.id);
+    const outcome = await executeOnce(provider, request);
+    input.budget?.recordCall(estCost);
+    if (!outcome.ok) {
+        return { verifierProviderId: verifier.candidate.providerId, verifierModel: verifier.candidate.model.id, agreement: 'inconclusive', reason: `verifier failed (${outcome.error.category})` };
+    }
+    let verdict;
+    try {
+        verdict = (outcome.response.json ?? extractJson(outcome.response.text ?? ''));
+    }
+    catch {
+        return { verifierProviderId: verifier.candidate.providerId, verifierModel: verifier.candidate.model.id, agreement: 'inconclusive', reason: 'verifier response was not parseable JSON' };
+    }
+    const agreement = verdict?.valid === true ? 'agree' : verdict?.valid === false ? 'disagree' : 'inconclusive';
+    return {
+        verifierProviderId: verifier.candidate.providerId,
+        verifierModel: verifier.candidate.model.id,
+        agreement,
+        ...(verdict?.reason ? { reason: verdict.reason } : {}),
+    };
+}