@xenterprises/fastify-x-ai

A Fastify plugin for the Vercel AI SDK providing unified access to AI providers (OpenAI, Anthropic, Google) with text generation, streaming, embeddings, and structured output.

Installation

npm install @xenterprises/fastify-x-ai ai

# Install provider SDKs as needed
npm install @ai-sdk/openai    # For OpenAI/GPT models
npm install @ai-sdk/anthropic # For Anthropic/Claude models
npm install @ai-sdk/google    # For 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 text completion
const text = await fastify.xai.complete("Write a haiku about coding");
console.log(text);

// Chat with conversation history
const result = await fastify.xai.chat({
  messages: [
    { role: "user", content: "What is the capital of France?" },
  ],
  system: "You are a helpful assistant.",
});
console.log(result.text);

Configuration Options

| Option | Type | Default | Required | Description | |--------|------|---------|----------|-------------| | active | boolean | true | No | Enable/disable the plugin | | defaultProvider | string | "openai" | No | Default AI provider (openai, anthropic, google) | | defaultModel | string | Provider default | No | Default model to use | | defaultMaxTokens | number | 4096 | No | Default max tokens (must be positive) | | defaultTemperature | number | 0.7 | No | Default temperature (0–2) | | providers | object | {} | No | Provider configurations (see below) |

Provider Configuration

await fastify.register(xAI, {
  providers: {
    openai: {
      apiKey: process.env.OPENAI_API_KEY,
      baseURL: "https://custom-endpoint.com", // Optional
    },
    anthropic: {
      apiKey: process.env.ANTHROPIC_API_KEY,
    },
    google: {
      apiKey: process.env.GOOGLE_API_KEY,
    },
  },
});

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENAI_API_KEY | If using OpenAI | OpenAI API key (auto-detected if no explicit config) | | ANTHROPIC_API_KEY | If using Anthropic | Anthropic API key (auto-detected if no explicit config) | | GOOGLE_API_KEY | If using Google | Google API key (auto-detected if no explicit config) |

API keys can be provided via environment variables or explicitly in the providers config. Explicit config takes precedence.

Decorated Properties

All methods are available on fastify.xai:

| Property | Type | Description | |----------|------|-------------| | fastify.xai.config | object | Current plugin configuration | | fastify.xai.providers | object | Initialized provider instances | | fastify.xai.generate(params) | function | Generate text with full control | | fastify.xai.stream(params) | function | Stream text generation | | fastify.xai.chat(params) | function | Chat with conversation history | | fastify.xai.complete(prompt, options) | function | Simple text completion | | fastify.xai.createEmbedding(params) | function | Create embeddings | | fastify.xai.similarity(a, b) | function | Calculate cosine similarity | | fastify.xai.generateStructured(params) | function | Generate structured output with schema | | fastify.xai.getModel(provider, model) | function | Get a model instance | | fastify.xai.raw | object | Raw AI SDK functions (generateText, streamText, embed, embedMany, cosineSimilarity) |

API Reference

generate(params)

Generate text with full control over parameters.

const result = await fastify.xai.generate({
  prompt: "Explain quantum computing",
  system: "You are a physics professor.",
  provider: "openai",
  model: "gpt-4o",
  maxTokens: 1000,
  temperature: 0.7,
});

console.log(result.text);
console.log(result.usage);

Returns: { text, content, toolCalls, toolResults, finishReason, usage, totalUsage, steps, response, warnings }

stream(params)

Stream text generation for real-time applications.

const result = await fastify.xai.stream({
  prompt: "Tell me a long story",
  onChunk: ({ chunk }) => console.log(chunk),
  onFinish: ({ text, usage }) => console.log("Done:", text),
  onError: ({ error }) => console.error(error),
});

for await (const text of result.textStream) {
  process.stdout.write(text);
}

chat(params)

Handle conversations with message history.

const result = await fastify.xai.chat({
  messages: [
    { role: "user", content: "What is 2+2?" },
    { role: "assistant", content: "2+2 equals 4." },
    { role: "user", content: "What about 3+3?" },
  ],
  system: "You are a helpful assistant.",
  stream: false, // set to true for streaming
});

complete(prompt, options)

Simple text completion helper.

const text = await fastify.xai.complete("Write a poem about the sea");

const text = await fastify.xai.complete("Summarize this article", {
  provider: "anthropic",
  model: "claude-sonnet-4-20250514",
  maxTokens: 500,
});

createEmbedding(params)

Create embeddings for semantic search and RAG.

// Single embedding
const { embedding } = await fastify.xai.createEmbedding({
  text: "Hello world",
});

// Multiple embeddings
const { embeddings } = await fastify.xai.createEmbedding({
  texts: ["Hello", "World", "Foo", "Bar"],
});

// Calculate similarity
const score = fastify.xai.similarity(embedding1, embedding2);

generateStructured(params)

Generate structured output with a Zod schema.

import { z } from "zod";

const result = await fastify.xai.generateStructured({
  prompt: "Generate a recipe for chocolate cake",
  schema: z.object({
    name: z.string(),
    ingredients: z.array(z.object({
      item: z.string(),
      amount: z.string(),
    })),
    instructions: z.array(z.string()),
  }),
  schemaName: "Recipe",
  schemaDescription: "A cooking recipe",
});

Tool Calling

const result = await fastify.xai.generate({
  prompt: "What's the weather in San Francisco?",
  tools: {
    getWeather: {
      description: "Get weather for a location",
      parameters: z.object({ location: z.string() }),
      execute: async ({ location }) => {
        return { temperature: 72, condition: "sunny" };
      },
    },
  },
  maxSteps: 3,
});

Raw SDK Access

const { generateText, streamText, embed } = fastify.xai.raw;

const result = await generateText({
  model: fastify.xai.getModel("openai", "gpt-4o"),
  prompt: "Hello",
});

Default Models

| Provider | Default Model | |----------|---------------| | OpenAI | gpt-4o | | Anthropic | claude-sonnet-4-20250514 | | Google | gemini-2.0-flash |

Error Reference

| Error | When | |-------|------| | xAI: Invalid defaultProvider '...' | defaultProvider is not openai, anthropic, or google | | xAI: defaultMaxTokens must be a positive number | defaultMaxTokens is not a positive number | | xAI: defaultTemperature must be a number between 0 and 2 | defaultTemperature is outside 0–2 | | xAI: 'ai' package is required | The ai peer dependency is not installed | | xAI: Provider '...' not configured | Calling a method 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 |

How It Works

The plugin dynamically imports the Vercel AI SDK (ai package) and any configured provider SDKs (@ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google) at registration time. Provider availability is determined by checking explicit providers config or environment variables — if a key is found and the SDK is installed, that provider is initialized.

All methods (generate, stream, chat, complete, createEmbedding, generateStructured) are thin wrappers around the AI SDK's generateText, streamText, embed, and embedMany functions. They resolve the model from the provider/model params (falling back to defaults), validate inputs, and forward to the underlying SDK. The raw SDK functions are also exposed via fastify.xai.raw for advanced use cases.

The plugin decorates the Fastify instance with fastify.xai, making all methods available to any route handler or plugin in the same scope.

Testing

npm test

License

UNLICENSED