@mupt-ai/dari-router 0.1.0 → 0.2.0

package/src/cache_scope.ts

@@ -1,58 +0,0 @@
-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

@@ -1,53 +0,0 @@
-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

@@ -1,257 +0,0 @@
-// 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: [],
-    },
-  };
-}

package/src/candidate_resolution.ts

@@ -1,208 +0,0 @@
-import {
-  MIN_SWITCH_SAVINGS_RATIO,
-  pruneSwitchCandidates,
-  type CandidatePruningAudit,
-} from "./candidate_pruning.js";
-import {
-  routingCandidateKey,
-  type CandidateCostEstimate,
-  type CustomRouterConfig,
-  type CustomRouterRule,
-  type PreviousDecision,
-  type ReasoningEffort,
-  type RouterModelPrice,
-  type RoutingCandidate,
-  type RoutingStrategy,
-} from "./types.js";
-
-export type CustomDefaultTarget = {
-  model: string;
-  thinkingLevel: ReasoningEffort | null;
-};
-
-type CandidateSet = {
-  candidates: RoutingCandidate[];
-  costEstimates: CandidateCostEstimate[];
-};
-
-type CustomDetails = {
-  rules: CustomRouterRule[];
-  defaultTarget: CustomDefaultTarget | null;
-  audit: {
-    dropped_rules: CustomRouterRule[];
-    fallback_all_candidates: boolean;
-    no_routable_rule_models: boolean;
-  };
-};
-
-export type StrategyCandidateResolution = CandidateSet & (
-  | { strategy: "slm"; pruning: CandidatePruningAudit }
-  | { strategy: "custom"; pruning: null; custom: null }
-  | {
-      strategy: "custom";
-      pruning: CandidatePruningAudit;
-      custom: CustomDetails;
-    }
-);
-
-type CustomCandidateResolution = Extract<
-  StrategyCandidateResolution,
-  { strategy: "custom"; custom: CustomDetails }
->;
-
-type CandidateResolutionArgs = {
-  strategy: RoutingStrategy;
-  candidates: RoutingCandidate[];
-  costEstimates: CandidateCostEstimate[];
-  previousDecision?: PreviousDecision;
-  customConfig?: CustomRouterConfig | null;
-  modelPrices: Record<string, RouterModelPrice>;
-};
-
-export function resolveStrategyCandidates(
-  args: CandidateResolutionArgs,
-): StrategyCandidateResolution {
-  if (args.strategy === "slm") {
-    const pruned = pruneSwitchCandidates({
-      candidates: args.candidates,
-      costEstimates: args.costEstimates,
-      previousDecision: args.previousDecision,
-      minSwitchSavingsRatio: MIN_SWITCH_SAVINGS_RATIO,
-    });
-    return {
-      strategy: "slm",
-      candidates: pruned.candidates,
-      costEstimates: pruned.costEstimates,
-      pruning: pruned.audit,
-    };
-  }
-
-  const config = args.customConfig;
-  if (!config || !Array.isArray(config.rules) || config.rules.length === 0) {
-    return {
-      strategy: "custom",
-      candidates: [],
-      costEstimates: [],
-      pruning: null,
-      custom: null,
-    };
-  }
-
-  return resolveCustomCandidates(args, config);
-}
-
-function resolveCustomCandidates(
-  args: CandidateResolutionArgs,
-  config: CustomRouterConfig,
-): CustomCandidateResolution {
-  const usableRules = config.rules.filter((rule) =>
-    args.candidates.some((candidate) => matchesRule(candidate, rule)),
-  );
-  const defaultModel = typeof config.default === "string" ? config.default : null;
-  const defaultTarget =
-    defaultModel !== null &&
-    args.candidates.some((candidate) =>
-      matchesTarget(candidate, defaultModel, config.default_thinking_level),
-    )
-      ? {
-          model: defaultModel,
-          thinkingLevel: config.default_thinking_level ?? null,
-        }
-      : null;
-  const matchesDefault = (candidate: RoutingCandidate) =>
-    defaultTarget !== null &&
-    matchesTarget(candidate, defaultTarget.model, defaultTarget.thinkingLevel);
-  const configuredCandidates = orderCandidatesByCostDesc(
-    args.candidates.filter(
-      (candidate) =>
-        usableRules.some((rule) => matchesRule(candidate, rule)) ||
-        matchesDefault(candidate),
-    ),
-    args.modelPrices,
-  );
-  const pruned = pruneSwitchCandidates({
-    candidates: configuredCandidates,
-    costEstimates: reorderEstimates(args.costEstimates, configuredCandidates),
-    previousDecision: args.previousDecision,
-    minSwitchSavingsRatio: MIN_SWITCH_SAVINGS_RATIO,
-  });
-  const ruleOrder = (rule: CustomRouterRule) =>
-    pruned.candidates.findIndex((candidate) => matchesRule(candidate, rule));
-
-  return {
-    strategy: "custom",
-    candidates: pruned.candidates,
-    costEstimates: pruned.costEstimates,
-    pruning: pruned.audit,
-    custom: {
-      rules: usableRules
-        .filter((rule) => ruleOrder(rule) >= 0)
-        .sort((a, b) => ruleOrder(a) - ruleOrder(b)),
-      defaultTarget: pruned.candidates.some(matchesDefault)
-        ? defaultTarget
-        : null,
-      audit: {
-        dropped_rules: config.rules.filter((rule) => !usableRules.includes(rule)),
-        fallback_all_candidates: false,
-        no_routable_rule_models: configuredCandidates.length === 0,
-      },
-    },
-  };
-}
-
-function matchesRule(
-  candidate: RoutingCandidate,
-  rule: CustomRouterRule,
-): boolean {
-  return matchesTarget(candidate, rule.use, rule.thinking_level);
-}
-
-function matchesTarget(
-  candidate: RoutingCandidate,
-  model: string,
-  thinkingLevel: ReasoningEffort | null | undefined,
-): boolean {
-  return candidate.model === model &&
-    (thinkingLevel == null || candidate.reasoningEffort === thinkingLevel);
-}
-
-// Catalog rates are model-scoped, so sorting remains stable across a model's
-// thinking-level variants.
-function orderCandidatesByCostDesc(
-  candidates: RoutingCandidate[],
-  modelPrices: Record<string, RouterModelPrice>,
-): RoutingCandidate[] {
-  return [...candidates].sort((a, b) => {
-    const priceA = usablePrice(modelPrices[a.model]);
-    const priceB = usablePrice(modelPrices[b.model]);
-    if (priceA === null && priceB === null) return 0;
-    if (priceA === null) return 1;
-    if (priceB === null) return -1;
-    return priceB.output - priceA.output || priceB.input - priceA.input;
-  });
-}
-
-function usablePrice(price: RouterModelPrice | undefined): RouterModelPrice | null {
-  return price && Number.isFinite(price.input) && Number.isFinite(price.output)
-    ? price
-    : null;
-}
-
-function reorderEstimates(
-  estimates: CandidateCostEstimate[],
-  candidates: RoutingCandidate[],
-): CandidateCostEstimate[] {
-  const byCandidate = new Map(
-    estimates.map((estimate) => [
-      routingCandidateKey({
-        model: estimate.model,
-        reasoningEffort: estimate.reasoning_effort,
-      }),
-      estimate,
-    ]),
-  );
-  return candidates.flatMap((candidate) => {
-    const estimate = byCandidate.get(routingCandidateKey(candidate));
-    return estimate ? [estimate] : [];
-  });
-}