@acentric/llm 0.0.0-stage → 0.1.0

package/src/client/anthropic/request.ts

@@ -0,0 +1,272 @@
+// The body of an Anthropic create-message request. Each of the request's
+// messages becomes one Anthropic message. As for the Responses format, every
+// shape is checked as it is written.
+
+import type { Json, JsonObject } from '@acentric/types';
+
+import { isArray, isObject } from '../../json.js';
+import { findModel } from '../../models.js';
+import type { LlmRequest } from '../../request.js';
+import { invalidRequest, ownFields, plainText, show } from '../util.js';
+
+const PROVIDER = 'anthropic';
+const LABEL = 'Anthropic';
+
+/** Request fields the request itself sets. */
+const OWNED_OPTIONS = ['model', 'messages', 'system'];
+
+/** The output limit for a model the catalog does not know: the Claude 5 maximum. */
+const DEFAULT_MAX_TOKENS = 128_000;
+
+export type AnthropicRequest = {
+  readonly body: JsonObject;
+  /** Beta names, for the `anthropic-beta` header. */
+  readonly betas: readonly string[];
+};
+
+export function buildRequest(request: LlmRequest<'anthropic'>): AnthropicRequest {
+  const options = ownFields(PROVIDER, request.options, OWNED_OPTIONS, 'request', 'options');
+  if (options['stream'] === true) {
+    throw invalidRequest(
+      PROVIDER,
+      'streaming is not supported: a call returns one finished response',
+    );
+  }
+  const { tools: nativeTools, betas, ...rest } = options;
+  if (nativeTools !== undefined && !isArray(nativeTools)) {
+    throw invalidRequest(PROVIDER, 'options.tools must be an array of native tool definitions');
+  }
+  const messages: Json = request.messages;
+  if (!isArray(messages)) throw invalidRequest(PROVIDER, 'messages must be an array');
+  const tools = [
+    ...(request.tools ?? []).map((tool, index) => buildTool(tool, `tools[${index}]`)),
+    ...(nativeTools ?? []),
+  ];
+  const system = buildSystem(request.instructions);
+  const maxTokens =
+    rest['max_tokens'] ?? findModel(PROVIDER, request.model)?.maxOutputTokens ?? DEFAULT_MAX_TOKENS;
+  return {
+    body: {
+      ...rest,
+      model: request.model,
+      max_tokens: maxTokens,
+      ...(system === undefined ? {} : { system }),
+      messages: messages.flatMap((message, index) =>
+        buildMessage(message, `messages[${index}]`, request.model),
+      ),
+      ...(tools.length > 0 ? { tools } : {}),
+    },
+    betas: readBetas(betas),
+  };
+}
+
+function readBetas(value: Json | undefined): string[] {
+  if (value === undefined) return [];
+  if (isArray(value)) {
+    const names = value.filter(
+      (name): name is string => typeof name === 'string' && /^[\w.-]+$/.test(name),
+    );
+    if (names.length === value.length) return names;
+  }
+  throw invalidRequest(
+    PROVIDER,
+    'options.betas must be an array of beta names, such as "compact-2026-01-12"',
+  );
+}
+
+/** A string stays a string; text parts become blocks, which may carry `cache_control`. */
+function buildSystem(value: Json | undefined): Json | undefined {
+  if (value === undefined || typeof value === 'string') return value;
+  if (!isArray(value))
+    throw invalidRequest(PROVIDER, 'instructions must be a string or text parts');
+  return value.map((part, index) => textBlock(part, `instructions[${index}]`));
+}
+
+function buildMessage(message: Json, where: string, model: string): JsonObject[] {
+  if (!isObject(message)) throw invalidRequest(PROVIDER, `${where} must be a message`);
+  switch (message['role']) {
+    case 'user':
+      return [{ role: 'user', content: buildParts(message['content'], where) }];
+    case 'system': {
+      const content = message['content'];
+      if (!isArray(content))
+        throw invalidRequest(PROVIDER, `${where}.content must be an array of text parts`);
+      return [
+        {
+          role: 'system',
+          content: content.map((part, index) => textBlock(part, `${where}.content[${index}]`)),
+        },
+      ];
+    }
+    case 'assistant': {
+      if (message['provider'] !== PROVIDER) {
+        throw invalidRequest(
+          PROVIDER,
+          `${where} is from ${show(message['provider'])}: convert it before sending it to ${LABEL}`,
+        );
+      }
+      const content = blocks(message['content'], where);
+      if (message['model'] === model) return [{ role: 'assistant', content }];
+      // Another model's thinking is bound to it: some models read it, others
+      // ignore it without a word. Its other blocks are sent as written.
+      const kept = content.filter(
+        (block) => block['type'] !== 'thinking' && block['type'] !== 'redacted_thinking',
+      );
+      return kept.length > 0 ? [{ role: 'assistant', content: kept }] : [];
+    }
+    case 'native':
+      if (message['provider'] !== PROVIDER) {
+        throw invalidRequest(
+          PROVIDER,
+          `${where} holds ${show(message['provider'])} items, which ${LABEL} cannot take`,
+        );
+      }
+      return [{ role: 'user', content: blocks(message['content'], where) }];
+    case 'tool_result':
+      return [{ role: 'user', content: [buildToolResult(message, where)] }];
+    case 'custom':
+      throw invalidRequest(
+        PROVIDER,
+        `${where} is the application's own: leave custom messages out`,
+      );
+    default:
+      throw invalidRequest(PROVIDER, `${where} has an unknown role: ${show(message['role'])}`);
+  }
+}
+
+function blocks(value: Json | undefined, where: string): JsonObject[] {
+  if (!isArray(value))
+    throw invalidRequest(PROVIDER, `${where}.content must be an array of blocks`);
+  return value.map((block, index) => {
+    if (!isObject(block) || typeof block['type'] !== 'string') {
+      throw invalidRequest(PROVIDER, `${where}.content[${index}] must be a block with a type`);
+    }
+    return block;
+  });
+}
+
+function buildToolResult(message: JsonObject, where: string): JsonObject {
+  const callId = message['toolCallId'];
+  if (typeof callId !== 'string' || callId === '') {
+    throw invalidRequest(PROVIDER, `${where}.toolCallId must be a string that is not empty`);
+  }
+  const toolType = message['toolType'] ?? 'function';
+  if (toolType === 'custom')
+    throw invalidRequest(PROVIDER, `${where} answers a custom tool, and ${LABEL} has none`);
+  if (toolType !== 'function')
+    throw invalidRequest(PROVIDER, `${where}.toolType must be function or custom`);
+  const isError = message['isError'];
+  if (isError !== undefined && typeof isError !== 'boolean') {
+    throw invalidRequest(PROVIDER, `${where}.isError must be true or false`);
+  }
+  const owned = ['type', 'tool_use_id', 'content', 'is_error'];
+  return {
+    ...ownFields(PROVIDER, message['providerOptions'], owned, where),
+    type: 'tool_result',
+    tool_use_id: callId,
+    content: plainText(message['content']) ?? buildParts(message['content'], where),
+    ...(isError === undefined ? {} : { is_error: isError }),
+  };
+}
+
+function textBlock(part: Json, at: string): JsonObject {
+  if (!isObject(part) || part['type'] !== 'text' || typeof part['text'] !== 'string') {
+    throw invalidRequest(PROVIDER, `${at} must be a text part`);
+  }
+  return {
+    ...ownFields(PROVIDER, part['providerOptions'], ['type', 'text'], at),
+    type: 'text',
+    text: part['text'],
+  };
+}
+
+function buildParts(value: Json | undefined, where: string): JsonObject[] {
+  if (!isArray(value)) throw invalidRequest(PROVIDER, `${where}.content must be an array of parts`);
+  return value.map((part, index) => buildPart(part, `${where}.content[${index}]`));
+}
+
+function buildPart(part: Json, at: string): JsonObject {
+  if (!isObject(part)) throw invalidRequest(PROVIDER, `${at} must be a content part`);
+  const options = part['providerOptions'];
+  switch (part['type']) {
+    case 'text':
+      return textBlock(part, at);
+    case 'image':
+      return {
+        ...ownFields(PROVIDER, options, ['type', 'source'], at),
+        type: 'image',
+        source: mediaSource(part['source'], at, false),
+      };
+    case 'file': {
+      const filename = part['filename'];
+      if (filename !== undefined && typeof filename !== 'string') {
+        throw invalidRequest(PROVIDER, `${at}.filename must be a string`);
+      }
+      const owned = filename === undefined ? ['type', 'source'] : ['type', 'source', 'title'];
+      return {
+        ...ownFields(PROVIDER, options, owned, at),
+        type: 'document',
+        source: mediaSource(part['source'], at, true),
+        ...(filename === undefined ? {} : { title: filename }),
+      };
+    }
+    default:
+      throw invalidRequest(PROVIDER, `${at} has an unknown type: ${show(part['type'])}`);
+  }
+}
+
+/** A shared source as Anthropic's. A plain text document goes as text, the only way Anthropic takes it. */
+function mediaSource(source: Json | undefined, at: string, document: boolean): JsonObject {
+  if (isObject(source)) {
+    const { type, url, id, data, mediaType } = source;
+    if (type === 'url' && typeof url === 'string') return { type: 'url', url };
+    if (type === 'file_id' && typeof id === 'string') return { type: 'file', file_id: id };
+    if (type === 'base64' && typeof data === 'string' && typeof mediaType === 'string') {
+      if (document && mediaType === 'text/plain') {
+        return { type: 'text', media_type: 'text/plain', data: decodeText(data, at) };
+      }
+      return { type: 'base64', media_type: mediaType, data };
+    }
+  }
+  throw invalidRequest(PROVIDER, `${at}.source must be a url, base64 or file_id source`);
+}
+
+function decodeText(base64: string, at: string): string {
+  try {
+    const bytes = Uint8Array.from(atob(base64), (char) => char.codePointAt(0) ?? 0);
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    throw invalidRequest(PROVIDER, `${at}.source must hold UTF-8 text in base64 for text/plain`);
+  }
+}
+
+function buildTool(tool: Json, where: string): JsonObject {
+  if (
+    !isObject(tool) ||
+    typeof tool['name'] !== 'string' ||
+    typeof tool['description'] !== 'string'
+  ) {
+    throw invalidRequest(PROVIDER, `${where} needs a type, a name and a description`);
+  }
+  const { name, description, parameters, strict } = tool;
+  const at = `tool ${name}`;
+  if (tool['type'] === 'custom') {
+    throw invalidRequest(
+      PROVIDER,
+      `${at} is a custom tool, which ${LABEL} cannot take: use a function tool`,
+    );
+  }
+  if (tool['type'] !== 'function')
+    throw invalidRequest(PROVIDER, `${where} has an unknown type: ${show(tool['type'])}`);
+  const owned = ['type', 'name', 'description', 'input_schema', 'strict'];
+  const fields = ownFields(PROVIDER, tool['providerOptions'], owned, at);
+  if (!isObject(parameters))
+    throw invalidRequest(PROVIDER, `${at}: parameters must be a JSON Schema object`);
+  return {
+    ...fields,
+    name,
+    description,
+    input_schema: parameters,
+    ...(strict === undefined ? {} : { strict }),
+  };
+}

package/src/client/anthropic/response.ts

@@ -0,0 +1,236 @@
+// An Anthropic answer read into an LlmResponse.
+
+import type { JsonObject } from '@acentric/types';
+
+import { estimateCost } from '../../cost.js';
+import { isArray, isObject } from '../../json.js';
+import { findModel } from '../../models.js';
+import type { LlmRequest } from '../../request.js';
+import type { LlmResponse, StopReason } from '../../response.js';
+import type { Usage, UsageCost } from '../../usage.js';
+import type { JsonAnswer } from '../http.js';
+import { invalidResponse, omit, tokens } from '../util.js';
+
+const PROVIDER = 'anthropic';
+
+/** Response fields the response already holds elsewhere. */
+const ENVELOPE_FIELDS = ['id', 'type', 'role', 'content', 'model', 'stop_reason', 'usage'];
+
+/** Usage fields mapped to `Usage`; the rest of `usage` stays in `native`. */
+const USAGE_FIELDS = [
+  'input_tokens',
+  'output_tokens',
+  'cache_creation_input_tokens',
+  'cache_read_input_tokens',
+  'output_tokens_details',
+];
+
+const STOP_REASONS: { readonly [reason: string]: StopReason } = {
+  end_turn: 'stop',
+  stop_sequence: 'stop',
+  max_tokens: 'length',
+  model_context_window_exceeded: 'length',
+  tool_use: 'tool_use',
+  pause_turn: 'pause_turn',
+  // Compaction paused after summarizing; sending the message back goes on.
+  compaction: 'pause_turn',
+  refusal: 'refusal',
+};
+
+/** The only categories in which a refusal before any output is billed. */
+const BILLED_REFUSALS: ReadonlySet<string> = new Set([
+  'bio',
+  'frontier_llm',
+  'reasoning_extraction',
+]);
+
+export function parseResponse(
+  request: LlmRequest<'anthropic'>,
+  answer: JsonAnswer,
+): LlmResponse<'anthropic'> {
+  const body = answer.body;
+  if (!isObject(body) || body['type'] !== 'message' || !isArray(body['content'])) {
+    throw invalidResponse(PROVIDER, 'Anthropic did not answer with a message', body);
+  }
+  const content = body['content'];
+  const id = typeof body['id'] === 'string' && body['id'] !== '' ? body['id'] : undefined;
+  const stop = typeof body['stop_reason'] === 'string' ? body['stop_reason'] : undefined;
+  const stopReason = (stop === undefined ? undefined : STOP_REASONS[stop]) ?? 'stop';
+  const served = typeof body['model'] === 'string' ? body['model'] : request.model;
+  const rawUsage = isObject(body['usage']) ? body['usage'] : undefined;
+  const usage = rawUsage === undefined ? undefined : readUsage(rawUsage);
+  const cost =
+    rawUsage === undefined || freeRefusal(body) ? undefined : estimate(rawUsage, served, request);
+
+  // How cache writes split by time to live says nothing when nothing was written.
+  const extras =
+    rawUsage === undefined
+      ? undefined
+      : omit(
+          rawUsage,
+          usage?.cacheWrite === 0 ? [...USAGE_FIELDS, 'cache_creation'] : USAGE_FIELDS,
+        );
+  const native = {
+    ...omit(body, ENVELOPE_FIELDS),
+    ...(extras === undefined || Object.keys(extras).length === 0 ? {} : { usage: extras }),
+  };
+  const response = {
+    ...(id === undefined ? {} : { id }),
+    provider: PROVIDER,
+    model: request.model,
+    ...(served === request.model ? {} : { responseModel: served }),
+    message: {
+      role: 'assistant',
+      provider: PROVIDER,
+      api: 'anthropic-messages',
+      model: request.model,
+      ...(id === undefined ? {} : { id }),
+      timestamp: answer.timestamp,
+      content,
+    },
+    stopReason,
+    ...(stop === undefined || stop === stopReason ? {} : { providerStopReason: stop }),
+    ...(usage === undefined ? {} : { usage: cost === undefined ? usage : { ...usage, cost } }),
+    native,
+    durationMs: answer.durationMs,
+    timestamp: answer.timestamp,
+  };
+  // The content is Anthropic's own blocks, which the format's types describe.
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return response as unknown as LlmResponse<'anthropic'>;
+}
+
+/**
+ * Usage as the format reports it: `input_tokens` is only the uncached part.
+ * Where a request sampled more than once (compaction, a fallback model), the
+ * iterations hold the whole bill and the top-level counts leave some out.
+ */
+export function readUsage(raw: JsonObject): Usage {
+  const iterations = samplings(raw);
+  const counted = iterations === undefined ? counts(raw) : sum(iterations.map((one) => one.usage));
+  const details = isObject(raw['output_tokens_details']) ? raw['output_tokens_details'] : {};
+  const reasoning = tokens(details['thinking_tokens']);
+  return { ...counted, ...(reasoning === undefined ? {} : { reasoning }) };
+}
+
+/** One sampling's tokens. */
+function counts(raw: JsonObject): Usage {
+  const input = tokens(raw['input_tokens']);
+  const output = tokens(raw['output_tokens']);
+  // Anthropic leaves the cache counts out when nothing was cached.
+  const read = raw['cache_read_input_tokens'];
+  const written = raw['cache_creation_input_tokens'];
+  const cacheRead = read === undefined || read === null ? 0 : tokens(read);
+  const cacheWrite = written === undefined || written === null ? 0 : tokens(written);
+  const totalInput =
+    input === undefined || cacheRead === undefined || cacheWrite === undefined
+      ? undefined
+      : input + cacheRead + cacheWrite;
+  return {
+    ...(totalInput === undefined ? {} : { totalInput }),
+    ...(input === undefined ? {} : { input }),
+    ...(output === undefined ? {} : { output }),
+    ...(cacheRead === undefined ? {} : { cacheRead }),
+    ...(cacheWrite === undefined ? {} : { cacheWrite }),
+  };
+}
+
+type Sampling = {
+  readonly model: string | undefined;
+  readonly usage: Usage;
+  /** Undefined when cache writes are not split by time to live. */
+  readonly cacheWrite1h: number | undefined;
+};
+
+function samplings(raw: JsonObject): Sampling[] | undefined {
+  const iterations = raw['iterations'];
+  if (!isArray(iterations) || iterations.length === 0) return undefined;
+  return iterations.filter(isObject).map((iteration) => {
+    const model = iteration['model'];
+    return {
+      model: typeof model === 'string' ? model : undefined,
+      usage: counts(iteration),
+      cacheWrite1h: hourWrites(iteration),
+    };
+  });
+}
+
+function hourWrites(raw: JsonObject): number | undefined {
+  if (!raw['cache_creation_input_tokens']) return 0;
+  const split = raw['cache_creation'];
+  return isObject(split) ? tokens(split['ephemeral_1h_input_tokens'] ?? 0) : undefined;
+}
+
+function sum(usages: readonly Usage[]): Usage {
+  const keys = ['totalInput', 'input', 'output', 'cacheRead', 'cacheWrite'] as const;
+  const total: { [key: string]: number } = {};
+  for (const key of keys) {
+    if (usages.every((usage) => usage[key] !== undefined)) {
+      total[key] = usages.reduce((all, usage) => all + (usage[key] ?? 0), 0);
+    }
+  }
+  return total;
+}
+
+/**
+ * The cost at standard prices, each sampling at its own model's prices and
+ * long-context tier, times the multiplier for where and how it ran. Undefined
+ * when any part cannot be priced.
+ */
+function estimate(
+  raw: JsonObject,
+  served: string,
+  request: LlmRequest<'anthropic'>,
+): UsageCost | undefined {
+  const multiplier = priceMultiplier(raw, request);
+  if (multiplier === undefined) return undefined;
+  const each = samplings(raw) ?? [
+    { model: served, usage: counts(raw), cacheWrite1h: hourWrites(raw) },
+  ];
+  const costs: UsageCost[] = [];
+  for (const { model, usage, cacheWrite1h } of each) {
+    if (cacheWrite1h === undefined) return undefined;
+    const pricing = findModel(PROVIDER, model ?? served)?.pricing;
+    const cost = estimateCost(usage, pricing, { multiplier, cacheWrite1h });
+    if (cost === undefined) return undefined;
+    costs.push(cost);
+  }
+  const [first] = costs;
+  if (costs.length === 1 && first !== undefined) return first;
+  const parts = ['input', 'output', 'cacheRead', 'cacheWrite', 'total'] as const;
+  const total: { [key: string]: number } = {};
+  for (const cost of costs) {
+    for (const part of parts) {
+      const value = cost[part];
+      if (value !== undefined) total[part] = (total[part] ?? 0) + value;
+    }
+  }
+  return { source: 'estimated', total: 0, ...total };
+}
+
+/**
+ * Standard prices hold unless the response says otherwise: inference kept in
+ * the US costs 1.1 times as much, fast mode twice, a batch half. Priority Tier
+ * has no published price.
+ */
+function priceMultiplier(raw: JsonObject, request: LlmRequest<'anthropic'>): number | undefined {
+  let multiplier = 1;
+  const tier = raw['service_tier'];
+  if (tier === 'batch') multiplier *= 0.5;
+  else if (tier !== undefined && tier !== null && tier !== 'standard') return undefined;
+  if (raw['inference_geo'] === 'us') multiplier *= 1.1;
+  const speed = raw['speed'];
+  if (speed === 'fast') multiplier *= 2;
+  else if ((speed === undefined || speed === null) && request.options?.speed === 'fast')
+    return undefined;
+  return multiplier;
+}
+
+/** A refusal before any output, in a category Anthropic does not bill. */
+function freeRefusal(body: JsonObject): boolean {
+  const content = body['content'];
+  if (body['stop_reason'] !== 'refusal' || !isArray(content) || content.length > 0) return false;
+  const details = body['stop_details'];
+  const category = isObject(details) ? details['category'] : undefined;
+  return typeof category !== 'string' || !BILLED_REFUSALS.has(category);
+}

package/src/client/direct.ts

@@ -0,0 +1,157 @@
+// One call straight to a provider, with credentials in hand. What the client
+// does when it has a provider's key, and what a gateway runs for each request.
+
+import type { Json } from '@acentric/types';
+
+import { LlmError } from '../failure.js';
+import { isObject } from '../json.js';
+import type { Credentials, Provider } from '../providers.js';
+import type { LlmRequest } from '../request.js';
+import type { LlmResponse } from '../response.js';
+import { httpFailure as anthropicFailure } from './anthropic/errors.js';
+import { buildRequest as anthropicRequest } from './anthropic/request.js';
+import { parseResponse as anthropicResponse } from './anthropic/response.js';
+import { postJson, withRequestId } from './http.js';
+import type { JsonAnswer } from './http.js';
+import { httpFailure as responsesFailure } from './responses/errors.js';
+import type { ResponsesProfile, ResponsesProvider } from './responses/profile.js';
+import { fireworksProfile, openAiProfile } from './responses/providers.js';
+import { buildRequest as responsesRequest } from './responses/request.js';
+import { parseResponse as responsesResponse } from './responses/response.js';
+import { invalidRequest } from './util.js';
+
+/** The only Anthropic Messages API version. */
+const ANTHROPIC_VERSION = '2023-06-01';
+
+export type CallOptions = {
+  /** Stops the call; it then fails with `cancelled`. */
+  readonly signal?: AbortSignal;
+  /** A fetch to use instead of the global one, such as in tests. */
+  readonly fetch?: typeof fetch;
+};
+
+/** One completion from the request's provider. Never retried. */
+export async function callProvider<P extends Provider>(
+  request: LlmRequest<P>,
+  credentials: Credentials<P>,
+  options: CallOptions = {},
+): Promise<LlmResponse<P>> {
+  // Each branch narrows the request to its provider; the result is that provider's.
+  const any: LlmRequest = request;
+  const name: string = request.provider;
+  switch (any.provider) {
+    case 'anthropic':
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      return (await callAnthropic(
+        any,
+        readCredentials('anthropic', credentials),
+        options,
+      )) as LlmResponse<P>;
+    case 'openai':
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      return (await callResponses(
+        any,
+        readCredentials('openai', credentials),
+        openAiProfile,
+        options,
+      )) as LlmResponse<P>;
+    case 'fireworks':
+      // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+      return (await callResponses(
+        any,
+        readCredentials('fireworks', credentials),
+        fireworksProfile,
+        options,
+      )) as LlmResponse<P>;
+    default:
+      throw invalidRequest(undefined, `there is no provider ${name}`);
+  }
+}
+
+async function callAnthropic(
+  request: LlmRequest<'anthropic'>,
+  credentials: Credentials<'anthropic'>,
+  options: CallOptions,
+): Promise<LlmResponse<'anthropic'>> {
+  const { body, betas } = anthropicRequest(request);
+  const answer = await postJson({
+    provider: 'anthropic',
+    label: 'Anthropic',
+    url: 'https://api.anthropic.com/v1/messages',
+    headers: {
+      'x-api-key': credentials.apiKey,
+      ...(credentials.workspaceId === undefined
+        ? {}
+        : { 'anthropic-workspace-id': credentials.workspaceId }),
+      'anthropic-version': ANTHROPIC_VERSION,
+      ...(betas.length > 0 ? { 'anthropic-beta': betas.join(',') } : {}),
+    },
+    body,
+    ...common(request, options),
+    failed: anthropicFailure,
+  });
+  return read(answer, () => anthropicResponse(request, answer));
+}
+
+async function callResponses<P extends ResponsesProvider>(
+  request: LlmRequest<P>,
+  credentials: Credentials<P>,
+  profile: ResponsesProfile<P>,
+  options: CallOptions,
+): Promise<LlmResponse<P>> {
+  const body = responsesRequest(request, profile);
+  const answer = await postJson({
+    provider: profile.provider,
+    label: profile.label,
+    url: profile.url,
+    headers: profile.headers(credentials),
+    body,
+    ...common(request, options),
+    failed: (http) => responsesFailure(profile, http),
+  });
+  return read(answer, () => responsesResponse(request, answer, profile));
+}
+
+function common(
+  request: LlmRequest,
+  { signal, fetch }: CallOptions,
+): { timeoutMs?: number; signal?: AbortSignal; fetch?: typeof fetch } {
+  return {
+    ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+    ...(signal === undefined ? {} : { signal }),
+    ...(fetch === undefined ? {} : { fetch }),
+  };
+}
+
+/** Reads an answer; a failure while reading names the provider's request ID. */
+function read<T>(answer: JsonAnswer, parse: () => T): T {
+  try {
+    return parse();
+  } catch (error) {
+    throw error instanceof LlmError ? withRequestId(error, answer.requestId) : error;
+  }
+}
+
+/**
+ * Credentials checked before they are sent, such as the keys a gateway reads
+ * from its configuration. A message names the field at fault, never its value.
+ */
+export function readCredentials<P extends Provider>(
+  provider: P,
+  value: Json | undefined,
+): Credentials<P> {
+  if (!isObject(value))
+    throw invalidRequest(provider, `the ${provider} credentials must be an object with an apiKey`);
+  const fields: { [name: string]: string } = {};
+  for (const [name, field] of Object.entries(value)) {
+    if (typeof field !== 'string' || field.trim() === '') {
+      throw invalidRequest(provider, `credentials.${name} must be a string that is not empty`);
+    }
+    fields[name] = field.trim();
+  }
+  if (fields['apiKey'] === undefined)
+    throw invalidRequest(provider, 'credentials.apiKey is missing');
+  // Every provider's credentials are an apiKey and optional string fields.
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return fields as unknown as Credentials<P>;
+}