@mupt-ai/dari-router 0.1.0

package/src/auto_router.ts

@@ -0,0 +1,95 @@
+// Dari Auto Router — a hosted routing policy for self-hosted createRouter
+// users. Dari bills the calling org per selection call.
+
+import { RouterFrameworkError } from "./framework_error.js";
+import { createDariRoutingPolicy, type DariRoutingPolicyOptions } from "./dari_policy.js";
+import type { RoutingPolicy } from "./framework_types.js";
+
+export const DEFAULT_AUTO_ROUTER_ENDPOINT = "https://routing.dari.dev/v1/auto-router";
+export const DEFAULT_AUTO_ROUTER_MODEL = "dari/auto-router";
+export const DEFAULT_AUTO_ROUTER_CONTEXT_WINDOW_CHARS = 32_000;
+
+export type CreateAutoRouterOptions<Metadata = unknown> = {
+  apiKey: string;
+  endpoint?: string;
+} & Omit<
+  DariRoutingPolicyOptions<Metadata>,
+  | "selector"
+  | "runtime"
+  | "selectorModel"
+  | "selectorContextWindowChars"
+  | "strategy"
+  | "customConfig"
+>;
+
+export function createAutoRouter<Metadata = unknown>(
+  options: CreateAutoRouterOptions<Metadata>,
+): RoutingPolicy<Metadata> {
+  if (!options.apiKey?.trim()) {
+    throw new RouterFrameworkError(
+      "configuration",
+      "createAutoRouter requires an apiKey.",
+      "auto_router_api_key_missing",
+    );
+  }
+  // The hosted Auto Router serves only the default routing policy and drops
+  // custom rules server-side, so accepting them here would silently ignore
+  // them. Reject loudly instead of routing with rules the user thinks apply.
+  const unsupported = options as { strategy?: unknown; customConfig?: unknown };
+  if (unsupported.strategy !== undefined || unsupported.customConfig !== undefined) {
+    throw new RouterFrameworkError(
+      "configuration",
+      "createAutoRouter does not support custom routing rules (strategy/customConfig): " +
+        "the hosted Dari Auto Router serves only the default policy. Use " +
+        "createDariRoutingPolicy with a self-hosted selector or the Dari managed " +
+        "platform for custom routing.",
+      "auto_router_custom_rules_unsupported",
+    );
+  }
+  const endpoint = (options.endpoint ?? DEFAULT_AUTO_ROUTER_ENDPOINT)
+    .replace(/\/+$/, "")
+    .replace(/\/select$/, "");
+  const {
+    apiKey,
+    endpoint: _endpoint,
+    ...policyOptions
+  } = options;
+
+  return createDariRoutingPolicy<Metadata>({
+    ...policyOptions,
+    selectorModel: DEFAULT_AUTO_ROUTER_MODEL,
+    selectorContextWindowChars: DEFAULT_AUTO_ROUTER_CONTEXT_WINDOW_CHARS,
+    selector: async (request, signal) => {
+      let response: Response;
+      try {
+        response = await fetch(`${endpoint}/select`, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify(request),
+          signal,
+        });
+      } catch (error) {
+        if (error instanceof Error && error.name === "AbortError") throw error;
+        throw new RouterFrameworkError(
+          "policy",
+          `Dari Auto Router request failed: ${error instanceof Error ? error.message : String(error)}`,
+          "auto_router_request_failed",
+          undefined,
+          { cause: error },
+        );
+      }
+      if (!response.ok) {
+        const body = await response.text().catch(() => "");
+        throw new RouterFrameworkError(
+          "policy",
+          `Dari Auto Router returned HTTP ${response.status}: ${body}`,
+          "auto_router_http_error",
+        );
+      }
+      return await response.text();
+    },
+  });
+}

package/src/cache_behavior.ts

@@ -0,0 +1,130 @@
+import { nativeModelId, providerForModel } from "./model_ids.js";
+import type { RouterPrefixHit } from "./types.js";
+
+// Provider prompt caches stop serving a prefix roughly five minutes after it
+// was last written. Stored prefix entries outlive that: a host's lookback
+// keeps them long enough to still name the conversation and the decision it
+// continued from. Only entries inside this window describe warmth.
+export const PREFIX_WARMTH_WINDOW_MS = 5 * 60 * 1000;
+
+// Anthropic checks 20 positions per breakpoint, counting the breakpoint
+// itself as the first, so an old cached breakpoint hits only when at most
+// 19 content blocks were appended after it. These are routing estimates, never
+// billing.
+export const ANTHROPIC_LOOKBACK_BLOCKS = 19;
+export const CROSS_TOKENIZER_RATIO = 1.1;
+const OPENAI_MIN_CACHE_TOKENS = 1024;
+const OPENAI_CACHE_INCREMENT_TOKENS = 128;
+
+export type PromptCacheProvider = "openai" | "anthropic" | "fireworks" | "meta";
+
+// providerForModel() lowercases the provider prefix, so family checks must
+// compare case-insensitively too. Unlike providerForModel this never throws;
+// malformed ids classify as no family.
+function providerPrefix(model: string): string {
+  const slash = model.indexOf("/");
+  return slash <= 0 ? "" : model.slice(0, slash).toLowerCase();
+}
+
+export function isAnthropicFamily(model: string): boolean {
+  return providerPrefix(model) === "anthropic";
+}
+
+export function isOpenAiFamily(model: string): boolean {
+  return providerPrefix(model) === "openai";
+}
+
+function isFireworksFamily(model: string): boolean {
+  return providerPrefix(model) === "fireworks";
+}
+
+function isMetaFamily(model: string): boolean {
+  return providerPrefix(model) === "meta";
+}
+
+export function promptCacheProviderForModel(model: string): PromptCacheProvider | null {
+  if (isOpenAiFamily(model)) return "openai";
+  if (isAnthropicFamily(model)) return "anthropic";
+  if (isFireworksFamily(model)) return "fireworks";
+  if (isMetaFamily(model)) return "meta";
+  return null;
+}
+
+export function openAiCachedPrefixTokens(promptTokens: number): number {
+  if (promptTokens < OPENAI_MIN_CACHE_TOKENS) return 0;
+  const extra = promptTokens - OPENAI_MIN_CACHE_TOKENS;
+  return (
+    OPENAI_MIN_CACHE_TOKENS +
+    Math.floor(extra / OPENAI_CACHE_INCREMENT_TOKENS) * OPENAI_CACHE_INCREMENT_TOKENS
+  );
+}
+
+// Anthropic cache minimums vary by model family. Keep this routing-side
+// estimate conservative for known higher-minimum models; unknown future
+// direct Anthropic models fall back to the common 1024-token threshold.
+export function anthropicMinCacheTokens(model: string): number {
+  if (!isAnthropicFamily(model)) return OPENAI_MIN_CACHE_TOKENS;
+  const native = nativeModelId(model)
+    .toLowerCase()
+    .replace(/(?<=\d)\.(?=\d)/g, "-");
+
+  if (
+    native.includes("opus-4-6") ||
+    native.includes("opus-4-5") ||
+    native.includes("haiku-4-5")
+  ) {
+    return 4096;
+  }
+  if (native.includes("fable-5")) {
+    return 512;
+  }
+  return OPENAI_MIN_CACHE_TOKENS;
+}
+
+export function tokenizerFamily(model: string): string {
+  const provider = providerForModel(model);
+  if (provider === "fireworks") {
+    const native = nativeModelId(model).toLowerCase();
+    const accountPrefix = "accounts/fireworks/models/";
+    const modelFamily = native.startsWith(accountPrefix)
+      ? native.slice(accountPrefix.length)
+      : native;
+    const slash = modelFamily.indexOf("/");
+    return `${provider}/${slash === -1 ? modelFamily : modelFamily.slice(0, slash)}`;
+  }
+  return provider;
+}
+
+export function providerMinCacheTokens(model: string): number {
+  if (isAnthropicFamily(model)) return anthropicMinCacheTokens(model);
+  if (isFireworksFamily(model) || isMetaFamily(model)) return 0;
+  return OPENAI_MIN_CACHE_TOKENS;
+}
+
+// The stored entries a provider cache can still be re-reading at nowMs. This
+// is the definition of "warm", and every cost estimate rests on it, so an
+// unparseable timestamp reads as cold: warmth is proven, never assumed.
+// nowMs is supplied by the caller because this package reads no clock.
+export function warmPrefixHits(
+  hits: readonly RouterPrefixHit[] | undefined,
+  nowMs: number
+): RouterPrefixHit[] {
+  const cutoffMs = nowMs - PREFIX_WARMTH_WINDOW_MS;
+  return (hits ?? []).filter((hit) => {
+    const updatedAtMs = Date.parse(hit.updated_at);
+    return Number.isFinite(updatedAtMs) && updatedAtMs >= cutoffMs;
+  });
+}
+
+export function providerCacheableTokens(
+  model: string,
+  provider: PromptCacheProvider,
+  prefixTokens: number
+): number {
+  if (prefixTokens <= 0) return 0;
+  if (provider === "openai") return openAiCachedPrefixTokens(prefixTokens);
+  if (provider === "anthropic") {
+    return prefixTokens >= anthropicMinCacheTokens(model) ? Math.floor(prefixTokens) : 0;
+  }
+  return Math.floor(prefixTokens);
+}

package/src/cache_scope.ts

@@ -0,0 +1,58 @@
+import { canonicalModelId } from "./model_ids.js";
+
+export type ReasoningCacheScope = "effort_keyed" | "shared";
+
+// How a model's provider prompt cache behaves when the reasoning payload
+// changes between otherwise identical requests, from live-provider and
+// router-path validation:
+//   effort_keyed - each effective reasoning effort warms its own cache
+//                  partition; switching effort misses/rewrites, switching back
+//                  reuses that effort's still-warm partition.
+//   shared       - one cache partition regardless of reasoning effort.
+// OpenAI reasoning models are effort_keyed (a first-ever effort missed a
+// steady-warm prefix on every model tested). Anthropic models are effort_keyed
+// because pi-ai places cache_control on message blocks, which Anthropic
+// invalidates on thinking changes; budget-thinking Haiku would share under a
+// system-block breakpoint, so revalidate its entry if pi-ai's Anthropic cache
+// placement changes. Fireworks caching ignored reasoning entirely.
+// Unlisted models default to effort_keyed: the safe direction is to
+// under-claim warmth, never to price a cold prefix as a cache read.
+export const DEFAULT_REASONING_CACHE_SCOPES: Readonly<Record<string, ReasoningCacheScope>> = {
+  "openai/gpt-5.6-sol": "effort_keyed",
+  "openai/gpt-5.6-terra": "effort_keyed",
+  "openai/gpt-5.6-luna": "effort_keyed",
+  "openai/gpt-5.5": "effort_keyed",
+  "openai/gpt-4.1-mini": "shared", // single reasoning mode; nothing to key on
+  "anthropic/claude-opus-4-8": "effort_keyed",
+  "anthropic/claude-sonnet-4-6": "effort_keyed",
+  "anthropic/claude-haiku-4-5": "effort_keyed", // via pi-ai message-block cache_control; see note above
+  "fireworks/deepseek-ai/DeepSeek-V4-Pro": "shared",
+  "fireworks/deepseek-ai/DeepSeek-V4-Flash": "shared",
+  "fireworks/deepseek-ai/DeepSeek-V4-Flash-0731": "shared",
+  "fireworks/zai-org/GLM-5.2": "shared",
+};
+
+export type ReasoningCacheScopeLookup = (modelId: string) => ReasoningCacheScope;
+
+export function reasoningCacheScope(modelId: string): ReasoningCacheScope {
+  return DEFAULT_REASONING_CACHE_SCOPES[canonicalModelId(modelId)] ?? "effort_keyed";
+}
+
+// The provider cache partition a prefix entry belongs to. An effort-keyed
+// provider warms one partition per effective reasoning effort, so the pair
+// identifies it; a shared-scope provider holds a single partition per model,
+// and keying that by effort would remember several entries describing one
+// cache. Hosts that store warmth per partition derive their key here so a
+// reclassified provider moves the estimator and their storage together.
+// modelId is used verbatim, matching how ChainHits keys warm prefixes: ids that
+// differ only in spelling stay separate rather than cross-contaminating. The
+// separator cannot appear in a model id or a bucket, so the pair is injective
+// and can never collide with a shared-scope key.
+export function cachePartitionKey(
+  modelId: string,
+  reasoningBucket: string | null | undefined,
+  cacheScope: ReasoningCacheScopeLookup = reasoningCacheScope
+): string {
+  if (cacheScope(modelId) === "shared") return modelId;
+  return `${modelId}\u0000${reasoningBucket ?? ""}`;
+}

package/src/cache_switch_decision.ts

@@ -0,0 +1,53 @@
+export type WarmIncumbentCost = {
+  fixedTurnCostUsd: number;
+  outputCostPerMtok: number;
+};
+
+export type SwitchCandidateCost = {
+  fixedTurnCostUsd: number | null;
+  outputCostPerMtok: number | null;
+};
+
+export type CacheSwitchDecision =
+  | {
+      action: "keep";
+      reason: "unknown_switch_cost" | "unknown_switch_output_price" | "not_cheaper_output_tier" | "saves_more_than_threshold";
+      fixedTurnCostUsd?: number;
+      savingsRatio?: number;
+    }
+  | {
+      action: "prune";
+      reason: "insufficient_savings";
+      fixedTurnCostUsd: number;
+      savingsRatio: number;
+    };
+
+export function decideCacheSwitch(args: {
+  warmIncumbent: WarmIncumbentCost;
+  switchCandidate: SwitchCandidateCost;
+  minSwitchSavingsRatio: number;
+}): CacheSwitchDecision {
+  const fixedTurnCostUsd = args.switchCandidate.fixedTurnCostUsd;
+  if (fixedTurnCostUsd === null) {
+    return { action: "keep", reason: "unknown_switch_cost" };
+  }
+
+  const outputCostPerMtok = args.switchCandidate.outputCostPerMtok;
+  if (outputCostPerMtok === null) {
+    return { action: "keep", reason: "unknown_switch_output_price" };
+  }
+
+  // Higher output price is our capability-upgrade guard. The pruning rule is
+  // only for cheaper-tier switches that look cheap before cache effects.
+  if (outputCostPerMtok >= args.warmIncumbent.outputCostPerMtok) {
+    return { action: "keep", reason: "not_cheaper_output_tier", fixedTurnCostUsd };
+  }
+
+  const savingsRatio =
+    (args.warmIncumbent.fixedTurnCostUsd - fixedTurnCostUsd) / args.warmIncumbent.fixedTurnCostUsd;
+  if (savingsRatio > args.minSwitchSavingsRatio) {
+    return { action: "keep", reason: "saves_more_than_threshold", fixedTurnCostUsd, savingsRatio };
+  }
+
+  return { action: "prune", reason: "insufficient_savings", fixedTurnCostUsd, savingsRatio };
+}

package/src/candidate_pruning.ts

@@ -0,0 +1,257 @@
+// Cache-aware pruning for selector-based routing strategies. When the previous
+// model/thinking-level pair is still warm, a nominally cheaper pair can be a
+// fake-cheap switch: the cold start erases most of the sticker-price saving.
+
+import {
+  decideCacheSwitch,
+  type CacheSwitchDecision,
+} from "./cache_switch_decision.js";
+import { turnCostUsdAt } from "./cost.js";
+import { FIXED_TURN_COST_COMPARISON_TURNS } from "./fixed_turn_cost_config.js";
+import {
+  REASONING_EFFORTS,
+  routingCandidateKey,
+  type CandidateCostEstimate,
+  type PreviousDecision,
+  type ReasoningEffort,
+  type RoutingCandidate,
+} from "./types.js";
+
+export const MIN_SWITCH_SAVINGS_RATIO = 0.1;
+
+type PrunedCandidate = {
+  model: string;
+  reasoning_effort: ReasoningEffort;
+  fixed_turn_cost_usd: number;
+  savings_ratio: number;
+};
+
+type CandidateSwitchKeepDecision = {
+  action: "keep";
+  reason:
+    | Extract<CacheSwitchDecision, { action: "keep" }>["reason"]
+    | "same_model_upgrade";
+  fixedTurnCostUsd?: number;
+  savingsRatio?: number;
+};
+
+type CandidateSwitchDecision =
+  | CandidateSwitchKeepDecision
+  | Extract<CacheSwitchDecision, { action: "prune" }>;
+
+type KeptReason = "incumbent" | CandidateSwitchKeepDecision["reason"];
+
+type KeptCandidate = {
+  model: string;
+  reasoning_effort: ReasoningEffort;
+  reason: KeptReason;
+  savings_ratio?: number;
+};
+
+export type CandidatePruningAudit = {
+  min_switch_savings_ratio: number;
+  incumbent_model: string | null;
+  incumbent_reasoning_effort: ReasoningEffort | null;
+  incumbent_fixed_turn_cost_usd: number | null;
+  skip_reason:
+    | "no_previous_decision"
+    | "incumbent_not_warm"
+    | "incumbent_unpriced"
+    | null;
+  pruned_candidates: PrunedCandidate[];
+  kept_candidates: KeptCandidate[];
+};
+
+export type CandidatePruning = {
+  candidates: RoutingCandidate[];
+  costEstimates: CandidateCostEstimate[];
+  audit: CandidatePruningAudit;
+};
+
+export function pruneSwitchCandidates(args: {
+  candidates: RoutingCandidate[];
+  costEstimates: CandidateCostEstimate[];
+  previousDecision?: PreviousDecision;
+  minSwitchSavingsRatio: number;
+}): CandidatePruning {
+  const incumbentCandidate = args.previousDecision
+    ? {
+        model: args.previousDecision.model,
+        reasoningEffort: args.previousDecision.reasoningEffort,
+      }
+    : null;
+  const candidateKeys = new Set(args.candidates.map(routingCandidateKey));
+  const incumbentKey = incumbentCandidate
+    ? routingCandidateKey(incumbentCandidate)
+    : null;
+  const estimateByKey = new Map(
+    args.costEstimates.map((estimate) => [
+      routingCandidateKey({
+        model: estimate.model,
+        reasoningEffort: estimate.reasoning_effort,
+      }),
+      estimate,
+    ]),
+  );
+  const incumbent = incumbentKey && candidateKeys.has(incumbentKey)
+    ? estimateByKey.get(incumbentKey)
+    : undefined;
+  if (!incumbent || !incumbentCandidate) {
+    return keepAll(args, incumbentCandidate, "no_previous_decision");
+  }
+  if (incumbent.warm_tokens <= 0) {
+    return keepAll(args, incumbentCandidate, "incumbent_not_warm");
+  }
+  const incumbentCost = turnCostUsdAt(
+    incumbent.fixed_turn_cost_estimate,
+    FIXED_TURN_COST_COMPARISON_TURNS,
+  );
+  const incumbentOutputPrice = incumbent.output_cost_per_mtok;
+  if (
+    incumbentCost === null ||
+    incumbentCost <= 0 ||
+    incumbentOutputPrice === null
+  ) {
+    return keepAll(args, incumbentCandidate, "incumbent_unpriced");
+  }
+
+  const prunedCandidates: PrunedCandidate[] = [];
+  const keptCandidates: KeptCandidate[] = [];
+  const survivors = args.candidates.filter((candidate) => {
+    const key = routingCandidateKey(candidate);
+    if (key === incumbentKey) {
+      keptCandidates.push({
+        model: candidate.model,
+        reasoning_effort: candidate.reasoningEffort,
+        reason: "incumbent",
+      });
+      return true;
+    }
+    const decision = candidateSwitchDecision({
+      candidate,
+      estimate: estimateByKey.get(key),
+      incumbent: incumbentCandidate,
+      incumbentCost,
+      incumbentOutputPrice,
+      minSwitchSavingsRatio: args.minSwitchSavingsRatio,
+    });
+    if (decision.action === "keep") {
+      keptCandidates.push({
+        model: candidate.model,
+        reasoning_effort: candidate.reasoningEffort,
+        reason: decision.reason,
+        ...(decision.savingsRatio === undefined
+          ? {}
+          : { savings_ratio: decision.savingsRatio }),
+      });
+      return true;
+    }
+    prunedCandidates.push({
+      model: candidate.model,
+      reasoning_effort: candidate.reasoningEffort,
+      fixed_turn_cost_usd: decision.fixedTurnCostUsd,
+      savings_ratio: decision.savingsRatio,
+    });
+    return false;
+  });
+  const survivorKeys = new Set(survivors.map(routingCandidateKey));
+
+  return {
+    candidates: survivors,
+    costEstimates: args.costEstimates.filter((estimate) =>
+      survivorKeys.has(
+        routingCandidateKey({
+          model: estimate.model,
+          reasoningEffort: estimate.reasoning_effort,
+        }),
+      )
+    ),
+    audit: {
+      min_switch_savings_ratio: args.minSwitchSavingsRatio,
+      incumbent_model: incumbentCandidate.model,
+      incumbent_reasoning_effort: incumbentCandidate.reasoningEffort,
+      incumbent_fixed_turn_cost_usd: incumbentCost,
+      skip_reason: null,
+      pruned_candidates: prunedCandidates,
+      kept_candidates: keptCandidates,
+    },
+  };
+}
+
+function candidateSwitchDecision(args: {
+  candidate: RoutingCandidate;
+  estimate?: CandidateCostEstimate;
+  incumbent: RoutingCandidate;
+  incumbentCost: number;
+  incumbentOutputPrice: number;
+  minSwitchSavingsRatio: number;
+}): CandidateSwitchDecision {
+  const candidateCost = turnCostUsdAt(
+    args.estimate?.fixed_turn_cost_estimate,
+    FIXED_TURN_COST_COMPARISON_TURNS,
+  );
+  if (args.candidate.model !== args.incumbent.model) {
+    return decideCacheSwitch({
+      warmIncumbent: {
+        fixedTurnCostUsd: args.incumbentCost,
+        outputCostPerMtok: args.incumbentOutputPrice,
+      },
+      switchCandidate: {
+        fixedTurnCostUsd: candidateCost,
+        outputCostPerMtok: args.estimate?.output_cost_per_mtok ?? null,
+      },
+      minSwitchSavingsRatio: args.minSwitchSavingsRatio,
+    });
+  }
+
+  // Output price cannot distinguish thinking levels on one model, so preserve
+  // capability upgrades and judge lower-effort switches by projected cost.
+  if (
+    REASONING_EFFORTS.indexOf(args.candidate.reasoningEffort) >=
+    REASONING_EFFORTS.indexOf(args.incumbent.reasoningEffort)
+  ) {
+    return { action: "keep", reason: "same_model_upgrade" };
+  }
+  if (candidateCost === null) {
+    return { action: "keep", reason: "unknown_switch_cost" };
+  }
+  const savingsRatio =
+    (args.incumbentCost - candidateCost) / args.incumbentCost;
+  return savingsRatio > args.minSwitchSavingsRatio
+    ? {
+        action: "keep",
+        reason: "saves_more_than_threshold",
+        fixedTurnCostUsd: candidateCost,
+        savingsRatio,
+      }
+    : {
+        action: "prune",
+        reason: "insufficient_savings",
+        fixedTurnCostUsd: candidateCost,
+        savingsRatio,
+      };
+}
+
+function keepAll(
+  args: {
+    candidates: RoutingCandidate[];
+    costEstimates: CandidateCostEstimate[];
+    minSwitchSavingsRatio: number;
+  },
+  incumbent: RoutingCandidate | null,
+  skipReason: NonNullable<CandidatePruningAudit["skip_reason"]>,
+): CandidatePruning {
+  return {
+    candidates: args.candidates,
+    costEstimates: args.costEstimates,
+    audit: {
+      min_switch_savings_ratio: args.minSwitchSavingsRatio,
+      incumbent_model: incumbent?.model ?? null,
+      incumbent_reasoning_effort: incumbent?.reasoningEffort ?? null,
+      incumbent_fixed_turn_cost_usd: null,
+      skip_reason: skipReason,
+      pruned_candidates: [],
+      kept_candidates: [],
+    },
+  };
+}