localarena 0.1.0 → 0.2.0

package/javascript/src/providers.js

@@ -0,0 +1,1303 @@
+const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_MAX_RETRIES = 0;
+const DEFAULT_RETRY_BASE_MS = 500;
+const DEFAULT_RETRY_MAX_MS = 8_000;
+const DEFAULT_MAX_RESPONSE_BYTES = 8 * 1024 * 1024;
+
+const RESERVED_REQUEST_FIELDS = new Set([
+  "model",
+  "messages",
+  "stream",
+  "max_tokens",
+  "max_completion_tokens",
+  "temperature",
+  "seed",
+  "stop",
+]);
+
+const TARGET_REQUEST_OVERRIDE_FIELDS = new Set([
+  "maxTokens",
+  "maxOutputTokens",
+  "max_tokens",
+  "temperature",
+  "seed",
+  "stop",
+  "extraBody",
+  "extra_body",
+]);
+
+const DEFAULT_RETRY_STATUSES = Object.freeze([
+  408,
+  429,
+  500,
+  502,
+  503,
+  504,
+]);
+
+const PROVIDER_PRESETS = Object.freeze({
+  llamacpp: Object.freeze({
+    id: "llamacpp",
+    baseURL: "http://127.0.0.1:8080/v1",
+    maxTokensField: "max_tokens",
+  }),
+  ollama: Object.freeze({
+    id: "ollama",
+    baseURL: "http://127.0.0.1:11434/v1",
+    maxTokensField: "max_tokens",
+  }),
+  lmstudio: Object.freeze({
+    id: "lmstudio",
+    baseURL: "http://127.0.0.1:1234/v1",
+    maxTokensField: "max_tokens",
+  }),
+  openrouter: Object.freeze({
+    id: "openrouter",
+    baseURL: "https://openrouter.ai/api/v1",
+    maxTokensField: "max_tokens",
+    requiresAPIKey: true,
+  }),
+  openai: Object.freeze({
+    id: "openai",
+    baseURL: "https://api.openai.com/v1",
+    maxTokensField: "max_completion_tokens",
+    requiresAPIKey: true,
+  }),
+});
+
+function assertRecord(value, field) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${field} must be an object`);
+  }
+}
+
+function assertNonEmptyString(value, field) {
+  if (typeof value !== "string") {
+    throw new TypeError(`${field} must be a string`);
+  }
+  if (value.trim().length === 0) {
+    throw new RangeError(`${field} must not be empty`);
+  }
+}
+
+function assertOptionalString(value, field) {
+  if (value === undefined || value === null) {
+    return;
+  }
+  assertNonEmptyString(value, field);
+}
+
+function compareCodePoints(left, right) {
+  const leftPoints = Array.from(left, (value) => value.codePointAt(0));
+  const rightPoints = Array.from(right, (value) => value.codePointAt(0));
+  const length = Math.min(leftPoints.length, rightPoints.length);
+
+  for (let index = 0; index < length; index += 1) {
+    if (leftPoints[index] !== rightPoints[index]) {
+      return leftPoints[index] - rightPoints[index];
+    }
+  }
+  return leftPoints.length - rightPoints.length;
+}
+
+function assertFiniteNumber(value, field, minimum = -Infinity) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new TypeError(`${field} must be a finite number`);
+  }
+  if (value < minimum) {
+    throw new RangeError(`${field} must be at least ${minimum}`);
+  }
+}
+
+function assertSafeInteger(value, field, minimum = Number.MIN_SAFE_INTEGER) {
+  if (!Number.isSafeInteger(value)) {
+    throw new TypeError(`${field} must be a safe integer`);
+  }
+  if (value < minimum) {
+    throw new RangeError(`${field} must be at least ${minimum}`);
+  }
+}
+
+function freezeJson(value, field) {
+  const seen = new Set();
+
+  function clone(current, path) {
+    if (
+      current === null ||
+      typeof current === "string" ||
+      typeof current === "boolean"
+    ) {
+      return current;
+    }
+    if (typeof current === "number") {
+      if (!Number.isFinite(current)) {
+        throw new TypeError(`${path} must contain only finite numbers`);
+      }
+      if (Number.isInteger(current) && !Number.isSafeInteger(current)) {
+        throw new TypeError(`${path} integers must be within the safe range`);
+      }
+      return current;
+    }
+    if (typeof current !== "object") {
+      throw new TypeError(`${path} must contain only JSON values`);
+    }
+    if (seen.has(current)) {
+      throw new TypeError(`${field} must not contain cycles`);
+    }
+
+    seen.add(current);
+    let result;
+    if (Array.isArray(current)) {
+      result = current.map((item, index) => clone(item, `${path}[${index}]`));
+    } else {
+      const prototype = Object.getPrototypeOf(current);
+      if (prototype !== Object.prototype && prototype !== null) {
+        throw new TypeError(`${path} must contain only plain objects`);
+      }
+      result = {};
+      for (const [key, item] of Object.entries(current)) {
+        Object.defineProperty(result, key, {
+          configurable: true,
+          enumerable: true,
+          value: clone(item, `${path}.${key}`),
+          writable: true,
+        });
+      }
+    }
+    seen.delete(current);
+    return Object.freeze(result);
+  }
+
+  return clone(value, field);
+}
+
+function normalizeBaseURL(value) {
+  assertNonEmptyString(value, "baseURL");
+
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new ProviderConfigurationError("baseURL must be a valid URL");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new ProviderConfigurationError(
+      "baseURL must use the http or https protocol",
+    );
+  }
+  if (parsed.username || parsed.password) {
+    throw new ProviderConfigurationError(
+      "baseURL must not contain credentials",
+    );
+  }
+  if (parsed.search || parsed.hash) {
+    throw new ProviderConfigurationError(
+      "baseURL must not contain a query or fragment",
+    );
+  }
+
+  return parsed.href.replace(/\/+$/, "");
+}
+
+function normalizeHeaders(headers) {
+  assertRecord(headers, "headers");
+  const normalized = {};
+
+  for (const [rawName, rawValue] of Object.entries(headers)) {
+    assertNonEmptyString(rawName, "header name");
+    if (typeof rawValue !== "string") {
+      throw new TypeError("header values must be strings");
+    }
+    if (/[\r\n]/u.test(rawName) || /[\r\n]/u.test(rawValue)) {
+      throw new TypeError("headers must not contain line breaks");
+    }
+    const name = rawName.toLowerCase();
+    if (name === "host" || name === "content-length") {
+      throw new ProviderConfigurationError(
+        `${name} cannot be supplied as a default header`,
+      );
+    }
+    normalized[name] = rawValue;
+  }
+
+  return Object.freeze(normalized);
+}
+
+function optionalNonNegativeInteger(value, field) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+  assertSafeInteger(value, field, 0);
+  return value;
+}
+
+function normalizeUsage(value) {
+  if (value === undefined || value === null) {
+    return new TokenUsage();
+  }
+  assertRecord(value, "usage");
+  return new TokenUsage({
+    inputTokens: value.prompt_tokens,
+    outputTokens: value.completion_tokens,
+    totalTokens: value.total_tokens,
+    cachedInputTokens: value.prompt_tokens_details?.cached_tokens,
+    reasoningTokens: value.completion_tokens_details?.reasoning_tokens,
+  });
+}
+
+function extractTextContent(content) {
+  if (typeof content === "string") {
+    return content;
+  }
+  if (!Array.isArray(content)) {
+    throw new ProviderResponseError(
+      "provider response did not contain text content",
+    );
+  }
+
+  const text = [];
+  let foundText = false;
+  for (const part of content) {
+    if (typeof part === "string") {
+      text.push(part);
+      foundText = true;
+      continue;
+    }
+    if (part === null || typeof part !== "object" || part.type !== "text") {
+      continue;
+    }
+    if (typeof part.text === "string") {
+      text.push(part.text);
+      foundText = true;
+      continue;
+    }
+    if (
+      part.text !== null &&
+      typeof part.text === "object" &&
+      typeof part.text.value === "string"
+    ) {
+      text.push(part.text.value);
+      foundText = true;
+    }
+  }
+
+  if (!foundText) {
+    throw new ProviderResponseError(
+      "provider response did not contain text content",
+    );
+  }
+  return text.join("");
+}
+
+function parseRetryAfter(value, now) {
+  if (value === null) {
+    return undefined;
+  }
+  const seconds = Number(value);
+  if (Number.isFinite(seconds) && seconds >= 0) {
+    return seconds * 1_000;
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp)) {
+    return undefined;
+  }
+  return Math.max(0, timestamp - now());
+}
+
+function requestIdFrom(response) {
+  return (
+    response.headers.get("x-request-id") ??
+    response.headers.get("request-id") ??
+    undefined
+  );
+}
+
+function abortError(provider, attempts) {
+  return new ProviderAbortError("provider request was aborted", {
+    provider,
+    attempts,
+  });
+}
+
+function defaultSleep(delayMs, signal) {
+  if (signal?.aborted) {
+    return Promise.reject(signal.reason);
+  }
+  return new Promise((resolve, reject) => {
+    let onAbort;
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, delayMs);
+    if (signal === undefined) {
+      return;
+    }
+    onAbort = () => {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", onAbort);
+      reject(signal.reason);
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function createAttemptSignal(parentSignal, timeoutMs) {
+  const controller = new AbortController();
+  let timedOut = false;
+
+  const onAbort = () => controller.abort(parentSignal.reason);
+  if (parentSignal !== undefined) {
+    if (parentSignal.aborted) {
+      controller.abort(parentSignal.reason);
+    } else {
+      parentSignal.addEventListener("abort", onAbort, { once: true });
+    }
+  }
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, timeoutMs);
+
+  return {
+    signal: controller.signal,
+    timedOut: () => timedOut,
+    cleanup() {
+      clearTimeout(timer);
+      parentSignal?.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+async function cancelBody(response) {
+  try {
+    await response.body?.cancel();
+  } catch {
+    // The response is already unusable, so cancellation errors are irrelevant.
+  }
+}
+
+async function readBoundedJson(response, maxBytes) {
+  const contentLength = response.headers.get("content-length");
+  if (contentLength !== null) {
+    const declared = Number(contentLength);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      await cancelBody(response);
+      throw new ProviderResponseError("provider response exceeded the size limit");
+    }
+  }
+
+  if (response.body === null || response.body === undefined) {
+    throw new ProviderResponseError("provider response did not contain a body");
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let bytes = 0;
+  let text = "";
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      bytes += value.byteLength;
+      if (bytes > maxBytes) {
+        await reader.cancel();
+        throw new ProviderResponseError(
+          "provider response exceeded the size limit",
+        );
+      }
+      text += decoder.decode(value, { stream: true });
+    }
+    text += decoder.decode();
+  } catch (error) {
+    if (error instanceof ProviderError) {
+      throw error;
+    }
+    throw new ProviderResponseError("provider response could not be read");
+  } finally {
+    reader.releaseLock();
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new ProviderResponseError("provider response was not valid JSON");
+  }
+}
+
+function normalizeGenerationRequest(value) {
+  if (value instanceof GenerationRequest) {
+    return value;
+  }
+  assertRecord(value, "request");
+  return new GenerationRequest(value);
+}
+
+function generationRequestValues(request) {
+  return {
+    model: request.model,
+    messages: request.messages,
+    maxTokens: request.maxTokens,
+    temperature: request.temperature,
+    seed: request.seed,
+    stop: request.stop,
+    extraBody: request.extraBody,
+  };
+}
+
+function canonicalRequestValues(value) {
+  assertRecord(value, "request");
+  const output = { ...value };
+
+  let maxTokens;
+  for (const key of ["maxTokens", "maxOutputTokens", "max_tokens"]) {
+    if (Object.hasOwn(value, key) && value[key] !== undefined) {
+      maxTokens = value[key];
+      break;
+    }
+  }
+  delete output.maxOutputTokens;
+  delete output.max_tokens;
+  if (maxTokens === undefined) {
+    delete output.maxTokens;
+  } else {
+    output.maxTokens = maxTokens;
+  }
+
+  const extraBody = value.extraBody ?? value.extra_body;
+  delete output.extra_body;
+  if (extraBody === undefined || extraBody === null) {
+    delete output.extraBody;
+  } else {
+    output.extraBody = extraBody;
+  }
+  return output;
+}
+
+function mergeRequestValues(defaults, request, model) {
+  const input =
+    request instanceof GenerationRequest
+      ? generationRequestValues(request)
+      : request;
+  const normalizedDefaults = canonicalRequestValues(defaults);
+  const normalizedInput = canonicalRequestValues(input);
+
+  const merged = {
+    ...normalizedDefaults,
+    ...normalizedInput,
+    model,
+    extraBody: {
+      ...(normalizedDefaults.extraBody ?? {}),
+      ...(normalizedInput.extraBody ?? {}),
+    },
+  };
+  return merged;
+}
+
+export class ChatMessage {
+  constructor(roleOrOptions, content) {
+    const options =
+      typeof roleOrOptions === "string"
+        ? { role: roleOrOptions, content }
+        : roleOrOptions;
+    assertRecord(options, "message");
+    assertNonEmptyString(options.role, "message.role");
+    if (!["system", "user", "assistant"].includes(options.role)) {
+      throw new RangeError(
+        "message.role must be system, user, or assistant",
+      );
+    }
+    if (typeof options.content !== "string") {
+      throw new TypeError("message.content must be a string");
+    }
+
+    this.role = options.role;
+    this.content = options.content;
+    Object.freeze(this);
+  }
+}
+
+export class GenerationRequest {
+  constructor(options) {
+    assertRecord(options, "request");
+    assertNonEmptyString(options.model, "request.model");
+
+    let messages = options.messages;
+    if (messages === undefined) {
+      const input = options.input ?? options.prompt;
+      if (typeof input === "string") {
+        messages = [new ChatMessage("user", input)];
+      } else if (Array.isArray(input)) {
+        messages = input;
+      }
+    }
+    if (!Array.isArray(messages) || messages.length === 0) {
+      throw new TypeError("request.messages must be a non-empty array");
+    }
+
+    const normalizedMessages = messages.map((message, index) => {
+      try {
+        return message instanceof ChatMessage
+          ? message
+          : new ChatMessage(message);
+      } catch (error) {
+        throw new TypeError(`request.messages[${index}] is invalid`, {
+          cause: error,
+        });
+      }
+    });
+    if (options.system !== undefined) {
+      if (typeof options.system !== "string") {
+        throw new TypeError("request.system must be a string");
+      }
+      normalizedMessages.unshift(new ChatMessage("system", options.system));
+    }
+
+    let maxTokens;
+    for (const key of ["maxTokens", "maxOutputTokens", "max_tokens"]) {
+      if (Object.hasOwn(options, key) && options[key] !== undefined) {
+        maxTokens = options[key];
+        break;
+      }
+    }
+    if (maxTokens === undefined) {
+      maxTokens = 512;
+    }
+    if (maxTokens !== null) {
+      assertSafeInteger(maxTokens, "request.maxTokens", 1);
+    }
+    if (options.temperature !== undefined) {
+      assertFiniteNumber(options.temperature, "request.temperature", 0);
+      if (options.temperature > 2) {
+        throw new RangeError("request.temperature must be at most 2");
+      }
+    }
+    if (options.seed !== undefined) {
+      assertSafeInteger(options.seed, "request.seed");
+    }
+
+    const stop = options.stop ?? [];
+    if (!Array.isArray(stop)) {
+      throw new TypeError("request.stop must be an array");
+    }
+    const normalizedStop = stop.map((value, index) => {
+      assertNonEmptyString(value, `request.stop[${index}]`);
+      return value;
+    });
+
+    const extraBody = options.extraBody ?? options.extra_body ?? {};
+    assertRecord(extraBody, "request.extraBody");
+    const reserved = Object.keys(extraBody).filter((key) =>
+      RESERVED_REQUEST_FIELDS.has(key)
+    );
+    if (reserved.length > 0) {
+      throw new ProviderConfigurationError(
+        `request.extraBody must not override reserved fields: ${reserved.sort().join(", ")}`,
+      );
+    }
+
+    this.model = options.model;
+    this.messages = Object.freeze(normalizedMessages);
+    this.maxTokens = maxTokens;
+    this.temperature = options.temperature;
+    this.seed = options.seed;
+    this.stop = Object.freeze(normalizedStop);
+    this.extraBody = freezeJson(extraBody, "request.extraBody");
+    Object.freeze(this);
+  }
+}
+
+export class TokenUsage {
+  constructor(options = {}) {
+    assertRecord(options, "usage");
+    this.inputTokens = optionalNonNegativeInteger(
+      options.inputTokens,
+      "usage.inputTokens",
+    );
+    this.outputTokens = optionalNonNegativeInteger(
+      options.outputTokens,
+      "usage.outputTokens",
+    );
+    this.totalTokens = optionalNonNegativeInteger(
+      options.totalTokens,
+      "usage.totalTokens",
+    );
+    this.cachedInputTokens = optionalNonNegativeInteger(
+      options.cachedInputTokens,
+      "usage.cachedInputTokens",
+    );
+    this.reasoningTokens = optionalNonNegativeInteger(
+      options.reasoningTokens,
+      "usage.reasoningTokens",
+    );
+    Object.freeze(this);
+  }
+}
+
+export class GenerationResult {
+  constructor(options) {
+    assertRecord(options, "generation");
+    if (typeof options.text !== "string") {
+      throw new TypeError("generation.text must be a string");
+    }
+    assertNonEmptyString(options.provider, "generation.provider");
+    assertNonEmptyString(options.model, "generation.model");
+    assertOptionalString(options.responseModel, "generation.responseModel");
+    assertOptionalString(options.finishReason, "generation.finishReason");
+    assertOptionalString(options.responseId, "generation.responseId");
+    assertOptionalString(options.requestId, "generation.requestId");
+    assertFiniteNumber(options.latencySeconds, "generation.latencySeconds", 0);
+    assertSafeInteger(options.attempts, "generation.attempts", 1);
+
+    this.text = options.text;
+    this.provider = options.provider;
+    this.model = options.model;
+    this.responseModel = options.responseModel;
+    this.finishReason = options.finishReason;
+    this.usage =
+      options.usage instanceof TokenUsage
+        ? options.usage
+        : new TokenUsage(options.usage);
+    this.latencySeconds = options.latencySeconds;
+    this.attempts = options.attempts;
+    this.responseId = options.responseId;
+    this.requestId = options.requestId;
+    this.metadata = freezeJson(options.metadata ?? {}, "generation.metadata");
+    Object.freeze(this);
+  }
+}
+
+export class ModelInfo {
+  constructor(options) {
+    assertRecord(options, "model");
+    assertNonEmptyString(options.id, "model.id");
+    assertNonEmptyString(options.provider, "model.provider");
+    assertOptionalString(options.displayName, "model.displayName");
+
+    this.id = options.id;
+    this.provider = options.provider;
+    this.displayName = options.displayName;
+    this.metadata = freezeJson(options.metadata ?? {}, "model.metadata");
+    Object.freeze(this);
+  }
+}
+
+export class RequestPolicy {
+  constructor(options = {}) {
+    assertRecord(options, "requestPolicy");
+
+    const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const retryBaseMs = options.retryBaseMs ?? DEFAULT_RETRY_BASE_MS;
+    const retryMaxMs = options.retryMaxMs ?? DEFAULT_RETRY_MAX_MS;
+    const maxResponseBytes =
+      options.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES;
+    const retryStatuses = options.retryStatuses ?? DEFAULT_RETRY_STATUSES;
+
+    assertSafeInteger(timeoutMs, "requestPolicy.timeoutMs", 1);
+    assertSafeInteger(maxRetries, "requestPolicy.maxRetries", 0);
+    if (maxRetries > 9) {
+      throw new RangeError("requestPolicy.maxRetries must be at most 9");
+    }
+    assertSafeInteger(retryBaseMs, "requestPolicy.retryBaseMs", 0);
+    assertSafeInteger(retryMaxMs, "requestPolicy.retryMaxMs", retryBaseMs);
+    assertSafeInteger(
+      maxResponseBytes,
+      "requestPolicy.maxResponseBytes",
+      1,
+    );
+    if (!Array.isArray(retryStatuses)) {
+      throw new TypeError("requestPolicy.retryStatuses must be an array");
+    }
+    const normalizedStatuses = retryStatuses.map((status, index) => {
+      assertSafeInteger(status, `requestPolicy.retryStatuses[${index}]`, 100);
+      if (status > 599) {
+        throw new RangeError(
+          `requestPolicy.retryStatuses[${index}] must be at most 599`,
+        );
+      }
+      return status;
+    });
+
+    this.timeoutMs = timeoutMs;
+    this.maxRetries = maxRetries;
+    this.retryBaseMs = retryBaseMs;
+    this.retryMaxMs = retryMaxMs;
+    this.maxResponseBytes = maxResponseBytes;
+    this.retryStatuses = Object.freeze(Array.from(new Set(normalizedStatuses)));
+    Object.freeze(this);
+  }
+}
+
+export class ProviderError extends Error {
+  constructor(
+    message,
+    {
+      code = "provider_error",
+      provider,
+      status,
+      retryable = false,
+      requestId,
+      attempts = 0,
+    } = {},
+  ) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.provider = provider;
+    this.status = status;
+    this.retryable = retryable;
+    this.requestId = requestId;
+    this.attempts = attempts;
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      provider: this.provider,
+      status: this.status,
+      retryable: this.retryable,
+      requestId: this.requestId,
+      attempts: this.attempts,
+    };
+  }
+}
+
+export class ProviderConfigurationError extends ProviderError {
+  constructor(message, details = {}) {
+    super(message, { ...details, code: "configuration_error" });
+  }
+}
+
+export class ProviderRequestError extends ProviderError {
+  constructor(message, details = {}) {
+    super(message, { ...details, code: "request_error" });
+  }
+}
+
+export class ProviderResponseError extends ProviderError {
+  constructor(message, details = {}) {
+    super(message, { ...details, code: "response_error" });
+  }
+}
+
+export class ProviderTimeoutError extends ProviderError {
+  constructor(message, details = {}) {
+    super(message, {
+      ...details,
+      code: "timeout",
+      retryable: details.retryable ?? true,
+    });
+  }
+}
+
+export class ProviderAbortError extends ProviderError {
+  constructor(message, details = {}) {
+    super(message, {
+      ...details,
+      code: "aborted",
+      retryable: false,
+    });
+  }
+}
+
+export class OpenAICompatibleProvider {
+  #baseURL;
+  #apiKey;
+  #fetch;
+  #headers;
+  #policy;
+  #sleep;
+  #random;
+  #now;
+  #maxTokensField;
+
+  constructor(options) {
+    assertRecord(options, "provider");
+    const id = options.id ?? "generic";
+    assertNonEmptyString(id, "provider.id");
+
+    const fetchImplementation =
+      options.fetch ??
+      (typeof globalThis.fetch === "function"
+        ? globalThis.fetch.bind(globalThis)
+        : undefined);
+    if (typeof fetchImplementation !== "function") {
+      throw new ProviderConfigurationError(
+        "a Fetch API implementation is required",
+        { provider: id },
+      );
+    }
+    if (options.apiKey !== undefined && options.apiKey !== null) {
+      assertNonEmptyString(options.apiKey, "provider.apiKey");
+      if (/[\r\n]/u.test(options.apiKey)) {
+        throw new ProviderConfigurationError(
+          "provider.apiKey must not contain line breaks",
+          { provider: id },
+        );
+      }
+    }
+    if (options.sleep !== undefined && typeof options.sleep !== "function") {
+      throw new TypeError("provider.sleep must be a function");
+    }
+    if (options.random !== undefined && typeof options.random !== "function") {
+      throw new TypeError("provider.random must be a function");
+    }
+    if (options.now !== undefined && typeof options.now !== "function") {
+      throw new TypeError("provider.now must be a function");
+    }
+    const maxTokensField = options.maxTokensField ?? "max_tokens";
+    if (
+      maxTokensField !== "max_tokens" &&
+      maxTokensField !== "max_completion_tokens"
+    ) {
+      throw new ProviderConfigurationError(
+        "provider.maxTokensField must be max_tokens or max_completion_tokens",
+        { provider: id },
+      );
+    }
+
+    this.id = id;
+    this.kind = "openai-compatible";
+    this.#baseURL = normalizeBaseURL(options.baseURL);
+    this.#apiKey = options.apiKey ?? undefined;
+    this.#fetch = fetchImplementation;
+    this.#headers = normalizeHeaders(
+      options.headers ?? options.defaultHeaders ?? {},
+    );
+    this.#policy =
+      options.requestPolicy instanceof RequestPolicy
+        ? options.requestPolicy
+        : new RequestPolicy(options.requestPolicy);
+    this.#sleep = options.sleep ?? defaultSleep;
+    this.#random = options.random ?? Math.random;
+    this.#now = options.now ?? Date.now;
+    this.#maxTokensField = maxTokensField;
+    Object.freeze(this);
+  }
+
+  get requestPolicy() {
+    return this.#policy;
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      kind: this.kind,
+    };
+  }
+
+  async listModels(options = {}) {
+    assertRecord(options, "options");
+    const { payload } = await this.#request("models", {
+      method: "GET",
+      signal: options.signal,
+      policy: options.requestPolicy,
+    });
+
+    if (!Array.isArray(payload?.data)) {
+      throw new ProviderResponseError(
+        "provider model response did not contain a data array",
+        { provider: this.id },
+      );
+    }
+
+    const models = payload.data.map((value, index) => {
+      if (value === null || typeof value !== "object") {
+        throw new ProviderResponseError(
+          `provider model entry ${index} was invalid`,
+          { provider: this.id },
+        );
+      }
+      try {
+        const metadata = {};
+        if (typeof value.owned_by === "string") {
+          metadata.ownedBy = value.owned_by;
+        }
+        if (Number.isSafeInteger(value.created) && value.created >= 0) {
+          metadata.created = value.created;
+        }
+        if (
+          Number.isSafeInteger(value.context_length) &&
+          value.context_length >= 0
+        ) {
+          metadata.contextLength = value.context_length;
+        }
+        return new ModelInfo({
+          id: value.id,
+          provider: this.id,
+          displayName:
+            typeof value.name === "string" && value.name.trim().length > 0
+              ? value.name
+              : undefined,
+          metadata,
+        });
+      } catch {
+        throw new ProviderResponseError(
+          `provider model entry ${index} was invalid`,
+          { provider: this.id },
+        );
+      }
+    });
+
+    models.sort((left, right) => compareCodePoints(left.id, right.id));
+    return Object.freeze(models);
+  }
+
+  async generate(requestValue, options = {}) {
+    assertRecord(options, "options");
+    const request = normalizeGenerationRequest(requestValue);
+    const body = {
+      ...request.extraBody,
+      model: request.model,
+      messages: request.messages.map(({ role, content }) => ({ role, content })),
+      stream: false,
+    };
+    if (request.maxTokens !== null) {
+      body[this.#maxTokensField] = request.maxTokens;
+    }
+    if (request.temperature !== undefined) {
+      body.temperature = request.temperature;
+    }
+    if (request.seed !== undefined) {
+      body.seed = request.seed;
+    }
+    if (request.stop.length > 0) {
+      body.stop = request.stop;
+    }
+
+    const startedAt = this.#now();
+    const { payload, attempts, requestId } = await this.#request(
+      "chat/completions",
+      {
+        method: "POST",
+        body,
+        signal: options.signal,
+        policy: options.requestPolicy,
+      },
+    );
+    const latencySeconds = Math.max(0, (this.#now() - startedAt) / 1_000);
+
+    if (!Array.isArray(payload?.choices) || payload.choices.length === 0) {
+      throw new ProviderResponseError(
+        "provider response did not contain a choice",
+        { provider: this.id, requestId, attempts },
+      );
+    }
+    const choice = payload.choices[0];
+    if (choice === null || typeof choice !== "object") {
+      throw new ProviderResponseError(
+        "provider response choice was invalid",
+        { provider: this.id, requestId, attempts },
+      );
+    }
+    const content = choice.message?.content ?? choice.text;
+    let text;
+    try {
+      text = extractTextContent(content);
+    } catch (error) {
+      if (error instanceof ProviderError) {
+        error.provider = this.id;
+        error.requestId = requestId;
+        error.attempts = attempts;
+      }
+      throw error;
+    }
+
+    const metadata = {};
+    if (typeof payload.system_fingerprint === "string") {
+      metadata.systemFingerprint = payload.system_fingerprint;
+    }
+    if (typeof payload.service_tier === "string") {
+      metadata.serviceTier = payload.service_tier;
+    }
+
+    return new GenerationResult({
+      text,
+      provider: this.id,
+      model: request.model,
+      responseModel:
+        typeof payload.model === "string" ? payload.model : undefined,
+      finishReason:
+        typeof choice.finish_reason === "string"
+          ? choice.finish_reason
+          : undefined,
+      usage: normalizeUsage(payload.usage),
+      latencySeconds,
+      attempts,
+      responseId: typeof payload.id === "string" ? payload.id : undefined,
+      requestId,
+      metadata,
+    });
+  }
+
+  async #request(path, { method, body, signal, policy }) {
+    if (signal !== undefined && !(signal instanceof AbortSignal)) {
+      throw new TypeError("options.signal must be an AbortSignal");
+    }
+    const requestPolicy =
+      policy === undefined
+        ? this.#policy
+        : policy instanceof RequestPolicy
+          ? policy
+          : new RequestPolicy({
+              ...this.#policy,
+              ...policy,
+            });
+
+    if (signal?.aborted) {
+      throw abortError(this.id, 0);
+    }
+
+    const url = `${this.#baseURL}/${path}`;
+    const headers = {
+      accept: "application/json",
+      ...this.#headers,
+    };
+    if (body !== undefined) {
+      headers["content-type"] = "application/json";
+    }
+    if (this.#apiKey !== undefined) {
+      headers.authorization = `Bearer ${this.#apiKey}`;
+    }
+    const serializedBody = body === undefined ? undefined : JSON.stringify(body);
+    const maximumAttempts = requestPolicy.maxRetries + 1;
+
+    for (let attempts = 1; attempts <= maximumAttempts; attempts += 1) {
+      if (signal?.aborted) {
+        throw abortError(this.id, attempts - 1);
+      }
+
+      const attemptSignal = createAttemptSignal(
+        signal,
+        requestPolicy.timeoutMs,
+      );
+      let failure;
+      let retryAfterMs;
+
+      try {
+        const response = await this.#fetch(url, {
+          method,
+          headers,
+          body: serializedBody,
+          signal: attemptSignal.signal,
+          redirect: "error",
+        });
+        const requestId = requestIdFrom(response);
+
+        if (!response.ok) {
+          retryAfterMs = parseRetryAfter(
+            response.headers.get("retry-after"),
+            this.#now,
+          );
+          await cancelBody(response);
+          failure = new ProviderRequestError(
+            `provider request failed with HTTP ${response.status}`,
+            {
+              provider: this.id,
+              status: response.status,
+              retryable: requestPolicy.retryStatuses.includes(response.status),
+              requestId,
+              attempts,
+            },
+          );
+        } else {
+          try {
+            const payload = await readBoundedJson(
+              response,
+              requestPolicy.maxResponseBytes,
+            );
+            return { payload, attempts, requestId };
+          } catch (error) {
+            if (signal?.aborted) {
+              failure = abortError(this.id, attempts);
+            } else if (attemptSignal.timedOut()) {
+              failure = new ProviderTimeoutError(
+                "provider request timed out",
+                { provider: this.id, attempts },
+              );
+            } else if (error instanceof ProviderError) {
+              error.provider = this.id;
+              error.requestId = requestId;
+              error.attempts = attempts;
+              failure = error;
+            } else {
+              failure = new ProviderResponseError(
+                "provider response could not be processed",
+                { provider: this.id, requestId, attempts },
+              );
+            }
+          }
+        }
+      } catch {
+        if (signal?.aborted) {
+          failure = abortError(this.id, attempts);
+        } else if (attemptSignal.timedOut()) {
+          failure = new ProviderTimeoutError("provider request timed out", {
+            provider: this.id,
+            attempts,
+          });
+        } else {
+          failure = new ProviderRequestError("provider request failed", {
+            provider: this.id,
+            retryable: true,
+            attempts,
+          });
+        }
+      } finally {
+        attemptSignal.cleanup();
+      }
+
+      if (signal?.aborted) {
+        throw abortError(this.id, attempts);
+      }
+      if (!failure.retryable || attempts >= maximumAttempts) {
+        throw failure;
+      }
+
+      const randomValue = Number(this.#random());
+      const boundedRandom = Number.isFinite(randomValue)
+        ? Math.min(1, Math.max(0, randomValue))
+        : 0;
+      const exponential = Math.min(
+        requestPolicy.retryMaxMs,
+        requestPolicy.retryBaseMs * 2 ** (attempts - 1),
+      );
+      const delayMs = Math.min(
+        requestPolicy.retryMaxMs,
+        Math.max(exponential * boundedRandom, retryAfterMs ?? 0),
+      );
+      try {
+        await this.#sleep(delayMs, signal);
+      } catch {
+        throw abortError(this.id, attempts);
+      }
+    }
+
+    throw new ProviderRequestError("provider request failed", {
+      provider: this.id,
+    });
+  }
+}
+
+export class ModelTarget {
+  constructor(options) {
+    assertRecord(options, "target");
+    assertNonEmptyString(options.name, "target.name");
+    assertNonEmptyString(options.model, "target.model");
+    if (
+      options.provider === null ||
+      typeof options.provider !== "object" ||
+      typeof options.provider.generate !== "function"
+    ) {
+      throw new TypeError("target.provider must implement generate()");
+    }
+    const providerLabel = options.provider.id ?? options.provider.name;
+    assertNonEmptyString(providerLabel, "target.provider label");
+    const requestOverrides = options.requestOverrides ?? {};
+    assertRecord(requestOverrides, "target.requestOverrides");
+    const unsupportedOverrides = Object.keys(requestOverrides).filter(
+      (key) => !TARGET_REQUEST_OVERRIDE_FIELDS.has(key),
+    );
+    if (unsupportedOverrides.length > 0) {
+      throw new ProviderConfigurationError(
+        `target.requestOverrides contains unsupported fields: ${unsupportedOverrides.sort().join(", ")}`,
+      );
+    }
+    const normalizedOverrides = canonicalRequestValues(requestOverrides);
+    new GenerationRequest({
+      model: options.model,
+      input: "",
+      ...normalizedOverrides,
+    });
+
+    this.name = options.name;
+    this.provider = options.provider;
+    this.providerName = providerLabel;
+    this.model = options.model;
+    this.requestOverrides = freezeJson(
+      normalizedOverrides,
+      "target.requestOverrides",
+    );
+    Object.freeze(this);
+  }
+
+  async generate(request, options = {}) {
+    const merged = mergeRequestValues(
+      this.requestOverrides,
+      request,
+      this.model,
+    );
+    return this.provider.generate(merged, options);
+  }
+
+  toJSON() {
+    const maxTokens = Object.hasOwn(this.requestOverrides, "maxTokens")
+      ? this.requestOverrides.maxTokens
+      : 512;
+    return {
+      name: this.name,
+      provider: this.providerName,
+      model: this.model,
+      parameters: {
+        max_tokens: maxTokens,
+        temperature: this.requestOverrides.temperature ?? null,
+        seed: this.requestOverrides.seed ?? null,
+        stop: Array.isArray(this.requestOverrides.stop)
+          ? [...this.requestOverrides.stop]
+          : [],
+      },
+    };
+  }
+}
+
+export function createProvider(name, options = {}) {
+  assertNonEmptyString(name, "name");
+  assertRecord(options, "options");
+
+  const normalized = name.toLowerCase().replace(/[\s_.-]+/gu, "");
+  if (normalized === "generic" || normalized === "custom") {
+    if (options.baseURL === undefined) {
+      throw new ProviderConfigurationError(
+        "custom provider requires baseURL",
+        { provider: options.id ?? "custom" },
+      );
+    }
+    return new OpenAICompatibleProvider({
+      ...options,
+      id: options.id ?? "custom",
+    });
+  }
+
+  const presetName =
+    normalized === "llamacpp"
+      ? "llamacpp"
+      : normalized === "lmstudio"
+        ? "lmstudio"
+        : normalized;
+  const preset = PROVIDER_PRESETS[presetName];
+  if (preset === undefined) {
+    throw new ProviderConfigurationError(`unknown provider preset: ${name}`);
+  }
+  if (
+    preset.requiresAPIKey &&
+    (options.apiKey === undefined || options.apiKey === null)
+  ) {
+    throw new ProviderConfigurationError(
+      `${preset.id} requires an API key`,
+      { provider: preset.id },
+    );
+  }
+
+  return new OpenAICompatibleProvider({
+    ...options,
+    id: options.id ?? preset.id,
+    baseURL: options.baseURL ?? preset.baseURL,
+    maxTokensField: options.maxTokensField ?? preset.maxTokensField,
+  });
+}