Xsai

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