Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

11.3 KB
Raw Blame
import { z } from "zod";

/**
 * Standardization layer for the canonical `effort` + `thinking` request params (#6241).
 *
 * OmniRoute already has a mature, per-provider reasoning-mapping pipeline: the translators
 * consume `reasoning_effort` / `reasoning.effort` / `thinking` and fan them out to the
 * Anthropic thinking blocks, Gemini `thinkingConfig`, xAI `reasoning.effort`, and the
 * Responses API. This module is a THIN normalization layer on top of that plumbing — it
 * does NOT re-implement any provider mapping. It only exposes a single, documented,
 * provider-agnostic pair of request fields and folds them onto the fields the existing
 * mappers already read.
 *
 * The provider-agnostic vocabulary is `none|low|medium|high|xhigh|max`. Provider-native
 * additions such as Codex GPT-5.6 Ultra remain exposed separately.
 */
export const CANONICAL_EFFORT_VALUES = ["none", "low", "medium", "high", "xhigh", "max"] as const;

export type CanonicalEffort = (typeof CANONICAL_EFFORT_VALUES)[number];

/** Use provider-native effort levels without widening the global request vocabulary. */
export function extendCodexGpt56EffortValues(
  provider: string | null | undefined,
  model: string | null | undefined,
  baseValues: readonly string[]
): string[] {
  const values = [...baseValues];
  const normalizedProvider = provider?.trim().toLowerCase();
  const normalizedModel = model
    ?.trim()
    .toLowerCase()
    .replace(/^(?:codex|cx|kiro|kr)\//, "");
  if (!normalizedModel) return values;

  const isKiroProvider = normalizedProvider === "kiro" || normalizedProvider === "kr";
  if (
    isKiroProvider &&
    /^claude-opus-5(?:-(?:none|low|medium|high|xhigh|max))?$/.test(normalizedModel)
  ) {
    return values.includes("max") ? values : [...values, "max"];
  }

  const match = normalizedModel.match(
    /^gpt-(?:5\.6-(sol|terra|luna)|6(?:\.1)?-(astra|sol|luna))(?:-(?:none|low|medium|high|xhigh|max|ultra))?$/
  );
  if (!match) return values;

  if (isKiroProvider) {
    if (!match[1]) return values;
    return values.includes("max") ? values : [...values, "max"];
  }

  if (normalizedProvider !== "codex" && normalizedProvider !== "cx") return values;

  const nativeValues = ["low", "medium", "high", "xhigh", "max"];
  return (match[1] || match[2]) === "luna" ? nativeValues : [...nativeValues, "ultra"];
}

/**
 * UI-facing tier synonyms mapped onto the canonical set. "extra" is a synonym for `xhigh`.
 * `max` is a first-class canonical value and passes through natively.
 */
const EFFORT_TIER_ALIASES: Record<string, CanonicalEffort> = {
  extra: "xhigh",
};

/**
 * DeepSeek V4 exposes a native `max` reasoning tier ABOVE its `high` tier.
 *
 * Per https://api-docs.deepseek.com/api/create-chat-completion the accepted
 * `reasoning_effort` values are `low`, `high` and `max`, the default is `high`,
 * and **`medium` / `xhigh` are both mapped to `high` upstream**. Canonical
 * `max` is first-class (#11875) so `{"effort":"max"}` reaches DeepSeek's
 * native top tier instead of collapsing onto `xhigh` → upstream `high`.
 *
 * Mirrors extendCodexGpt56EffortValues: keep catalog advertising of the native
 * tier idempotent when `max` is already in the base vocabulary.
 */
export function extendDeepSeekEffortValues(
  provider: string | null | undefined,
  model: string | null | undefined,
  baseValues: readonly string[]
): string[] {
  const values = [...baseValues];
  if (!isDeepSeekNativeMaxModel(provider, model)) return values;
  return values.includes("max") ? values : [...values, "max"];
}

/**
 * Whether `<provider>/<model>` is a DeepSeek V4 model served by the native
 * DeepSeek provider (registry id `deepseek`, alias `ds`).
 *
 * Deliberately scoped to the native provider: routed namespaces such as
 * `openrouter/deepseek/...` or `opencode-zen/deepseek-v4-flash-free` terminate at a different
 * upstream whose accepted effort vocabulary we do not control.
 */
export function isDeepSeekNativeMaxModel(
  provider: string | null | undefined,
  model: string | null | undefined
): boolean {
  const rawModel = model?.trim().toLowerCase();
  if (!rawModel) return false;

  // The provider is not always resolved yet at the point the canonical request
  // params are folded in (see chat.ts), so accept either an explicit provider or
  // a `<prefix>/<model>` id carrying the native DeepSeek prefix.
  const prefixMatch = rawModel.match(/^(deepseek|ds)\//);
  const normalizedProvider = provider?.trim().toLowerCase() || prefixMatch?.[1];
  if (normalizedProvider !== "deepseek" && normalizedProvider !== "ds") return false;

  const normalizedModel = rawModel.replace(/^(?:deepseek|ds)\//, "");
  if (!normalizedModel) return false;
  return /^deepseek-v4-(?:pro|flash)(?:-(?:none|minimal|low|medium|high|xhigh|max))?$/.test(
    normalizedModel
  );
}

/**
 * Normalize an arbitrary effort value onto the canonical vocabulary. Accepts the canonical
 * values plus the UI tier synonym (`extra` → `xhigh`), case-insensitively. Returns
 * `undefined` for anything unrecognized so callers can leave the request untouched.
 */
export function normalizeEffort(value: unknown): CanonicalEffort | undefined {
  if (typeof value !== "string") return undefined;
  const lowered = value.trim().toLowerCase();
  if (!lowered) return undefined;
  if (lowered in EFFORT_TIER_ALIASES) return EFFORT_TIER_ALIASES[lowered];
  return (CANONICAL_EFFORT_VALUES as readonly string[]).includes(lowered)
    ? (lowered as CanonicalEffort)
    : undefined;
}

/**
 * Zod schema for the canonical `effort` request field. Accepts the canonical values plus
 * the UI tier synonyms (case-insensitively) and normalizes them onto the canonical set.
 * Unrecognized strings are rejected with a clear enum error.
 */
export const effortRequestSchema = z.preprocess(
  (value) => normalizeEffort(value) ?? value,
  z.enum(CANONICAL_EFFORT_VALUES)
);

/**
 * Zod schema for the canonical `thinking` request field: a simple boolean toggle. Kept as
 * a union with an object so the existing Anthropic-style `thinking: { type, budget_tokens }`
 * object shape that clients already send keeps validating (backward compatible) — the
 * normalizer only acts on the boolean form.
 */
export const thinkingRequestSchema = z.union([z.boolean(), z.record(z.string(), z.unknown())]);

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/** Read a request body's `model` field when it is a usable string. */
function asModelId(value: unknown): string | undefined {
  return typeof value === "string" && value.trim() ? value : undefined;
}

function hasCompetingReasoningControl(
  body: Record<string, unknown>,
  reasoning: Record<string, unknown>
): boolean {
  const outputConfig = isPlainObject(body.output_config) ? body.output_config : null;
  const templateKwargs = isPlainObject(body.chat_template_kwargs)
    ? body.chat_template_kwargs
    : null;
  const generationConfig = isPlainObject(body.generationConfig) ? body.generationConfig : null;
  return (
    body.reasoningEffort !== undefined ||
    body.thinking !== undefined ||
    body.thinkingLevel !== undefined ||
    body.thinking_level !== undefined ||
    body.thinking_budget !== undefined ||
    body.thinkingBudget !== undefined ||
    outputConfig?.effort !== undefined ||
    reasoning.budget_tokens !== undefined ||
    reasoning.budgetTokens !== undefined ||
    reasoning.max_tokens !== undefined ||
    typeof templateKwargs?.thinking === "boolean" ||
    typeof templateKwargs?.enable_thinking === "boolean" ||
    generationConfig?.thinkingConfig !== undefined ||
    generationConfig?.thinking_config !== undefined
  );
}

/** Whether OpenRouter's disabled toggle is the request's only reasoning control. */
export function shouldDeriveDisabledReasoningEffort(body: Record<string, unknown>): boolean {
  const reasoning = isPlainObject(body.reasoning) ? body.reasoning : null;
  if (reasoning?.enabled !== false) return false;
  return (
    body.reasoning_effort === undefined &&
    reasoning.effort === undefined &&
    body.effort === undefined &&
    !hasCompetingReasoningControl(body, reasoning)
  );
}

/**
 * Fold the canonical `effort` / `thinking` request params onto the per-provider reasoning
 * fields the existing translators already consume (`reasoning_effort`, `reasoning.effort`,
 * `thinking`). Pure function — returns the same reference untouched when there is nothing
 * to normalize, otherwise a shallow copy with the derived fields populated.
 *
 * Backward compatibility rules (an explicit client signal ALWAYS wins):
 *  - `reasoning_effort` / `reasoning.effort` explicitly set by the client are never
 *    overwritten by the canonical `effort`.
 *  - OpenRouter-style `reasoning.enabled: false` becomes the canonical `none` fallback
 *    only when no explicit effort, thinking, native override, or budget is present.
 *  - An explicit object-shaped `thinking` (the Anthropic `{ type, budget_tokens }` config)
 *    is never overwritten by the canonical boolean `thinking`.
 */
export function normalizeReasoningRequest<T>(body: T, provider?: string | null): T {
  if (!isPlainObject(body)) return body;

  // DeepSeek V4 has a native `max` tier above `high`. Canonical `max` normally
  // collapses to `xhigh`, which DeepSeek maps back down to `high` — so preserve
  // the literal value for those models instead of round-tripping it away.
  const rawEffort = typeof body.effort === "string" ? body.effort.trim().toLowerCase() : undefined;
  const canonicalEffort =
    rawEffort === "max" && isDeepSeekNativeMaxModel(provider, asModelId(body.model))
      ? ("max" as const)
      : normalizeEffort(body.effort);
  const canonicalThinking = body.thinking;
  const hasCanonicalThinkingBool = typeof canonicalThinking === "boolean";
  const reasoning = body.reasoning;
  const reasoningRecord = isPlainObject(reasoning) ? reasoning : null;
  const clientDisabledReasoning = reasoningRecord?.enabled === false;

  if (canonicalEffort === undefined && !hasCanonicalThinkingBool && !clientDisabledReasoning) {
    return body;
  }

  const clientSetReasoningEffort = body.reasoning_effort !== undefined;
  const clientSetReasoningObjEffort = reasoningRecord?.effort !== undefined;
  const effectiveEffort =
    canonicalEffort ?? (shouldDeriveDisabledReasoningEffort(body) ? "none" : undefined);

  const next: Record<string, unknown> = { ...body };
  const normalizedReasoning = reasoningRecord ? { ...reasoningRecord } : null;
  if (clientDisabledReasoning && normalizedReasoning) delete normalizedReasoning.enabled;

  // Resolved effort → the fields the mappers read. Skip entirely if the client already
  // expressed a reasoning effort (either shape) so client intent is preserved.
  if (effectiveEffort !== undefined && !clientSetReasoningEffort && !clientSetReasoningObjEffort) {
    next.reasoning_effort = effectiveEffort;
    next.reasoning = {
      ...(normalizedReasoning ?? {}),
      effort: effectiveEffort,
    };
  } else if (clientDisabledReasoning) {
    if (normalizedReasoning && Object.keys(normalizedReasoning).length > 0) {
      next.reasoning = normalizedReasoning;
    } else {
      delete next.reasoning;
    }
  }

  // Canonical boolean `thinking` → keep the truthy toggle the mappers read. Only when the
  // client did NOT provide an explicit object-shaped thinking config (that always wins).
  if (hasCanonicalThinkingBool) {
    next.thinking = canonicalThinking;
  }

  return next as T;
}