@mupt-ai/dari-router 0.1.0 → 0.2.1

package/src/routing_history.ts

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

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

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

@@ -1,130 +0,0 @@
-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",
-            ],
-          },
-        },
-      },
-    },
-  };
-}