Skip to content

Text API ​

Import these exports from @xsai/text. Create a language model with a wire adapter.

Operations ​

ts
generateText(model: LanguageModel, options: StreamTextOptions): Promise<CollectResult>
streamText(model: LanguageModel, options: StreamTextOptions): ReadableStream<TextEvent>
collect(stream: ReadableStream<TextEvent>): Promise<CollectResult>

streamText runs model requests and executable tools as the consumer reads. It stops when a stop condition applies. Without a consumer, it does not start the model. generateText is collect(streamText(...)). collect consumes the entire stream and rejects when a step fails or the stream is truncated.

Options ​

streamText and generateText take StreamTextOptions, which extends LanguageModelOptions with tool loop options. collect takes only a stream.

FieldDescription
inputRequired. A string, which becomes one user message, or a Message[].
instructionsSystem instructions.
maxOutputTokensThe output token limit. The provider defines the range.
temperature, topPSampling controls. The provider defines the range and the support.
reasoningEffortA string. Common values are none, low, medium, high, xhigh, and max.
serviceTierA string, sent unchanged as service_tier. Common values are auto, default, flex, priority, and standard_only. The endpoint defines which values it accepts.
toolsAn array of tools from tool().
toolChoiceauto, none, required, or { name: string }.
outputFormatA strict schema for structured output.
includeRawEventsIf true, the stream also emits raw events with the provider events.
providerOptionsAdapter-specific options, by namespace.
signalAn AbortSignal.

xsAI sets no default for sampling or token fields. The adapter or the provider supplies them.

A schema is a JSON Schema, or a value that exposes ~standard.jsonSchema.input. If it also exposes ~standard.validate, the loop uses it to validate tool input. A raw JSON Schema has no validator. A Standard Schema without JSON Schema support must go through xsschema first.

Tool loop options ​

FieldDescription
stopWhenA function of the completed steps. Defaults to maxSteps(10).
prepareStepRuns before each request and can override the model, the input, and the request options.
preToolCallRuns before a local tool.
postToolCallRuns after a local tool.

A step is one model request. The loop stops after a failed or cancelled step. It also stops when stopWhen returns true, or when a step has no tool calls and its reason is not pause_turn. Otherwise, it runs the local tools, appends their results as a user message, and sends the next request.

maxSteps(n) stops once at least n steps have run. hasToolCall(name?) stops when the last step has a matching tool call, or any tool call without a name. and, or, and not combine conditions. Details of the hooks are in Control the tool loop.

Result ​

CollectResult is the StepResult of the last step plus steps and an optional totalUsage.

FieldDescription
messageThe assistant message of the step.
statuscompleted, incomplete, or cancelled.
reasonA finish reason: stop, length, tool-calls, content-filter, refusal, or another provider string.
usageOptional Usage for the step.
textThe text Parts of the step, joined. Reasoning and refusals stay in message.content.
toolCallsThe tool calls of the step.
toolResultsThe local tool results that followed the step.
stepsThe results of all steps that did not fail.
totalUsageusage summed over the steps. Absent when no step reports usage.

Usage has inputTokens, outputTokens, and totalTokens, and it can have reasoningTokens, cacheReadInputTokens, and cacheCreationInputTokens. inputTokens counts all input, including cache reads and cache writes, on every wire. cacheReadInputTokens and cacheCreationInputTokens are parts of inputTokens, and reasoningTokens is part of outputTokens. totalTokens is inputTokens + outputTokens.

Messages ​

RoleContent
userA string, or an array of text, image, file, and tool-result Parts.
assistantA string, or an array of text, reasoning, refusal, tool-call, and provider Parts.
system, developerA string, or an array of text Parts.

An assistant message can also have an id and providerMetadata. MessageProviderMetadata and PartProviderMetadata are interfaces that adapters extend.

Parts ​

PartFields
texttext, optional providerMetadata.
audiodata: string, raw base64 audio. format: 'wav' | 'mp3'. User input only.
imagedata: string | URL, optional detail: 'auto' | 'high' | 'low'.
filedata: string | URL.
tool-callarguments: string, callId, id, name.
tool-resultcallId, output, optional isError. output is a string or an array of text and image Parts.
reasoningcontent, an array of { type, text } where type is text, summary, encrypted, or redacted. Optional id and providerMetadata.
refusalrefusal: string.
providersource: string, value: unknown. Holds content that has no shared form.

Tools ​

ts
tool({ name, inputSchema, description?, outputSchema?, execute? })

Without execute, tool() returns a declaration. With execute, it returns an ExecutableTool that the loop can run.

execute(input, { callId, signal }) receives validated input when the schema has a validator. callId identifies the tool invocation and matches its result. The loop always supplies the context. Direct calls can omit it. Without outputSchema, it returns a string or an array of tool-result content. With outputSchema, the handler returns the schema's input type. The tool runs the schema's validator, if available, and converts the result to JSON.

Events ​

See Text events for the event types. TextEventTarget, toCustomEvent, and withEventTarget are covered in Use event listeners.

Errors ​

CodeCause
http-errorAn HTTP error status. Thrown as HttpError.
network-errorfetch rejected.
invalid-inputThe adapter cannot accept the options.
invalid-responseThe provider data is not valid.
truncated-streamThe stream ended without step.end.
model-errorThe adapter reports a model failure.
protocol-errorOne request emitted several terminal events.

A failed step.end rejects collect and generateText. The event stream can close normally after a failed event. If you read events directly, inspect the status of each step.end. A thrown stream error also rejects collect and generateText. Cancel the output stream to stop the run. A cancelled step from the provider is a status and does not throw.

Contributors

Changelog