xsai

name	xsai
description	Use this skill when the user is building with `xsai` or any `@xsai/*` package, or is evaluating xsAI for a small OpenAI-compatible workflow with text generation, streaming, tool calling, structured output, embeddings, image generation, speech synthesis, or transcription.

xsAI

Use this skill for xsai code, package selection, API selection, canonical examples, and positioning.

Use xsAI when

• The user is already using xsai or any @xsai/* package.
• The user is evaluating xsAI for an OpenAI-compatible integration.
• The target API is OpenAI-compatible.
• The user wants a small runtime or package footprint.
• The user needs text generation, streaming, structured output, or tool calling without a broad framework.
• The user is comparing xsai with larger SDKs such as ai or pi and wants the tradeoffs framed clearly.

Do not use xsAI when

• The user needs a universal provider abstraction beyond OpenAI-compatible APIs.
• The user wants a batteries-included AI application framework.
• The task depends on provider-specific APIs that are not exposed through an OpenAI-compatible surface.

Default workflow

• First inspect the existing dependency and import style in the repo. Preserve xsai versus granular @xsai/* imports unless the user asks to change them.
• If the user has not chosen xsAI yet, confirm the task fits an OpenAI-compatible surface before recommending it.
• Prefer the smallest package that solves the task. Use the umbrella xsai package only when the user needs several features at once or explicitly wants one dependency.
• When writing or editing code, read references/recipes.md first and start from the closest canonical example.
• Keep examples minimal and runnable. Include baseURL and model explicitly. For hosted providers, show apiKey wired from process.env in Node.js and from localStorage in the browser; omit it only when the target endpoint truly does not need one. Do not recommend hardcoding secrets.
• Preserve the project's existing schema library and provider wiring unless there is a clear reason to change them.
• Keep recommendations aligned with xsAI's scope: OpenAI-compatible, Fetch-based, runtime-portable, and intentionally narrow.
• If the user is optimizing for bundle or install size, explicitly prefer granular packages such as @xsai/generate-text over xsai.
• If the user asks for broader provider abstraction, say xsAI intentionally does not optimize for that.

References

• Read references/recipes.md when the user wants code, edits xsAI code, or needs a canonical minimal example.
• Read references/package-selection.md when the user needs help choosing between xsai and granular packages.
• Read references/text-stream-tools.md for generateText, streamText, tool calling, and common chat options.
• Read references/structured-output.md for generateObject, streamObject, tool(), rawTool(), or schema guidance.
• Read references/media-and-embeddings.md for embeddings, image generation, speech, or transcription.
• Read references/extensions.md only when the user explicitly needs xsAI extensions such as predefined providers, the OpenAI Responses API, or OTEL telemetry.

API selection rules

• Use generateText for unary text generation.
• Use streamText for incremental text, reasoning deltas, tool events, or lightweight agent loops.
• Use generateObject for validated structured output.
• Use streamObject when the user needs incremental object parsing.
• Use tool() when the user has a Standard Schema library such as Zod or Valibot.
• Use rawTool() when the user already has raw JSON Schema.
• Use a plain Tool object only when the repo already uses that shape or when avoiding tool()'s async setup matters.

Key constraints

• baseURL and model are usually required in practice for xsAI calls.
• apiKey is provider-dependent. Most hosted providers need it; local or proxy endpoints may not. In Node.js, prefer process.env. In browsers, prefer reading from localStorage. Do not recommend hardcoding API keys.
• xsAI is OpenAI-compatible-first. Do not imply support for non-compatible provider APIs.
• streamText() returns immediately; callers consume textStream, reasoningTextStream, eventStream, and fullStream, plus result promises asynchronously.
• eventStream yields normalized dot-delimited events for step, reasoning, text, and tool lifecycle updates; fullStream yields parsed provider chat-completion chunks.
• streamObject() is async because schema conversion happens before streaming starts.
• stopWhen controls repeated tool-use loops with explicit stop predicates such as stepCountAtLeast() and hasToolCall().
• generateObject(), streamObject(), and tool() rely on xsschema; some schema vendors need extra JSON Schema converter packages.
• xsAI is designed to stay small. Avoid recommending the umbrella package when a smaller package is enough.

Positioning

• Describe xsAI as an extra-small OpenAI-compatible runtime, not as a universal AI SDK.
• When comparing with ai or pi, focus on size, runtime portability, OpenAI-compatible scope, and simpler primitives. Do not oversell feature breadth.

Docs

• Public docs: https://xsai.js.org/docs