Text API
Import these exports from @xsai/text. Create a language model with a wire adapter.
Operations
generateText(model: LanguageModel, options: LoopOptions): Promise<CollectResult>
streamText(model: LanguageModel, options: LoopOptions): { result: Promise<CollectResult>, stream: ReadableStream<TextEvent> }
loop(model: LanguageModel, options: LoopOptions): ReadableStream<TextEvent>
collect(stream: ReadableStream<TextEvent>): Promise<CollectResult>loop runs model requests and executable tools until a stop condition applies. generateText is collect(loop(...)). streamText also consumes the model stream when you do not read stream, and you must handle a rejection of result. collect rejects when a step fails or when the stream contains no step.end.
Options
All operations take LanguageModelOptions. The loop operations also take loop options.
| Field | Description |
|---|---|
input | Required. A string, which becomes one user message, or a Message[]. |
instructions | System instructions. |
maxOutputTokens | The output token limit. The provider defines the range. |
temperature, topP | Sampling controls. The provider defines the range and the support. |
reasoningEffort | A string. Common values are none, low, medium, high, xhigh, and max. |
tools | An array of tools from tool(). |
toolChoice | auto, none, required, or { name: string }. |
outputFormat | A strict schema for structured output. |
includeRawEvents | If true, the stream also emits raw events with the provider events. |
providerOptions | Adapter-specific options, by namespace. |
signal | An 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.
Loop options
| Field | Description |
|---|---|
stopWhen | A function of the completed steps. Defaults to maxSteps(10). |
prepareStep | Runs before each request and can override the model, the input, and the request options. |
preToolCall | Runs before a local tool. |
postToolCall | Runs 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.
| Field | Description |
|---|---|
message | The assistant message of the step. |
status | completed, incomplete, or cancelled. |
reason | A finish reason: stop, length, tool-calls, content-filter, refusal, or another provider string. |
usage | Optional Usage for the step. |
text | The text Parts of the step, joined. Reasoning and refusals stay in message.content. |
toolCalls | The tool calls of the step. |
toolResults | The local tool results that followed the step. |
steps | The results of all steps that did not fail. |
totalUsage | usage summed over the steps. Absent when no step reports usage. |
Usage has inputTokens, outputTokens, and totalTokens, and it can have reasoningTokens, cacheReadInputTokens, and cacheCreationInputTokens.
Messages
| Role | Content |
|---|---|
user | A string, or an array of text, image, file, and tool-result Parts. |
assistant | A string, or an array of text, reasoning, refusal, tool-call, and provider Parts. |
system, developer | A 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
| Part | Fields |
|---|---|
text | text, optional providerMetadata. |
image | data: string | URL, optional detail: 'auto' | 'high' | 'low'. |
file | data: string | URL. |
tool-call | arguments: string, callId, id, name. |
tool-result | callId, output, optional isError. output is a string or an array of text and image Parts. |
reasoning | content, an array of { type, text } where type is text, summary, encrypted, or redacted. Optional id and providerMetadata. |
refusal | refusal: string. |
provider | source: string, value: unknown. Holds content that has no shared form. |
Tools
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, { signal }) receives validated input when the schema has a validator. Without outputSchema, it returns a string or an array of tool-result content. With outputSchema, it returns a value of that schema's type, which the tool serializes as JSON. xsAI does not validate the output at runtime.
Events
See Text events for the event types. TextEventTarget, toCustomEvent, and withEventTarget are covered in Use event listeners.
Errors
| Code | Cause |
|---|---|
http-error | An HTTP error status. Thrown as HttpError. |
network-error | fetch rejected. |
invalid-input | The adapter cannot accept the options. |
invalid-response | The provider data is not valid. |
truncated-stream | The stream ended without step.end. |
model-error | The adapter reports a model failure. |
protocol-error | One request emitted several terminal events. |
A failed step.end rejects generateText and the result of streamText. The event stream can still close normally. A thrown stream error rejects result and errors the output stream. Cancelling the output stream rejects result. A cancelled step from the provider is a status and does not throw.
藍+85CD