@xenterprises/fastify-x-ai 1.0.1

package/.gitlab-ci.yml

@@ -0,0 +1,45 @@
+# ============================================================================
+# GitLab CI/CD Pipeline - xAI
+# ============================================================================
+# Runs tests on merge requests and commits to main/master
+
+stages:
+  - test
+
+variables:
+  NODE_ENV: test
+
+# ============================================================================
+# Shared Configuration
+# ============================================================================
+.shared_rules: &shared_rules
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == "main"'
+    - if: '$CI_COMMIT_BRANCH == "master"'
+    - if: '$CI_COMMIT_TAG'
+
+# ============================================================================
+# STAGE: TEST
+# ============================================================================
+test:
+  stage: test
+  image: node:20-alpine
+  <<: *shared_rules
+
+  cache:
+    key: ${CI_COMMIT_REF_SLUG}
+    paths:
+      - node_modules/
+
+  before_script:
+    - npm ci
+
+  script:
+    - echo "Running xAI tests..."
+    - npm test
+    - npm audit --audit-level=high || true
+
+  retry:
+    max: 2
+    when: runner_system_failure

package/README.md

@@ -0,0 +1,357 @@
+# xAI
+
+A Fastify plugin for the [Vercel AI SDK](https://ai-sdk.dev/) providing unified access to AI providers (OpenAI, Anthropic, Google) with text generation, streaming, embeddings, and structured output.
+
+## Features
+
+- **Unified Provider Access** - Single API for OpenAI, Anthropic, Google, and more
+- **Text Generation** - Generate text with `generate()` and `complete()`
+- **Streaming** - Real-time streaming with `stream()`
+- **Chat** - Conversation handling with `chat()`
+- **Embeddings** - Create embeddings for semantic search and RAG
+- **Structured Output** - Generate typed objects with schemas
+- **Tool Calling** - Function/tool execution support
+
+## Installation
+
+```bash
+npm install xai 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
+
+```javascript
+import Fastify from "fastify";
+import xAI from "xai";
+
+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: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "What is the capital of France?" },
+  ],
+});
+console.log(result.text);
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `active` | boolean | `true` | Enable/disable the plugin |
+| `defaultProvider` | string | `"openai"` | Default AI provider |
+| `defaultModel` | string | Provider default | Default model to use |
+| `defaultMaxTokens` | number | `4096` | Default max tokens |
+| `defaultTemperature` | number | `0.7` | Default temperature (0-1) |
+| `providers` | object | `{}` | Provider configurations |
+
+### Provider Configuration
+
+```javascript
+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
+
+You can also configure providers via environment variables:
+- `OPENAI_API_KEY`
+- `ANTHROPIC_API_KEY`
+- `GOOGLE_API_KEY`
+
+## API Reference
+
+### Decorators
+
+| Method | Description |
+|--------|-------------|
+| `fastify.xai.generate(params)` | Generate text with full control |
+| `fastify.xai.stream(params)` | Stream text generation |
+| `fastify.xai.chat(params)` | Chat with conversation history |
+| `fastify.xai.complete(prompt, options)` | Simple text completion |
+| `fastify.xai.createEmbedding(params)` | Create embeddings |
+| `fastify.xai.similarity(a, b)` | Calculate cosine similarity |
+| `fastify.xai.generateStructured(params)` | Generate structured output |
+| `fastify.xai.getModel(provider, model)` | Get model instance |
+| `fastify.xai.raw` | Raw AI SDK functions |
+
+### `generate(params)`
+
+Generate text with full control over parameters.
+
+```javascript
+const result = await fastify.xai.generate({
+  prompt: "Explain quantum computing",
+  // Or use messages for chat-style
+  messages: [
+    { role: "user", content: "Hello!" },
+  ],
+  system: "You are a physics professor.",
+  provider: "openai",        // Optional: override default
+  model: "gpt-4o",           // Optional: specific model
+  maxTokens: 1000,           // Optional: max tokens
+  temperature: 0.7,          // Optional: creativity (0-1)
+  tools: { ... },            // Optional: tool definitions
+  maxSteps: 5,               // Optional: max tool execution steps
+});
+
+console.log(result.text);
+console.log(result.usage);    // Token usage
+console.log(result.toolCalls); // Tool calls made
+```
+
+### `stream(params)`
+
+Stream text generation for real-time applications.
+
+```javascript
+const result = await fastify.xai.stream({
+  prompt: "Tell me a long story",
+  onChunk: ({ chunk }) => {
+    // Handle each chunk
+    console.log(chunk);
+  },
+  onFinish: ({ text, usage }) => {
+    console.log("Done:", text);
+  },
+  onError: ({ error }) => {
+    console.error(error);
+  },
+});
+
+// Iterate over the stream
+for await (const text of result.textStream) {
+  process.stdout.write(text);
+}
+```
+
+### `chat(params)`
+
+Handle conversations with message history.
+
+```javascript
+// Non-streaming chat
+const result = await fastify.xai.chat({
+  messages: [
+    { role: "system", content: "You are a helpful assistant." },
+    { role: "user", content: "What is 2+2?" },
+    { role: "assistant", content: "2+2 equals 4." },
+    { role: "user", content: "What about 3+3?" },
+  ],
+});
+
+// Streaming chat
+const streamResult = await fastify.xai.chat({
+  messages: [...],
+  stream: true,
+});
+```
+
+### `complete(prompt, options)`
+
+Simple text completion helper.
+
+```javascript
+const text = await fastify.xai.complete("Write a poem about the sea");
+
+// With options
+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.
+
+```javascript
+// 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 similarity = fastify.xai.similarity(embedding1, embedding2);
+console.log(`Similarity: ${similarity}`); // -1 to 1
+```
+
+### `generateStructured(params)`
+
+Generate structured output with a Zod schema.
+
+```javascript
+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()),
+    prepTime: z.number(),
+    cookTime: z.number(),
+  }),
+  schemaName: "Recipe",
+  schemaDescription: "A cooking recipe",
+});
+
+console.log(result.output); // Typed recipe object
+```
+
+### Tool Calling
+
+Use tools/functions with AI models.
+
+```javascript
+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 }) => {
+        // Call weather API
+        return { temperature: 72, condition: "sunny" };
+      },
+    },
+  },
+  maxSteps: 3, // Allow up to 3 tool execution steps
+});
+
+console.log(result.text);
+console.log(result.toolCalls);
+console.log(result.toolResults);
+```
+
+### Raw SDK Access
+
+Access the underlying Vercel AI SDK functions directly.
+
+```javascript
+const { generateText, streamText, embed } = fastify.xai.raw;
+
+// Use raw functions for advanced scenarios
+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` |
+
+## Usage in Routes
+
+```javascript
+fastify.post("/chat", async (request, reply) => {
+  const { messages } = request.body;
+
+  const result = await fastify.xai.chat({
+    messages,
+    system: "You are a helpful assistant.",
+  });
+
+  return { response: result.text };
+});
+
+fastify.post("/stream", async (request, reply) => {
+  const { prompt } = request.body;
+
+  const result = await fastify.xai.stream({ prompt });
+
+  reply.header("Content-Type", "text/event-stream");
+  reply.header("Cache-Control", "no-cache");
+
+  for await (const chunk of result.textStream) {
+    reply.raw.write(`data: ${JSON.stringify({ text: chunk })}\n\n`);
+  }
+
+  reply.raw.end();
+});
+
+fastify.post("/search", async (request, reply) => {
+  const { query, documents } = request.body;
+
+  // Create embeddings
+  const { embedding: queryEmbed } = await fastify.xai.createEmbedding({
+    text: query,
+  });
+
+  const { embeddings: docEmbeds } = await fastify.xai.createEmbedding({
+    texts: documents,
+  });
+
+  // Find most similar
+  const similarities = docEmbeds.map((embed, i) => ({
+    document: documents[i],
+    score: fastify.xai.similarity(queryEmbed, embed),
+  }));
+
+  similarities.sort((a, b) => b.score - a.score);
+
+  return { results: similarities.slice(0, 5) };
+});
+```
+
+## Testing
+
+```bash
+npm test
+```
+
+## Resources
+
+- [Vercel AI SDK Documentation](https://ai-sdk.dev/docs/introduction)
+- [AI SDK Core: Generating Text](https://ai-sdk.dev/docs/ai-sdk-core/generating-text)
+- [AI SDK GitHub](https://github.com/vercel/ai)
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@xenterprises/fastify-x-ai",
+  "version": "1.0.1",
+  "description": "Fastify plugin for Vercel AI SDK - unified AI provider access with text generation, streaming, embeddings, and structured output",
+  "type": "module",
+  "main": "src/xAI.js",
+  "exports": {
+    ".": "./src/xAI.js"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "npm": ">=10.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/xAI.test.js",
+    "lint": "eslint src/ test/"
+  },
+  "keywords": [
+    "fastify",
+    "ai",
+    "vercel",
+    "openai",
+    "anthropic",
+    "google",
+    "llm",
+    "chatgpt",
+    "claude",
+    "gemini",
+    "embeddings",
+    "streaming",
+    "text-generation"
+  ],
+  "author": "X Enterprises",
+  "license": "MIT",
+  "dependencies": {
+    "fastify-plugin": "^5.0.1"
+  },
+  "peerDependencies": {
+    "ai": "^4.0.0 || ^5.0.0 || ^6.0.0",
+    "fastify": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/openai": "^1.0.0",
+    "ai": "^4.0.0",
+    "eslint": "^9.0.0",
+    "fastify": "^5.0.0"
+  }
+}

package/src/xAI.js

@@ -0,0 +1,377 @@
+/**
+ * xAI - Vercel AI SDK Integration for Fastify
+ *
+ * A Fastify plugin that wraps the Vercel AI SDK providing:
+ * - Unified model provider access (OpenAI, Anthropic, Google, etc.)
+ * - Text generation (generateText, streamText)
+ * - Structured output generation
+ * - Embeddings for semantic search and RAG
+ * - Tool/function calling support
+ * - Streaming responses for real-time applications
+ *
+ * @see https://ai-sdk.dev/docs/introduction
+ */
+
+import fp from "fastify-plugin";
+
+/**
+ * Default model configurations
+ */
+const DEFAULT_MODELS = {
+  openai: "gpt-4o",
+  anthropic: "claude-sonnet-4-20250514",
+  google: "gemini-2.0-flash",
+};
+
+/**
+ * xAI Plugin
+ *
+ * @param {import('fastify').FastifyInstance} fastify - Fastify instance
+ * @param {Object} options - Plugin options
+ * @param {boolean} [options.active] - Enable/disable the plugin (default: true)
+ * @param {string} [options.defaultProvider] - Default AI provider (openai, anthropic, google)
+ * @param {string} [options.defaultModel] - Default model to use
+ * @param {Object} [options.providers] - Provider configurations
+ * @param {Object} [options.providers.openai] - OpenAI configuration
+ * @param {string} [options.providers.openai.apiKey] - OpenAI API key
+ * @param {string} [options.providers.openai.baseURL] - Custom base URL
+ * @param {Object} [options.providers.anthropic] - Anthropic configuration
+ * @param {string} [options.providers.anthropic.apiKey] - Anthropic API key
+ * @param {Object} [options.providers.google] - Google configuration
+ * @param {string} [options.providers.google.apiKey] - Google API key
+ * @param {number} [options.defaultMaxTokens] - Default max tokens (default: 4096)
+ * @param {number} [options.defaultTemperature] - Default temperature (default: 0.7)
+ */
+async function xAI(fastify, options) {
+  // Check if plugin is disabled
+  if (options.active === false) {
+    console.info("   ⏸️  xAI Disabled");
+    return;
+  }
+
+  // Dynamically import AI SDK
+  let ai;
+  try {
+    ai = await import("ai");
+  } catch {
+    throw new Error("xAI: 'ai' package is required. Install with: npm install ai");
+  }
+
+  const { generateText, streamText, embed, embedMany, cosineSimilarity } = ai;
+
+  // Initialize providers
+  const providers = {};
+  const providerConfigs = options.providers || {};
+
+  // Setup OpenAI provider
+  if (providerConfigs.openai?.apiKey || process.env.OPENAI_API_KEY) {
+    try {
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      providers.openai = createOpenAI({
+        apiKey: providerConfigs.openai?.apiKey || process.env.OPENAI_API_KEY,
+        baseURL: providerConfigs.openai?.baseURL,
+      });
+    } catch {
+      fastify.log.warn("OpenAI provider not available. Install @ai-sdk/openai");
+    }
+  }
+
+  // Setup Anthropic provider
+  if (providerConfigs.anthropic?.apiKey || process.env.ANTHROPIC_API_KEY) {
+    try {
+      const { createAnthropic } = await import("@ai-sdk/anthropic");
+      providers.anthropic = createAnthropic({
+        apiKey: providerConfigs.anthropic?.apiKey || process.env.ANTHROPIC_API_KEY,
+      });
+    } catch {
+      fastify.log.warn("Anthropic provider not available. Install @ai-sdk/anthropic");
+    }
+  }
+
+  // Setup Google provider
+  if (providerConfigs.google?.apiKey || process.env.GOOGLE_API_KEY) {
+    try {
+      const { createGoogleGenerativeAI } = await import("@ai-sdk/google");
+      providers.google = createGoogleGenerativeAI({
+        apiKey: providerConfigs.google?.apiKey || process.env.GOOGLE_API_KEY,
+      });
+    } catch {
+      fastify.log.warn("Google provider not available. Install @ai-sdk/google");
+    }
+  }
+
+  const config = {
+    defaultProvider: options.defaultProvider || "openai",
+    defaultModel: options.defaultModel,
+    defaultMaxTokens: options.defaultMaxTokens || 4096,
+    defaultTemperature: options.defaultTemperature ?? 0.7,
+    providers: Object.keys(providers),
+  };
+
+  /**
+   * Get model instance for a provider
+   * @param {string} [providerName] - Provider name (openai, anthropic, google)
+   * @param {string} [modelName] - Model name
+   * @returns {Object} Model instance
+   */
+  function getModel(providerName, modelName) {
+    const provider = providerName || config.defaultProvider;
+    const model = modelName || config.defaultModel || DEFAULT_MODELS[provider];
+
+    if (!providers[provider]) {
+      throw new Error(`xAI: Provider '${provider}' not configured. Available: ${config.providers.join(", ")}`);
+    }
+
+    return providers[provider](model);
+  }
+
+  /**
+   * Generate text using AI
+   * @param {Object} params - Generation parameters
+   * @param {string} params.prompt - The prompt to generate from
+   * @param {string} [params.system] - System message
+   * @param {Array} [params.messages] - Chat messages array
+   * @param {string} [params.provider] - Provider to use
+   * @param {string} [params.model] - Model to use
+   * @param {number} [params.maxTokens] - Maximum tokens
+   * @param {number} [params.temperature] - Temperature (0-1)
+   * @param {Object} [params.tools] - Tools/functions for the model to use
+   * @param {number} [params.maxSteps] - Max tool execution steps
+   * @param {Object} [params.output] - Structured output schema
+   * @returns {Promise<Object>} Generation result
+   */
+  async function generate(params) {
+    const {
+      prompt,
+      system,
+      messages,
+      provider,
+      model: modelName,
+      maxTokens = config.defaultMaxTokens,
+      temperature = config.defaultTemperature,
+      tools,
+      maxSteps,
+      output,
+      ...rest
+    } = params;
+
+    const model = getModel(provider, modelName);
+
+    const generateParams = {
+      model,
+      maxTokens,
+      temperature,
+      ...rest,
+    };
+
+    if (prompt) generateParams.prompt = prompt;
+    if (system) generateParams.system = system;
+    if (messages) generateParams.messages = messages;
+    if (tools) generateParams.tools = tools;
+    if (maxSteps) generateParams.maxSteps = maxSteps;
+    if (output) generateParams.output = output;
+
+    const result = await generateText(generateParams);
+
+    return {
+      text: result.text,
+      content: result.content,
+      toolCalls: result.toolCalls,
+      toolResults: result.toolResults,
+      finishReason: result.finishReason,
+      usage: result.usage,
+      totalUsage: result.totalUsage,
+      steps: result.steps,
+      response: result.response,
+      warnings: result.warnings,
+    };
+  }
+
+  /**
+   * Stream text using AI
+   * @param {Object} params - Generation parameters (same as generate)
+   * @returns {Promise<Object>} Stream result with textStream and helpers
+   */
+  async function stream(params) {
+    const {
+      prompt,
+      system,
+      messages,
+      provider,
+      model: modelName,
+      maxTokens = config.defaultMaxTokens,
+      temperature = config.defaultTemperature,
+      tools,
+      maxSteps,
+      onChunk,
+      onFinish,
+      onError,
+      ...rest
+    } = params;
+
+    const model = getModel(provider, modelName);
+
+    const streamParams = {
+      model,
+      maxTokens,
+      temperature,
+      ...rest,
+    };
+
+    if (prompt) streamParams.prompt = prompt;
+    if (system) streamParams.system = system;
+    if (messages) streamParams.messages = messages;
+    if (tools) streamParams.tools = tools;
+    if (maxSteps) streamParams.maxSteps = maxSteps;
+    if (onChunk) streamParams.onChunk = onChunk;
+    if (onFinish) streamParams.onFinish = onFinish;
+    if (onError) streamParams.onError = onError;
+
+    return streamText(streamParams);
+  }
+
+  /**
+   * Generate embeddings for text
+   * @param {Object} params - Embedding parameters
+   * @param {string} params.text - Single text to embed
+   * @param {string[]} [params.texts] - Multiple texts to embed
+   * @param {string} [params.provider] - Provider to use
+   * @param {string} [params.model] - Embedding model
+   * @returns {Promise<Object>} Embedding result
+   */
+  async function createEmbedding(params) {
+    const { text, texts, provider, model: modelName } = params;
+
+    // Default embedding models
+    const embeddingModels = {
+      openai: "text-embedding-3-small",
+      google: "text-embedding-004",
+    };
+
+    const providerName = provider || config.defaultProvider;
+    const model = getModel(providerName, modelName || embeddingModels[providerName]);
+
+    if (texts && texts.length > 0) {
+      const result = await embedMany({
+        model,
+        values: texts,
+      });
+      return {
+        embeddings: result.embeddings,
+        usage: result.usage,
+      };
+    }
+
+    const result = await embed({
+      model,
+      value: text,
+    });
+
+    return {
+      embedding: result.embedding,
+      usage: result.usage,
+    };
+  }
+
+  /**
+   * Calculate cosine similarity between two embeddings
+   * @param {number[]} a - First embedding
+   * @param {number[]} b - Second embedding
+   * @returns {number} Similarity score (-1 to 1)
+   */
+  function similarity(a, b) {
+    return cosineSimilarity(a, b);
+  }
+
+  /**
+   * Chat completion with conversation history
+   * @param {Object} params - Chat parameters
+   * @param {Array<{role: string, content: string}>} params.messages - Conversation messages
+   * @param {string} [params.system] - System message
+   * @param {string} [params.provider] - Provider to use
+   * @param {string} [params.model] - Model to use
+   * @param {boolean} [params.stream] - Whether to stream the response
+   * @returns {Promise<Object>} Chat result
+   */
+  async function chat(params) {
+    const { messages, system, stream: shouldStream = false, ...rest } = params;
+
+    if (shouldStream) {
+      return stream({ messages, system, ...rest });
+    }
+
+    return generate({ messages, system, ...rest });
+  }
+
+  /**
+   * Simple text completion
+   * @param {string} prompt - The prompt
+   * @param {Object} [options] - Additional options
+   * @returns {Promise<string>} Generated text
+   */
+  async function complete(prompt, options = {}) {
+    const result = await generate({ prompt, ...options });
+    return result.text;
+  }
+
+  /**
+   * Generate structured output using a schema
+   * @param {Object} params - Generation parameters
+   * @param {string} params.prompt - The prompt
+   * @param {Object} params.schema - Zod schema for output
+   * @param {string} [params.schemaName] - Name for the schema
+   * @param {string} [params.schemaDescription] - Description for the schema
+   * @returns {Promise<Object>} Structured output
+   */
+  async function generateStructured(params) {
+    const { prompt, schema, schemaName, schemaDescription, ...rest } = params;
+
+    // Import Output helper from ai package
+    const { Output } = await import("ai");
+
+    const result = await generate({
+      prompt,
+      output: Output.object({
+        schema,
+        name: schemaName,
+        description: schemaDescription,
+      }),
+      ...rest,
+    });
+
+    return result;
+  }
+
+  // Store configuration and methods
+  fastify.decorate("xai", {
+    config,
+    providers,
+    getModel,
+    generate,
+    stream,
+    chat,
+    complete,
+    createEmbedding,
+    similarity,
+    generateStructured,
+    // Re-export raw AI SDK functions for advanced use
+    raw: {
+      generateText,
+      streamText,
+      embed,
+      embedMany,
+      cosineSimilarity,
+    },
+  });
+
+  const enabledProviders = config.providers.length > 0 ? config.providers.join(", ") : "none";
+  console.info("   ✅ xAI Vercel AI SDK Enabled");
+  console.info(`      • Default Provider: ${config.defaultProvider}`);
+  console.info(`      • Enabled Providers: ${enabledProviders}`);
+}
+
+export default fp(xAI, {
+  name: "xAI",
+});
+
+export { DEFAULT_MODELS };

package/test/xAI.test.js

@@ -0,0 +1,280 @@
+/**
+ * xAI Tests
+ *
+ * Tests for the xAI Fastify plugin (Vercel AI SDK integration)
+ * Note: These are unit tests that don't require actual API calls
+ */
+
+import { describe, test, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import Fastify from "fastify";
+import xAI, { DEFAULT_MODELS } from "../src/xAI.js";
+
+describe("xAI Plugin", () => {
+  let fastify;
+
+  beforeEach(() => {
+    fastify = Fastify({ logger: { level: "silent" } });
+  });
+
+  afterEach(async () => {
+    await fastify.close();
+  });
+
+  describe("Plugin Registration", () => {
+    test("should skip registration when active is false", async () => {
+      await fastify.register(xAI, { active: false });
+      await fastify.ready();
+
+      assert.ok(!fastify.xai, "xai should not exist");
+    });
+
+    test("should register with OpenAI provider from env", async () => {
+      // Set env var temporarily
+      const originalKey = process.env.OPENAI_API_KEY;
+      process.env.OPENAI_API_KEY = "test-key-12345";
+
+      try {
+        await fastify.register(xAI, {});
+        await fastify.ready();
+
+        assert.ok(fastify.xai, "xai should exist");
+        assert.ok(fastify.xai.config, "xai.config should exist");
+        assert.ok(fastify.xai.generate, "xai.generate should exist");
+        assert.ok(fastify.xai.stream, "xai.stream should exist");
+        assert.ok(fastify.xai.chat, "xai.chat should exist");
+        assert.ok(fastify.xai.complete, "xai.complete should exist");
+        assert.ok(fastify.xai.createEmbedding, "xai.createEmbedding should exist");
+        assert.ok(fastify.xai.similarity, "xai.similarity should exist");
+        assert.ok(fastify.xai.generateStructured, "xai.generateStructured should exist");
+        assert.ok(fastify.xai.getModel, "xai.getModel should exist");
+        assert.ok(fastify.xai.raw, "xai.raw should exist");
+      } finally {
+        if (originalKey) {
+          process.env.OPENAI_API_KEY = originalKey;
+        } else {
+          delete process.env.OPENAI_API_KEY;
+        }
+      }
+    });
+
+    test("should register with explicit provider config", async () => {
+      await fastify.register(xAI, {
+        providers: {
+          openai: { apiKey: "test-api-key" },
+        },
+      });
+      await fastify.ready();
+
+      assert.ok(fastify.xai, "xai should exist");
+      assert.ok(fastify.xai.config.providers.includes("openai"), "openai should be in providers");
+    });
+
+    test("should store default configuration", async () => {
+      await fastify.register(xAI, {
+        defaultProvider: "openai",
+        defaultMaxTokens: 2048,
+        defaultTemperature: 0.5,
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      assert.strictEqual(fastify.xai.config.defaultProvider, "openai");
+      assert.strictEqual(fastify.xai.config.defaultMaxTokens, 2048);
+      assert.strictEqual(fastify.xai.config.defaultTemperature, 0.5);
+    });
+
+    test("should use default values when not specified", async () => {
+      await fastify.register(xAI, {
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      assert.strictEqual(fastify.xai.config.defaultProvider, "openai");
+      assert.strictEqual(fastify.xai.config.defaultMaxTokens, 4096);
+      assert.strictEqual(fastify.xai.config.defaultTemperature, 0.7);
+    });
+  });
+
+  describe("Model Selection", () => {
+    test("should get model for configured provider", async () => {
+      await fastify.register(xAI, {
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      const model = fastify.xai.getModel("openai", "gpt-4o");
+      assert.ok(model, "model should exist");
+    });
+
+    test("should throw for unconfigured provider", async () => {
+      await fastify.register(xAI, {
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      assert.throws(() => {
+        fastify.xai.getModel("anthropic", "claude-3");
+      }, /Provider 'anthropic' not configured/);
+    });
+
+    test("should use default provider when not specified", async () => {
+      await fastify.register(xAI, {
+        defaultProvider: "openai",
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      // Should not throw when provider not specified
+      const model = fastify.xai.getModel();
+      assert.ok(model, "model should exist");
+    });
+  });
+
+  describe("Raw SDK Access", () => {
+    test("should expose raw AI SDK functions", async () => {
+      await fastify.register(xAI, {
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      assert.ok(fastify.xai.raw, "raw should exist");
+      assert.ok(fastify.xai.raw.generateText, "generateText should exist");
+      assert.ok(fastify.xai.raw.streamText, "streamText should exist");
+      assert.ok(fastify.xai.raw.embed, "embed should exist");
+      assert.ok(fastify.xai.raw.embedMany, "embedMany should exist");
+      assert.ok(fastify.xai.raw.cosineSimilarity, "cosineSimilarity should exist");
+    });
+  });
+
+  describe("Similarity Function", () => {
+    test("should calculate cosine similarity", async () => {
+      await fastify.register(xAI, {
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      // Test with identical vectors - should be 1
+      const sim1 = fastify.xai.similarity([1, 0, 0], [1, 0, 0]);
+      assert.ok(Math.abs(sim1 - 1) < 0.001, "identical vectors should have similarity ~1");
+
+      // Test with orthogonal vectors - should be 0
+      const sim2 = fastify.xai.similarity([1, 0], [0, 1]);
+      assert.ok(Math.abs(sim2) < 0.001, "orthogonal vectors should have similarity ~0");
+
+      // Test with opposite vectors - should be -1
+      const sim3 = fastify.xai.similarity([1, 0], [-1, 0]);
+      assert.ok(Math.abs(sim3 + 1) < 0.001, "opposite vectors should have similarity ~-1");
+    });
+  });
+
+  describe("Provider Configuration", () => {
+    test("should list enabled providers", async () => {
+      await fastify.register(xAI, {
+        providers: {
+          openai: { apiKey: "test-key" },
+        },
+      });
+      await fastify.ready();
+
+      assert.ok(Array.isArray(fastify.xai.config.providers));
+      assert.ok(fastify.xai.config.providers.includes("openai"));
+    });
+
+    test("should have empty providers when none configured", async () => {
+      // Clear any env vars
+      const originalOpenAI = process.env.OPENAI_API_KEY;
+      const originalAnthropic = process.env.ANTHROPIC_API_KEY;
+      const originalGoogle = process.env.GOOGLE_API_KEY;
+
+      delete process.env.OPENAI_API_KEY;
+      delete process.env.ANTHROPIC_API_KEY;
+      delete process.env.GOOGLE_API_KEY;
+
+      try {
+        await fastify.register(xAI, {});
+        await fastify.ready();
+
+        assert.ok(Array.isArray(fastify.xai.config.providers));
+        assert.strictEqual(fastify.xai.config.providers.length, 0);
+      } finally {
+        if (originalOpenAI) process.env.OPENAI_API_KEY = originalOpenAI;
+        if (originalAnthropic) process.env.ANTHROPIC_API_KEY = originalAnthropic;
+        if (originalGoogle) process.env.GOOGLE_API_KEY = originalGoogle;
+      }
+    });
+  });
+});
+
+describe("Exports", () => {
+  test("should export DEFAULT_MODELS", () => {
+    assert.ok(DEFAULT_MODELS, "DEFAULT_MODELS should exist");
+    assert.strictEqual(DEFAULT_MODELS.openai, "gpt-4o");
+    assert.strictEqual(DEFAULT_MODELS.anthropic, "claude-sonnet-4-20250514");
+    assert.strictEqual(DEFAULT_MODELS.google, "gemini-2.0-flash");
+  });
+});
+
+describe("Method Signatures", () => {
+  let fastify;
+
+  beforeEach(async () => {
+    fastify = Fastify({ logger: { level: "silent" } });
+    await fastify.register(xAI, {
+      providers: {
+        openai: { apiKey: "test-key" },
+      },
+    });
+    await fastify.ready();
+  });
+
+  afterEach(async () => {
+    await fastify.close();
+  });
+
+  test("generate should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.generate, "function");
+  });
+
+  test("stream should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.stream, "function");
+  });
+
+  test("chat should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.chat, "function");
+  });
+
+  test("complete should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.complete, "function");
+  });
+
+  test("createEmbedding should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.createEmbedding, "function");
+  });
+
+  test("similarity should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.similarity, "function");
+  });
+
+  test("generateStructured should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.generateStructured, "function");
+  });
+
+  test("getModel should be a function", () => {
+    assert.strictEqual(typeof fastify.xai.getModel, "function");
+  });
+});