Completion
Completion messages, requests, responses, model contracts, usage, and content helpers.
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 };Purpose: provider-safe JSON contracts used by tool arguments, model parameters, schemas, and metadata.
Return behavior: type-only exports.
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; 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 SystemMessage = { role: "system"; content: string };
type UserMessage = { role: "user"; content: UserContent[] };
type AssistantMessage = { role: "assistant"; id?: string; content: AssistantContent[] };
type ToolMessage = { role: "tool"; content: ToolContent[] };
type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage;
const Message: {
system(content: string): Message;
user(content: string | UserContent[]): Message;
assistant(content: string | AssistantContent[], id?: string): Message;
tool(content: ToolContent | ToolContent[]): Message;
toolResult(id: string, output: unknown, options?: { callId?: string | undefined }): Message;
};Purpose: normalized chat history and prompt shape.
Return behavior: factory methods return message objects with normalized content arrays. 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[].
Notable errors: none directly.
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[], callId?: 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 }));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; signature?: string }
| { type: "tool_call"; toolCall: ToolCall }
| { type: "message_id"; id: string }
| { type: "final"; response: CompletionResponse<RawResponse> }
| { type: "error"; error: unknown };
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.
Return behavior: streaming models yield deltas and finish with a final event.
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 transcript. input accepts a string, one message, or multiple messages and is appended after messages. At least one of input or messages is required.
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.
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.