@mupt-ai/dari-router 0.1.0

package/src/candidate_resolution.ts

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

package/src/compatibility.ts

@@ -0,0 +1,162 @@
+import { RouterCoreError } from "./errors.js";
+import {
+  isReasoningEffort,
+  type HardCapability,
+  type ReasoningEffort,
+  type RoutingCandidate,
+} from "./types.js";
+
+// Host-supplied capability facts for one candidate model. Hosts derive this
+// from their model registry/catalog; the core only applies the eligibility
+// rules and never inspects provider metadata records directly.
+export type CandidateModelMetadata = {
+  // Provider identifier, e.g. "meta" or "anthropic".
+  provider: string;
+  // Provider API identifier, e.g. "anthropic-messages" or "openai-responses".
+  api: string;
+  supportsImageInput: boolean;
+  supportsHostedWebSearch: boolean;
+  // Whether the provider API can serialize response_format for structured
+  // output (JSON schema) requests.
+  supportsStructuredOutput: boolean;
+  supportedThinkingLevels: string[];
+};
+
+export type CandidateMetadataLookup = (modelId: string) => CandidateModelMetadata;
+
+export type CompatibleCandidates = {
+  candidates: RoutingCandidate[];
+};
+
+export function resolveCompatibleCandidates(args: {
+  requiredCapabilities: readonly HardCapability[];
+  // The client's explicit reasoning_effort request, when present. Pins every
+  // candidate to that level.
+  requestedReasoningEffort?: ReasoningEffort;
+  // Some protocols carry an independent hard thinking-enabled constraint.
+  thinkingEnabled?: boolean;
+  // The request's tool_choice value in OpenAI wire shape ("none" | "auto" |
+  // "required" | "any" | {..forced tool..}). Only forced-tool detection is
+  // applied here.
+  toolChoice?: unknown;
+  candidateModels: string[];
+  metadataLookup: CandidateMetadataLookup;
+  modelThinkingLevels?: Readonly<Record<string, ReasoningEffort[]>>;
+}): CompatibleCandidates {
+  const compatible: RoutingCandidate[] = [];
+  let anthropicToolChoiceRejected = false;
+  let metaToolChoiceRejected = false;
+  let candidates = args.candidateModels.map((model) => ({
+    model,
+    metadata: args.metadataLookup(model),
+  }));
+
+  if (args.requiredCapabilities.includes("image_input")) {
+    candidates = candidates.filter(({ metadata }) => metadata.supportsImageInput);
+    if (candidates.length === 0) {
+      throw new RouterCoreError(
+        "invalid_request",
+        "Image input is not supported by any enabled model for this router.",
+        "unsupported_input_modality",
+      );
+    }
+  }
+
+  if (args.requiredCapabilities.includes("structured_output")) {
+    candidates = candidates.filter(({ metadata }) => metadata.supportsStructuredOutput);
+    if (candidates.length === 0) {
+      throw new RouterCoreError(
+        "invalid_request",
+        "Structured output is not supported by any enabled model for this router.",
+        "unsupported_response_format",
+        "response_format",
+      );
+    }
+  }
+
+  if (args.requiredCapabilities.includes("openai_hosted_web_search")) {
+    candidates = candidates.filter(({ metadata }) => metadata.supportsHostedWebSearch);
+    if (candidates.length === 0) {
+      throw new RouterCoreError(
+        "invalid_request",
+        "Hosted web search requires an enabled OpenAI or Azure Responses model for this router.",
+        "unsupported_tool",
+        "tools",
+      );
+    }
+  }
+
+  const requested = args.requestedReasoningEffort;
+  for (const { model, metadata } of candidates) {
+    if (
+      metadata.provider === "meta" &&
+      args.toolChoice !== undefined &&
+      args.toolChoice !== "auto"
+    ) {
+      metaToolChoiceRejected = true;
+      continue;
+    }
+    const supportedLevels = metadata.supportedThinkingLevels.filter(
+      isReasoningEffort,
+    );
+    const configuredLevels = args.modelThinkingLevels?.[model] ?? supportedLevels;
+    const enabledLevels = configuredLevels.filter(
+      (level) => isReasoningEffort(level) && supportedLevels.includes(level),
+    );
+    const levels = requested === undefined
+      ? args.thinkingEnabled
+        ? enabledLevels.filter((level) => level !== "off")
+        : enabledLevels
+      : enabledLevels.includes(requested)
+        ? [requested]
+        : [];
+    for (const reasoningEffort of levels) {
+      if (
+        reasoningEffort !== "off" &&
+        metadata.api === "anthropic-messages" &&
+        forcesToolUse(args.toolChoice)
+      ) {
+        anthropicToolChoiceRejected = true;
+        continue;
+      }
+      compatible.push({ model, reasoningEffort });
+    }
+  }
+
+  if (compatible.length > 0) return { candidates: compatible };
+
+  if (anthropicToolChoiceRejected) {
+    throw new RouterCoreError(
+      "invalid_request",
+      "Forced tool choice is not supported by any enabled model at the requested reasoning setting.",
+      "unsupported_tool_choice",
+      "tool_choice",
+    );
+  }
+
+  if (metaToolChoiceRejected) {
+    throw new RouterCoreError(
+      "invalid_request",
+      "Meta models currently support only omitted or 'auto' tool_choice.",
+      "unsupported_tool_choice",
+      "tool_choice",
+    );
+  }
+
+  throw new RouterCoreError(
+    "invalid_request",
+    requested === undefined
+      ? args.thinkingEnabled
+        ? "Thinking is enabled, but no enabled non-off model/thinking-level pair is compatible with this request."
+        : "No enabled model/thinking-level pair is compatible with this request."
+      : `reasoning_effort '${requested}' is not supported by any enabled model for this router.`,
+    "unsupported_reasoning_effort",
+    requested === undefined ? undefined : "reasoning_effort",
+  );
+}
+
+function forcesToolUse(choice: unknown): boolean {
+  return choice === "required" ||
+    choice === "any" ||
+    (typeof choice === "object" && choice !== null);
+}