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

The plugin never reads process.env — pass API keys in explicitly. A provider is configured only when its providers.<name> entry is present, and each entry requires an apiKey. If the matching provider SDK (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google) is not installed, registration logs a warning and that provider is skipped.

Default Models

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

Registration fails fast with actionable Errors:

At call time:

Provider API errors (auth failures, rate limits, etc.) are AI SDK errors and propagate to the caller unchanged — use Fastify's error handling in routes.

Environment Variables

The plugin never reads process.env — the consumer owns env access and passes the values into app.register(xAI, { ... }). These are the conventional variables a consumer sets:

await fastify.register(xAI, {
  providers: {
    openai: { apiKey: process.env.OPENAI_API_KEY }, // the consumer owns env access
  },
});

A provider is configured only when its providers.<name> entry is present — there is no env fallback or auto-detection.

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 providers.<name> entry is present with a valid apiKey — the plugin never reads environment variables; 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, similarity, generateStructured, getModel, raw)
env: consumer-set OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_API_KEY passed via providers.<name>.apiKey — plugin never reads process.env
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)