pi-smart-router 0.1.0

package/src/infrastructure/pricing/litellm-fetch.ts

@@ -0,0 +1,215 @@
+/**
+ * LiteLLM pricing fetch — manual refresh path (SP-045).
+ *
+ * Fetches the public LiteLLM model pricing JSON and normalizes chat-model
+ * rates into PriceCatalog.registry_snapshot entries keyed by model id and
+ * provider/model aliases for tri-tier broker lookup.
+ */
+
+import type { ModelLimits, PriceCatalog } from '../../domain/types/index.js';
+
+export const DEFAULT_LITELLM_PRICING_URL =
+  'https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json';
+
+const CHAT_MODES = new Set(['chat', 'completion']);
+
+export interface LitellmFetchResult {
+  readonly registry_snapshot: Readonly<Record<string, number>>;
+  readonly registry_limits_snapshot: Readonly<Record<string, ModelLimits>>;
+  /** Number of LiteLLM chat/completion models normalized (before alias keys). */
+  readonly model_count: number;
+}
+
+export interface LitellmFetchDeps {
+  readonly fetchFn?: typeof fetch;
+  readonly pricingUrl?: string;
+}
+
+export class LitellmFetchError extends Error {
+  override readonly name = 'LitellmFetchError';
+}
+
+/**
+ * Resolve pricing URL from env with documented LiteLLM GitHub default.
+ */
+export function getLitellmPricingUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env.LITELLM_PRICING_URL?.trim();
+  return configured && configured.length > 0 ? configured : DEFAULT_LITELLM_PRICING_URL;
+}
+
+/**
+ * Weighted blend of input/output per-token rates → USD per 1M tokens.
+ * Matches the registry-cost formula planned for SP-046.
+ */
+export function computeCostPer1MTokens(
+  inputCostPerToken: number,
+  outputCostPerToken: number,
+): number {
+  const inputPer1M = inputCostPerToken * 1_000_000;
+  const outputPer1M = outputCostPerToken * 1_000_000;
+  return (inputPer1M + outputPer1M) / 2;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readNumberField(entry: Record<string, unknown>, field: string): number | undefined {
+  const value = entry[field];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function readStringField(entry: Record<string, unknown>, field: string): string | undefined {
+  const value = entry[field];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function readPositiveIntField(entry: Record<string, unknown>, field: string): number | undefined {
+  const value = entry[field];
+  return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
+}
+
+function parseModelLimits(entry: Record<string, unknown>): ModelLimits | undefined {
+  const maxInputTokens = readPositiveIntField(entry, 'max_input_tokens');
+  const maxOutputTokens =
+    readPositiveIntField(entry, 'max_output_tokens') ?? readPositiveIntField(entry, 'max_tokens');
+
+  if (maxInputTokens === undefined && maxOutputTokens === undefined) {
+    return undefined;
+  }
+
+  return {
+    ...(maxInputTokens !== undefined ? { max_input_tokens: maxInputTokens } : {}),
+    ...(maxOutputTokens !== undefined ? { max_output_tokens: maxOutputTokens } : {}),
+  };
+}
+
+function storeLimitsAlias(
+  registry_limits_snapshot: Record<string, ModelLimits>,
+  key: string,
+  limits: ModelLimits,
+): void {
+  registry_limits_snapshot[key] = limits;
+}
+
+/**
+ * Normalize LiteLLM pricing JSON into registry_snapshot rates.
+ * Validates shape and fails fast with actionable errors.
+ */
+export function normalizeLitellmPricing(raw: unknown): LitellmFetchResult {
+  if (!isRecord(raw)) {
+    throw new LitellmFetchError(
+      'LiteLLM pricing response must be a JSON object. Check LITELLM_PRICING_URL points at model_prices_and_context_window.json.',
+    );
+  }
+
+  const registry_snapshot: Record<string, number> = {};
+  const registry_limits_snapshot: Record<string, ModelLimits> = {};
+  let modelCount = 0;
+
+  for (const [modelKey, entry] of Object.entries(raw)) {
+    if (modelKey === 'sample_spec') {
+      continue;
+    }
+
+    if (!isRecord(entry)) {
+      throw new LitellmFetchError(
+        `LiteLLM pricing entry "${modelKey}" must be an object. Received ${typeof entry}.`,
+      );
+    }
+
+    const mode = readStringField(entry, 'mode');
+    if (mode !== undefined && !CHAT_MODES.has(mode)) {
+      continue;
+    }
+
+    const inputCost = readNumberField(entry, 'input_cost_per_token');
+    const outputCost = readNumberField(entry, 'output_cost_per_token');
+    if (inputCost === undefined || outputCost === undefined) {
+      continue;
+    }
+
+    const costPer1M = computeCostPer1MTokens(inputCost, outputCost);
+    registry_snapshot[modelKey] = costPer1M;
+    modelCount += 1;
+
+    const limits = parseModelLimits(entry);
+    if (limits !== undefined) {
+      storeLimitsAlias(registry_limits_snapshot, modelKey, limits);
+    }
+
+    const provider = readStringField(entry, 'litellm_provider');
+    if (provider !== undefined) {
+      registry_snapshot[`${provider}/${modelKey}`] = costPer1M;
+      if (limits !== undefined) {
+        storeLimitsAlias(registry_limits_snapshot, `${provider}/${modelKey}`, limits);
+      }
+    }
+  }
+
+  if (Object.keys(registry_snapshot).length === 0) {
+    throw new LitellmFetchError(
+      'LiteLLM pricing response contained no chat models with input/output token costs.',
+    );
+  }
+
+  return {
+    registry_snapshot,
+    registry_limits_snapshot,
+    model_count: modelCount,
+  };
+}
+
+export interface LitellmPriceCatalogResult {
+  readonly catalog: PriceCatalog;
+  /** Number of chat/completion models in the LiteLLM source payload. */
+  readonly model_count: number;
+}
+
+/**
+ * Fetch LiteLLM pricing and build a PriceCatalog payload (does not persist).
+ */
+export async function fetchLitellmPriceCatalog(
+  deps: LitellmFetchDeps = {},
+): Promise<LitellmPriceCatalogResult> {
+  const fetchFn = deps.fetchFn ?? fetch;
+  const url = deps.pricingUrl ?? getLitellmPricingUrl();
+
+  let response: Response;
+  try {
+    response = await fetchFn(url);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new LitellmFetchError(
+      `Failed to fetch LiteLLM pricing from ${url}: ${detail}`,
+    );
+  }
+
+  if (!response.ok) {
+    throw new LitellmFetchError(
+      `LiteLLM pricing fetch failed (${response.status} ${response.statusText}) from ${url}`,
+    );
+  }
+
+  let raw: unknown;
+  try {
+    raw = await response.json();
+  } catch {
+    throw new LitellmFetchError(
+      `LiteLLM pricing response from ${url} is not valid JSON.`,
+    );
+  }
+
+  const normalized = normalizeLitellmPricing(raw);
+
+  return {
+    catalog: {
+      registry_snapshot: normalized.registry_snapshot,
+      registry_limits_snapshot: normalized.registry_limits_snapshot,
+      user_overrides: {},
+      last_updated: new Date().toISOString(),
+      source: 'registry',
+    },
+    model_count: normalized.model_count,
+  };
+}

package/src/infrastructure/pricing/price-broker.ts

@@ -0,0 +1,183 @@
+/**
+ * Tri-tier price broker — FR-019 (T053).
+ *
+ * Resolves per-model pricing using a strict priority cascade:
+ *   1. Operator overrides (highest priority)
+ *   2. Registry snapshot (refreshed external data)
+ *   3. YAML/catalog fallback (ModelProfile.pricing.fallback_cost_per_1m)
+ *
+ * The broker is a pure function layer; it reads from the PriceCatalog
+ * and ModelProfile without side effects.
+ */
+
+import type { ModelProfile, ModelLimits, PriceCatalog, PriceSource } from '../../domain/types/index.js';
+import { getDefaultLimitsForTier } from '../../config/pi-model-mapper.js';
+
+export interface ResolvedPrice {
+  readonly model_id: string;
+  readonly cost_per_1m_tokens: number;
+  readonly source: PriceSource;
+}
+
+export interface ResolvedLimits {
+  readonly model_id: string;
+  readonly limits: ModelLimits;
+}
+
+function lookupRegistryLimits(
+  model: ModelProfile,
+  catalog: PriceCatalog,
+): ModelLimits | undefined {
+  const snapshot = catalog.registry_limits_snapshot;
+  if (!snapshot) {
+    return undefined;
+  }
+
+  const registryKey = model.pricing.registry_key ?? model.id;
+  return snapshot[registryKey] ?? snapshot[model.id];
+}
+
+/**
+ * Resolve effective context limits for a model.
+ *
+ * Priority: YAML/profile override → LiteLLM registry snapshot → tier default.
+ */
+export function resolveLimits(
+  model: ModelProfile,
+  catalog: PriceCatalog | null,
+): ResolvedLimits {
+  const yamlLimits = model.limits;
+  const registryLimits = catalog ? lookupRegistryLimits(model, catalog) : undefined;
+  const defaults = getDefaultLimitsForTier(model.tier);
+
+  return {
+    model_id: model.id,
+    limits: {
+      max_input_tokens:
+        yamlLimits?.max_input_tokens ??
+        registryLimits?.max_input_tokens ??
+        defaults.max_input_tokens,
+      max_output_tokens:
+        yamlLimits?.max_output_tokens ??
+        registryLimits?.max_output_tokens ??
+        defaults.max_output_tokens,
+    },
+  };
+}
+
+/**
+ * Apply resolved context limits to fleet profiles for routing gates (SP-092).
+ */
+export function applyCatalogLimitsToFleet(
+  fleet: readonly ModelProfile[],
+  catalog: PriceCatalog | null,
+): ModelProfile[] {
+  return fleet.map((profile) => {
+    const resolved = resolveLimits(profile, catalog);
+    return {
+      ...profile,
+      limits: resolved.limits,
+    };
+  });
+}
+
+/**
+ * Resolve the effective price for a single model.
+ *
+ * Priority: operator override → registry snapshot → catalog fallback.
+ * Always returns a price — the fallback from ModelProfile is guaranteed
+ * by schema to exist.
+ */
+export function resolvePrice(
+  model: ModelProfile,
+  catalog: PriceCatalog | null,
+): ResolvedPrice {
+  if (catalog) {
+    const override = catalog.user_overrides[model.id];
+    if (override !== undefined) {
+      return {
+        model_id: model.id,
+        cost_per_1m_tokens: override,
+        source: 'override',
+      };
+    }
+
+    const registryKey = model.pricing.registry_key ?? model.id;
+    const registryPrice = catalog.registry_snapshot[registryKey];
+    if (registryPrice !== undefined) {
+      return {
+        model_id: model.id,
+        cost_per_1m_tokens: registryPrice,
+        source: 'registry',
+      };
+    }
+  }
+
+  return {
+    model_id: model.id,
+    cost_per_1m_tokens: model.pricing.fallback_cost_per_1m,
+    source: 'yaml_fallback',
+  };
+}
+
+/**
+ * Resolve prices for the entire fleet in a single pass.
+ *
+ * Returns a Map keyed by model ID for O(1) lookup during scoring.
+ */
+export function resolveFleetPrices(
+  fleet: readonly ModelProfile[],
+  catalog: PriceCatalog | null,
+): ReadonlyMap<string, ResolvedPrice> {
+  const prices = new Map<string, ResolvedPrice>();
+  for (const model of fleet) {
+    prices.set(model.id, resolvePrice(model, catalog));
+  }
+  return prices;
+}
+
+/**
+ * Apply tri-tier resolved prices and context limits to fleet profiles.
+ * When no catalog is loaded, applies tier default limits only.
+ */
+export function applyCatalogPricesToFleet(
+  fleet: readonly ModelProfile[],
+  catalog: PriceCatalog | null,
+): ModelProfile[] {
+  if (!catalog) {
+    return applyCatalogLimitsToFleet(fleet, catalog);
+  }
+
+  const prices = resolveFleetPrices(fleet, catalog);
+
+  const priced = fleet.map((profile) => {
+    const resolved = prices.get(profile.id);
+    if (!resolved || resolved.source === 'yaml_fallback') {
+      return profile;
+    }
+
+    return {
+      ...profile,
+      pricing: {
+        ...profile.pricing,
+        fallback_cost_per_1m: resolved.cost_per_1m_tokens,
+      },
+    };
+  });
+
+  return applyCatalogLimitsToFleet(priced, catalog);
+}
+
+/**
+ * Resolve per-request cost rate for frugality scoring and telemetry (SP-096).
+ * Subscription-quota virtual cost takes precedence over API/catalog rates.
+ */
+export function resolveFrugalityCostPer1M(
+  model: ModelProfile,
+  catalog: PriceCatalog | null,
+): number {
+  if (model.pricing.quota_cost_per_1m !== undefined) {
+    return model.pricing.quota_cost_per_1m;
+  }
+  return resolvePrice(model, catalog).cost_per_1m_tokens;
+}

package/src/infrastructure/pricing/pricing-monitor.ts

@@ -0,0 +1,65 @@
+/**
+ * Pricing staleness monitor — FR-020 (T054).
+ *
+ * Checks whether the PriceCatalog's last_updated timestamp exceeds a
+ * configurable staleness threshold (default: 14 days). When stale,
+ * emits a structured warning for operator visibility.
+ *
+ * The monitor is stateless and side-effect-free beyond returning a
+ * diagnostic result. Callers (gateway, CLI, health-check) decide how
+ * to surface the warning.
+ */
+
+import type { PriceCatalog } from '../../domain/types/index.js';
+
+const MS_PER_DAY = 86_400_000;
+
+export interface StalenessResult {
+  readonly stale: boolean;
+  readonly age_days: number;
+  readonly threshold_days: number;
+  readonly warning?: string;
+}
+
+/**
+ * Evaluate pricing freshness against the configured threshold.
+ *
+ * @param catalog       Current price catalog, or null if none loaded.
+ * @param stalenessDays Operator-configured threshold (default 14).
+ * @param now           Reference time for testability.
+ */
+export function checkStaleness(
+  catalog: PriceCatalog | null,
+  stalenessDays: number = 14,
+  now: Date = new Date(),
+): StalenessResult {
+  if (!catalog) {
+    return {
+      stale: true,
+      age_days: Infinity,
+      threshold_days: stalenessDays,
+      warning:
+        'No pricing catalog loaded. Model costs will use YAML fallback values.',
+    };
+  }
+
+  const lastUpdated = new Date(catalog.last_updated);
+  const ageDays = (now.getTime() - lastUpdated.getTime()) / MS_PER_DAY;
+
+  if (ageDays > stalenessDays) {
+    return {
+      stale: true,
+      age_days: Math.round(ageDays * 10) / 10,
+      threshold_days: stalenessDays,
+      warning:
+        `Pricing data is ${Math.round(ageDays)} days old (threshold: ${stalenessDays} days). ` +
+        'Consider refreshing registry rates to ensure accurate cost estimation.',
+    };
+  }
+
+  return {
+    stale: false,
+    age_days: Math.round(ageDays * 10) / 10,
+    threshold_days: stalenessDays,
+  };
+}

package/src/infrastructure/telemetry/dataset-limits.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared retention bounds for routing dataset records (in-memory and SQLite).
+ * GitHub #8: 30 days / 10k rows.
+ */
+
+import type { RoutingDatasetRecord } from '../../domain/types/index.js';
+
+export const DATASET_WINDOW_DAYS = 30;
+export const DATASET_WINDOW_MS = DATASET_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+export const DATASET_MAX_ENTRIES = 10_000;
+
+/** Remove dataset entries older than the rolling window. */
+export function evictExpiredDatasetEntries(
+  entries: RoutingDatasetRecord[],
+  windowMs: number = DATASET_WINDOW_MS,
+): void {
+  const cutoff = Date.now() - windowMs;
+
+  while (entries.length > 0) {
+    const oldest = entries[0]!;
+    if (new Date(oldest.timestamp).getTime() < cutoff) {
+      entries.shift();
+    } else {
+      break;
+    }
+  }
+}
+
+/** Make room for one more dataset entry before append. */
+export function makeDatasetRoom(
+  entries: RoutingDatasetRecord[],
+  maxEntries: number = DATASET_MAX_ENTRIES,
+  windowMs: number = DATASET_WINDOW_MS,
+): void {
+  evictExpiredDatasetEntries(entries, windowMs);
+  while (entries.length >= maxEntries) {
+    entries.shift();
+  }
+}