xsai-sdk

name	xsai-sdk
description	xsAI SDK v0.4.x API reference - extra-small AI SDK with OpenAI-compatible API
globs	["utils/ai-service.ts","hooks/useStreamProcessor.ts","hooks/useAiSummary.ts","hooks/useAiSettings.ts"]

xsAI SDK v0.4.x Quick Reference

xsAI is an extra-small AI SDK with OpenAI-compatible API interface, similar to Vercel AI SDK but much smaller.

Project packages: @xsai/generate-text, @xsai/stream-text, @xsai/model

Core APIs

streamText (sync call, returns StreamTextResult)

import { streamText } from "@xsai/stream-text"

// NOTE: streamText is SYNCHRONOUS (not async) in 0.4.x
const { textStream } = streamText({
  apiKey: "...",
  baseURL: "https://api.openai.com/v1/",
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello" },
  ],
  streamOptions: { includeUsage: true },
})

// textStream is a ReadableStream<string>, supports async iteration
for await (const textPart of textStream) {
  console.log(textPart)
}

Types:

interface StreamTextResult {
  textStream: ReadableStream<string>
  fullStream: ReadableStream<StreamTextEvent>
  reasoningTextStream: ReadableStream<string>
  messages: Promise<Message[]>
  steps: Promise<CompletionStep[]>
  usage: Promise<undefined | Usage>
  totalUsage: Promise<undefined | Usage>
}

interface StreamTextOptions extends ChatOptions {
  maxSteps?: number  // default: 1
  onEvent?: (event: StreamTextEvent) => Promise<unknown> | unknown
  onFinish?: (step?: CompletionStep) => Promise<unknown> | unknown
  onStepFinish?: (step: CompletionStep) => Promise<unknown> | unknown
  streamOptions?: { includeUsage?: boolean }
}

// StreamTextEvent replaces the old StreamTextChunkResult
type StreamTextEvent = /* union of stream event types */

generateText (async call)

import { generateText } from "@xsai/generate-text"

const { text, usage } = await generateText({
  apiKey: "...",
  baseURL: "https://api.openai.com/v1/",
  model: "gpt-4o",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Why is the sky blue?" },
  ],
})

Types:

interface GenerateTextResult {
  text?: string  // NOTE: optional in 0.4.x (was required in 0.2.x)
  usage: Usage
  finishReason: FinishReason
  messages: Message[]
  steps: CompletionStep<true>[]
  toolCalls: CompletionToolCall[]
  toolResults: CompletionToolResult[]
  reasoningText?: string
}

listModels (async call)

import { listModels } from "@xsai/model"

const models = await listModels({
  apiKey: "...",
  baseURL: "https://api.openai.com/v1/",
})
// Returns Model[] with { id, object, created, owned_by }

Shared Types

// From @xsai/shared-chat
interface ChatOptions {
  apiKey?: string
  baseURL: string
  model: string
  messages: Message[]
  // ... other OpenAI-compatible options
}

interface Usage {
  prompt_tokens: number
  completion_tokens: number
  total_tokens: number
}

type Message = SystemMessage | UserMessage | AssistantMessage | ToolMessage | DeveloperMessage

Breaking Changes from 0.2.0-beta.3

Change	0.2.0-beta.3	0.4.x
streamText call	await streamText() (async)	streamText() (sync)
StreamTextResult	{ textStream, chunkStream }	{ textStream, fullStream, usage: Promise, ... }
Usage retrieval	Iterate chunkStream chunks	await result.usage
StreamTextChunkResult	Exists	Removed, replaced by StreamTextEvent
textStream type	Required as unknown as AsyncIterable cast	Native ReadableStream, supports for await and pipeThrough()
generateText result .text	string	string | undefined

Utils

smoothStream (from @xsai/utils-stream)

import { smoothStream } from "@xsai/utils-stream"

const smoothed = textStream.pipeThrough(smoothStream({
  delay: 20,
  chunking: "line",
}))

toAsyncIterator (polyfill for Safari)

import { toAsyncIterator } from "@xsai/utils-stream"

// For browsers that don't support ReadableStream async iteration
const iterableStream = toAsyncIterator(textStream)

Reference Documentation

• references/index.md - Full documentation index with all examples
• references/docs/ - Individual package documentation (27 files with complete code examples)
• references/type-defs/ - Deno Doc type definitions from esm.sh