fastify-x-ai

Vercel AI SDK plugin for unified access to AI providers — text generation, streaming, embeddings, structured output, and tool calling.

fastify-x-ai

A Fastify plugin wrapping the Vercel AI SDK for unified access to OpenAI, Anthropic, and Google AI providers. Exposes text generation, streaming, chat, embeddings, structured output, and tool calling through a single fastify.xai decorator.

Installation

npm install @xenterprises/fastify-x-ai ai

# Install provider SDKs as needed
npm install @ai-sdk/openai    # OpenAI / GPT models
npm install @ai-sdk/anthropic # Anthropic / Claude models
npm install @ai-sdk/google    # Google / Gemini models

Quick Start

import Fastify from "fastify";
import xAI from "@xenterprises/fastify-x-ai";

const fastify = Fastify();

await fastify.register(xAI, {
  defaultProvider: "openai",
  providers: {
    openai: { apiKey: process.env.OPENAI_API_KEY },
  },
});

// Simple completion
const text = await fastify.xai.complete("Write a haiku about coding");

// Chat endpoint
fastify.post("/chat", async (request, reply) => {
  const result = await fastify.xai.chat({ messages: request.body.messages });
  return { text: result.text };
});

Options

Name	Type	Default	Required	Description
`active`	`boolean`	`true`	No	Set `false` to disable the plugin entirely
`defaultProvider`	`string`	`"openai"`	No	Default provider: `openai`, `anthropic`, or `google`
`defaultModel`	`string`	Provider default	No	Default model name (falls back to per-provider defaults)
`defaultMaxTokens`	`number`	`4096`	No	Default max tokens; must be a positive integer
`defaultTemperature`	`number`	`0.7`	No	Default temperature; must be 0–2
`providers`	`object`	`{}`	No	Per-provider config objects
`providers.openai.apiKey`	`string`	`OPENAI_API_KEY`	No	OpenAI API key (falls back to env var)
`providers.openai.baseURL`	`string`	—	No	Custom OpenAI-compatible endpoint
`providers.anthropic.apiKey`	`string`	`ANTHROPIC_API_KEY`	No	Anthropic API key
`providers.google.apiKey`	`string`	`GOOGLE_API_KEY`	No	Google API key

Default Models

Provider	Default Model
`openai`	`gpt-4o`
`anthropic`	`claude-sonnet-4-20250514`
`google`	`gemini-2.0-flash`

Methods

All methods are available on fastify.xai.

generate — Full-control text generation with prompt, messages, tools, and per-call model overrides.
stream — Streaming text generation; returns an async-iterable textStream.
chat — Chat with conversation history; delegates to generate or stream.
complete — Convenience wrapper that returns result.text directly from a prompt string.
createEmbedding — Create single or batch embeddings; includes similarity() helper.
generateStructured — Generate structured output validated against a Zod schema.
getModel / raw — Get a raw model instance; access underlying AI SDK functions via fastify.xai.raw.

Error Reference

Error	Cause
`xAI: Invalid defaultProvider '…'`	`defaultProvider` not one of `openai`, `anthropic`, `google`
`xAI: defaultMaxTokens must be a positive number`	`defaultMaxTokens` ≤ 0 or not a number
`xAI: defaultTemperature must be a number between 0 and 2`	`defaultTemperature` outside 0–2
`xAI: 'ai' package is required`	`ai` peer dependency not installed
`xAI: Provider '…' not configured. Available: …`	Method called with a provider that has no API key
`xAI generate: Either 'prompt' or 'messages' is required`	`generate()` called without input
`xAI stream: Either 'prompt' or 'messages' is required`	`stream()` called without input
`xAI chat: 'messages' is required`	`chat()` called without messages
`xAI complete: 'prompt' is required`	`complete()` called with empty/missing prompt
`xAI createEmbedding: Either 'text' or 'texts' is required`	`createEmbedding()` called without input
`xAI generateStructured: 'prompt' is required`	`generateStructured()` called without prompt
`xAI generateStructured: 'schema' is required`	`generateStructured()` called without schema

Environment Variables

Variable	Required	Description
`OPENAI_API_KEY`	If using OpenAI	Auto-detected if not passed via `providers.openai.apiKey`
`ANTHROPIC_API_KEY`	If using Anthropic	Auto-detected if not passed via `providers.anthropic.apiKey`
`GOOGLE_API_KEY`	If using Google	Auto-detected if not passed via `providers.google.apiKey`

Explicit config in providers takes precedence over environment variables.

How It Works

On registration the plugin validates options, dynamically imports the ai package, then attempts to load each configured provider SDK (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google). A provider is initialized only when its API key is found — either in providers config or the corresponding environment variable; missing SDKs log a warning instead of failing. All public methods resolve the correct model via getModel, validate inputs, and delegate to the underlying AI SDK primitives (generateText, streamText, embed, embedMany). The decorated fastify.xai object is available to every route handler and plugin in scope.

AI Context

package: "@xenterprises/fastify-x-ai"
type: fastify-plugin
use-when: Unified AI text generation, streaming, embeddings, and structured output via Vercel AI SDK — supports OpenAI, Anthropic, Google
decorator: fastify.xai (generate, stream, chat, complete, createEmbedding, generateStructured, getModel, raw)
env: OPENAI_API_KEY, ANTHROPIC_API_KEY (optional), GOOGLE_API_KEY (optional)
defaults: openai/gpt-4o, anthropic/claude-sonnet-4-20250514, google/gemini-2.0-flash
peer-deps: ai, @ai-sdk/openai (and/or @ai-sdk/anthropic, @ai-sdk/google)

Edit this pageorReport an issue

Users Routes

Admin REST endpoints for listing, reading, updating, and deleting user accounts — GET /api/admin/users, GET/PATCH/DELETE /api/admin/users/:id.

chat

Chat with conversation history — delegates to generate() or stream() based on the stream flag.