@mupt-ai/dari-router 0.1.0 → 0.2.0

package/src/framework_models.ts

@@ -1,186 +0,0 @@
-import { providerForModel } from "./model_ids.js";
-import { RouterFrameworkError } from "./framework_error.js";
-import { isReasoningEffort } from "./types.js";
-import type {
-  RouterCandidate,
-  RouterExecutor,
-  RouterModel,
-  RouterRequest,
-} from "./framework_types.js";
-
-const DEFAULT_CAPABILITIES = {
-  imageInput: false,
-  toolUse: false,
-  structuredOutput: false,
-  streaming: false,
-} as const;
-
-export function normalizeRouterModels<Metadata>(
-  models: readonly RouterModel<Metadata>[],
-  executors: Readonly<Record<string, RouterExecutor<Metadata>>>,
-): RouterCandidate<Metadata>[] {
-  if (!Array.isArray(models) || models.length === 0) {
-    throw configurationError("A router requires at least one model.", "models_empty");
-  }
-  if (!executors || typeof executors !== "object") {
-    throw configurationError("executors must be an object.", "executors_invalid");
-  }
-
-  const ids = new Set<string>();
-  return models.map((model, index) => {
-    if (typeof model?.id !== "string" || !model.id.trim() || model.id !== model.id.trim()) {
-      throw configurationError(`models[${index}].id must be a trimmed non-empty string.`, "model_invalid");
-    }
-    if (ids.has(model.id)) {
-      throw configurationError(`Duplicate router model '${model.id}'.`, "model_duplicate");
-    }
-    ids.add(model.id);
-    if (
-      typeof model.executor !== "string" ||
-      !model.executor.trim() ||
-      model.executor !== model.executor.trim() ||
-      !Object.hasOwn(executors, model.executor)
-    ) {
-      throw configurationError(
-        `Model '${model.id}' references missing executor '${String(model.executor)}'.`,
-        "executor_missing",
-      );
-    }
-    const executor = executors[model.executor];
-    if (!executor || typeof executor.execute !== "function") {
-      throw configurationError(
-        `Executor '${model.executor}' must define an execute function.`,
-        "executor_invalid",
-      );
-    }
-
-    const reasoningEfforts = model.reasoningEfforts === undefined
-      ? ["off" as const]
-      : [...model.reasoningEfforts];
-    if (
-      reasoningEfforts.length === 0 ||
-      reasoningEfforts.some((effort) => !isReasoningEffort(effort)) ||
-      new Set(reasoningEfforts).size !== reasoningEfforts.length
-    ) {
-      throw configurationError(
-        `Model '${model.id}' must declare unique supported reasoning efforts.`,
-        "model_reasoning_invalid",
-      );
-    }
-    const defaultReasoningEffort = model.defaultReasoningEffort ?? reasoningEfforts[0]!;
-    if (!reasoningEfforts.includes(defaultReasoningEffort)) {
-      throw configurationError(
-        `Model '${model.id}' default reasoning effort is not supported by that model.`,
-        "model_reasoning_invalid",
-      );
-    }
-
-    let provider = model.provider;
-    if (provider !== undefined && (
-      typeof provider !== "string" || !provider.trim() || provider !== provider.trim()
-    )) {
-      throw configurationError(
-        `Model '${model.id}' provider must be a trimmed non-empty string.`,
-        "model_provider_invalid",
-      );
-    }
-    if (provider === undefined) {
-      try {
-        provider = providerForModel(model.id);
-      } catch (error) {
-        throw configurationError(
-          `Model '${model.id}' needs an explicit provider because its id has no provider prefix.`,
-          "model_provider_missing",
-          error,
-        );
-      }
-    }
-
-    const api = model.api ?? model.executor;
-    if (typeof api !== "string" || !api.trim() || api !== api.trim()) {
-      throw configurationError(
-        `Model '${model.id}' api must be a trimmed non-empty string.`,
-        "model_api_invalid",
-      );
-    }
-    const capabilities = { ...DEFAULT_CAPABILITIES, ...model.capabilities };
-    if (Object.values(capabilities).some((value) => typeof value !== "boolean")) {
-      throw configurationError(
-        `Model '${model.id}' capabilities must be booleans.`,
-        "model_capabilities_invalid",
-      );
-    }
-
-    return {
-      id: model.id,
-      executor: model.executor,
-      provider,
-      api,
-      reasoningEfforts,
-      defaultReasoningEffort,
-      capabilities,
-      ...(model.metadata === undefined ? {} : { metadata: model.metadata }),
-    };
-  });
-}
-
-export function eligibleRouterModels<Metadata>(
-  request: RouterRequest,
-  models: readonly RouterCandidate<Metadata>[],
-): RouterCandidate<Metadata>[] {
-  const requiresImage = request.items.some((item) =>
-    item.type === "message"
-      ? item.content.some((part) => part.type === "image")
-      : item.type === "tool_result" && item.content.some((part) => part.type === "image"),
-  );
-  const requiresTools = request.tools.length > 0 || request.items.some((item) =>
-    item.type === "tool_call" || item.type === "tool_result" || item.type === "hosted_tool_call",
-  );
-  const requiresStructuredOutput =
-    request.responseFormat !== undefined && request.responseFormat.type !== "text";
-  const requestedEffort = request.reasoning?.effort;
-
-  const eligible = models.flatMap((model) => {
-    if (requiresImage && !model.capabilities.imageInput) return [];
-    if (requiresTools && !model.capabilities.toolUse) return [];
-    if (requiresStructuredOutput && !model.capabilities.structuredOutput) return [];
-    if (request.stream && !model.capabilities.streaming) return [];
-
-    const efforts = requestedEffort === undefined
-      ? request.reasoning?.enabled === true
-        ? model.reasoningEfforts.filter((effort) => effort !== "off")
-        : [...model.reasoningEfforts]
-      : model.reasoningEfforts.includes(requestedEffort)
-        ? [requestedEffort]
-        : [];
-    if (efforts.length === 0) return [];
-    return [{
-      ...model,
-      reasoningEfforts: efforts,
-      defaultReasoningEffort: efforts.includes(model.defaultReasoningEffort)
-        ? model.defaultReasoningEffort
-        : efforts[0]!,
-    }];
-  });
-
-  if (eligible.length > 0) return eligible;
-  throw new RouterFrameworkError(
-    "invalid_request",
-    "No configured model supports this request's protocol features and reasoning settings.",
-    "no_eligible_models",
-  );
-}
-
-function configurationError(
-  message: string,
-  code: string,
-  cause?: unknown,
-): RouterFrameworkError {
-  return new RouterFrameworkError(
-    "configuration",
-    message,
-    code,
-    undefined,
-    cause === undefined ? undefined : { cause },
-  );
-}

package/src/framework_router.ts

@@ -1,490 +0,0 @@
-import { RouterFrameworkError } from "./framework_error.js";
-import { eligibleRouterModels, normalizeRouterModels } from "./framework_models.js";
-import {
-  anthropicRequest,
-  anthropicResponse,
-} from "./protocol_anthropic.js";
-import {
-  openAIChatRequest,
-  openAIChatResponse,
-} from "./protocol_openai_chat.js";
-import {
-  primeStream,
-  streamResponse,
-  type StartedExecution,
-} from "./framework_streaming.js";
-import {
-  cancelled,
-  closeAsyncIterable,
-  closeAsyncIterator,
-  errorMessage,
-  executorStartError,
-  normalizeError,
-  safeHook,
-  throwIfAborted,
-} from "./framework_lifecycle.js";
-import {
-  validateCompletion,
-  validatePolicyDecision,
-} from "./framework_validation.js";
-import type { ReasoningEffort } from "./types.js";
-import type {
-  CreateRouterOptions,
-  LeaseStore,
-  Router,
-  RouterCandidate,
-  RouterExecutor,
-  RouterExecutorResult,
-  RouterLease,
-  RouterProtocol,
-  RouterRequest,
-  RouterSelection,
-  RoutingPolicyDecision,
-} from "./framework_types.js";
-
-export function createRouter<Metadata = unknown>(
-  options: CreateRouterOptions<Metadata>,
-): Router<Metadata> {
-  if (
-    typeof options.policy !== "function" &&
-    (!options.policy || typeof options.policy.select !== "function")
-  ) {
-    throw new RouterFrameworkError(
-      "configuration",
-      "policy must be a function or define a select function.",
-      "policy_invalid",
-    );
-  }
-  if (options.generateId !== undefined && typeof options.generateId !== "function") {
-    throw new RouterFrameworkError(
-      "configuration",
-      "generateId must be a function.",
-      "id_generator_invalid",
-    );
-  }
-  const executors: Record<string, RouterExecutor<Metadata>> = {
-    ...(options.runtime === undefined ? {} : { pi: options.runtime }),
-    ...(options.executors ?? {}),
-  };
-  const modelDeclarations = options.models.map((model) =>
-    model.executor === undefined ? { ...model, executor: "pi" } : model
-  );
-  const models = Object.freeze(normalizeRouterModels(modelDeclarations, executors));
-  // In-memory lease commitments keyed by request cacheKey. When a policy
-  // returns leaseTurnsRemaining > 0, the router serves the same model for
-  // subsequent requests sharing the cacheKey without calling the policy
-  // again, decrementing the remaining turns each time. Leases dissolve when
-  // the leased model is no longer an eligible candidate, when their turns run
-  // out, or when they sit unused past LEASE_TTL_MS (abandoned conversations
-  // must not accumulate).
-  const LEASE_TTL_MS = 30 * 60_000;
-  // Default in-memory lease store; callers can inject a persistent store.
-  const leaseStore: LeaseStore = options.leaseStore ?? inMemoryLeaseStore();
-  // Store calls are advisory: an injected store that throws must never fail the request.
-  const tryLeaseStore = async <T>(op: () => T | Promise<T>): Promise<T | undefined> => {
-    try {
-      return await op();
-    } catch {
-      return undefined;
-    }
-  };
-  const hooks = options.hooks ?? {};
-  const fallbackConfig = options.fallback ?? {};
-  const idGenerator = options.generateId ?? (() => globalThis.crypto.randomUUID());
-  const generateId = (): string => {
-    const id = idGenerator();
-    if (typeof id !== "string" || !id.trim()) {
-      throw new RouterFrameworkError(
-        "configuration",
-        "generateId must return a non-empty string.",
-        "id_generator_invalid",
-      );
-    }
-    return id;
-  };
-
-  const selectWithoutLeases = async (
-    request: RouterRequest,
-    signal: AbortSignal = new AbortController().signal,
-  ): Promise<RouterSelection<Metadata>> => {
-    throwIfAborted(signal);
-    const candidates = eligibleRouterModels(request, models);
-    let chosen: RoutingPolicyDecision;
-    try {
-      chosen = await (typeof options.policy === "function"
-        ? options.policy({ request, candidates, signal })
-        : options.policy.select({ request, candidates, signal }));
-    } catch (error) {
-      if (signal.aborted) throw cancelled(signal.reason);
-      if (error instanceof RouterFrameworkError) throw error;
-      throw new RouterFrameworkError(
-        "policy",
-        errorMessage(error, "Routing policy failed."),
-        "policy_failed",
-        undefined,
-        { cause: error },
-      );
-    }
-    throwIfAborted(signal);
-    return validatePolicyDecision(chosen, candidates);
-  };
-
-  // Real serving path: consumes and commits leases keyed by cacheKey. The
-  // public select() above never mutates lease state, so callers can inspect
-  // decisions (e.g. auto-router thinking traces) without burning selection
-  // turns or skipping committed leases.
-  const selectWithLeases = async (
-    request: RouterRequest,
-    signal: AbortSignal,
-  ): Promise<RouterSelection<Metadata>> => {
-    throwIfAborted(signal);
-    const candidates = eligibleRouterModels(request, models);
-
-    // Lease short-circuit: if a prior decision committed turns to a model that
-    // is still eligible for this request, serve it without calling the policy.
-    const leaseKey = leaseKeyFor(request);
-    if (leaseKey !== undefined) {
-      const now = Date.now();
-      await tryLeaseStore(() => leaseStore.pruneExpired(now));
-      const lease = await tryLeaseStore(() => leaseStore.get(leaseKey));
-      if (lease !== undefined) {
-        // Defensive expiry check: pruneExpired is advisory and injected
-        // stores may not implement it strictly.
-        const candidate = lease.expiresAt > now
-          ? candidates.find(
-              (item) => item.id === lease.model && item.reasoningEfforts.includes(lease.reasoningEffort),
-            )
-          : undefined;
-        if (candidate !== undefined) {
-          const turnsRemaining = lease.turnsRemaining - 1;
-          if (turnsRemaining <= 0) await tryLeaseStore(() => leaseStore.delete(leaseKey));
-          else {
-            await tryLeaseStore(() =>
-              leaseStore.set(leaseKey, {
-                ...lease,
-                turnsRemaining,
-                expiresAt: now + LEASE_TTL_MS,
-              })
-            );
-          }
-          return {
-            decision: {
-              selectedModel: candidate.id,
-              reasoningEffort: lease.reasoningEffort,
-              reason: `Serving committed lease (${turnsRemaining <= 0 ? "final" : `${turnsRemaining} left`}).`,
-              ...(turnsRemaining <= 0 ? {} : { leaseTurnsRemaining: turnsRemaining }),
-            },
-            candidates,
-          };
-        }
-        await tryLeaseStore(() => leaseStore.delete(leaseKey));
-      }
-    }
-
-    const selection = await selectWithoutLeases(request, signal);
-
-    // Record a new lease when the policy committed turns and the request
-    // carries a cacheKey to correlate subsequent turns.
-    if (
-      leaseKey !== undefined &&
-      selection.decision.leaseTurnsRemaining !== undefined &&
-      selection.decision.leaseTurnsRemaining > 0
-    ) {
-      await tryLeaseStore(() =>
-        leaseStore.set(leaseKey, {
-          model: selection.decision.selectedModel,
-          reasoningEffort: selection.decision.reasoningEffort,
-          turnsRemaining: selection.decision.leaseTurnsRemaining!,
-          expiresAt: Date.now() + LEASE_TTL_MS,
-        })
-      );
-    }
-
-    return selection;
-  };
-
-  const fetch = async (request: Request): Promise<Response> => {
-    const protocol = protocolFor(request);
-    if (protocol === null) {
-      return errorResponse(
-        "openai_chat_completions",
-        new RouterFrameworkError("not_found", "Not found.", "not_found"),
-      );
-    }
-    if (request.method !== "POST") {
-      return Response.json(
-        protocol === "anthropic_messages"
-          ? {
-              type: "error",
-              error: { type: "invalid_request_error", message: "Method not allowed. Use POST." },
-            }
-          : {
-              error: {
-                message: "Method not allowed. Use POST.",
-                type: "invalid_request_error",
-                code: "method_not_allowed",
-              },
-            },
-        { status: 405, headers: { Allow: "POST" } },
-      );
-    }
-
-    const controller = new AbortController();
-    const abort = () => controller.abort(request.signal.reason);
-    if (request.signal.aborted) abort();
-    else request.signal.addEventListener("abort", abort, { once: true });
-
-    let streamOwnsAbortListener = false;
-    let effectiveSelection: RouterSelection<Metadata> | undefined;
-    try {
-      const payload = await parseJson(request);
-      const normalized = protocol === "openai_chat_completions"
-        ? openAIChatRequest(payload)
-        : anthropicRequest(payload);
-      const selection = await selectWithLeases(normalized, controller.signal);
-      effectiveSelection = selection;
-      safeHook(() => hooks.onSelection?.(selection, normalized));
-      const model = selection.candidates.find(
-        (candidate) => candidate.id === selection.decision.selectedModel,
-      )!;
-      // eligibleRouterModels guarantees each candidate's default effort is in
-      // its (filtered) reasoningEfforts.
-      const effectiveEffort = (candidate: RouterCandidate<Metadata>): ReasoningEffort =>
-        candidate.reasoningEfforts.includes(selection.decision.reasoningEffort)
-          ? selection.decision.reasoningEffort
-          : candidate.defaultReasoningEffort;
-      // Primes streams here: first-pull provider failures must surface inside
-      // the fallback-covered region, before anything reaches the client.
-      const startWithModel = async (
-        candidate: RouterCandidate<Metadata>,
-      ): Promise<StartedExecution> => {
-        const attempt: RouterExecutorResult = await executors[candidate.executor]!.execute({
-          request: normalized,
-          model: candidate,
-          decision: {
-            ...selection.decision,
-            selectedModel: candidate.id,
-            reasoningEffort: effectiveEffort(candidate),
-          },
-          signal: controller.signal,
-        });
-        if (normalized.stream) {
-          if (attempt.type !== "stream") {
-            throw new RouterFrameworkError(
-              "executor",
-              `Executor '${candidate.executor}' returned a non-streaming result for a streaming request.`,
-              "executor_mode_mismatch",
-            );
-          }
-          return { type: "stream", primed: await primeStream(attempt.events, controller) };
-        }
-        if (attempt.type !== "complete") {
-          await closeAsyncIterable(attempt.events);
-          throw new RouterFrameworkError(
-            "executor",
-            `Executor '${candidate.executor}' returned a stream for a non-streaming request.`,
-            "executor_mode_mismatch",
-          );
-        }
-        validateCompletion(attempt.output);
-        return { type: "complete", output: attempt.output };
-      };
-      const leaseKey = leaseKeyFor(normalized);
-      let started: StartedExecution;
-      let executedModel = model;
-      try {
-        started = await startWithModel(model);
-      } catch (error) {
-        if (controller.signal.aborted) throw cancelled(controller.signal.reason);
-        const startError = executorStartError(error, model.executor);
-        // Pure cancellation keeps the lease: the user aborted, the model did
-        // not fail.
-        if (startError.kind === "cancelled") throw startError;
-        // Drop before the fallback attempt: any lease pins the failing primary.
-        if (leaseKey !== undefined) await tryLeaseStore(() => leaseStore.delete(leaseKey));
-        // Fallback: try a different model if configured and available.
-        const fallback = fallbackCandidate(selection, model, fallbackConfig);
-        if (fallback === undefined) throw startError;
-        try {
-          started = await startWithModel(fallback);
-        } catch (fallbackError) {
-          if (controller.signal.aborted) throw cancelled(controller.signal.reason);
-          throw executorStartError(fallbackError, fallback.executor);
-        }
-        executedModel = fallback;
-        effectiveSelection = {
-          ...selection,
-          decision: {
-            selectedModel: fallback.id,
-            reasoningEffort: effectiveEffort(fallback),
-            reason: `Fell back to '${fallback.id}' after executor for '${selection.decision.selectedModel}' failed. Original reason: ${selection.decision.reason}`,
-          },
-        };
-      }
-
-      const served = effectiveSelection;
-
-      if (started.type === "stream") {
-        const primedStream = started.primed;
-        try {
-          throwIfAborted(controller.signal);
-          const response = streamResponse({
-            protocol,
-            id: generateId(),
-            model: executedModel.id,
-            requestedModel: normalized.requestedModel,
-            selection: served,
-            primed: primedStream,
-            controller,
-            headers: selectionHeaders(served),
-            // Not awaited: stream teardown must not stall on the store; turns/TTL backstop.
-            onStreamFailure: leaseKey === undefined ? undefined : () => {
-              void tryLeaseStore(() => leaseStore.delete(leaseKey));
-            },
-            onFinalize: (completion, error) => {
-              request.signal.removeEventListener("abort", abort);
-              if (hooks.onStreamClose) {
-                safeHook(() => hooks.onStreamClose!(completion, served, error));
-              }
-            },
-          });
-          streamOwnsAbortListener = true;
-          return response;
-        } catch (error) {
-          await closeAsyncIterator(primedStream.iterator);
-          throw error;
-        }
-      }
-      throwIfAborted(controller.signal);
-      const id = generateId();
-      const output = started.output;
-      safeHook(() => hooks.onCompletion?.(output, served));
-      return Response.json(
-        protocol === "openai_chat_completions"
-          ? openAIChatResponse({
-              id,
-              model: executedModel.id,
-              requestedModel: normalized.requestedModel,
-              output,
-              selection: served,
-            })
-          : anthropicResponse({
-              id,
-              model: executedModel.id,
-              requestedModel: normalized.requestedModel,
-              output,
-              selection: served,
-            }),
-        { headers: selectionHeaders(served) },
-      );
-    } catch (error) {
-      const normalizedError = request.signal.aborted
-        ? cancelled(request.signal.reason)
-        : normalizeError(error);
-      const errorSelection = effectiveSelection;
-      if (errorSelection !== undefined) {
-        safeHook(() => hooks.onError?.(normalizedError, errorSelection));
-      }
-      return errorResponse(protocol, normalizedError);
-    } finally {
-      if (!streamOwnsAbortListener) request.signal.removeEventListener("abort", abort);
-    }
-  };
-
-  return { models, select: selectWithoutLeases, fetch };
-}
-function protocolFor(request: Request): RouterProtocol | null {
-  const path = new URL(request.url).pathname.replace(/\/+$/, "");
-  if (path === "/v1/chat/completions" || path === "/chat/completions") {
-    return "openai_chat_completions";
-  }
-  if (path === "/v1/messages" || path === "/messages") return "anthropic_messages";
-  return null;
-}
-
-async function parseJson(request: Request): Promise<unknown> {
-  try {
-    return await request.json();
-  } catch (error) {
-    throw new RouterFrameworkError(
-      "invalid_request",
-      "Request body is not valid JSON.",
-      "invalid_json",
-      undefined,
-      { cause: error },
-    );
-  }
-}
-
-function selectionHeaders<Metadata>(selection: RouterSelection<Metadata>): Headers {
-  return new Headers({
-    "X-Router-Selected-Model": selection.decision.selectedModel,
-    "X-Router-Reasoning-Effort": selection.decision.reasoningEffort,
-  });
-}
-
-function errorResponse(protocol: RouterProtocol, error: RouterFrameworkError): Response {
-  if (protocol === "anthropic_messages") {
-    return Response.json(
-      {
-        type: "error",
-        error: {
-          type: error.status >= 500 ? "api_error" : "invalid_request_error",
-          message: error.message,
-        },
-      },
-      { status: error.status },
-    );
-  }
-  return Response.json(
-    {
-      error: {
-        message: error.message,
-        type: error.status >= 500 ? "server_error" : "invalid_request_error",
-        code: error.code,
-        ...(error.param === undefined ? {} : { param: error.param }),
-      },
-    },
-    { status: error.status },
-  );
-}
-
-function fallbackCandidate<Metadata>(
-  selection: RouterSelection<Metadata>,
-  primary: RouterCandidate<Metadata>,
-  config: { enabled?: boolean; requiresDifferentProvider?: boolean },
-): RouterCandidate<Metadata> | undefined {
-  if (!config.enabled) return undefined;
-  return selection.candidates.find((candidate) => {
-    if (candidate.id === primary.id) return false;
-    if (config.requiresDifferentProvider && candidate.provider === primary.provider) return false;
-    return true;
-  });
-}
-
-// Protocol adapters normalize empty cache keys away, but programmatic
-// callers can still pass "": treat it as no cache key so unrelated requests
-// never share a lease bucket.
-function leaseKeyFor(request: RouterRequest): string | undefined {
-  return request.cacheKey !== undefined && request.cacheKey.trim()
-    ? request.cacheKey
-    : undefined;
-}
-
-function inMemoryLeaseStore(): LeaseStore {
-  const leases = new Map<string, RouterLease>();
-  return {
-    get: (cacheKey) => leases.get(cacheKey),
-    set: (cacheKey, lease) => {
-      leases.set(cacheKey, lease);
-    },
-    delete: (cacheKey) => {
-      leases.delete(cacheKey);
-    },
-    pruneExpired: (nowMs) => {
-      for (const [cacheKey, lease] of leases) {
-        if (lease.expiresAt <= nowMs) leases.delete(cacheKey);
-      }
-    },
-  };
-}