DOCSEARCHbyAlgolia
Submit Docs

xsAI Documentation

repository·main·Indexed 20 days ago

https://github.com/moeru-ai/xsai

An extra-small, OpenAI-compatible AI SDK designed for runtime portability and minimal footprint. It provides a unified interface for text, object, image, and speech generation, as well as embeddings, supporting Node.js, Bun, Deno, and browser environments. Features include granular packages like @xsai/generate-text and @xsai/stream-text to reduce bundle size, tool calling support via @xsai/tool, and integrations with Composio and the Model Context Protocol (MCP).

Tokens
65.5K
Snippets
209
Records
287
Agent score
70%

What's inside xsAI

  1. What is xsAI and why use it?

    main

    xsAI is a lightweight utility suite for using OpenAI or OpenAI-compatible APIs. It provides an interface similar to the Vercel AI SDK but with a significantly smaller footprint.

    Key Benefits:

    • Small Bundle Size: Reduces installation size by approximately 40x and bundled size by 13x compared to larger alternatives like the Vercel AI SDK.
    • Granular Packages: You can install only the specific functionality you need (e.g., @xsai/generate-text) to achieve even smaller sizes.
    • OpenAI Compatibility: By focusing exclusively on the OpenAI-compatible API standard, xsAI avoids bloat and compatibility issues. This allows you to use providers like Anthropic or Google Gemini, as they both offer OpenAI-compatible endpoints.

  2. Overview of xsAI

    main

    xsAI is a lightweight, unified interface for interacting with various AI capabilities, including text generation, object generation, image generation, speech generation, and embeddings. It is designed to be small and highly portable across different runtimes.

    Key features include:

    • Unified API: A consistent way to interact with different AI models and providers.
    • Small Footprint: Minimal dependencies and a focus on being lightweight.
    • Broad Runtime Support: Works in Node.js, Bun, Deno, and browser environments.
    • Extensible: Supports various providers and response formats through extension packages.

  3. Control tool-use loops with stopWhen

    main

    When using agentic patterns or tool-calling loops, you can use the stopWhen option to prevent infinite loops or to exit the loop based on specific conditions. Common predicates include:

    • stepCountAtLeast(): Stops after a certain number of steps.
    • hasToolCall(): Stops once a tool call has been detected.

  4. Understand the different stream types in streamText()

    main

    The streamText() function exposes multiple streams depending on the level of detail required for your application:

    • textStream: Provides only the text deltas.
    • reasoningTextStream: Provides only the reasoning deltas (useful for models that emit chain-of-thought reasoning).
    • eventStream: Provides normalized xsAI events. Event types include text-delta, reasoning-delta, tool-call, tool-result, and finish.
    • fullStream: Provides the raw, parsed chat completion chunks directly from the provider.

    Note: Always check if your chosen model supports the specific stream type (like reasoning) before implementation.

    import { streamText } from '@xsai/stream-text'
import { env } from 'node:process'

const { eventStream, fullStream } = streamText({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  messages: [{
    content: 'Tell me a short joke.',
    role: 'user',
  }],
  model: 'gpt-4o',
})

for await (const event of eventStream) {
  console.log(event.type)
}

for await (const chunk of fullStream) {
  console.log(chunk.object)
}

  5. Use @xsai-ext/responses for the OpenAI Responses API

    main

    Use the @xsai-ext/responses package if your workflow requires the OpenAI Responses API instead of the standard Chat Completions API.

    Use cases:

    • Handling OpenAI Responses API event streams.
    • Implementing function calling flows built specifically on Responses API semantics.
    • Normalizing input and output shapes around the Responses API.

    Note: Do not use this as a default; only use it if Chat Completions does not satisfy your requirements.

  6. How event streams work in @xsai-ext/responses

    main

    The package provides two distinct event layers for streaming:

    1. fullStream: Provides raw Responses API streaming events. Use this if you require protocol-level fidelity.
    2. eventStream: Provides normalized xsAI events (e.g., text.delta, reasoning.delta, tool-call.start, step.done). Use this for a smaller, implementation-oriented interface.

    Both are available as async iterables.

    import { responses } from '@xsai-ext/responses'
import { env } from 'node:process'

const { eventStream, fullStream } = responses({
  apiKey: env.OPENAI_API_KEY!,
  baseURL: 'https://api.openai.com/v1/',
  input: 'Give me a one sentence answer.',
  model: 'gpt-5.5',
})

for await (const event of eventStream) {
  console.log(event.type)
}

for await (const event of fullStream) {
  console.log(event.type)
}

  7. Transcribe speech with @xsai/generate-transcription or @xsai/stream-transcription

    main

    xsAI provides two distinct patterns for speech-to-text transcription depending on your use case:

    1. Unary Transcription (@xsai/generate-transcription): Use this for batch transcription of complete audio files.
    2. Streaming Transcription (@xsai/stream-transcription): Use this for live audio input or when you require incremental, real-time output.

  8. Understand the shared mental model for xsAI text APIs

    main

    Most text-based APIs in xsAI (such as generateText and streamText) share a common set of configuration options.

    Core options:

    • apiKey: The authentication key for the provider.
    • baseURL: The endpoint URL for the provider.
    • model: The specific model identifier to use.
    • messages: The array of message objects representing the conversation history.
    • fetch (optional): Custom fetch implementation.
    • headers (optional): Custom HTTP headers.
    • abortSignal (optional): An AbortSignal to cancel the request.

    Chat-style options: When using chat-oriented interfaces, you can also provide:

    • temperature: Controls randomness.
    • topP: Nucleus sampling parameter.
    • stop: Stop sequences.
    • seed: For reproducible outputs.
    • toolChoice: Controls how tools are selected (e.g., 'required').
    • tools: Definitions of available tools.
    • stopWhen: Predicates that determine when to stop the execution loop.

  9. When to use xsAI extension packages

    main

    xsAI follows a core-first philosophy. You should prefer the core xsai and @xsai/* packages by default to keep your dependency footprint minimal. Only reach for @xsai-ext/* packages when you require specific capabilities that are not provided by the core path.

    Decision Guide:

    • Smallest setup/footprint: Use core xsai and @xsai/* packages.
    • Specific functionality needed: Use the corresponding @xsai-ext/* package (e.g., for predefined providers, Responses API, or OpenTelemetry).

  10. Use @xsai-ext/providers for OpenAI-compatible vendors

    main

    Use the @xsai-ext/providers package when you want to use predefined provider factories for OpenAI-compatible vendors. This acts as a convenience layer to simplify configuration.

    Use cases:

    • Avoiding repetitive baseURL and apiKey wiring.
    • Creating reusable provider presets.
    • Interacting with OpenAI-compatible vendors through a small helper layer.

    Note: If you prioritize the absolute smallest bundle size, you may prefer to configure providers directly using baseURL and apiKey without this extension.

  11. Available streams from streamObject()

    main

    Since streamObject() is built on streamText(), it returns several stream types in addition to object-specific streams:

    • textStream: Raw JSON text deltas.
    • eventStream: Normalized xsAI events.
    • fullStream: Parsed chat completion chunks from the provider.
    • partialObjectStream: (Object mode) Streams partial updates of the object.
    • elementStream: (Array mode) Streams individual elements of the array.

  12. Use @xsai-ext/telemetry for OpenTelemetry observability

    main

    Use the @xsai-ext/telemetry package when you need to integrate OpenTelemetry (OTEL) into your xsAI operations.

    Use cases:

    • Generating OpenTelemetry spans around xsAI calls.
    • Integrating xsAI operations into telemetry pipelines and observability platforms.

    Note: This is an optional extension. Avoid it if you are optimizing for the smallest possible dependency footprint and do not require observability.