@cloudpeers-jkl/model-router 0.2.0

package/dist/policy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Policy (the central control plane, distributed as deploy-time config).
+ *
+ * Tier table per the 2026-07-09 resolutions (supersedes the April spec table):
+ *   Tier 0 — self-hosted in-boundary (OpenMed extraction / Nemotron pending
+ *            the Q3 eval; the ONLY tier permitted for local_only once the
+ *            hard gate flips)
+ *   Tier 1 — Gemini Flash  (fast, non-PHI; local_only only under Vertex BAA)
+ *   Tier 2 — Claude        (primary reasoning; local_only only under BAA)
+ * No OpenAI tier, by directive.
+ *
+ * Privacy gate — interim cloud-PHI policy (decision 2026-07-09), three stages:
+ *   Stage 1 MONITOR (default): local_only → cloud logs `would_block`, proceeds.
+ *   Stage 2 governed egress:   providers listed in MODEL_ROUTER_BAA_PROVIDERS
+ *                              (set ONLY once the instrument is executed) are
+ *                              permitted for local_only.
+ *   Stage 3 enforce:           MODEL_PRIVACY_GATE_ENFORCE=true — local_only is
+ *                              Tier-0-or-BAA only, fail closed.
+ */
+import type { GateOutcome, Provider, SovereigntyClass, TaskClass, TierDef } from './types.js';
+export declare const TIERS: Record<number, TierDef>;
+/** Static routing table (confidence v1): tier chain per task class, in order. */
+export declare const TASK_ROUTES: Record<TaskClass, number[]>;
+export declare function gateEnforced(): boolean;
+/**
+ * The privacy gate. Evaluated per tier, before any call.
+ * Never triggers for aggregate_only/externalizable (spec scope: local_only).
+ */
+export declare function evaluateGate(sovereigntyClass: SovereigntyClass, tier: TierDef): GateOutcome;
+/**
+ * Resolve the tier chain for a request: the static task-class chain,
+ * optionally reordered by an advisory backend_hint (§4). The hint never adds
+ * a tier the task class wouldn't reach and never bypasses the gate.
+ */
+export declare function resolveChain(taskClass: TaskClass, backendHint?: Provider): number[];

package/dist/policy.js

@@ -0,0 +1,48 @@
+export const TIERS = {
+    0: { tier: 0, provider: 'selfhosted', model: process.env.MODEL_ROUTER_TIER0_MODEL || 'openmed-extraction', cloud: false },
+    1: { tier: 1, provider: 'gemini', model: process.env.MODEL_ROUTER_GEMINI_MODEL || 'gemini-2.0-flash-exp', cloud: true },
+    2: { tier: 2, provider: 'anthropic', model: process.env.MODEL_ROUTER_ANTHROPIC_MODEL || 'claude-haiku-4-5', cloud: true },
+};
+/** Static routing table (confidence v1): tier chain per task class, in order. */
+export const TASK_ROUTES = {
+    extraction: [0, 1],
+    classification: [0, 1],
+    coaching: [1, 2],
+    reasoning: [2, 1],
+    synthesis: [2, 1],
+};
+function baaProviders() {
+    return new Set((process.env.MODEL_ROUTER_BAA_PROVIDERS ?? '')
+        .split(',')
+        .map((p) => p.trim().toLowerCase())
+        .filter(Boolean));
+}
+export function gateEnforced() {
+    return process.env.MODEL_PRIVACY_GATE_ENFORCE === 'true';
+}
+/**
+ * The privacy gate. Evaluated per tier, before any call.
+ * Never triggers for aggregate_only/externalizable (spec scope: local_only).
+ */
+export function evaluateGate(sovereigntyClass, tier) {
+    if (sovereigntyClass !== 'local_only' || !tier.cloud)
+        return 'allowed';
+    if (baaProviders().has(tier.provider))
+        return 'allowed'; // Stage 2 governed egress
+    return gateEnforced() ? 'blocked' : 'would_block'; // Stage 3 : Stage 1
+}
+/**
+ * Resolve the tier chain for a request: the static task-class chain,
+ * optionally reordered by an advisory backend_hint (§4). The hint never adds
+ * a tier the task class wouldn't reach and never bypasses the gate.
+ */
+export function resolveChain(taskClass, backendHint) {
+    const chain = TASK_ROUTES[taskClass];
+    if (!chain?.length)
+        throw new Error(`Unknown task class: ${taskClass}`);
+    if (!backendHint)
+        return chain;
+    const hinted = chain.filter((t) => TIERS[t].provider === backendHint);
+    const rest = chain.filter((t) => TIERS[t].provider !== backendHint);
+    return [...hinted, ...rest];
+}

package/dist/router.d.ts

@@ -0,0 +1,36 @@
+import type { AnthropicSSEEvent, GateOutcome, MessagesRouteResult, RouterDeps, RouterRequest, RouterResult, TierDef } from './types.js';
+export interface RouteContext {
+    userId: string;
+    serviceId: string;
+    /** Metering label (token-tracker `operation`). */
+    operation: string;
+    metadata?: Record<string, unknown>;
+    /** Confidence v1: validate the response text; failure escalates a tier. */
+    validate?: (text: string) => boolean;
+    signal?: AbortSignal;
+}
+/**
+ * Spec API — route an Anthropic-shape request with a `cloudpeers` envelope
+ * (§4). Returns the full Anthropic response plus routing telemetry.
+ */
+export declare function routeMessages(input: unknown, ctx: RouteContext, deps: RouterDeps): Promise<MessagesRouteResult>;
+export interface MessagesStreamResult {
+    provider: TierDef['provider'];
+    model: string;
+    tier: number;
+    gate: GateOutcome;
+    /** Anthropic SSE event sequence. Usage is metered when the stream completes. */
+    stream: AsyncIterable<AnthropicSSEEvent>;
+}
+/**
+ * Streaming variant. Pre-call enforcement is identical; the first eligible
+ * streaming-capable tier serves the request (no mid-stream escalation — a
+ * failed stream surfaces to the caller).
+ */
+export declare function routeMessagesStream(input: unknown, ctx: RouteContext, deps: RouterDeps): Promise<MessagesStreamResult>;
+/**
+ * v1 convenience API — prompt in, text out. Behavior-identical to
+ * ModelRouter v1 (first caller: mcp lab-coaching); implemented over
+ * routeMessages so both APIs share one enforcement path.
+ */
+export declare function routeModel(req: RouterRequest, deps: RouterDeps): Promise<RouterResult>;

package/dist/router.js

@@ -0,0 +1,328 @@
+/**
+ * The routing core (in-process; no data plane service).
+ *
+ * Flow per request: validate envelope (§4/§7.1 #1) → mandate + policy hooks
+ * (§7.1 #2/#4, fail closed when named but unwired) → quota → resolve the
+ * task-class tier chain → per tier: privacy gate (monitor/BAA/enforce) →
+ * adapter availability + eligibility → invoke → post-call hooks (§7.2,
+ * observation-only) → optional validation (confidence v1: failure escalates)
+ * → uniform metering via the injected meter.
+ * Fail-closed: if enforcement blocks every tier, RouterBlockedError — never a
+ * silent fallback to an unapproved path.
+ *
+ * Monitor-gate log lines ([privacy-gate-monitor] / [privacy-gate]) are a
+ * stable interface: the Stage-3 enforcement flip decision is made from them.
+ */
+import { RouterBlockedError } from './errors.js';
+import { evaluateGate, resolveChain, TIERS } from './policy.js';
+import { parseRouterRequest } from './schema.js';
+function firstText(content) {
+    return content.find((b) => b.type === 'text')?.text ?? '';
+}
+function promptChars(req) {
+    let chars = req.system?.length ?? 0;
+    for (const m of req.messages) {
+        chars +=
+            typeof m.content === 'string'
+                ? m.content.length
+                : m.content.reduce((n, b) => n + (b.type === 'text' ? b.text.length : JSON.stringify(b).length), 0);
+    }
+    return chars;
+}
+/** §4 — the envelope never appears in upstream provider traffic. */
+function stripEnvelope(req, model) {
+    const { cloudpeers: _cloudpeers, stream: _stream, ...rest } = req;
+    return { ...rest, model };
+}
+/**
+ * §7.1 #2/#4 + A1.2 — pre-call enforcement that applies to the request as a
+ * whole. Fail closed: a named instrument with no wired verifier blocks.
+ */
+async function enforcePreCall(env, deps) {
+    if (env.byok) {
+        throw new RouterBlockedError('BYOK routing is deferred pending policy review (Amendment A1.2)', 501, 'byok_deferred');
+    }
+    if (env.mandate_id) {
+        if (!deps.hooks?.verifyMandate) {
+            throw new RouterBlockedError(`mandate_id ${env.mandate_id} present but no mandate verifier is wired (fail closed)`, 412, 'mandate_verifier_unavailable');
+        }
+        const verdict = await deps.hooks.verifyMandate(env.mandate_id);
+        if (!verdict.valid) {
+            if (verdict.reason === 'expired')
+                throw new RouterBlockedError(`Mandate ${env.mandate_id} is expired`, 410, 'mandate_expired');
+            if (verdict.reason === 'revoked')
+                throw new RouterBlockedError(`Mandate ${env.mandate_id} is revoked`, 409, 'mandate_revoked');
+            throw new RouterBlockedError(`Mandate ${env.mandate_id} is invalid: ${verdict.reason}`, 412, 'mandate_invalid');
+        }
+    }
+    if (env.policy_id && !deps.hooks?.applyPolicy) {
+        throw new RouterBlockedError(`policy_id ${env.policy_id} present but no policy engine is wired (fail closed)`, 412, 'policy_engine_unavailable');
+    }
+}
+async function checkQuotaOnce(req, ctx, deps) {
+    const quotaCheck = await deps.quota(ctx.userId, Math.ceil(promptChars(req) / 4));
+    if (!quotaCheck.allowed) {
+        throw new Error(`Token quota exceeded. ${quotaCheck.remainingTokens} tokens remaining. Quota resets at ${quotaCheck.quotaResetAt}.`);
+    }
+}
+/**
+ * Walk the chain applying availability, the privacy gate, per-backend policy,
+ * and adapter eligibility (§3.3/§7.1 #3-4, §8.2). Yields callable candidates
+ * in order; records why each skipped tier was skipped.
+ */
+async function* eligibleTiers(req, ctx, deps, state) {
+    const env = req.cloudpeers;
+    const chain = resolveChain(env.task_class, env.backend_hint);
+    for (const tierNo of chain) {
+        const tier = TIERS[tierNo];
+        const adapter = deps.adapters[tier.provider];
+        if (!adapter?.available())
+            continue; // tier not deployed (e.g. Tier 0 pre-OpenMed) — next
+        const gate = evaluateGate(env.sovereignty_class, tier);
+        if (gate === 'blocked') {
+            console.warn(`[privacy-gate] BLOCKED local_only → tier${tier.tier}/${tier.provider} (op=${ctx.operation} svc=${ctx.serviceId})`);
+            continue; // fail closed on this tier
+        }
+        if (gate === 'would_block') {
+            state.requestGate = 'would_block';
+            // Stage 1 MONITOR: the log line the Stage-3 flip decision is made from.
+            console.warn(`[privacy-gate-monitor] would_block local_only → tier${tier.tier}/${tier.provider} (op=${ctx.operation} svc=${ctx.serviceId} task=${env.task_class})`);
+        }
+        if (env.policy_id && deps.hooks?.applyPolicy) {
+            const verdict = await deps.hooks.applyPolicy(env.policy_id, {
+                backend_id: tier.provider,
+                model: tier.model,
+                tier: tier.tier,
+            });
+            if (!verdict.allowed) {
+                console.warn(`[model-router] policy ${env.policy_id} denied tier${tier.tier}/${tier.provider}: ${verdict.reason}`);
+                continue;
+            }
+        }
+        // §8.2 — a backend that cannot satisfy the request's tool use is skipped,
+        // never silently degraded (dropping tool calls entirely is not "degraded").
+        if (req.tools?.length && !adapter.supports_tool_use) {
+            if (env.tool_use_strict)
+                state.toolStrictViolation = true;
+            continue;
+        }
+        const eligibility = await adapter.isEligible(req, {
+            sovereignty_class: env.sovereignty_class,
+            tier: tier.tier,
+            gate,
+        });
+        if (!eligibility.eligible) {
+            const reason = eligibility.reason ?? 'ineligible';
+            console.warn(`[model-router] tier${tier.tier}/${tier.provider} ineligible: ${reason}`);
+            continue;
+        }
+        yield { tier, adapter, gate };
+    }
+}
+function exhaustedError(env, state, lastError) {
+    if (state.toolStrictViolation) {
+        return new RouterBlockedError(`tool_use_strict: no eligible backend supports the requested tool use for ${env.task_class}`, 422, 'tool_use_unsupported');
+    }
+    if (state.requestGate !== 'would_block' && env.sovereignty_class === 'local_only') {
+        return new RouterBlockedError(`No permitted tier for local_only ${env.task_class} (gate enforced and Tier 0 unavailable)`);
+    }
+    return lastError ?? new Error(`No available tier for task class ${env.task_class}`);
+}
+/** §7.2 post-call hooks + §10 uniform metering. Observation-only; never gates. */
+async function postCall(candidate, stripped, response, latencyMs, req, ctx, deps, state) {
+    const env = req.cloudpeers;
+    const usage = {
+        ...candidate.adapter.reportUsage(stripped, response),
+        latency_ms: latencyMs,
+        sovereignty_class: env.sovereignty_class,
+    };
+    let outcomeMatches;
+    if (env.mandate_id && deps.hooks?.verifyOutcome) {
+        try {
+            outcomeMatches = (await deps.hooks.verifyOutcome(env.mandate_id, response)).outcome_matches_mandate;
+        }
+        catch (err) {
+            console.warn('[model-router] outcome verification failed (non-blocking):', err?.message);
+        }
+    }
+    if (env.attribution_chain) {
+        if (deps.hooks?.writeAttribution) {
+            await deps.hooks
+                .writeAttribution([...env.attribution_chain, `model-router:${usage.backend_id}`], usage)
+                .catch((err) => console.warn('[model-router] attribution write failed (non-blocking):', err?.message));
+        }
+        else {
+            console.warn('[model-router] attribution_chain present but no attribution writer is wired');
+        }
+    }
+    const gate = state.requestGate === 'would_block' ? 'would_block' : candidate.gate;
+    await deps
+        .meter({
+        userId: ctx.userId,
+        serviceId: ctx.serviceId,
+        model: candidate.tier.model,
+        operation: ctx.operation,
+        promptTokens: usage.tokens_in,
+        completionTokens: usage.tokens_out,
+        metadata: {
+            ...ctx.metadata,
+            router: {
+                provider: candidate.tier.provider,
+                tier: candidate.tier.tier,
+                taskClass: env.task_class,
+                gate,
+                ...(outcomeMatches !== undefined ? { outcome_matches_mandate: outcomeMatches } : {}),
+            },
+        },
+    })
+        .catch((err) => console.error('[model-router] metering failed (non-blocking):', err?.message));
+    return usage;
+}
+/**
+ * Spec API — route an Anthropic-shape request with a `cloudpeers` envelope
+ * (§4). Returns the full Anthropic response plus routing telemetry.
+ */
+export async function routeMessages(input, ctx, deps) {
+    const req = parseRouterRequest(input);
+    const env = req.cloudpeers;
+    await enforcePreCall(env, deps);
+    await checkQuotaOnce(req, ctx, deps);
+    const state = { requestGate: 'allowed', toolStrictViolation: false };
+    let escalations = 0;
+    let lastError = null;
+    let bestEffort = null;
+    for await (const candidate of eligibleTiers(req, ctx, deps, state)) {
+        const stripped = stripEnvelope(req, candidate.tier.model);
+        const started = performance.now();
+        try {
+            const response = await candidate.adapter.invoke(stripped, {
+                userId: ctx.userId,
+                serviceId: ctx.serviceId,
+                operation: ctx.operation,
+                signal: ctx.signal,
+            });
+            const usage = await postCall(candidate, stripped, response, Math.round(performance.now() - started), req, ctx, deps, state);
+            const result = {
+                response,
+                provider: candidate.tier.provider,
+                model: candidate.tier.model,
+                tier: candidate.tier.tier,
+                escalations,
+                degraded: false,
+                gate: state.requestGate === 'would_block' ? 'would_block' : candidate.gate,
+                usage,
+            };
+            if (ctx.validate && !ctx.validate(firstText(response.content))) {
+                // Confidence v1: shape validation failed — keep as best-effort, escalate.
+                bestEffort = { ...result, degraded: true };
+                escalations++;
+                continue;
+            }
+            return result;
+        }
+        catch (err) {
+            lastError = err;
+            console.warn(`[model-router] tier${candidate.tier.tier}/${candidate.tier.provider} failed (op=${ctx.operation}): ${lastError.message}`);
+            escalations++;
+        }
+    }
+    if (bestEffort)
+        return { ...bestEffort, escalations };
+    throw exhaustedError(env, state, lastError);
+}
+/**
+ * Streaming variant. Pre-call enforcement is identical; the first eligible
+ * streaming-capable tier serves the request (no mid-stream escalation — a
+ * failed stream surfaces to the caller).
+ */
+export async function routeMessagesStream(input, ctx, deps) {
+    const req = parseRouterRequest(input);
+    const env = req.cloudpeers;
+    await enforcePreCall(env, deps);
+    await checkQuotaOnce(req, ctx, deps);
+    const state = { requestGate: 'allowed', toolStrictViolation: false };
+    for await (const candidate of eligibleTiers(req, ctx, deps, state)) {
+        if (!candidate.adapter.supports_streaming)
+            continue;
+        const stripped = stripEnvelope(req, candidate.tier.model);
+        const gate = state.requestGate === 'would_block' ? 'would_block' : candidate.gate;
+        const started = performance.now();
+        const events = candidate.adapter.invokeStream(stripped, {
+            userId: ctx.userId,
+            serviceId: ctx.serviceId,
+            operation: ctx.operation,
+            signal: ctx.signal,
+        });
+        const metered = async function* () {
+            let inputTokens = 0;
+            let outputTokens = 0;
+            let stopReason = null;
+            for await (const event of events) {
+                if (event.type === 'message_start') {
+                    const usage = event.message?.usage;
+                    inputTokens = usage?.input_tokens ?? 0;
+                }
+                if (event.type === 'message_delta') {
+                    const usage = event.usage;
+                    if (usage?.output_tokens !== undefined)
+                        outputTokens = usage.output_tokens;
+                    if (usage?.input_tokens !== undefined)
+                        inputTokens = usage.input_tokens;
+                    stopReason = event.delta?.stop_reason ?? stopReason;
+                }
+                yield event;
+            }
+            const response = {
+                id: 'streamed',
+                type: 'message',
+                role: 'assistant',
+                content: [],
+                model: candidate.tier.model,
+                stop_reason: stopReason,
+                usage: { input_tokens: inputTokens, output_tokens: outputTokens },
+            };
+            await postCall(candidate, stripped, response, Math.round(performance.now() - started), req, ctx, deps, state);
+        };
+        return {
+            provider: candidate.tier.provider,
+            model: candidate.tier.model,
+            tier: candidate.tier.tier,
+            gate,
+            stream: metered(),
+        };
+    }
+    throw exhaustedError(env, state, null);
+}
+/**
+ * v1 convenience API — prompt in, text out. Behavior-identical to
+ * ModelRouter v1 (first caller: mcp lab-coaching); implemented over
+ * routeMessages so both APIs share one enforcement path.
+ */
+export async function routeModel(req, deps) {
+    const request = {
+        messages: [{ role: 'user', content: req.prompt }],
+        ...(req.system !== undefined ? { system: req.system } : {}),
+        ...(req.maxTokens !== undefined ? { max_tokens: req.maxTokens } : {}),
+        ...(req.temperature !== undefined ? { temperature: req.temperature } : {}),
+        cloudpeers: { v: 1, sovereignty_class: req.sovereigntyClass, task_class: req.taskClass },
+    };
+    const result = await routeMessages(request, {
+        userId: req.userId,
+        serviceId: req.serviceId,
+        operation: req.operation,
+        metadata: req.metadata,
+        validate: req.validate,
+    }, deps);
+    return {
+        text: firstText(result.response.content),
+        provider: result.provider,
+        model: result.model,
+        tier: result.tier,
+        escalations: result.escalations,
+        degraded: result.degraded,
+        gate: result.gate,
+        promptTokens: result.usage.tokens_in,
+        completionTokens: result.usage.tokens_out,
+        totalTokens: result.usage.tokens_in + result.usage.tokens_out,
+    };
+}