@acentric/llm 0.0.0-stage → 0.1.0

package/src/client/gateway.ts

@@ -0,0 +1,120 @@
+// One call through the acentric gateway, which acentric-cloud runs with
+// provider keys of its own. The request goes as it is, with the token and the
+// client's version in headers and the effect that made the call in the body;
+// the response comes back as it is.
+
+import { isLlmFailure, LlmError } from '../failure.js';
+import type { LlmFailure } from '../failure.js';
+import { isObject } from '../json.js';
+import type { Provider } from '../providers.js';
+import type { LlmRequest } from '../request.js';
+import type { LlmResponse } from '../response.js';
+import { LLM_VERSION } from '../version.js';
+import type { CallOptions } from './direct.js';
+import { postJson, retryAfter } from './http.js';
+import type { HttpAnswer } from './http.js';
+import { kindForStatus } from './responses/errors.js';
+import { cut, invalidResponse } from './util.js';
+
+/** Where a gateway takes completions, under its URL. */
+export const GATEWAY_ROUTE = '/v1/complete';
+
+/** The header that carries the client's LLM_VERSION to the gateway. */
+export const VERSION_HEADER = 'acentric-llm-version';
+
+/**
+ * The effect a call is made for, as its handler's context names it. A gateway
+ * shows each call under it, but it is the caller's word: never a credential,
+ * and never what a call is charged to.
+ */
+export type GatewayEffect = {
+  readonly key?: string;
+  readonly kind?: string;
+  readonly attempt?: number;
+};
+
+/**
+ * The body of a call to the gateway: the request, and the effect that made
+ * it. It carries no credentials, since the gateway calls providers with its
+ * own keys.
+ */
+export type GatewayRequest<P extends Provider = Provider> = P extends Provider
+  ? LlmRequest<P> & { readonly effect?: GatewayEffect }
+  : never;
+
+/** The body of a gateway's answer that is not 2xx. */
+export type GatewayFailure = { readonly error: LlmFailure };
+
+export type Gateway = {
+  /** The gateway's address, such as `https://llm.cloud.acentric.dev`. */
+  readonly url: string;
+  /** Sent as `Authorization: Bearer`. */
+  readonly token: string;
+};
+
+export type GatewayCallOptions = CallOptions & {
+  /** The effect the call is made for, sent for the gateway to show. */
+  readonly effect?: GatewayEffect;
+};
+
+export async function callGateway<P extends Provider>(
+  request: LlmRequest<P>,
+  gateway: Gateway,
+  { signal, fetch, effect }: GatewayCallOptions = {},
+): Promise<LlmResponse<P>> {
+  const provider = request.provider;
+  const answer = await postJson({
+    provider,
+    label: 'the acentric gateway',
+    url: `${base(provider, gateway.url)}${GATEWAY_ROUTE}`,
+    headers: { authorization: `Bearer ${gateway.token}`, [VERSION_HEADER]: LLM_VERSION },
+    body: effect === undefined ? request : { ...request, effect },
+    ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
+    ...(signal === undefined ? {} : { signal }),
+    ...(fetch === undefined ? {} : { fetch }),
+    failed: (http) => gatewayFailure(provider, http),
+    // The gateway's request ID is not the provider's; its failures carry that.
+    providerAnswers: false,
+  });
+  const body = answer.body;
+  const message = isObject(body) ? body['message'] : undefined;
+  if (!isObject(body) || body['provider'] !== provider || !isObject(message)) {
+    throw invalidResponse(provider, 'the acentric gateway did not answer with a response', body);
+  }
+  // The gateway answers what callProvider returned, for this provider.
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return body as unknown as LlmResponse<P>;
+}
+
+/** The gateway's own failure as it sent it, or one read from the HTTP status. */
+function gatewayFailure(provider: Provider, answer: HttpAnswer): LlmError {
+  const error = isObject(answer.body) ? answer.body['error'] : undefined;
+  if (isLlmFailure(error)) return LlmError.fromJSON(error);
+  const after = retryAfter(answer.headers);
+  return new LlmError(`the acentric gateway answered HTTP ${answer.status}`, {
+    kind: kindForStatus(answer.status),
+    provider,
+    httpStatus: answer.status,
+    providerError: cut(answer.body),
+    ...(after === undefined ? {} : { retryAfterMs: after }),
+  });
+}
+
+function base(provider: Provider, value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new LlmError(`the gateway's URL is not a URL: ${value}`, {
+      kind: 'invalid_request',
+      provider,
+    });
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new LlmError('the gateway must be reached over https, or http for local development', {
+      kind: 'invalid_request',
+      provider,
+    });
+  }
+  return url.href.replace(/\/+$/, '');
+}

package/src/client/http.ts

@@ -0,0 +1,231 @@
+// One HTTP exchange with a provider or the gateway: a JSON body out, a JSON
+// body back, stopped by the handler's signal or a time limit. Never retried:
+// whether to try again is the agent's decision.
+
+import type { Json } from '@acentric/types';
+
+import { LlmError } from '../failure.js';
+import { cut } from './util.js';
+
+/** The longest one call may take, and the default, in milliseconds. */
+export const MAX_TIMEOUT_MS = 15 * 60 * 1000;
+
+const MAX_RESPONSE_BYTES = 32 * 1024 * 1024;
+
+export type Post = {
+  readonly provider: string;
+  /** Names the other end in messages, such as "Anthropic". */
+  readonly label: string;
+  readonly url: string;
+  readonly headers: { readonly [name: string]: string };
+  readonly body: Json;
+  readonly timeoutMs?: number;
+  readonly signal?: AbortSignal;
+  readonly fetch?: typeof fetch;
+  /** Turns an answer that is not 2xx into an error. */
+  readonly failed: (answer: HttpAnswer) => LlmError;
+  /** Whether the answer's request ID is the provider's, for its failures to name. Defaults to true. */
+  readonly providerAnswers?: boolean;
+};
+
+/** An answer that is not 2xx. */
+export type HttpAnswer = {
+  readonly status: number;
+  readonly headers: Headers;
+  /** The JSON body, or the text body cut short. */
+  readonly body: Json;
+};
+
+export type JsonAnswer = {
+  readonly body: Json;
+  readonly durationMs: number;
+  /** When the answer arrived, in milliseconds since the Unix epoch. */
+  readonly timestamp: number;
+  readonly requestId?: string;
+};
+
+export async function postJson(post: Post): Promise<JsonAnswer> {
+  const { provider, label } = post;
+  const timeoutMs = Math.min(post.timeoutMs ?? MAX_TIMEOUT_MS, MAX_TIMEOUT_MS);
+  if (!(Number.isSafeInteger(timeoutMs) && timeoutMs > 0)) {
+    throw new LlmError('timeoutMs must be a positive whole number', {
+      kind: 'invalid_request',
+      provider,
+    });
+  }
+  const controller = new AbortController();
+  const onAbort = () =>
+    controller.abort(
+      new LlmError(`the ${label} call was cancelled`, { kind: 'cancelled', provider }),
+    );
+  post.signal?.addEventListener('abort', onAbort, { once: true });
+  if (post.signal?.aborted === true) onAbort();
+  const timer = setTimeout(
+    () =>
+      controller.abort(
+        new LlmError(`the ${label} call took longer than ${timeoutMs} ms`, {
+          kind: 'timeout',
+          provider,
+        }),
+      ),
+    timeoutMs,
+  );
+  const started = performance.now();
+  let requestId: string | undefined;
+  try {
+    controller.signal.throwIfAborted();
+    const send = post.fetch ?? globalThis.fetch;
+    // Raced against the signal, so a fetch that does not watch it cannot outlast a timeout.
+    const response = await untilAborted(
+      send(post.url, {
+        method: 'POST',
+        headers: requestHeaders(provider, post.headers),
+        body: JSON.stringify(post.body),
+        signal: controller.signal,
+        redirect: 'manual',
+      }),
+      controller.signal,
+    );
+    if (post.providerAnswers !== false) requestId = readRequestId(response.headers);
+    if (response.status >= 300 && response.status < 400) {
+      void response.body?.cancel().catch(() => undefined);
+      throw new LlmError(`${label} answered with a redirect, which is not followed`, {
+        kind: 'network_error',
+        provider,
+      });
+    }
+    const text = await readText(response, provider, label);
+    controller.signal.throwIfAborted();
+    if (!response.ok) {
+      throw post.failed({
+        status: response.status,
+        headers: response.headers,
+        body: parseLoosely(text),
+      });
+    }
+    let body: Json;
+    try {
+      body = JSON.parse(text);
+    } catch {
+      throw new LlmError(`${label} answered with something that is not JSON`, {
+        kind: 'invalid_response',
+        provider,
+        httpStatus: response.status,
+        providerError: cut(text),
+      });
+    }
+    return {
+      body,
+      durationMs: Math.round(performance.now() - started),
+      timestamp: Date.now(),
+      ...(requestId === undefined ? {} : { requestId }),
+    };
+  } catch (error) {
+    const reason: unknown = controller.signal.aborted ? controller.signal.reason : error;
+    if (reason instanceof LlmError) throw withRequestId(reason, requestId);
+    throw new LlmError(`${label} could not be reached`, {
+      kind: 'network_error',
+      provider,
+      ...(requestId === undefined ? {} : { requestId }),
+    });
+  } finally {
+    clearTimeout(timer);
+    post.signal?.removeEventListener('abort', onAbort);
+  }
+}
+
+/** `Retry-After` in milliseconds, given in seconds or as an HTTP date. */
+export function retryAfter(headers: Headers): number | undefined {
+  const value = headers.get('retry-after')?.trim();
+  if (value === undefined || value === '') return undefined;
+  const seconds = Number(value);
+  if (Number.isFinite(seconds)) return seconds >= 0 ? Math.round(seconds * 1000) : undefined;
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+
+/** A failure from after the provider answered names its request ID, for its support. */
+export function withRequestId(error: LlmError, requestId: string | undefined): LlmError {
+  if (requestId === undefined || error.failure.requestId !== undefined) return error;
+  return LlmError.fromJSON({ ...error.failure, requestId });
+}
+
+/** The promise's value, or the signal's reason as soon as it fires. */
+function untilAborted<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener('abort', abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', abort));
+  });
+}
+
+function requestHeaders(provider: string, entries: { readonly [name: string]: string }): Headers {
+  try {
+    return new Headers({
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...entries,
+    });
+  } catch {
+    throw new LlmError('the credentials hold characters a header cannot', {
+      kind: 'invalid_request',
+      provider,
+    });
+  }
+}
+
+function readRequestId(answer: Headers): string | undefined {
+  const id =
+    answer.get('x-request-id') ?? answer.get('request-id') ?? answer.get('x-oai-request-id');
+  return id?.trim() || undefined;
+}
+
+function parseLoosely(text: string): Json {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return cut(text);
+  }
+}
+
+async function readText(response: Response, provider: string, label: string): Promise<string> {
+  if (response.body === null) return '';
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder('utf-8', { fatal: true });
+  const decode = (value?: Uint8Array): string => {
+    try {
+      return decoder.decode(value, { stream: value !== undefined });
+    } catch {
+      throw new LlmError(`${label} answered with text that is not UTF-8`, {
+        kind: 'invalid_response',
+        provider,
+        httpStatus: response.status,
+      });
+    }
+  };
+  let bytes = 0;
+  let text = '';
+  try {
+    for (;;) {
+      // Reading a stream is one chunk at a time.
+      // oxlint-disable-next-line no-await-in-loop
+      const { done, value } = await reader.read();
+      if (done) break;
+      bytes += value.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) {
+        throw new LlmError(`${label} answered with more than ${MAX_RESPONSE_BYTES} bytes`, {
+          kind: 'invalid_response',
+          provider,
+          httpStatus: response.status,
+        });
+      }
+      text += decode(value);
+    }
+    return text + decode();
+  } catch (error) {
+    void reader.cancel().catch(() => undefined);
+    throw error;
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/client/llm.ts

@@ -0,0 +1,151 @@
+// The client a handler uses: it finds the provider's key or the gateway in
+// the handler's secrets, never in the environment, so the same code runs on
+// every runner.
+//
+// A call goes straight to its provider when that provider's key is set, so an
+// application with its own account uses it. Otherwise, with ACENTRIC_LLM_URL
+// and ACENTRIC_LLM_TOKEN set, it goes through the gateway, which calls the
+// provider with keys of its own. Options override all of this.
+
+import type { Secrets } from '@acentric/types';
+
+import { LlmError } from '../failure.js';
+import type { Credentials, Provider } from '../providers.js';
+import { requestMessages } from '../read.js';
+import type { LlmRequest } from '../request.js';
+import type { LlmResponse } from '../response.js';
+import { GATEWAY_SECRETS, PROVIDER_SECRETS } from '../secrets.js';
+import { callProvider } from './direct.js';
+import { callGateway } from './gateway.js';
+import type { Gateway, GatewayEffect } from './gateway.js';
+
+/** What the client needs of a handler's context. A HandlerContext is one. */
+export type LlmContext = {
+  readonly secrets: Secrets;
+  /** Stops every call, unless a call passes its own. */
+  readonly signal?: AbortSignal;
+  /** The effect's key, kind and attempt, which the gateway shows each call under. */
+  readonly key?: string;
+  readonly kind?: string;
+  readonly attempt?: number;
+};
+
+export type LlmOptions = {
+  /** Credentials for a provider, used instead of its secret or a gateway. */
+  readonly credentials?: { readonly [P in Provider]?: Credentials<P> };
+  /**
+   * A gateway to call instead of the provider's key or the gateway in the
+   * secrets, or `false` to call providers directly even when the secrets name
+   * one.
+   */
+  readonly gateway?: Gateway | false;
+  /** A fetch to use instead of the global one, such as in tests. */
+  readonly fetch?: typeof fetch;
+};
+
+export type LlmClient = {
+  /**
+   * One completion, from the request's provider. The application's `custom`
+   * messages are left out. Never retried: on failure it throws an LlmError,
+   * which step reads back with `llmFailure`.
+   */
+  complete<P extends Provider>(
+    request: LlmRequest<P>,
+    options?: { readonly signal?: AbortSignal },
+  ): Promise<LlmResponse<P>>;
+};
+
+export function createLlm(context: LlmContext, options: LlmOptions = {}): LlmClient {
+  return {
+    async complete<P extends Provider>(
+      request: LlmRequest<P>,
+      call: { readonly signal?: AbortSignal } = {},
+    ): Promise<LlmResponse<P>> {
+      const signal = call.signal ?? context.signal;
+      const callOptions = {
+        ...(signal === undefined ? {} : { signal }),
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+      };
+      const sent = withoutCustom(request);
+      const route = await routeFor(request.provider, context.secrets, options);
+      if (route === undefined) {
+        throw new LlmError(
+          `no credentials for ${request.provider}: set the secret ${PROVIDER_SECRETS[request.provider]}, ` +
+            `or ${GATEWAY_SECRETS.url} and ${GATEWAY_SECRETS.token} for the gateway`,
+          { kind: 'auth', provider: request.provider },
+        );
+      }
+      if ('credentials' in route) return callProvider(sent, route.credentials, callOptions);
+      return callGateway(sent, route.gateway, { ...callOptions, ...effectOf(context) });
+    },
+  };
+}
+
+/** The request without the application's own messages, which never reach a provider. */
+function withoutCustom<P extends Provider>(request: LlmRequest<P>): LlmRequest<P> {
+  return { ...request, messages: requestMessages(request.messages) };
+}
+
+async function gatewayIn(secrets: Secrets): Promise<Gateway | undefined> {
+  const url = await secret(secrets, GATEWAY_SECRETS.url);
+  const token = await secret(secrets, GATEWAY_SECRETS.token);
+  if (url === undefined && token === undefined) return undefined;
+  if (url === undefined || token === undefined) {
+    const [set, missing] =
+      url === undefined
+        ? [GATEWAY_SECRETS.token, GATEWAY_SECRETS.url]
+        : [GATEWAY_SECRETS.url, GATEWAY_SECRETS.token];
+    throw new LlmError(`${set} is set but ${missing} is not: the gateway needs both`, {
+      kind: 'auth',
+    });
+  }
+  return { url, token };
+}
+
+/**
+ * Where a call goes: credentials or a gateway given as options, then the
+ * provider's key, then the gateway in the secrets. Undefined when there is
+ * none of these.
+ */
+async function routeFor<P extends Provider>(
+  provider: P,
+  secrets: Secrets,
+  options: LlmOptions,
+): Promise<{ readonly credentials: Credentials<P> } | { readonly gateway: Gateway } | undefined> {
+  const given: Credentials<P> | undefined = options.credentials?.[provider];
+  if (given !== undefined) return { credentials: given };
+  if (options.gateway !== undefined && options.gateway !== false) {
+    return { gateway: options.gateway };
+  }
+  const apiKey = await secret(secrets, PROVIDER_SECRETS[provider]);
+  if (apiKey !== undefined) return { credentials: { apiKey } };
+  if (options.gateway === false) return undefined;
+  const gateway = await gatewayIn(secrets);
+  return gateway === undefined ? undefined : { gateway };
+}
+
+/** The effect the context names, for the gateway, when it names one. */
+function effectOf(context: LlmContext): { readonly effect?: GatewayEffect } {
+  const { key, kind, attempt } = context;
+  if (key === undefined && kind === undefined && attempt === undefined) return {};
+  return {
+    effect: {
+      ...(key === undefined ? {} : { key }),
+      ...(kind === undefined ? {} : { kind }),
+      ...(attempt === undefined ? {} : { attempt }),
+    },
+  };
+}
+
+/**
+ * A secret's value, or undefined when it is not set. Any other failure to
+ * read it is thrown: it must not quietly send the call another way.
+ */
+async function secret(secrets: Secrets, name: string): Promise<string | undefined> {
+  try {
+    return await secrets.get(name);
+  } catch (error) {
+    if (error instanceof Error && error.name === 'SecretNotSet') return undefined;
+    throw error;
+  }
+}

package/src/client/responses/errors.ts

@@ -0,0 +1,166 @@
+// Responses failures read into LlmErrors: from an HTTP error, or from a
+// failed response that came with HTTP 200.
+
+import type { Json, JsonObject } from '@acentric/types';
+
+import { LlmError } from '../../failure.js';
+import type { LlmFailureKind } from '../../failure.js';
+import { isArray, isObject } from '../../json.js';
+import type { Usage } from '../../usage.js';
+import { retryAfter } from '../http.js';
+import type { HttpAnswer } from '../http.js';
+import { cut, show } from '../util.js';
+import type { ErrorInput, ResponsesProfile, ResponsesProvider } from './profile.js';
+
+const POLICY_CODES: ReadonlySet<string> = new Set([
+  'bio_policy',
+  'cyber_policy',
+  'misalignment_policy_violation',
+  'image_content_policy_violation',
+]);
+
+const QUOTA_CODES: ReadonlySet<string> = new Set([
+  'insufficient_quota',
+  'credit_balance_exhausted',
+  'organization_spend_limit_exceeded',
+  'project_spend_limit_exceeded',
+  'organization_usage_limit_exceeded',
+]);
+
+const KIND_BY_CODE: { readonly [code: string]: LlmFailureKind } = {
+  context_length_exceeded: 'context_overflow',
+  previous_response_not_found: 'not_found',
+  rate_limit_exceeded: 'rate_limited',
+  slow_down: 'rate_limited',
+  server_is_overloaded: 'overloaded',
+  server_error: 'provider_error',
+  vector_store_timeout: 'timeout',
+};
+
+/** The kind an HTTP status means when nothing more is known. */
+export function kindForStatus(status: number): LlmFailureKind {
+  if (status === 401 || status === 403) return 'auth';
+  if (status === 402) return 'quota_exceeded';
+  if (status === 404) return 'not_found';
+  if (status === 408) return 'timeout';
+  if (status === 429) return 'rate_limited';
+  if (status === 503 || status === 529) return 'overloaded';
+  if (status >= 500) return 'provider_error';
+  return 'invalid_request';
+}
+
+type Fields = {
+  readonly message?: string;
+  readonly code?: string;
+  readonly type?: string;
+  readonly param?: string;
+};
+
+/** A provider's answer that is not 2xx, as an LlmError. */
+export function httpFailure<P extends ResponsesProvider>(
+  profile: ResponsesProfile<P>,
+  answer: HttpAnswer,
+): LlmError {
+  const { fields, detail } = readError(answer.body);
+  const input: ErrorInput = { ...fields, status: answer.status };
+  const reading = profile.classifyError?.(input);
+  const message =
+    fields.message ??
+    (typeof answer.body === 'string' && answer.body !== '' ? answer.body : undefined) ??
+    `the ${profile.label} call failed with HTTP ${answer.status}`;
+  const param = fields.param ?? reading?.param;
+  const after = retryAfter(answer.headers);
+  return new LlmError(message, {
+    kind: reading?.kind ?? kindForCode(fields) ?? kindForStatus(answer.status),
+    provider: profile.provider,
+    httpStatus: answer.status,
+    providerError: cut(detail),
+    ...(fields.code === undefined ? {} : { providerCode: fields.code }),
+    ...(fields.type === undefined ? {} : { providerType: fields.type }),
+    ...(param === undefined ? {} : { providerParam: param }),
+    ...(after === undefined ? {} : { retryAfterMs: after }),
+  });
+}
+
+/** A response whose status is `failed`, or an error that came with HTTP 200. */
+export function failedResponse<P extends ResponsesProvider>(
+  profile: ResponsesProfile<P>,
+  error: Json,
+  responseId: string | undefined,
+  usage: Usage | undefined,
+): LlmError {
+  const { fields, detail } = readError({ error });
+  const reading = profile.classifyError?.(fields);
+  const param = fields.param ?? reading?.param;
+  return new LlmError(fields.message ?? `the ${profile.label} response failed`, {
+    kind:
+      reading?.kind ??
+      kindForCode(fields) ??
+      (fields.code === undefined ? 'provider_error' : 'invalid_request'),
+    provider: profile.provider,
+    providerError: cut(detail),
+    ...(fields.code === undefined ? {} : { providerCode: fields.code }),
+    ...(param === undefined ? {} : { providerParam: param }),
+    ...(responseId === undefined ? {} : { responseId }),
+    ...(usage === undefined ? {} : { usage }),
+  });
+}
+
+function kindForCode({ code, type }: Fields): LlmFailureKind | undefined {
+  if (code !== undefined && POLICY_CODES.has(code)) return 'policy_violation';
+  if ((code !== undefined && QUOTA_CODES.has(code)) || type === 'insufficient_quota') {
+    return 'quota_exceeded';
+  }
+  return code === undefined ? undefined : KIND_BY_CODE[code];
+}
+
+/**
+ * The error in an answer. Besides the format's `{ error: {...} }`, Fireworks
+ * also answers FastAPI's `{ detail }`: a message, an error, or a list of
+ * validation errors.
+ */
+function readError(body: Json): { fields: Fields; detail: Json } {
+  if (isObject(body) && body['error'] === undefined && body['detail'] !== undefined) {
+    const detail = body['detail'];
+    if (typeof detail === 'string') return { fields: { message: detail }, detail };
+    if (isArray(detail)) return { fields: validationErrors(detail), detail };
+    return { fields: errorFields(detail), detail };
+  }
+  const detail = isObject(body) && body['error'] !== undefined ? body['error'] : body;
+  return { fields: errorFields(detail), detail };
+}
+
+function errorFields(detail: Json): Fields {
+  if (!isObject(detail)) return {};
+  const { message, code, type, param } = detail;
+  return {
+    ...(typeof message === 'string' ? { message } : {}),
+    ...(typeof code === 'string' || typeof code === 'number' ? { code: String(code) } : {}),
+    ...(typeof type === 'string' ? { type } : {}),
+    ...(typeof param === 'string' ? { param } : {}),
+  };
+}
+
+/** FastAPI's validation errors: `[{ loc: ["body", "temperature"], msg }]`. */
+function validationErrors(list: readonly Json[]): Fields {
+  const entries = list.filter(isObject).map((entry: JsonObject) => {
+    const loc = entry['loc'];
+    const msg = entry['msg'];
+    const path = isArray(loc)
+      ? loc
+          .filter((part) => part !== 'body')
+          .map((part) => show(part))
+          .join('.')
+      : '';
+    return { param: path, message: typeof msg === 'string' ? msg : '' };
+  });
+  const message = entries
+    .map((entry) => (entry.param === '' ? entry.message : `${entry.param}: ${entry.message}`))
+    .filter((text) => text !== '')
+    .join('; ');
+  const only = entries.length === 1 ? entries[0]?.param : undefined;
+  return {
+    ...(message === '' ? {} : { message }),
+    ...(only === undefined || only === '' ? {} : { param: only }),
+  };
+}