@acentric/llm 0.0.0-stage → 0.1.0

package/src/read/responses.ts

@@ -0,0 +1,159 @@
+// Readers over a Responses assistant message (OpenAI, Fireworks). They never
+// change the message, which is sent back as it is.
+
+import type { Json, JsonObject } from '@acentric/types';
+
+import { isArray, isObject } from '../json.js';
+
+/** What a reader returns for one call, before it is typed for its provider. */
+export type ReadCall = {
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly toolType: 'function' | 'custom' | 'native';
+  readonly arguments?: string;
+  readonly input?: string;
+  readonly namespace?: string;
+  readonly async?: boolean;
+  readonly resultOptions?: JsonObject;
+  readonly itemType: string;
+  readonly item: JsonObject;
+};
+
+export type TextOptions = {
+  /** `final`, the default, leaves out commentary, which is a progress update and not the answer. */
+  readonly phase?: 'final' | 'all';
+};
+
+/** Item types answered with a `tool_result` message, and the tool type they answer. */
+const RESULT_CALLS: { readonly [type: string]: 'function' | 'custom' } = {
+  function_call: 'function',
+  custom_tool_call: 'custom',
+};
+
+/** Provider-defined calls the caller runs and answers with a `native` message. */
+const NATIVE_CALLS: ReadonlySet<string> = new Set([
+  'computer_call',
+  'shell_call',
+  'apply_patch_call',
+  'local_shell_call',
+  'tool_search_call',
+  'mcp_approval_request',
+]);
+
+function messages(items: readonly Json[]): JsonObject[] {
+  return items.filter(
+    (item): item is JsonObject =>
+      isObject(item) && item['type'] === 'message' && isArray(item['content']),
+  );
+}
+
+function parts(message: JsonObject): JsonObject[] {
+  const content = message['content'];
+  return isArray(content) ? content.filter(isObject) : [];
+}
+
+export function outputText(items: readonly Json[], { phase = 'final' }: TextOptions = {}): string {
+  return messages(items)
+    .filter((message) => phase === 'all' || message['phase'] !== 'commentary')
+    .map((message) =>
+      parts(message)
+        .map((part) => (part['type'] === 'output_text' ? text(part['text']) : ''))
+        .join(''),
+    )
+    .filter((joined) => joined !== '')
+    .join('\n\n');
+}
+
+export function refusals(items: readonly Json[]): string[] {
+  return messages(items).flatMap((message) =>
+    parts(message).flatMap((part) => {
+      const refusal = part['refusal'];
+      return part['type'] === 'refusal' && typeof refusal === 'string' ? [refusal] : [];
+    }),
+  );
+}
+
+export function reasoningSummary(items: readonly Json[]): string[] {
+  return items.flatMap((item) => {
+    if (!isObject(item) || item['type'] !== 'reasoning') return [];
+    const summary = item['summary'];
+    if (!isArray(summary)) return [];
+    return summary.flatMap((part) =>
+      isObject(part) && typeof part['text'] === 'string' ? [part['text']] : [],
+    );
+  });
+}
+
+/** Every call the caller answers, answered within the message or not. */
+export function toolCalls(items: readonly Json[]): ReadCall[] {
+  const calls: ReadCall[] = [];
+  for (const item of items) {
+    if (!isObject(item)) continue;
+    const type = item['type'];
+    if (typeof type !== 'string') continue;
+    const toolType = RESULT_CALLS[type] ?? (NATIVE_CALLS.has(type) ? 'native' : undefined);
+    if (toolType === undefined) continue;
+    // Tool search that runs at the provider has no call to answer.
+    if (type === 'tool_search_call' && item['execution'] !== 'client') continue;
+    const id = type === 'mcp_approval_request' ? item['id'] : item['call_id'];
+    if (typeof id !== 'string' || id === '') continue;
+    calls.push(toCall(item, type, id, toolType));
+  }
+  return calls;
+}
+
+/** Calls with no answer in the message itself, as a hosted shell call has in its output. */
+export function pendingToolCalls(items: readonly Json[]): ReadCall[] {
+  const answered = new Set<string>();
+  for (const item of items) {
+    if (!isObject(item)) continue;
+    const type = item['type'];
+    const request = item['approval_request_id'];
+    const callId = item['call_id'];
+    if (type === 'mcp_approval_response' && typeof request === 'string') answered.add(request);
+    else if (typeof type === 'string' && type.endsWith('_output') && typeof callId === 'string')
+      answered.add(callId);
+  }
+  return toolCalls(items).filter((call) => !answered.has(call.toolCallId));
+}
+
+function toCall(
+  item: JsonObject,
+  type: string,
+  id: string,
+  toolType: ReadCall['toolType'],
+): ReadCall {
+  const name = item['name'];
+  const namespace = item['namespace'];
+  const serverLabel = item['server_label'];
+  const args = item['arguments'];
+  const input = item['input'];
+  const caller = item['caller'];
+  const callNamespace =
+    typeof namespace === 'string'
+      ? namespace
+      : type === 'mcp_approval_request' && typeof serverLabel === 'string'
+        ? serverLabel
+        : undefined;
+  // A result must repeat the call's caller (programmatic tool calling) and may name its namespace.
+  const resultOptions: JsonObject = {
+    ...(isObject(caller) ? { caller } : {}),
+    ...(toolType === 'function' && typeof namespace === 'string' ? { namespace } : {}),
+  };
+  return {
+    toolCallId: id,
+    toolName: typeof name === 'string' ? name : type.replace(/_call$/, ''),
+    toolType,
+    ...(typeof args === 'string' && toolType !== 'native' ? { arguments: args } : {}),
+    ...(typeof input === 'string' ? { input } : {}),
+    ...(callNamespace === undefined ? {} : { namespace: callNamespace }),
+    ...(item['async'] === true ? { async: true } : {}),
+    ...(Object.keys(resultOptions).length > 0 ? { resultOptions } : {}),
+    itemType: type,
+    item,
+  };
+}
+
+function text(value: Json | undefined): string {
+  return typeof value === 'string' ? value : '';
+}

package/src/read.ts

@@ -0,0 +1,108 @@
+// Readers over any provider's assistant message, and the helpers that build
+// what a request sends. Each reader goes to its message's API format. Pure:
+// a step can use them.
+
+import type { Json } from '@acentric/types';
+
+import type { ContentPart } from './content.js';
+import type { AssistantMessage, Message, RequestMessage, ToolResultMessage } from './messages.js';
+import type { Provider } from './providers.js';
+import * as anthropic from './read/anthropic.js';
+import * as responses from './read/responses.js';
+import type { ReadCall, TextOptions } from './read/responses.js';
+import type { ToolCall } from './tool-calls.js';
+
+export type { TextOptions } from './read/responses.js';
+
+/** The message's items, read as plain Json. */
+function items(message: AssistantMessage): readonly Json[] {
+  return message.content;
+}
+
+/** Typed for the message's provider: a reader returns that message's own items. */
+function typed<P extends Provider>(calls: readonly ReadCall[]): ToolCall<P>[] {
+  // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+  return calls as unknown as ToolCall<P>[];
+}
+
+/**
+ * The text of the message's answer. On the Responses format, messages are
+ * joined by a blank line and commentary is left out unless `{ phase: 'all' }`.
+ */
+export function outputText(message: AssistantMessage, options?: TextOptions): string {
+  return message.api === 'anthropic-messages'
+    ? anthropic.outputText(items(message))
+    : responses.outputText(items(message), options);
+}
+
+/** What the model refused to do, in order. Anthropic says so in the stop reason instead, so its messages have none. */
+export function refusals(message: AssistantMessage): string[] {
+  return message.api === 'anthropic-messages'
+    ? anthropic.refusals()
+    : responses.refusals(items(message));
+}
+
+/** Reasoning summaries or thinking texts, in order. Encrypted reasoning stays in the message. */
+export function reasoningSummary(message: AssistantMessage): string[] {
+  return message.api === 'anthropic-messages'
+    ? anthropic.reasoningSummary(items(message))
+    : responses.reasoningSummary(items(message));
+}
+
+/** Every call in the message that the caller answers, answered within it or not. */
+export function toolCalls<P extends Provider>(message: AssistantMessage<P>): ToolCall<P>[] {
+  const any: AssistantMessage = message;
+  return typed<P>(
+    any.api === 'anthropic-messages'
+      ? anthropic.toolCalls(items(any))
+      : responses.toolCalls(items(any)),
+  );
+}
+
+/** Calls the caller still has to answer. An async call may stay pending while the conversation goes on. */
+export function pendingToolCalls<P extends Provider>(message: AssistantMessage<P>): ToolCall<P>[] {
+  const any: AssistantMessage = message;
+  return typed<P>(
+    any.api === 'anthropic-messages'
+      ? anthropic.toolCalls(items(any))
+      : responses.pendingToolCalls(items(any)),
+  );
+}
+
+export type ToolResultOptions = {
+  /** Sent only where the provider has a field for it, so the content must say what failed. */
+  readonly isError?: boolean;
+};
+
+/**
+ * The message answering a `function` or `custom` call, with the fields the
+ * provider requires on its result, such as OpenAI's `caller`. A `native` call
+ * is answered with a `native` message instead.
+ */
+export function toolResult(
+  call: ToolCall,
+  content: string | readonly ContentPart[],
+  { isError }: ToolResultOptions = {},
+): ToolResultMessage {
+  if (call.toolType === 'native') {
+    throw new TypeError(
+      `${call.itemType} is a provider-defined call: answer it with a native message`,
+    );
+  }
+  return {
+    role: 'tool_result',
+    toolCallId: call.toolCallId,
+    toolName: call.toolName,
+    toolType: call.toolType,
+    content: typeof content === 'string' ? [{ type: 'text', text: content }] : content,
+    ...(isError === undefined ? {} : { isError }),
+    ...(call.resultOptions === undefined ? {} : { providerOptions: call.resultOptions }),
+  };
+}
+
+/** The messages a provider receives: the application's own `custom` messages left out. */
+export function requestMessages<P extends Provider>(
+  messages: readonly Message<P>[],
+): RequestMessage<P>[] {
+  return messages.filter((message): message is RequestMessage<P> => message.role !== 'custom');
+}

package/src/request.ts

@@ -0,0 +1,28 @@
+// What a handler asks the client for. It holds no credentials: the client
+// reads them from the handler's secrets, so they never reach args or the log.
+
+import type { TextPart } from './content.js';
+import type { Message } from './messages.js';
+import type { ModelId, Provider, ProviderOptions } from './providers.js';
+import type { ToolDefinition } from './tools.js';
+
+/**
+ * One completion from provider `P`. Distributes over providers, so the model
+ * IDs, options and messages sent back all belong to `provider`.
+ */
+export type LlmRequest<P extends Provider = Provider> = P extends Provider
+  ? {
+      readonly provider: P;
+      readonly model: ModelId<P>;
+      /** The provider's top-level system instructions. */
+      readonly instructions?: string | readonly TextPart[];
+      /** The conversation. `custom` messages are left out when sending. */
+      readonly messages: readonly Message<P>[];
+      /** Tools the caller runs. Hosted tools go in `options.tools`. */
+      readonly tools?: readonly ToolDefinition[];
+      /** The provider's own request fields, passed through. */
+      readonly options?: ProviderOptions<P>;
+      /** The most the call may take, in milliseconds. */
+      readonly timeoutMs?: number;
+    }
+  : never;

package/src/response.ts

@@ -0,0 +1,44 @@
+// What a completion returns, the same for every provider apart from the
+// assistant message and `native`, which are the provider's own.
+
+import type { AssistantMessage } from './messages.js';
+import type { ModelId, NativeResponse, Provider } from './providers.js';
+import type { Usage } from './usage.js';
+
+export type StopReason =
+  /** Generation ended normally, a stop sequence included. */
+  | 'stop'
+  /** Cut short by an output token or length limit. */
+  | 'length'
+  /** The model called tools for the caller to run. */
+  | 'tool_use'
+  /** The model declined. */
+  | 'refusal'
+  /** A provider's safety filter blocked or ended generation. */
+  | 'content_filter'
+  /** The provider paused a turn that can be continued, such as during a long server tool run. */
+  | 'pause_turn';
+
+/** One completion from provider `P`. */
+export type LlmResponse<P extends Provider = Provider> = P extends Provider
+  ? {
+      /** The provider's response ID, such as for `previous_response_id`. */
+      readonly id?: string;
+      readonly provider: P;
+      /** The model ID the request asked for. */
+      readonly model: ModelId<P>;
+      /** The model the provider says answered, when it differs. */
+      readonly responseModel?: string;
+      readonly message: AssistantMessage<P>;
+      readonly stopReason: StopReason;
+      /** The provider's own reason, as it is, when it says more than `stopReason`. */
+      readonly providerStopReason?: string;
+      readonly usage?: Usage;
+      /** The provider's response fields that say something new: not its output or echoes of the request. */
+      readonly native: NativeResponse<P>;
+      /** How long the provider took, in milliseconds. */
+      readonly durationMs: number;
+      /** When the response arrived, in milliseconds since the Unix epoch. */
+      readonly timestamp: number;
+    }
+  : never;

package/src/secrets.ts

@@ -0,0 +1,40 @@
+// The secrets the client reads, by name. Runners and the CLI import these
+// names to pass the matching environment variables to handlers, so no
+// runner names a provider itself.
+//
+// The client calls a provider directly when its key is set, and otherwise
+// the gateway when both gateway secrets are set. A secret that is not set
+// rejects with SecretNotSet on every runner (RUNNERS.md §8), which is how the
+// client tells which are set.
+
+import type { Provider } from './providers.js';
+
+/** The secret holding each provider's API key. */
+export const PROVIDER_SECRETS = {
+  anthropic: 'ANTHROPIC_API_KEY',
+  openai: 'OPENAI_API_KEY',
+  fireworks: 'FIREWORKS_API_KEY',
+} as const satisfies { readonly [P in Provider]: string };
+
+/** The gateway's address and token, which acentric-cloud sets for agents that use its gateway. */
+export const GATEWAY_SECRETS = {
+  url: 'ACENTRIC_LLM_URL',
+  token: 'ACENTRIC_LLM_TOKEN',
+} as const;
+
+/**
+ * The secrets the client reads, taken from an environment where they are set:
+ * what a runner on your own machine passes to handlers, such as
+ * `createMemoryRunner({ secrets: llmSecrets(process.env) })`.
+ */
+export function llmSecrets(env: { readonly [name: string]: string | undefined }): {
+  [name: string]: string;
+} {
+  const names = [...Object.values(PROVIDER_SECRETS), ...Object.values(GATEWAY_SECRETS)];
+  const found: { [name: string]: string } = {};
+  for (const name of names) {
+    const value = env[name];
+    if (value !== undefined && value !== '') found[name] = value;
+  }
+  return found;
+}

package/src/tool-calls.ts

@@ -0,0 +1,33 @@
+// A tool call as the readers report it: a view of an item in an assistant
+// message, which keeps the call itself.
+
+import type { ProviderFields } from './fields.js';
+import type { NativeOutputItem, Provider } from './providers.js';
+
+export type ToolCall<P extends Provider = Provider> = P extends Provider
+  ? {
+      /** The ID a result answers. */
+      readonly toolCallId: string;
+      /** The tool's name, or the item type for a provider-defined tool without one. */
+      readonly toolName: string;
+      /**
+       * `function` and `custom` calls are answered with a `tool_result` message,
+       * `native` ones (a provider-defined tool such as computer use, or an
+       * approval request) with a `native` message.
+       */
+      readonly toolType: 'function' | 'custom' | 'native';
+      /** A function call's arguments as the model wrote them: a JSON string, not parsed. */
+      readonly arguments?: string;
+      /** A custom tool call's text. */
+      readonly input?: string;
+      readonly namespace?: string;
+      /** The call may stay unanswered while the conversation goes on. */
+      readonly async?: boolean;
+      /** Fields the provider requires on this call's result; `toolResult` copies them. */
+      readonly resultOptions?: ProviderFields;
+      /** The provider's item type, such as `function_call` or `tool_use`. */
+      readonly itemType: string;
+      /** The call as the provider wrote it. */
+      readonly item: NativeOutputItem<P>;
+    }
+  : never;

package/src/tools.ts

@@ -0,0 +1,38 @@
+// Tools the caller runs. A provider's hosted tools (web search, code
+// execution, ...) are its own definitions, passed in the request's options.
+
+import type { JsonObject } from '@acentric/types';
+
+import type { ProviderFields } from './fields.js';
+
+/** A JSON Schema object. */
+export type JsonSchema = JsonObject;
+
+type ToolBase = {
+  readonly name: string;
+  readonly description: string;
+  /** Merged into the provider's tool definition, such as Anthropic's `cache_control`. */
+  readonly providerOptions?: ProviderFields;
+};
+
+/** A tool called with JSON arguments matching `parameters`. */
+export type FunctionTool = ToolBase & {
+  readonly type: 'function';
+  readonly parameters: JsonSchema;
+  /** Asks the provider to hold the arguments to the schema, where it can. */
+  readonly strict?: boolean;
+};
+
+/** A tool called with free-form text, optionally held to a grammar. Not every provider has them. */
+export type CustomTool = ToolBase & {
+  readonly type: 'custom';
+  readonly format?: CustomToolFormat;
+};
+
+export type CustomToolFormat =
+  | { readonly type: 'text' }
+  | { readonly type: 'grammar'; readonly syntax: 'lark' | 'regex'; readonly definition: string };
+
+export type ToolDefinition = FunctionTool | CustomTool;
+
+export type ToolType = ToolDefinition['type'];

package/src/usage.ts

@@ -0,0 +1,33 @@
+// Tokens and cost, the same for every provider.
+
+/** Token counts. A count the provider does not report is left out; zero is a known zero. */
+export type Usage = {
+  /** Every prompt token, cached or not. */
+  readonly totalInput?: number;
+  /** Prompt tokens neither read from nor written to a cache. */
+  readonly input?: number;
+  /** Output tokens, reasoning included where the provider counts it as output. */
+  readonly output?: number;
+  /** Reasoning tokens: part of `output` unless the provider bills them apart. */
+  readonly reasoning?: number;
+  readonly cacheRead?: number;
+  /** Every token written to a cache, whatever its time to live. */
+  readonly cacheWrite?: number;
+  /**
+   * What it cost: what the provider says it charged where it says so,
+   * otherwise estimated from the model's prices when they and every count
+   * needed are known.
+   */
+  readonly cost?: UsageCost;
+};
+
+/** US dollars. A part that is not known is left out. */
+export type UsageCost = {
+  /** `reported`: what the provider says it charged. `estimated`: tokens at known prices. */
+  readonly source: 'reported' | 'estimated';
+  readonly input?: number;
+  readonly output?: number;
+  readonly cacheRead?: number;
+  readonly cacheWrite?: number;
+  readonly total: number;
+};

package/src/version.ts

@@ -0,0 +1,6 @@
+// This package's version. The client sends it to the gateway, so a gateway
+// running an older copy can refuse a newer client's request plainly instead
+// of failing on a shape it does not know. A test keeps it equal to
+// package.json's version.
+
+export const LLM_VERSION = '0.1.0';