@mupt-ai/dari-router 0.1.0

package/src/routing_history.ts

@@ -0,0 +1,157 @@
+// Router-only history compaction shared by production routing and GRPO
+// training. Provider-bound requests keep the complete conversation.
+
+type RoutingHistoryMessage = {
+  role?: unknown;
+  content?: unknown;
+  [key: string]: unknown;
+};
+
+export function compactRoutingHistory<T extends RoutingHistoryMessage>(
+  messages: T[],
+  historyCharBudget: number | undefined,
+): T[] {
+  if (historyCharBudget === undefined || messages.length <= 1) return messages;
+  if (!Number.isSafeInteger(historyCharBudget) || historyCharBudget < 512) {
+    throw new Error("GRPO routing history character budget must be an integer of at least 512");
+  }
+  const first = messages[0] as T;
+  const history = messages.slice(1);
+  const totalChars = history.reduce(
+    (total, message) => total + JSON.stringify(message).length,
+    0,
+  );
+  if (totalChars <= historyCharBudget) return messages;
+
+  // The final marker embeds omission counts, so budget the tail against a
+  // worst-case-width placeholder to keep the result within the char budget.
+  const markerContent = (omittedMessages: number, omittedChars: number): string =>
+    `[Router-only compaction omitted ${omittedMessages} earlier messages (~${omittedChars} chars); ` +
+    "retained the task and most recent context.]";
+  const markerReserve = JSON.stringify({
+    role: "system",
+    content: markerContent(99_999_999, 999_999_999),
+  }).length;
+  let remainingChars = historyCharBudget - markerReserve;
+  const tail: T[] = [];
+  for (let index = history.length - 1; index >= 0 && remainingChars > 0; index -= 1) {
+    const message = history[index] as T;
+    const serializedChars = JSON.stringify(message).length;
+    if (serializedChars <= remainingChars) {
+      tail.unshift(message);
+      remainingChars -= serializedChars;
+      continue;
+    }
+    const compacted = compactRoutingMessage(message, remainingChars);
+    if (compacted !== undefined) tail.unshift(compacted);
+    break;
+  }
+  // Providers reject tool results whose originating assistant tool_calls
+  // message was compacted away, so the retained tail must never lead with one.
+  while (tail.length > 0 && tail[0]?.role === "tool") {
+    tail.shift();
+  }
+  const retainedChars = tail.reduce(
+    (total, message) => total + JSON.stringify(message).length,
+    0,
+  );
+  const marker = {
+    role: "system",
+    content: markerContent(
+      history.length - tail.length,
+      Math.max(totalChars - retainedChars, 0),
+    ),
+  } as T;
+  return [first, marker, ...tail];
+}
+
+function compactRoutingMessage<T extends RoutingHistoryMessage>(
+  message: T,
+  maxChars: number,
+): T | undefined {
+  const content = message.content;
+  if (Array.isArray(content)) {
+    return compactRoutingMessageParts(message, content, maxChars);
+  }
+  const text = contentText(content);
+  const shell = { ...message, content: "" };
+  // Leave room for JSON escaping introduced by the truncation marker.
+  const availableChars = maxChars - JSON.stringify(shell).length - 32;
+  if (availableChars < 128 || text.length === 0) return undefined;
+  const compacted = { ...message, content: elideMiddle(text, availableChars) };
+  return JSON.stringify(compacted).length <= maxChars ? compacted : undefined;
+}
+
+function compactRoutingMessageParts<T extends RoutingHistoryMessage>(
+  message: T,
+  content: unknown[],
+  maxChars: number,
+): T | undefined {
+  const text = contentText(content);
+  const nonTextContent = content.filter((part) => !isTextPart(part));
+  const shell = { ...message, content: nonTextContent };
+  const shellChars = JSON.stringify(shell).length;
+  if (shellChars > maxChars) return undefined;
+  if (text.length === 0) return shell;
+
+  const availableChars = maxChars - shellChars - 32;
+  if (availableChars < 128) {
+    return nonTextContent.length > 0 ? shell : undefined;
+  }
+  const textPart = { type: "text", text: elideMiddle(text, availableChars) };
+  const compacted = {
+    ...message,
+    content: compactContentParts(content, textPart),
+  };
+  if (JSON.stringify(compacted).length <= maxChars) return compacted;
+  return nonTextContent.length > 0 ? shell : undefined;
+}
+
+function compactContentParts(
+  content: unknown[],
+  textPart: Record<string, unknown>,
+): unknown[] {
+  let insertedText = false;
+  const compacted: unknown[] = [];
+  for (const part of content) {
+    if (isTextPart(part)) {
+      if (!insertedText) compacted.push(textPart);
+      insertedText = true;
+      continue;
+    }
+    compacted.push(part);
+  }
+  if (!insertedText) compacted.push(textPart);
+  return compacted;
+}
+
+function isTextPart(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    (value as Record<string, unknown>).type === "text" &&
+    typeof (value as Record<string, unknown>).text === "string"
+  );
+}
+
+function contentText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .flatMap((block) => {
+      if (typeof block !== "object" || block === null || Array.isArray(block)) return [];
+      const text = (block as Record<string, unknown>).text;
+      return typeof text === "string" ? [text] : [];
+    })
+    .join("\n");
+}
+
+function elideMiddle(value: string, maxChars: number): string {
+  if (value.length <= maxChars) return value;
+  const marker = "\n...[router history truncated]...\n";
+  if (maxChars <= marker.length) return value.slice(-maxChars);
+  const retainedChars = maxChars - marker.length;
+  const prefixChars = Math.floor(retainedChars / 2);
+  return `${value.slice(0, prefixChars)}${marker}${value.slice(-(retainedChars - prefixChars))}`;
+}

package/src/selector_input.ts

@@ -0,0 +1,246 @@
+// Builds the selector input: candidate pairs, matched eval scores, cost
+// estimates, the previous decision, and the (image-scrubbed) conversation.
+// The system prompts live in prompts.ts.
+
+import {
+  isRecord,
+  REASONING_EFFORTS,
+  routingCandidateKey,
+  type CandidateCostEstimate,
+  type ChatMessage,
+  type CustomRouterRule,
+  type PreviousDecision,
+  type ReasoningEffort,
+  type RouterEval,
+  type RouterEvalScore,
+  type RoutingCandidate,
+} from "./types.js";
+
+const IMAGE_OMITTED_PLACEHOLDER = "<image omitted>";
+
+type SelectorCandidate = {
+  model: string;
+  thinking_level: RoutingCandidate["reasoningEffort"];
+};
+
+type SelectorPreviousDecision = SelectorCandidate & { reason: string };
+
+export type SelectorInput = {
+  candidate_pairs: SelectorCandidate[];
+  imported_evals: Array<Record<string, unknown>>;
+  previous_decision: SelectorPreviousDecision | null;
+  cost_estimates: CandidateCostEstimate[] | null;
+  messages: ChatMessage[];
+};
+
+type SelectorCustomRule = Omit<CustomRouterRule, "thinking_level"> & {
+  thinking_level: ReasoningEffort | null;
+};
+
+export type CustomSelectorInput = SelectorInput & {
+  custom_rules: SelectorCustomRule[];
+  default_target: {
+    model: string;
+    thinking_level: ReasoningEffort | null;
+  } | null;
+};
+
+// Selector serialization must not include image bytes. The provider-facing
+// request and prefix fingerprint still use the original content, while this
+// stable placeholder preserves the selector's own prompt cache behavior.
+export function selectorSafeMessages(messages: ChatMessage[]): ChatMessage[] {
+  return messages.map((message) => {
+    if (!Array.isArray(message.content)) return message;
+    return {
+      ...message,
+      content: message.content.map((part) =>
+        isRecord(part) && part.type === "image_url"
+          ? { type: "image_url", image_url: { url: IMAGE_OMITTED_PLACEHOLDER } }
+          : part
+      ),
+    };
+  });
+}
+
+export function buildSelectorInput(args: {
+  candidates: RoutingCandidate[];
+  evals: RouterEval[];
+  previousDecision: PreviousDecision | null;
+  costEstimates: CandidateCostEstimate[] | null;
+  messages: ChatMessage[];
+  customRules?: CustomRouterRule[];
+  defaultTarget?: {
+    model: string;
+    thinkingLevel: ReasoningEffort | null;
+  } | null;
+  modelFallbackEnabled?: boolean;
+  fallbackRequiresDifferentProvider?: boolean;
+  // When true, candidates with no exact-level and no generic "Any" score get a
+  // linear interpolation between their two bracketing known levels instead of
+  // an empty row. Off by default so existing routers keep measured-only scores.
+  imputeEvalScores?: boolean;
+}): SelectorInput | CustomSelectorInput {
+  const input: SelectorInput = {
+    candidate_pairs: args.candidates.map(({ model, reasoningEffort }) => ({
+      model,
+      thinking_level: reasoningEffort,
+    })),
+    imported_evals: formatImportedEvals(
+      args.evals,
+      args.candidates,
+      args.imputeEvalScores ?? false,
+    ),
+    previous_decision: args.previousDecision
+      ? {
+          model: args.previousDecision.model,
+          thinking_level: args.previousDecision.reasoningEffort,
+          reason: args.previousDecision.reason,
+        }
+      : null,
+    cost_estimates: args.costEstimates,
+    messages: args.messages,
+  };
+  if (args.customRules !== undefined) {
+    (input as CustomSelectorInput).custom_rules = args.customRules.map(
+      (rule) => ({
+        ...rule,
+        thinking_level: rule.thinking_level ?? null,
+      }),
+    );
+    (input as CustomSelectorInput).default_target = args.defaultTarget
+      ? {
+          model: args.defaultTarget.model,
+          thinking_level: args.defaultTarget.thinkingLevel,
+        }
+      : null;
+  }
+  return input;
+}
+
+function formatImportedEvals(
+  evals: RouterEval[],
+  candidates: RoutingCandidate[],
+  imputeEvalScores: boolean,
+): Array<Record<string, unknown>> {
+  return evals.flatMap((evalCard) => {
+    const scores = matchingEvalScores(
+      evalCard.scores,
+      candidates,
+      imputeEvalScores,
+    );
+    if (scores.length === 0) return [];
+    return [
+      {
+        id: evalCard.id,
+        name: evalCard.name,
+        description: evalCard.description ?? null,
+        min_score: evalCard.min_score,
+        max_score: evalCard.max_score,
+        scores,
+      },
+    ];
+  });
+}
+
+function matchingEvalScores(
+  scores: RouterEvalScore[],
+  candidates: RoutingCandidate[],
+  imputeEvalScores: boolean,
+): Array<Record<string, unknown>> {
+  const uniqueCandidates = new Map(
+    candidates.map((candidate) => [routingCandidateKey(candidate), candidate]),
+  );
+  return [...uniqueCandidates.values()].flatMap((candidate) => {
+    const modelScores = scores.filter(
+      (score) => score.model_id === candidate.model,
+    );
+    const exact = modelScores.find(
+      (score) => score.thinking_level === candidate.reasoningEffort,
+    );
+    const generic = modelScores.find((score) => score.thinking_level == null);
+    const match = exact ?? generic;
+    if (match) {
+      return [
+        {
+          model_id: candidate.model,
+          thinking_level: candidate.reasoningEffort,
+          score: match.score,
+          ...normalizedScore(match.score, scores),
+          notes: match.notes ?? null,
+        },
+      ];
+    }
+    if (!imputeEvalScores) return [];
+    const imputed = interpolatedScore(candidate, modelScores);
+    if (imputed === null) return [];
+    return [
+      {
+        model_id: candidate.model,
+        thinking_level: candidate.reasoningEffort,
+        score: imputed,
+        ...normalizedScore(imputed, scores),
+        notes: null,
+        imputed: true,
+      },
+    ];
+  });
+}
+
+// Linear interpolation between the two per-level scores that bracket the
+// requested thinking level. A single known level (or zero) is not enough to
+// pin a line, so we only interpolate when the candidate has scores on both
+// sides of the requested level; one-sided cases stay empty.
+function interpolatedScore(
+  candidate: RoutingCandidate,
+  modelScores: RouterEvalScore[],
+): number | null {
+  const requestedIndex = REASONING_EFFORTS.indexOf(candidate.reasoningEffort);
+  if (requestedIndex < 0) return null;
+
+  let below: { index: number; score: number } | null = null;
+  let above: { index: number; score: number } | null = null;
+  for (const entry of modelScores) {
+    if (entry.thinking_level == null) continue;
+    const index = REASONING_EFFORTS.indexOf(entry.thinking_level);
+    if (index < 0) continue;
+    if (index < requestedIndex && (below === null || index > below.index)) {
+      below = { index, score: entry.score };
+    } else if (
+      index > requestedIndex &&
+      (above === null || index < above.index)
+    ) {
+      above = { index, score: entry.score };
+    }
+  }
+  if (below === null || above === null) return null;
+
+  const ratio =
+    (requestedIndex - below.index) / (above.index - below.index);
+  return round2(below.score + (above.score - below.score) * ratio);
+}
+
+// Positions a candidate's score against every model on the scorecard, not just
+// the candidates that survived pruning. Candidate-relative normalization would
+// move with the pruned set (with two candidates a z-score is always +/-1), so
+// the selector would read pure ordering as if it carried magnitude.
+function normalizedScore(
+  score: number,
+  population: RouterEvalScore[],
+): { rank: number; rank_total: number; z_score: number } {
+  const values = population.map((entry) => entry.score);
+  const mean = values.reduce((total, value) => total + value, 0) / values.length;
+  const variance =
+    values.reduce((total, value) => total + (value - mean) ** 2, 0) /
+    values.length;
+  const stdDev = Math.sqrt(variance);
+  return {
+    // Competition ranking, best score first; tied scores share the low rank.
+    rank: 1 + values.filter((value) => value > score).length,
+    rank_total: values.length,
+    z_score: stdDev === 0 ? 0 : round2((score - mean) / stdDev),
+  };
+}
+
+function round2(value: number): number {
+  return Math.round(value * 100) / 100;
+}

package/src/selector_parse.ts

@@ -0,0 +1,138 @@
+import { RouterCoreError } from "./errors.js";
+import { providerForModel } from "./model_ids.js";
+import {
+  isReasoningEffort,
+  sameRoutingCandidate,
+  type RoutingCandidate,
+  type RoutingDecision,
+} from "./types.js";
+
+export type ParsedSelectorDecision = {
+  decision: RoutingDecision;
+  fallbackDecision?: RoutingDecision;
+};
+
+// Parses the selector's raw output text into a routing decision (plus an
+// optional fallback). Tolerates a fenced ```json block; everything else must
+// be strict JSON matching the routing_decision schema.
+export function parseSelectorDecision(text: string): ParsedSelectorDecision {
+  const trimmed = text.trim().replace(/^```json\s*/i, "").replace(/^```\s*/i, "").replace(/```$/i, "").trim();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new RouterCoreError("selector_output", "Selector returned invalid JSON.", "selector_invalid_json");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new RouterCoreError("selector_output", "Selector returned invalid routing decision.", "selector_invalid_response");
+  }
+  const record = parsed as Record<string, unknown>;
+  if (typeof record.selected_model !== "string" || record.selected_model === "") {
+    throw new RouterCoreError("selector_output", "Selector response missing selected_model.", "selector_invalid_response");
+  }
+  if (!isReasoningEffort(record.reasoning_effort)) {
+    throw new RouterCoreError(
+      "selector_output",
+      "Selector response missing a valid reasoning_effort.",
+      "selector_invalid_response",
+    );
+  }
+  const reason = typeof record.reason === "string" ? record.reason.trim() : "";
+  const leaseTurnsRemaining =
+    typeof record.lease_turns_remaining === "number" && Number.isFinite(record.lease_turns_remaining)
+      ? Math.trunc(record.lease_turns_remaining)
+      : undefined;
+  const decision = {
+    selectedModel: record.selected_model,
+    reasoningEffort: record.reasoning_effort,
+    reason:
+      reason ||
+      `Selector selected ${record.selected_model}/${record.reasoning_effort}; no reason was provided.`,
+    ...(leaseTurnsRemaining === undefined ? {} : { leaseTurnsRemaining }),
+  };
+  const fallbackModel = record.fallback_model;
+  const fallbackEffort = record.fallback_reasoning_effort;
+  const fallbackReason = record.fallback_reason;
+  // Selectors that decline a fallback often still explain why in
+  // fallback_reason; a missing fallback_model alone means "no fallback".
+  const noFallback = fallbackModel === null || fallbackModel === undefined;
+  if (noFallback) return { decision };
+  if (
+    typeof fallbackModel !== "string" ||
+    !fallbackModel ||
+    !isReasoningEffort(fallbackEffort) ||
+    (fallbackReason !== undefined &&
+      fallbackReason !== null &&
+      typeof fallbackReason !== "string")
+  ) {
+    throw new RouterCoreError(
+      "selector_output",
+      "Selector response contains an incomplete fallback decision.",
+      "selector_invalid_response",
+    );
+  }
+  const normalizedFallbackReason = fallbackReason?.trim() ?? "";
+  return {
+    decision,
+    fallbackDecision: {
+      selectedModel: fallbackModel,
+      reasoningEffort: fallbackEffort,
+      reason:
+        normalizedFallbackReason ||
+        `Selector ranked ${fallbackModel}/${fallbackEffort} as the fallback; no reason was provided.`,
+    },
+  };
+}
+
+// Validates a parsed selector decision against the candidate set and fallback
+// policy: the selection must be a real candidate pair, and when fallback is
+// enabled a fallback must be present whenever an eligible one exists and must
+// itself be an eligible candidate on a distinct model (and provider, when
+// required).
+export function validateSelectorDecisions(args: {
+  decision: RoutingDecision;
+  fallbackDecision?: RoutingDecision;
+  candidates: RoutingCandidate[];
+  modelFallbackEnabled?: boolean;
+  fallbackRequiresDifferentProvider?: boolean;
+}): void {
+  const selected = {
+    model: args.decision.selectedModel,
+    reasoningEffort: args.decision.reasoningEffort,
+  };
+  if (!args.candidates.some((candidate) => sameRoutingCandidate(candidate, selected))) {
+    throw new RouterCoreError(
+      "selector_output",
+      "Selector returned a model/thinking-level pair outside this router's candidates.",
+      "selector_invalid_candidate",
+    );
+  }
+  const eligibleFallbacks = args.candidates.filter(
+    (candidate) =>
+      candidate.model !== selected.model &&
+      (!args.fallbackRequiresDifferentProvider ||
+        providerForModel(candidate.model) !== providerForModel(selected.model)),
+  );
+  if (args.modelFallbackEnabled) {
+    if (!args.fallbackDecision && eligibleFallbacks.length > 0) {
+      throw new RouterCoreError(
+        "selector_output",
+        "Selector response missing an eligible fallback model.",
+        "selector_invalid_response",
+      );
+    }
+    if (args.fallbackDecision) {
+      const fallback = {
+        model: args.fallbackDecision.selectedModel,
+        reasoningEffort: args.fallbackDecision.reasoningEffort,
+      };
+      if (!eligibleFallbacks.some((candidate) => sameRoutingCandidate(candidate, fallback))) {
+        throw new RouterCoreError(
+          "selector_output",
+          "Selector returned an ineligible fallback model/thinking-level pair.",
+          "selector_invalid_candidate",
+        );
+      }
+    }
+  }
+}

package/src/selector_request.ts

@@ -0,0 +1,130 @@
+import { RouterCoreError } from "./errors.js";
+import { CUSTOM_SELECTOR_SYSTEM_PROMPT, SELECTOR_SYSTEM_PROMPT } from "./prompts.js";
+import {
+  buildSelectorInput,
+  type CustomSelectorInput,
+  type SelectorInput,
+} from "./selector_input.js";
+import { trimMessagesFromFront } from "./selector_truncation.js";
+import { REASONING_EFFORTS } from "./types.js";
+import type {
+  CandidateCostEstimate,
+  ChatCompletionRequest,
+  ChatMessage,
+  CustomRouterRule,
+  PreviousDecision,
+  ReasoningEffort,
+  RouterEval,
+  RoutingCandidate,
+} from "./types.js";
+
+export type BuiltSelectorRequest = {
+  selectorInput: SelectorInput | CustomSelectorInput;
+  selectorRequest: ChatCompletionRequest;
+};
+
+export type SelectorRequestArgs = {
+  candidates: RoutingCandidate[];
+  evals?: RouterEval[];
+  previousDecision?: PreviousDecision;
+  costEstimates?: CandidateCostEstimate[];
+  customRules?: CustomRouterRule[];
+  defaultTarget?: {
+    model: string;
+    thinkingLevel: ReasoningEffort | null;
+  } | null;
+  selectorModel: string;
+  messages: ChatMessage[];
+  modelFallbackEnabled?: boolean;
+  fallbackRequiresDifferentProvider?: boolean;
+  imputeEvalScores?: boolean;
+};
+
+// Builds the selector request, front-trimming conversation messages until the
+// serialized prompt fits the selector's context window. The window size is an
+// explicit input (in characters) so the core stays free of model-registry
+// lookups.
+export function buildSizedSelectorRequest(
+  args: SelectorRequestArgs & { contextWindowChars: number },
+): BuiltSelectorRequest {
+  let messages = args.messages;
+  let built = buildSelectorRequest({ ...args, messages });
+  let previousInputChars = Number.POSITIVE_INFINITY;
+
+  while (true) {
+    const inputChars = selectorRequestInputChars(built.selectorRequest);
+    if (inputChars <= args.contextWindowChars) return built;
+    if (inputChars >= previousInputChars) {
+      throw new RouterCoreError(
+        "configuration",
+        `Selector prompt cannot fit configured context window for ${args.selectorModel}.`,
+        "configuration_error"
+      );
+    }
+    previousInputChars = inputChars;
+    messages = trimMessagesFromFront(messages, inputChars - args.contextWindowChars);
+    built = buildSelectorRequest({ ...args, messages });
+  }
+}
+
+function selectorRequestInputChars(request: ChatCompletionRequest): number {
+  return JSON.stringify(request.messages ?? []).length;
+}
+
+export function buildSelectorRequest(args: SelectorRequestArgs): BuiltSelectorRequest {
+  const isCustom = args.customRules !== undefined;
+  const selectorInput = buildSelectorInput({
+    candidates: args.candidates,
+    evals: args.evals ?? [],
+    previousDecision: args.previousDecision ?? null,
+    costEstimates: args.costEstimates ?? null,
+    messages: args.messages,
+    customRules: args.customRules,
+    defaultTarget: args.defaultTarget,
+    modelFallbackEnabled: args.modelFallbackEnabled,
+    fallbackRequiresDifferentProvider:
+      args.fallbackRequiresDifferentProvider,
+    imputeEvalScores: args.imputeEvalScores,
+  });
+  return {
+    selectorInput,
+    selectorRequest: {
+      model: args.selectorModel,
+      messages: [
+        { role: "system", content: isCustom ? CUSTOM_SELECTOR_SYSTEM_PROMPT : SELECTOR_SYSTEM_PROMPT },
+        {
+          role: "user",
+          content: JSON.stringify(selectorInput),
+        },
+      ],
+      // The selector is an internal fixed-purpose JSON pick; it must not inherit
+      // the client-facing implicit-medium reasoning default. Selector models
+      // must support a true off mode.
+      reasoning_effort: "off",
+      response_format: {
+        type: "json_schema",
+        json_schema: {
+          name: "routing_decision",
+          strict: true,
+          schema: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+              selected_model: { type: "string" },
+              reasoning_effort: {
+                type: "string",
+                enum: [...REASONING_EFFORTS],
+              },
+              reason: { type: "string" },
+            },
+            required: [
+              "selected_model",
+              "reasoning_effort",
+              "reason",
+            ],
+          },
+        },
+      },
+    },
+  };
+}