Completion

Import from @anvia/core or @anvia/core/completion.

JSON Types

type JsonPrimitive = string | number | boolean | null;
type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
type JsonObject = { [key: string]: JsonValue | undefined };

function isJsonValue(value: unknown): value is JsonValue;

Purpose: provider-safe JSON contracts used by tool arguments, model parameters, schemas, and metadata.

Return behavior: isJsonValue(...) accepts strict, JSON-serializable values. It rejects non-finite numbers, undefined, functions, symbols, bigint values, cycles, sparse arrays, accessors, and non-plain objects.

Notable errors: none directly.

Document

type Document = {
  id: string;
  text: string;
  additionalProps?: Record<string, string>;
};

Purpose: static or retrieved context document attached to a completion request.

Return behavior: sent through CompletionRequest.documents.

Notable errors: none directly.

Content Types and Factories

type Text = { type: "text"; text: string; signature?: string };
type ImageDetail = "auto" | "low" | "high";
type ImageContent = { type: "image"; source: { type: "url"; url: string } | { type: "base64"; data: string; mediaType: string }; detail?: ImageDetail };
type DocumentContent = { type: "document"; source: { type: "url"; url: string; mediaType: string; filename?: string } | { type: "base64"; data: string; mediaType: string; filename?: string } | { type: "text"; text: string; mediaType?: string; filename?: string } };
type ReasoningContent =
  | { type: "text"; text: string; signature?: string }
  | { type: "summary"; text: string }
  | { type: "encrypted"; data: string }
  | { type: "redacted"; data: string };
type ReasoningContentType = ReasoningContent["type"];
type Reasoning = { type: "reasoning"; text: string; id?: string; content?: ReasoningContent[] };
type ToolFunction = { name: string; arguments: JsonValue };
type ToolCall = { type: "tool_call"; id: string; callId?: string; function: ToolFunction; signature?: string; additionalParams?: JsonValue };
type ToolResultContent = { type: "text"; text: string } | { type: "image"; data: string; mediaType?: string };
type ToolResult = { type: "tool_result"; id: string; callId?: string; toolName?: string; content: ToolResultContent[] };
type ToolContent = ToolResult;

Purpose: normalized message content parts across providers.

Return behavior: use the UserContent, AssistantContent, and Message factory objects to create valid values.

Notable errors: none directly.

Message

type MessageOptions = { metadata?: JsonValue };
type AssistantMessageOptions = MessageOptions & { id?: string };
type ToolResultOptions = {
  callId?: string;
  toolName?: string;
};
type ToolResultMessageOptions = ToolResultOptions & MessageOptions;

type SystemMessage = { role: "system"; content: string; metadata?: JsonValue };
type UserMessage = { role: "user"; content: UserContent[]; metadata?: JsonValue };
type AssistantMessage = {
  role: "assistant";
  id?: string;
  content: AssistantContent[];
  metadata?: JsonValue;
};
type ToolMessage = { role: "tool"; content: ToolContent[]; metadata?: JsonValue };
type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;

type AssistantGenerationMetadata = {
  provider: string;
  model: string;
  usage: Usage;
};

function getAssistantGenerationMetadata(
  message: Message,
): AssistantGenerationMetadata | undefined;

const Message: {
  system(content: string, options?: MessageOptions): Message;
  user(content: string | UserContent[], options?: MessageOptions): Message;
  assistant(
    content: string | AssistantContent[],
    idOrOptions?: string | AssistantMessageOptions,
  ): Message;
  tool(content: ToolContent | ToolContent[], options?: MessageOptions): Message;
  toolResult(id: string, output: unknown, options?: ToolResultMessageOptions): Message;
};

Purpose: normalized chat history and prompt shape.

Return behavior: factory methods return message objects with normalized content arrays and optional strict JSON metadata. Existing assistant message ids remain supported as a string second argument; use { id, metadata } when both are needed. Message.tool(...) is the low-level factory for complete tool content. Message.toolResult(...) creates the common tool-role message after executing a model-requested tool call, serializing non-string output with JSON and preserving structured ToolResultContent[].

Provider adapters construct provider-native payloads from message role and content. Message metadata is persisted and observable at the run/transcript level, but is not sent to model APIs or included in generation input attributes.

Assistant messages generated by an agent prompt include provider-agnostic generation details under the reserved metadata.anvia.generation namespace:

{
  metadata: {
    "anvia": {
      generation: {
        provider: "openai",
        model: "gpt-5",
        usage: {
          inputTokens: 120,
          outputTokens: 30,
          totalTokens: 150,
          cachedInputTokens: 20,
          cacheCreationInputTokens: 0,
        },
      },
    },
  },
}

Usage belongs to that individual model generation, so tool loops can contain multiple assistant messages with distinct usage. The model is the effective request model after middleware, falling back to the completion model’s default. getAssistantGenerationMetadata(...) safely reads this namespace and returns undefined for manual, legacy, or malformed messages. Raw provider responses, timing, traces, costs, and finish reasons are not copied into message metadata.

Notable errors: factories throw TypeError when metadata is not a strict JSON value.

UserContent, AssistantContent, and ToolContent

const UserContent: {
  text(text: string): Text;
  imageUrl(url: string, options?: { detail?: ImageDetail }): ImageContent;
  imageBase64(data: string, mediaType: string, options?: { detail?: ImageDetail }): ImageContent;
  documentUrl(url: string, mediaType: string, options?: { filename?: string }): DocumentContent;
  documentBase64(data: string, mediaType: string, options?: { filename?: string }): DocumentContent;
  documentText(text: string): Text;
};

const AssistantContent: {
  text(text: string): Text;
  imageUrl(url: string, options?: { detail?: ImageDetail }): ImageContent;
  imageBase64(data: string, mediaType: string, options?: { detail?: ImageDetail }): ImageContent;
  reasoning(text: string, id?: string): Reasoning;
  reasoningFromContent(content: ReasoningContent[], id?: string): Reasoning;
  reasoningSummary(text: string, id?: string): Reasoning;
  reasoningEncrypted(data: string, id?: string): Reasoning;
  reasoningRedacted(data: string, id?: string): Reasoning;
  toolCall(id: string, name: string, args: JsonValue, callId?: string): ToolCall;
};

const ToolContent: {
  toolResult(id: string, content: string | ToolResultContent[], callIdOrOptions?: string | { callId?: string | undefined; toolName?: string | undefined }, toolName?: string): ToolResult;
};

Purpose: helper factories for user, assistant, and tool content.

Return behavior: returns normalized content values.

For normal manual tool execution, prefer:

messages.push(Message.toolResult(toolCall.id, result, { callId: toolCall.callId }));

Set toolName on persisted tool results when the result is created without a nearby assistant tool call. UI message rehydration also recovers tool names from matching assistant tool calls by id or callId.

AssistantContent.reasoning(text, id?) keeps the legacy shape. Provider adapters can populate reasoning.content with structured text, summary, encrypted, or redacted blocks; reasoning.text remains the display-safe text made from text and summary blocks.

Notable errors: none directly.

ToolChoice and ToolDefinition

type ToolChoice =
  | "auto"
  | "required"
  | "none"
  | { type: "function"; name: string };

type ToolDefinition = {
  name: string;
  description: string;
  parameters: JsonObject;
};

Purpose: provider-facing tool selection and JSON schema definitions.

Return behavior: passed through completion requests.

Notable errors: providers can reject unsupported tool choice modes.

Usage

type Usage = {
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  cachedInputTokens: number;
  cacheCreationInputTokens: number;
};

const Usage: {
  empty(): Usage;
  add(left: Usage, right: Usage): Usage;
};

Purpose: normalized token accounting.

Return behavior: empty() returns zeroed usage; add(...) sums matching fields.

Notable errors: none directly.

CompletionRequest and CompletionResponse

type CompletionRequest = {
  model?: string;
  instructions?: string;
  chatHistory: Message[];
  documents: Document[];
  tools: ToolDefinition[];
  temperature?: number;
  maxTokens?: number;
  toolChoice?: ToolChoice;
  additionalParams?: JsonValue;
  outputSchema?: JsonObject;
};

type CompletionResponse<RawResponse = unknown> = {
  choice: AssistantContent[];
  usage: Usage;
  rawResponse: RawResponse;
  messageId?: string;
};

Purpose: normalized model request and response contracts implemented by providers.

Return behavior: models return one CompletionResponse per non-streaming completion.

Notable errors: provider adapters can throw transport, authentication, or provider validation errors.

Completion Models

type CompletionModelCapabilities = {
  streaming: boolean;
  tools: boolean;
  toolChoice: boolean;
  imageInput: boolean;
  documentInput: boolean;
  outputSchema: boolean;
  reasoning: boolean;
};

interface CompletionModel<RawResponse = unknown> {
  readonly provider: string;
  readonly defaultModel: string;
  readonly capabilities: CompletionModelCapabilities;
  completion(request: CompletionRequest): Promise<CompletionResponse<RawResponse>>;
}

type CompletionStreamEvent<RawResponse = unknown> =
  | { type: "text_delta"; delta: string }
  | { type: "reasoning_delta"; delta: string; id?: string; contentType?: ReasoningContent["type"]; signature?: string }
  | { type: "tool_call_delta"; id: string; callId?: string; name?: string; argumentsDelta?: string; argumentsMode?: ToolCallArgumentsMode; signature?: string }
  | { type: "tool_call"; toolCall: ToolCall }
  | { type: "message_id"; id: string }
  | { type: "final"; response: CompletionResponse<RawResponse> }
  | { type: "error"; error: unknown; usage?: Usage };

interface StreamingCompletionModel<RawResponse = unknown> extends CompletionModel<RawResponse> {
  streamCompletion(request: CompletionRequest): AsyncIterable<CompletionStreamEvent<RawResponse>>;
}

Purpose: provider adapter interfaces. The metadata fields identify the adapter, its default model name, and the normalized request features the adapter supports.

ToolCallArgumentsMode is "append" | "replace". An omitted mode means append. Providers use "replace" when a completion event contains a full argument snapshot rather than the next fragment.

Return behavior: streaming models yield deltas and finish with a final event. Provider error events may include authoritative usage for the failed request; adapters omit it when the provider does not report usage.

Notable errors: provider adapters can throw transport, authentication, provider validation, stream, or capability validation errors.

Model Utilities

function isStreamingCompletionModel(model: CompletionModel): model is StreamingCompletionModel;

Purpose: type guard that checks whether a completion model supports streaming.

Return behavior: returns true when the model implements streamCompletion.

Notable errors: none.

Capability Validation

class CompletionCapabilityError extends Error {}

function assertCompletionRequestSupported(
  model: CompletionModel,
  request: CompletionRequest,
  options?: { streaming?: boolean },
): void;

Purpose: validates a normalized request against model.capabilities.

Return behavior: returns void when the request is supported.

Notable errors: throws CompletionCapabilityError for unsupported tools, tool choice, image input, file document input, output schema, or streaming. Static CompletionRequest.documents context and UserContent.documentText(...) are treated as text, not file document input.

Direct Completion Helpers

type CreateCompletionInput = string | Message | Message[];

type CreateCompletionBaseOptions = {
  input?: CreateCompletionInput;
  messages?: Message[];
  instructions?: string;
  documents?: Document[];
  tools?: ToolDefinition[];
  temperature?: number;
  maxTokens?: number;
  toolChoice?: ToolChoice;
  outputSchema?: JsonObject;
  params?: JsonValue;
};

type CreateCompletionOptions = CreateCompletionBaseOptions;
type CreateCompletionStreamOptions = CreateCompletionBaseOptions;
type CreateParsedCompletionOptions<T> =
  Omit<CreateCompletionBaseOptions, "outputSchema"> & {
    schema: ZodSchema<T>;
  };

type CreateCompletionResult<RawResponse = unknown> = {
  text: string;
  content: AssistantContent[];
  usage: Usage;
  response: CompletionResponse<RawResponse>;
};

type CreateParsedCompletionResult<T, RawResponse = unknown> =
  CreateCompletionResult<RawResponse> & {
    data: T;
  };

function createCompletion<Model extends CompletionModel>(
  model: Model,
  options: CreateCompletionOptions,
): Promise<CreateCompletionResult>;

function createCompletionStream<Model extends StreamingCompletionModel>(
  model: Model,
  options: CreateCompletionStreamOptions,
): AsyncIterable<CompletionStreamEvent>;

function createParsedCompletion<T, Model extends CompletionModel>(
  model: Model,
  options: CreateParsedCompletionOptions<T>,
): Promise<CreateParsedCompletionResult<T>>;

Purpose: call a completion model directly without building an agent or executing tools.

Return behavior: createCompletion(...) always returns a promise for the final response. createCompletionStream(...) returns the model’s normalized CompletionStreamEvent iterable directly.

createParsedCompletion(...) converts schema to outputSchema, calls the model once, parses the assistant text as JSON, validates it with the same schema, and returns data plus the normal completion result fields.

messages supplies an existing core message transcript. input accepts a string, one message, or multiple messages and is appended after messages. At least one of input or messages is required.

@anvia/react hooks convert UI message state into core messages before sending requests, so endpoints can pass body.messages directly to createCompletion(...), createCompletionStream(...), or createParsedCompletion(...).

params maps to CompletionRequest.additionalParams for provider-specific options.

Notable errors: createCompletion(...) rejects if input is empty or the request uses unsupported model features. createCompletionStream(...) throws before returning the stream when validation fails or when the model does not support streaming. createParsedCompletion(...) also rejects when the response text is not valid JSON or does not match schema.

Direct completion streams are raw model streams. They can include text deltas, reasoning deltas, tool call deltas, tool calls, message ids, final responses, and errors. They do not execute tools and do not emit agent stream events such as turn_start, tool_result, agent_tool_event, or agent final output. @anvia/react hooks consume these raw completion streams by default.

CompletionRequestBuilder

class CompletionRequestBuilder<M extends CompletionModel = CompletionModel> {
  constructor(model: M, promptMessage: Message);
  modelOverride(model: string | undefined): this;
  instructions(instructions: string | undefined): this;
  messages(messages: Message[]): this;
  documents(documents: Document[]): this;
  tools(tools: ToolDefinition[]): this;
  temperature(temperature: number | undefined): this;
  maxTokens(maxTokens: number | undefined): this;
  toolChoice(toolChoice: ToolChoice | undefined): this;
  additionalParams(additionalParams: JsonValue | undefined): this;
  outputSchema(outputSchema: JsonObject | undefined): this;
  build(): CompletionRequest;
  send(): Promise<CompletionResponse>;
}

Purpose: fluent construction of provider requests.

Return behavior: build() returns a CompletionRequest; send() validates capabilities and calls the configured model.

Notable errors: send() throws CompletionCapabilityError before provider transport when the request uses unsupported features, and otherwise forwards model errors.

Tool Result Serialization

function serializeToolResultOutput(output: unknown): string;

Purpose: serializes tool output to a string, with defensive error handling for non-serializable values.

Return behavior: returns string values unchanged; JSON-stringifies objects and arrays; falls back to String(output) when serialization fails.

Notable errors: none.

Document Helpers

function normalizeDocuments(documents: Document[]): Message | undefined;
function formatDocument(document: Document): string;
function textFromAssistantContent(content: AssistantContent[]): string;
function reasoningDisplayText(content: ReasoningContent[]): string;

Purpose: convert documents and assistant content into text-oriented formats.

Return behavior: normalizeDocuments([]) returns undefined; textFromAssistantContent(...) joins text parts with newlines; reasoningDisplayText(...) joins text and summary reasoning blocks.

Notable errors: none directly.