pi-smart-router 0.1.0

package/src/domain/types/schemas.ts

@@ -0,0 +1,289 @@
+/**
+ * Zod schemas mirroring JSON-schema contracts and data-model entities.
+ *
+ * Canonical contract sources:
+ *   - specs/001-build-smart-router/contracts/routing-request.schema.json
+ *   - specs/001-build-smart-router/contracts/routing-decision.schema.json
+ *   - specs/001-build-smart-router/data-model.md
+ */
+
+import { z } from 'zod';
+
+// ─── Enum schemas ────────────────────────────────────────────────────────────
+
+export const TurnTypeSchema = z.enum([
+  'planning',
+  'tool_result',
+  'subagent',
+  'main_loop',
+  'unknown',
+]);
+
+export const PinReasonSchema = z.enum([
+  'initial',
+  'user_forced',
+  'loop_escalation',
+  'compaction',
+  'cache_economics',
+  'context_overflow',
+]);
+
+export const TierSchema = z.enum([
+  'zero-tier',
+  'economical-cloud',
+  'frontier-cloud',
+]);
+
+export const RoutingStageSchema = z.enum([
+  'triage',
+  'turn_envelope',
+  'session_pin',
+  'local_zero',
+  'hydra_match',
+  'fallback',
+]);
+
+export const PriceSourceSchema = z.enum([
+  'override',
+  'registry',
+  'yaml_fallback',
+]);
+
+export const MessageRoleSchema = z.enum([
+  'user',
+  'assistant',
+  'system',
+  'tool',
+]);
+
+// ─── Message (contract: routing-request.schema.json) ─────────────────────────
+
+export const MessageSchema = z.object({
+  role: MessageRoleSchema,
+  content: z.string(),
+  tool_call_id: z.string().optional(),
+  tool_calls: z.array(z.unknown()).optional(),
+});
+
+// ─── RoutingRequest (contract: routing-request.schema.json) ──────────────────
+
+export const RoutingRequestSchema = z.object({
+  request_id: z.string().uuid(),
+  session_id: z.string().min(1),
+  prompt_text: z.string(),
+  messages: z.array(MessageSchema).optional(),
+  turn_type: TurnTypeSchema.optional(),
+  compaction_flag: z.boolean().optional(),
+  force_model_id: z.string().optional(),
+  candidate_model_id: z.string().optional(),
+  estimated_input_tokens: z.number().int().nonnegative().optional(),
+});
+
+// ─── SessionPin (data-model.md) ──────────────────────────────────────────────
+
+export const SessionPinSchema = z.object({
+  session_id: z.string(),
+  pinned_model_id: z.string(),
+  pin_reason: PinReasonSchema,
+  has_ever_switched: z.boolean(),
+  consecutive_upstream_errors: z.number().int().nonnegative(),
+  consecutive_tool_failures: z.number().int().nonnegative(),
+  last_tool_failure_signature: z.string().nullable(),
+  created_at: z.string().datetime(),
+  updated_at: z.string().datetime(),
+});
+
+// ─── ModelProfile (data-model.md) ────────────────────────────────────────────
+
+export const ModelCapabilitiesSchema = z.object({
+  reasoning: z.number().min(0).max(1),
+  code_gen: z.number().min(0).max(1),
+  tool_use: z.number().min(0).max(1),
+});
+
+export const ModelPerformanceSchema = z.object({
+  latency_p50_ms: z.number().optional(),
+  verbosity_factor: z.number().optional(),
+  cache_friendly: z.boolean().optional(),
+});
+
+export const ModelPricingSchema = z.object({
+  registry_key: z.string().optional(),
+  fallback_cost_per_1m: z.number(),
+});
+
+export const ModelLimitsSchema = z.object({
+  max_input_tokens: z.number().int().positive().optional(),
+  max_output_tokens: z.number().int().positive().optional(),
+});
+
+export const ModelProfileSchema = z.object({
+  id: z.string(),
+  tier: TierSchema,
+  provider: z.string(),
+  endpoint: z.string().optional(),
+  capabilities: ModelCapabilitiesSchema,
+  performance: ModelPerformanceSchema.optional(),
+  pricing: ModelPricingSchema,
+  limits: ModelLimitsSchema.optional(),
+  healthy: z.boolean().optional(),
+});
+
+/** Zod-validated model profile — aligned with {@link ModelProfile} in entities.ts. */
+export type ValidatedModelProfile = z.infer<typeof ModelProfileSchema>;
+
+// ─── CandidateScore (contract: routing-decision.schema.json) ─────────────────
+
+export const CandidateScoreSchema = z.object({
+  model_id: z.string(),
+  score: z.number(),
+  shortfall: z.number(),
+  rejected_reason: z.string().nullable(),
+});
+
+// ─── RoutingDecision (contract: routing-decision.schema.json) ────────────────
+
+export const RoutingDecisionSchema = z.object({
+  request_id: z.string().uuid(),
+  selected_model_id: z.string(),
+  tier: TierSchema,
+  stage: RoutingStageSchema,
+  reason_code: z.string(),
+  candidates: z.array(CandidateScoreSchema).optional(),
+  estimated_cost_usd: z.number().nonnegative().optional(),
+  routing_latency_ms: z.number().nonnegative(),
+  pin_reason: PinReasonSchema.nullable(),
+});
+
+// ─── PriceCatalog (data-model.md) ────────────────────────────────────────────
+
+export const PriceCatalogSchema = z.object({
+  registry_snapshot: z.record(z.string(), z.number()),
+  registry_limits_snapshot: z.record(z.string(), ModelLimitsSchema).optional(),
+  user_overrides: z.record(z.string(), z.number()),
+  last_updated: z.string().datetime(),
+  source: PriceSourceSchema,
+});
+
+// ─── RoutingTelemetry (data-model.md) ────────────────────────────────────────
+
+export const RoutingTelemetrySchema = z.object({
+  timestamp: z.string().datetime(),
+  session_id: z.string(),
+  request_id: z.string(),
+  turn_type: z.string(),
+  stage: z.string(),
+  reason_code: z.string(),
+  selected_model_id: z.string(),
+  estimated_cost_usd: z.number(),
+  routing_latency_ms: z.number(),
+  pin_reason: z.string().nullable(),
+});
+
+// ─── Operator configuration schema (data-model.md § Configuration) ───────────
+
+export const FrugalityConfigSchema = z.object({
+  lambda_cost: z.number().min(0).max(1),
+  lambda_latency: z.number().min(0),
+  lambda_verbosity: z.number().min(0),
+});
+
+export const LoopEscalationConfigSchema = z.object({
+  threshold: z.number().int().positive(),
+});
+
+export const PricingConfigSchema = z.object({
+  staleness_days: z.number().int().positive(),
+});
+
+export const LocalConfigSchema = z.object({
+  min_memory_gb_full: z.number().positive(),
+  min_memory_gb_classification: z.number().positive(),
+  battery_threshold_pct: z.number().min(0).max(100),
+});
+
+export const HydraConfigSchema = z.object({
+  artifact_cache_path: z.string(),
+});
+
+export const LowIntensityWeightsSchema = z.object({
+  prompt_shortness: z.number().min(0),
+  token_shortness: z.number().min(0),
+  cyclomatic_low: z.number().min(0),
+  trivial_signal: z.number().min(0),
+  complex_inverse: z.number().min(0),
+  triage_verdict: z.number().min(0),
+  turn_type: z.number().min(0),
+  no_tool_context: z.number().min(0),
+  message_shallow: z.number().min(0),
+  prose_ratio: z.number().min(0),
+  requirement_low: z.number().min(0),
+  cluster_signal: z.number().min(0),
+});
+
+export const LowIntensityConfigSchema = z.object({
+  weights: LowIntensityWeightsSchema,
+  high_threshold: z.number().min(0).max(1),
+  low_threshold: z.number().min(0).max(1),
+  /** Minimum P_success_cheap to bias toward economical/local tier (SP-105). */
+  p_success_alpha: z.number().min(0).max(1),
+}).superRefine((value, ctx) => {
+  if (value.high_threshold <= value.low_threshold) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: 'high_threshold must be greater than low_threshold',
+      path: ['high_threshold'],
+    });
+  }
+});
+
+export const RoutingClustersConfigSchema = z.object({
+  config_path: z.string().min(1),
+});
+
+/** Stable snake_case cluster id — used as reason-code suffix (`cluster_${id}`). */
+export const RoutingClusterIdSchema = z
+  .string()
+  .min(1)
+  .regex(/^[a-z][a-z0-9_]*$/, 'Cluster id must be lowercase snake_case');
+
+export const RoutingClusterSchema = z.object({
+  id: RoutingClusterIdSchema,
+  tier_bias: TierSchema,
+  reference_prompts: z.array(z.string().min(1)).min(1),
+  min_similarity: z.number().min(0).max(1),
+  min_margin: z.number().min(0).max(1),
+});
+
+export const RoutingClustersFileSchema = z
+  .object({
+    clusters: z.array(RoutingClusterSchema).min(1),
+  })
+  .superRefine((value, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, cluster] of value.clusters.entries()) {
+      if (seen.has(cluster.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Duplicate cluster id: ${cluster.id}`,
+          path: ['clusters', index, 'id'],
+        });
+      }
+      seen.add(cluster.id);
+    }
+  });
+
+export const OperatorConfigSchema = z.object({
+  frugality: FrugalityConfigSchema,
+  loop_escalation: LoopEscalationConfigSchema,
+  pricing: PricingConfigSchema,
+  local: LocalConfigSchema,
+  hydra: HydraConfigSchema,
+  low_intensity: LowIntensityConfigSchema,
+  routing_clusters: RoutingClustersConfigSchema.optional(),
+});
+
+// ─── Inferred types ──────────────────────────────────────────────────────────
+
+export type OperatorConfig = z.infer<typeof OperatorConfigSchema>;
+export type LowIntensityConfig = z.infer<typeof LowIntensityConfigSchema>;

package/src/domain/types/store-port.ts

@@ -0,0 +1,59 @@
+/**
+ * Persistence port for routing state.
+ * Implementations live in infrastructure/ (SQLite, in-memory for tests).
+ */
+
+import type { ModelProfile, PriceCatalog, RoutingDatasetRecord, RoutingOutcomeRecord, RoutingTelemetry, SessionPin } from './entities.js';
+
+export interface ListTelemetryOptions {
+  readonly limit?: number;
+  readonly sessionId?: string;
+}
+
+export interface ListDatasetOptions {
+  readonly limit?: number;
+}
+
+export interface ListOutcomeOptions {
+  readonly limit?: number;
+  readonly requestId?: string;
+  readonly sessionId?: string;
+}
+
+export interface StorePort {
+  /** Retrieve an active session pin, or null if unpinned. */
+  getSessionPin(sessionId: string): Promise<SessionPin | null>;
+
+  /** Upsert a session pin (create or replace). */
+  putSessionPin(pin: SessionPin): Promise<void>;
+
+  /** Delete a session pin (e.g. on explicit unpin). */
+  deleteSessionPin(sessionId: string): Promise<void>;
+
+  /** Load the full model fleet catalog. */
+  getModelProfiles(): Promise<readonly ModelProfile[]>;
+
+  /** Load the current price catalog. */
+  getPriceCatalog(): Promise<PriceCatalog | null>;
+
+  /** Persist an updated price catalog. */
+  putPriceCatalog(catalog: PriceCatalog): Promise<void>;
+
+  /** Append a routing telemetry audit record (sync hot path). */
+  appendTelemetry(entry: RoutingTelemetry): void;
+
+  /** List recent telemetry rows, newest first. */
+  listTelemetry(options?: ListTelemetryOptions): Promise<readonly RoutingTelemetry[]>;
+
+  /** Append a privacy-safe routing dataset record (sync hot path). */
+  appendDatasetRecord(entry: RoutingDatasetRecord): void;
+
+  /** List recent dataset rows, newest first. */
+  listDatasetRecords(options?: ListDatasetOptions): Promise<readonly RoutingDatasetRecord[]>;
+
+  /** Append a behavioral outcome label (sync hot path). */
+  appendOutcomeRecord(entry: RoutingOutcomeRecord): void;
+
+  /** List recent outcome rows, newest first. */
+  listOutcomeRecords(options?: ListOutcomeOptions): Promise<readonly RoutingOutcomeRecord[]>;
+}

package/src/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Public package exports — pi-smart-router.
+ *
+ * Exposes the router factory (T022) and pi lifecycle hook registrar (T021).
+ * Full pi integration uses `.pi/extensions/smart-router/`; library embedders
+ * route via `dispatch.dispatch()` after calling `register(hooks)`.
+ */
+
+import type { ModelProfile, RoutingDecision } from './domain/types/index.js';
+import { loadModels, type FleetCatalog } from './config/models-loader.js';
+import {
+  loadRoutingClusters,
+  clusterReasonCode,
+  type TextEmbedder,
+} from './config/routing-clusters-loader.js';
+import {
+  GatewayDispatch,
+  type GatewayDispatchOptions,
+} from './infrastructure/gateway/gateway-dispatch.js';
+import {
+  createPiRouterMiddleware,
+  LifecycleHookState,
+  type PiRouterMiddleware,
+  type PiExtensionHooks,
+} from './api/middleware/pi-router-middleware.js';
+
+/** Package identifier for diagnostics and telemetry. */
+export const PACKAGE_NAME = 'pi-smart-router' as const;
+
+// ─── Router factory types ────────────────────────────────────────────────────
+
+export interface RouterFactoryOptions {
+  readonly modelsPath?: string;
+}
+
+export interface RouterHandle {
+  readonly version: string;
+  readonly middleware: PiRouterMiddleware;
+  readonly dispatch: GatewayDispatch;
+  readonly fleet: readonly ModelProfile[];
+  readonly register: (hooks: PiExtensionHooks) => void;
+}
+
+// ─── Router factory (T022) ───────────────────────────────────────────────────
+
+export function createRouter(options?: RouterFactoryOptions): RouterHandle {
+  const catalog = loadModels(
+    options?.modelsPath ? { filePath: options.modelsPath } : undefined,
+  );
+
+  return createRouterFromCatalog(catalog);
+}
+
+export function createRouterFromCatalog(catalog: FleetCatalog): RouterHandle {
+  return createRouterFromFleet([...catalog.models]);
+}
+
+export interface CreateRouterFromFleetOptions extends GatewayDispatchOptions {
+  readonly lifecycleHookState?: LifecycleHookState;
+}
+
+export function createRouterFromFleet(
+  fleet: ModelProfile[],
+  options?: CreateRouterFromFleetOptions,
+): RouterHandle {
+  const { lifecycleHookState, ...dispatchOptions } = options ?? {};
+  const dispatch = new GatewayDispatch(fleet, dispatchOptions);
+  const middleware = createPiRouterMiddleware(
+    lifecycleHookState !== undefined ? { lifecycleHookState } : undefined,
+  );
+
+  return {
+    version: 'pi-smart-router',
+    middleware,
+    dispatch,
+    fleet,
+    register: middleware.register,
+  };
+}
+
+// ─── Re-exports for consumer convenience ─────────────────────────────────────
+
+export type { RoutingDecision, ModelProfile };
+export {
+  loadRoutingClusters,
+  clusterReasonCode,
+};
+export type { TextEmbedder };
+export type { RoutingClusterCatalog } from './domain/types/index.js';
+export type {
+  PiRouterMiddleware,
+  PiRouterMiddlewareOptions,
+  PiExtensionHooks,
+  PiExtensionContext,
+  PiProviderRequestEvent,
+  PiContextEvent,
+  PiModelSelectEvent,
+  PiSessionManager,
+  LifecycleFlags,
+} from './api/middleware/pi-router-middleware.js';
+export { createPiRouterMiddleware, LifecycleHookState } from './api/middleware/pi-router-middleware.js';
+export type { GatewayDispatchOptions } from './infrastructure/gateway/gateway-dispatch.js';
+export type { PipelineOptions } from './domain/pipeline/router-pipeline.js';

package/src/infra/gemini-provider.ts

@@ -0,0 +1,142 @@
+/**
+ * Gemini provider error classification and failover policy.
+ *
+ * thought_signature 400s are client/protocol validation errors (FR-018),
+ * not infrastructure outages — they must return terminal errors, not trigger
+ * stream delegation failover.
+ */
+
+import type { AssistantMessage } from '@earendil-works/pi-ai/compat';
+
+export interface GeminiProviderError {
+  readonly statusCode?: number;
+  readonly code?: string;
+  readonly message?: string;
+}
+
+/**
+ * Gemini returns 400 INVALID_ARGUMENT when tool-call replay omits thought_signature.
+ */
+export function isGeminiThoughtSignatureError(parsed: GeminiProviderError): boolean {
+  return (
+    parsed.statusCode === 400 &&
+    parsed.message?.includes('thought_signature') === true
+  );
+}
+
+export function isGeminiThoughtSignatureAssistantError(message: AssistantMessage): boolean {
+  if (message.stopReason !== 'error' || !message.errorMessage) {
+    return false;
+  }
+  return isGeminiThoughtSignatureError(parseGeminiErrorBlob(message.errorMessage));
+}
+
+/**
+ * Returns true when a Gemini provider error should trigger failover.
+ * thought_signature validation failures are terminal — never failover.
+ */
+export function shouldFailoverOnGeminiError(parsed: GeminiProviderError): boolean {
+  if (isGeminiThoughtSignatureError(parsed)) {
+    return false;
+  }
+  return parsed.statusCode !== undefined && (parsed.statusCode >= 500 || parsed.statusCode === 429);
+}
+
+const GEMINI_THOUGHT_SIGNATURE_DOCS =
+  'https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures';
+const PI_THOUGHT_SIGNATURE_ISSUE = 'https://github.com/earendil-works/pi/issues/6342';
+
+/**
+ * Format a Gemini thought_signature validation error with operator workarounds.
+ */
+export function formatGeminiThoughtSignatureErrorMessage(errorMessage: string): string {
+  const parsed = parseGeminiErrorBlob(errorMessage);
+  const prefixParts: string[] = [];
+  if (parsed.statusCode !== undefined) {
+    prefixParts.push(String(parsed.statusCode));
+  }
+  if (parsed.code) {
+    prefixParts.push(parsed.code);
+  }
+  const summary =
+    parsed.message && prefixParts.length > 0
+      ? `${prefixParts.join(' ')}: ${parsed.message}`
+      : parsed.message ?? 'Provider error (thought_signature validation)';
+
+  return [
+    summary,
+    '',
+    'Gemini rejected this request because a prior tool call is missing its thought_signature (protocol validation, not provider outage).',
+    'Workarounds: start a fresh session with /new, or route to a non-Google model until pi preserves thought signatures in replay.',
+    `Docs: ${GEMINI_THOUGHT_SIGNATURE_DOCS}`,
+    `Upstream: ${PI_THOUGHT_SIGNATURE_ISSUE}`,
+  ].join('\n');
+}
+
+function parseGeminiErrorBlob(errorMessage: string): GeminiProviderError {
+  const trimmed = errorMessage.trim();
+  if (!trimmed.startsWith('{')) {
+    return trimmed.includes('thought_signature') ? { statusCode: 400, message: trimmed } : {};
+  }
+
+  try {
+    const parsed = JSON.parse(trimmed) as {
+      error?: { code?: unknown; status?: unknown; message?: unknown };
+      code?: unknown;
+      status?: unknown;
+      message?: unknown;
+    };
+
+    const nested = parsed.error;
+    const statusCode =
+      parseNumericCode(nested?.code) ??
+      parseNumericCode(nested?.status) ??
+      parseNumericCode(parsed.code) ??
+      parseNumericCode(parsed.status);
+
+    const code =
+      typeof nested?.status === 'string'
+        ? nested.status
+        : typeof parsed.status === 'string'
+          ? parsed.status
+          : undefined;
+
+    let message =
+      typeof nested?.message === 'string'
+        ? nested.message
+        : typeof parsed.message === 'string'
+          ? parsed.message
+          : undefined;
+
+    if (message?.trim().startsWith('{')) {
+      try {
+        const inner = JSON.parse(message) as { error?: { message?: unknown }; message?: unknown };
+        if (typeof inner.error?.message === 'string') {
+          message = inner.error.message;
+        } else if (typeof inner.message === 'string') {
+          message = inner.message;
+        }
+      } catch {
+        // keep outer message
+      }
+    }
+
+    return {
+      ...(statusCode !== undefined ? { statusCode } : {}),
+      ...(code ? { code } : {}),
+      ...(message ? { message } : {}),
+    };
+  } catch {
+    return {};
+  }
+}
+
+function parseNumericCode(value: unknown): number | undefined {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === 'string' && /^\d+$/.test(value)) {
+    return Number.parseInt(value, 10);
+  }
+  return undefined;
+}