@mupt-ai/dari-router 0.1.0 → 0.2.1

package/src/compatibility.ts

@@ -1,162 +0,0 @@
-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);
-}

package/src/continuation_state.ts

@@ -1,368 +0,0 @@
-import { RouterFrameworkError } from "./framework_error.js";
-import { isRecord } from "./types.js";
-
-export type ProviderIdentity = {
-  provider: string;
-  api: string;
-  model: string;
-};
-
-export type ProviderContinuationState =
-  | {
-      kind: "openai_reasoning";
-      source: ProviderIdentity;
-      encryptedContent: string;
-      providerItemId?: string;
-      hostedToolCallIds?: string[];
-      hostedToolCallOffsets?: number[];
-    }
-  | {
-      kind: "anthropic_thinking";
-      source: ProviderIdentity;
-      thinking: string;
-      signature: string;
-    }
-  | {
-      kind: "anthropic_redacted_thinking";
-      source: ProviderIdentity;
-      data: string;
-    };
-
-/** @deprecated Alias kept for the framework-prefixed vocabulary; use {@link ProviderIdentity}. */
-export type RouterProviderIdentity = ProviderIdentity;
-/** @deprecated Alias kept for the framework-prefixed vocabulary; use {@link ProviderContinuationState}. */
-export type RouterContinuationState = ProviderContinuationState;
-
-const PREFIX = "dari-pcs-v1.";
-const FAMILY_PREFIX = "dari-pcs-";
-const MAX_JSON_BYTES = 4 * 1024 * 1024;
-const MAX_ENCODED_CHARS = Math.ceil(MAX_JSON_BYTES / 3) * 4;
-const MAX_PROVIDER_LENGTH = 128;
-const MAX_API_LENGTH = 128;
-const MAX_MODEL_LENGTH = 512;
-const MAX_ITEM_ID_LENGTH = 512;
-const MAX_HOSTED_TOOL_CALL_IDS = 256;
-const MAX_HOSTED_TOOL_CALL_OFFSET = 1_000_000;
-
-type EnvelopeV1 = {
-  v: 1;
-  kind: ProviderContinuationState["kind"];
-  source: ProviderIdentity;
-  state: Record<string, string>;
-};
-
-export function encodeProviderContinuationState(value: ProviderContinuationState): string {
-  const envelope = envelopeFor(value);
-  validateEnvelope(envelope, "configuration");
-  const json = JSON.stringify(envelope);
-  if (Buffer.byteLength(json, "utf8") > MAX_JSON_BYTES) {
-    throw invalidState(
-      "configuration",
-      "Provider continuation state exceeds the encoded size limit.",
-    );
-  }
-  return `${PREFIX}${Buffer.from(json, "utf8").toString("base64url")}`;
-}
-
-export function decodeUntrustedProviderContinuationState(
-  value: string,
-): ProviderContinuationState | null {
-  if (!value.startsWith(FAMILY_PREFIX)) return null;
-  if (!value.startsWith(PREFIX)) {
-    throw invalidState("invalid_request", "Provider continuation state version is not supported.");
-  }
-
-  const encoded = value.slice(PREFIX.length);
-  if (!encoded || encoded.length > MAX_ENCODED_CHARS || !/^[A-Za-z0-9_-]+$/.test(encoded)) {
-    throw invalidState("invalid_request", "Provider continuation state encoding is invalid.");
-  }
-
-  const bytes = Buffer.from(encoded, "base64url");
-  if (bytes.length > MAX_JSON_BYTES || bytes.toString("base64url") !== encoded) {
-    throw invalidState("invalid_request", "Provider continuation state encoding is invalid.");
-  }
-
-  let decoded: unknown;
-  try {
-    decoded = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
-  } catch {
-    throw invalidState("invalid_request", "Provider continuation state payload is invalid.");
-  }
-  return stateFromEnvelope(validateEnvelope(decoded, "invalid_request"));
-}
-
-export function isOpenAIResponsesApi(api: string): boolean {
-  return api === "openai-responses" || api === "azure-openai-responses";
-}
-
-export function compatibleProviderContinuation(
-  continuation: ProviderContinuationState | undefined,
-  target: ProviderIdentity | null,
-): ProviderContinuationState | null {
-  if (!continuation || !target || !sameProviderIdentity(continuation.source, target)) return null;
-  if (continuation.kind === "openai_reasoning") {
-    return isOpenAIResponsesApi(target.api) ? continuation : null;
-  }
-  return target.api === "anthropic-messages" ? continuation : null;
-}
-
-export function sameProviderIdentity(a: ProviderIdentity, b: ProviderIdentity): boolean {
-  return a.provider === b.provider && a.api === b.api && a.model === b.model;
-}
-
-export function providerIdentityFromModel(model: {
-  provider?: unknown;
-  api?: unknown;
-  id?: unknown;
-}): ProviderIdentity {
-  if (typeof model.provider !== "string" || typeof model.api !== "string" || typeof model.id !== "string") {
-    throw new RouterFrameworkError(
-      "configuration",
-      "Selected model metadata is missing provider identity.",
-      "provider_configuration_error",
-    );
-  }
-  return { provider: model.provider, api: model.api, model: model.id };
-}
-
-function envelopeFor(value: ProviderContinuationState): EnvelopeV1 {
-  if (value.kind === "openai_reasoning") {
-    return {
-      v: 1,
-      kind: value.kind,
-      source: value.source,
-      state: {
-        encrypted_content: value.encryptedContent,
-        ...(value.providerItemId ? { item_id: value.providerItemId } : {}),
-        ...(value.hostedToolCallIds?.length
-          ? { hosted_tool_call_ids: JSON.stringify(value.hostedToolCallIds) }
-          : {}),
-        ...(value.hostedToolCallOffsets?.length
-          ? { hosted_tool_call_offsets: JSON.stringify(value.hostedToolCallOffsets) }
-          : {}),
-      },
-    };
-  }
-  if (value.kind === "anthropic_thinking") {
-    return {
-      v: 1,
-      kind: value.kind,
-      source: value.source,
-      state: { thinking: value.thinking, signature: value.signature },
-    };
-  }
-  return { v: 1, kind: value.kind, source: value.source, state: { data: value.data } };
-}
-
-function stateFromEnvelope(envelope: EnvelopeV1): ProviderContinuationState {
-  if (envelope.kind === "openai_reasoning") {
-    return {
-      kind: envelope.kind,
-      source: envelope.source,
-      encryptedContent: envelope.state.encrypted_content,
-      ...(envelope.state.item_id ? { providerItemId: envelope.state.item_id } : {}),
-      ...(envelope.state.hosted_tool_call_ids
-        ? {
-            hostedToolCallIds: hostedToolCallIds(
-              envelope.state.hosted_tool_call_ids,
-              "invalid_request",
-            ),
-            ...(envelope.state.hosted_tool_call_offsets
-              ? {
-                  hostedToolCallOffsets: hostedToolCallOffsets(
-                    envelope.state.hosted_tool_call_offsets,
-                    "invalid_request",
-                  ),
-                }
-              : {}),
-          }
-        : {}),
-    };
-  }
-  if (envelope.kind === "anthropic_thinking") {
-    return {
-      kind: envelope.kind,
-      source: envelope.source,
-      thinking: envelope.state.thinking,
-      signature: envelope.state.signature,
-    };
-  }
-  return { kind: envelope.kind, source: envelope.source, data: envelope.state.data };
-}
-
-function validateEnvelope(
-  value: unknown,
-  kind: "configuration" | "invalid_request",
-): EnvelopeV1 {
-  if (!isRecord(value) || !hasExactKeys(value, ["v", "kind", "source", "state"]) || value.v !== 1) {
-    throw invalidState(kind, "Provider continuation state schema is invalid.");
-  }
-  if (
-    value.kind !== "openai_reasoning" &&
-    value.kind !== "anthropic_thinking" &&
-    value.kind !== "anthropic_redacted_thinking"
-  ) {
-    throw invalidState(kind, "Provider continuation state kind is invalid.");
-  }
-  return {
-    v: 1,
-    kind: value.kind,
-    source: validateSource(value.source, kind),
-    state: validateState(value.kind, value.state, kind),
-  };
-}
-
-function validateSource(
-  value: unknown,
-  kind: "configuration" | "invalid_request",
-): ProviderIdentity {
-  if (!isRecord(value) || !hasExactKeys(value, ["provider", "api", "model"])) {
-    throw invalidState(kind, "Provider continuation state source is invalid.");
-  }
-  return {
-    provider: boundedString(value.provider, MAX_PROVIDER_LENGTH, kind, "provider"),
-    api: boundedString(value.api, MAX_API_LENGTH, kind, "api"),
-    model: boundedString(value.model, MAX_MODEL_LENGTH, kind, "model"),
-  };
-}
-
-function validateState(
-  continuationKind: ProviderContinuationState["kind"],
-  value: unknown,
-  errorKind: "configuration" | "invalid_request",
-): Record<string, string> {
-  if (!isRecord(value)) {
-    throw invalidState(errorKind, "Provider continuation state payload is invalid.");
-  }
-  if (continuationKind === "openai_reasoning") {
-    const keys = Object.keys(value);
-    const keysValid = keys.includes("encrypted_content")
-      && keys.every((key) =>
-        key === "encrypted_content"
-        || key === "item_id"
-        || key === "hosted_tool_call_ids"
-        || key === "hosted_tool_call_offsets"
-      );
-    if (!keysValid || (value.hosted_tool_call_offsets !== undefined && value.hosted_tool_call_ids === undefined)) {
-      throw invalidState(errorKind, "OpenAI continuation state schema is invalid.");
-    }
-    const ids = value.hosted_tool_call_ids === undefined
-      ? undefined
-      : hostedToolCallIds(
-          nonEmptyString(value.hosted_tool_call_ids, errorKind, "hosted_tool_call_ids"),
-          errorKind,
-        );
-    const offsets = value.hosted_tool_call_offsets === undefined
-      ? undefined
-      : hostedToolCallOffsets(
-          nonEmptyString(value.hosted_tool_call_offsets, errorKind, "hosted_tool_call_offsets"),
-          errorKind,
-        );
-    if (ids && offsets && ids.length !== offsets.length) {
-      throw invalidState(errorKind, "OpenAI hosted tool continuation state is invalid.");
-    }
-    return {
-      encrypted_content: nonEmptyString(value.encrypted_content, errorKind, "encrypted_content"),
-      ...(value.item_id === undefined
-        ? {}
-        : { item_id: boundedString(value.item_id, MAX_ITEM_ID_LENGTH, errorKind, "item_id") }),
-      ...(ids ? { hosted_tool_call_ids: JSON.stringify(ids) } : {}),
-      ...(offsets ? { hosted_tool_call_offsets: JSON.stringify(offsets) } : {}),
-    };
-  }
-  if (continuationKind === "anthropic_thinking") {
-    if (!hasExactKeys(value, ["thinking", "signature"])) {
-      throw invalidState(errorKind, "Anthropic thinking state schema is invalid.");
-    }
-    if (typeof value.thinking !== "string") {
-      throw invalidState(errorKind, "Anthropic thinking text is invalid.");
-    }
-    return {
-      thinking: value.thinking,
-      signature: nonEmptyString(value.signature, errorKind, "signature"),
-    };
-  }
-  if (!hasExactKeys(value, ["data"])) {
-    throw invalidState(errorKind, "Anthropic redacted thinking state schema is invalid.");
-  }
-  return { data: nonEmptyString(value.data, errorKind, "data") };
-}
-
-function hostedToolCallIds(
-  value: string,
-  kind: "configuration" | "invalid_request",
-): string[] {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    throw invalidState(kind, "OpenAI hosted tool continuation state is invalid.");
-  }
-  if (!Array.isArray(parsed) || parsed.length === 0 || parsed.length > MAX_HOSTED_TOOL_CALL_IDS) {
-    throw invalidState(kind, "OpenAI hosted tool continuation state is invalid.");
-  }
-  return parsed.map((id) => boundedString(id, MAX_ITEM_ID_LENGTH, kind, "hosted_tool_call_id"));
-}
-
-function hostedToolCallOffsets(
-  value: string,
-  kind: "configuration" | "invalid_request",
-): number[] {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(value);
-  } catch {
-    throw invalidState(kind, "OpenAI hosted tool continuation state is invalid.");
-  }
-  if (!Array.isArray(parsed) || parsed.length === 0 || parsed.length > MAX_HOSTED_TOOL_CALL_IDS) {
-    throw invalidState(kind, "OpenAI hosted tool continuation state is invalid.");
-  }
-  return parsed.map((offset) => {
-    if (!Number.isSafeInteger(offset) || offset === 0 || Math.abs(offset) > MAX_HOSTED_TOOL_CALL_OFFSET) {
-      throw invalidState(kind, "OpenAI hosted tool continuation state is invalid.");
-    }
-    return offset as number;
-  });
-}
-
-function boundedString(
-  value: unknown,
-  maxLength: number,
-  kind: "configuration" | "invalid_request",
-  field: string,
-): string {
-  const text = nonEmptyString(value, kind, field);
-  if (text.length > maxLength) {
-    throw invalidState(kind, `Provider continuation state ${field} is too long.`);
-  }
-  return text;
-}
-
-function nonEmptyString(
-  value: unknown,
-  kind: "configuration" | "invalid_request",
-  field: string,
-): string {
-  if (typeof value !== "string" || value.length === 0) {
-    throw invalidState(kind, `Provider continuation state ${field} must be a non-empty string.`);
-  }
-  return value;
-}
-
-function hasExactKeys(value: Record<string, unknown>, expected: string[]): boolean {
-  const keys = Object.keys(value).sort();
-  const expectedKeys = [...expected].sort();
-  return keys.length === expectedKeys.length && keys.every((key, index) => key === expectedKeys[index]);
-}
-
-function invalidState(
-  kind: "configuration" | "invalid_request",
-  message: string,
-): RouterFrameworkError {
-  return new RouterFrameworkError(
-    kind,
-    message,
-    "invalid_provider_continuation_state",
-    "input.reasoning.encrypted_content",
-  );
-}