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 };
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 Reasoning = { type: "reasoning"; text: string; id?: string };
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[] };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 Message = SystemMessage | UserMessage | AssistantMessage;
const Message: {
system(content: string): Message;
user(content: string | UserContent[]): Message;
assistant(content: string | AssistantContent[], id?: string): Message;
};Purpose: normalized chat history and prompt shape.
Return behavior: factory methods return message objects with normalized content arrays.
Notable errors: none directly.
UserContent and AssistantContent
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;
toolResult(id: string, content: string | ToolResultContent[], callId?: string): ToolResult;
};
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;
toolCall(id: string, name: string, args: JsonValue, callId?: string): ToolCall;
};Purpose: helper factories for user and assistant content.
Return behavior: returns normalized content values.
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
interface CompletionModel<RawResponse = unknown> {
completion(request: CompletionRequest): Promise<CompletionResponse<RawResponse>>;
}
type CompletionStreamEvent<RawResponse = unknown> =
| { type: "text_delta"; delta: string }
| { type: "reasoning_delta"; delta: string; id?: string }
| { type: "tool_call_delta"; id: string; callId?: string; name?: string; argumentsDelta?: 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.
Return behavior: streaming models yield deltas and finish with a final event.
Notable errors: stream implementations can yield error events or throw from the async iterator.
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() calls the configured model.
Notable errors: send() forwards model errors.
Document Helpers
function normalizeDocuments(documents: Document[]): Message | undefined;
function formatDocument(document: Document): string;
function textFromAssistantContent(content: AssistantContent[]): string;Purpose: convert documents and assistant content into text-oriented formats.
Return behavior: normalizeDocuments([]) returns undefined; textFromAssistantContent(...) joins text parts with newlines.
Notable errors: none directly.