@nixxie-cms/ai 1.0.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Nixxie International DMCC
+Portions Copyright (c) 2023 Thinkmill Labs Pty Ltd and contributors
+(this software is derived from the KeystoneJS project, https://keystonejs.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @nixxie-cms/ai
+
+LLM text generation and embeddings for Nixxie CMS, with a provider-agnostic interface. Defaults to
+Anthropic's Claude (model `claude-opus-4-8`) via the official `@anthropic-ai/sdk`; OpenAI is also
+supported. SDKs are loaded lazily — install only the provider you use.
+
+```ts
+import { config } from '@nixxie-cms/core'
+import { createAi } from '@nixxie-cms/ai'
+
+export default config({
+  ai: createAi({ provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY! }),
+})
+```
+
+Available everywhere as `context.services.ai`:
+
+```ts
+// One-shot completion — great for generating SEO descriptions, summaries, alt text, etc.
+const { text } = await context.services.ai.complete(
+  `Write a 155-character meta description for: ${post.title}`
+)
+
+// Multi-turn chat
+const reply = await context.services.ai.chat([
+  { role: 'system', content: 'You are a helpful editorial assistant.' },
+  { role: 'user', content: 'Suggest five headline variations for this article.' },
+])
+
+// Embeddings — pair with @nixxie-cms/search for semantic search
+const vector = await context.services.ai.embed(post.body)
+```
+
+## Providers
+
+| provider    | SDK                | embeddings |
+| ----------- | ------------------ | ---------- |
+| `anthropic` | `@anthropic-ai/sdk` | via Voyage AI (`voyageApiKey`) — Anthropic has no native embeddings endpoint |
+| `openai`    | `openai`           | native (`text-embedding-3-small` by default) |
+
+Install the SDK for your chosen provider, e.g. `npm install @anthropic-ai/sdk`.

package/dist/nixxie-cms-ai.cjs.d.ts

@@ -0,0 +1,2 @@
+export * from "../src/index.js";
+//# sourceMappingURL=data:application/json;charset=utf-8;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibml4eGllLWNtcy1haS5janMuZC50cyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3NyYy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSJ9

package/dist/nixxie-cms-ai.cjs.js

@@ -0,0 +1,16 @@
+"use strict";
+// this file might look strange and you might be wondering what it's for
+// it's lets you import your source files by importing this entrypoint
+// as you would import it if it was built with preconstruct build
+// this file is slightly different to some others though
+// it has a require hook which compiles your code with Babel
+// this means that you don't have to set up @babel/register or anything like that
+// but you can still require this module and it'll be compiled
+
+// this bit of code imports the require hook and registers it
+let unregister = require("../../../node_modules/.pnpm/@preconstruct+hook@0.4.0/node_modules/@preconstruct/hook").___internalHook(typeof __dirname === 'undefined' ? undefined : __dirname, "../../..", "..");
+
+// this re-exports the source file
+module.exports = require("../src/index.ts");
+
+unregister();

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nixxie-cms/ai",
+  "version": "1.0.0",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-ai.cjs.js",
+  "module": "dist/nixxie-cms-ai.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-ai.cjs.js",
+      "module": "./dist/nixxie-cms-ai.esm.js",
+      "default": "./dist/nixxie-cms-ai.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@nixxie-cms/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.0"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/sdk": "^0.69.0",
+    "openai": "^6.0.0"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/ai"
+  }
+}

package/src/AnthropicProvider.ts

@@ -0,0 +1,115 @@
+import type {
+  NixxieAiCompleteOptions,
+  NixxieAiCompletion,
+  NixxieAiMessage,
+  NixxieAiService,
+} from '@nixxie-cms/core'
+import type { AiConfig } from './types'
+
+const DEFAULT_MODEL = 'claude-opus-4-8'
+
+function loadAnthropic(): any {
+  try {
+    return require('@anthropic-ai/sdk').default ?? require('@anthropic-ai/sdk')
+  } catch {
+    throw new Error(
+      'The Anthropic provider requires @anthropic-ai/sdk. Run: npm install @anthropic-ai/sdk'
+    )
+  }
+}
+
+/** Anthropic (Claude) provider, backed by the official @anthropic-ai/sdk. */
+export class AnthropicProvider implements NixxieAiService {
+  private config: AiConfig
+  private model: string
+  private maxTokens: number
+  private client: any
+
+  constructor(config: AiConfig) {
+    this.config = config
+    this.model = config.model ?? DEFAULT_MODEL
+    this.maxTokens = config.maxTokens ?? 4096
+    const Anthropic = loadAnthropic()
+    this.client = new Anthropic({ apiKey: config.apiKey, baseURL: config.baseUrl })
+  }
+
+  async complete(prompt: string, options?: NixxieAiCompleteOptions): Promise<NixxieAiCompletion> {
+    return this.chat([{ role: 'user', content: prompt }], options)
+  }
+
+  async chat(
+    messages: NixxieAiMessage[],
+    options?: NixxieAiCompleteOptions
+  ): Promise<NixxieAiCompletion> {
+    // Anthropic takes the system prompt as a top-level field, not a message.
+    const system = [
+      options?.system,
+      ...messages.filter(m => m.role === 'system').map(m => m.content),
+    ]
+      .filter(Boolean)
+      .join('\n\n')
+
+    const turns = messages
+      .filter(m => m.role !== 'system')
+      .map(m => ({ role: m.role as 'user' | 'assistant', content: m.content }))
+
+    const model = options?.model ?? this.model
+    const response = await this.client.messages.create({
+      model,
+      max_tokens: options?.maxTokens ?? this.maxTokens,
+      system: system || undefined,
+      messages: turns,
+      ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+    })
+
+    const text = (response.content ?? [])
+      .filter((block: any) => block.type === 'text')
+      .map((block: any) => block.text)
+      .join('')
+
+    return {
+      text,
+      model: response.model ?? model,
+      usage: {
+        inputTokens: response.usage?.input_tokens,
+        outputTokens: response.usage?.output_tokens,
+      },
+    }
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const [vector] = await this.embedMany([text])
+    if (!vector) throw new Error('Embedding provider returned no vector')
+    return vector
+  }
+
+  async embedMany(texts: string[]): Promise<number[][]> {
+    if (!this.config.voyageApiKey) {
+      throw new Error(
+        'Anthropic has no native embeddings endpoint. Set `voyageApiKey` to generate embeddings via Voyage AI, or use the OpenAI provider.'
+      )
+    }
+    const model = this.config.embeddingModel ?? 'voyage-3'
+    const res = await fetch('https://api.voyageai.com/v1/embeddings', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.config.voyageApiKey}`,
+      },
+      body: JSON.stringify({ input: texts, model }),
+    })
+    if (!res.ok) throw new Error(`Voyage embeddings failed (${res.status}): ${await res.text()}`)
+    const data: any = await res.json()
+    const items = (data.data ?? []) as Array<{ index?: number; embedding: number[] }>
+    if (items.length !== texts.length) {
+      throw new Error(
+        `Voyage returned ${items.length} embeddings for ${texts.length} inputs`
+      )
+    }
+    // The API does not guarantee response order matches input order — sort by `index`.
+    return items
+      .slice()
+      .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+      .map(d => d.embedding)
+  }
+}

package/src/OpenAiProvider.ts

@@ -0,0 +1,86 @@
+import type {
+  NixxieAiCompleteOptions,
+  NixxieAiCompletion,
+  NixxieAiMessage,
+  NixxieAiService,
+} from '@nixxie-cms/core'
+import type { AiConfig } from './types'
+
+const DEFAULT_MODEL = 'gpt-4o'
+const DEFAULT_EMBEDDING_MODEL = 'text-embedding-3-small'
+
+function loadOpenAi(): any {
+  try {
+    return require('openai').default ?? require('openai')
+  } catch {
+    throw new Error('The OpenAI provider requires the openai package. Run: npm install openai')
+  }
+}
+
+/** OpenAI provider, backed by the official openai SDK. */
+export class OpenAiProvider implements NixxieAiService {
+  private config: AiConfig
+  private model: string
+  private maxTokens: number
+  private client: any
+
+  constructor(config: AiConfig) {
+    this.config = config
+    this.model = config.model ?? DEFAULT_MODEL
+    this.maxTokens = config.maxTokens ?? 4096
+    const OpenAI = loadOpenAi()
+    this.client = new OpenAI({ apiKey: config.apiKey, baseURL: config.baseUrl })
+  }
+
+  async complete(prompt: string, options?: NixxieAiCompleteOptions): Promise<NixxieAiCompletion> {
+    return this.chat([{ role: 'user', content: prompt }], options)
+  }
+
+  async chat(
+    messages: NixxieAiMessage[],
+    options?: NixxieAiCompleteOptions
+  ): Promise<NixxieAiCompletion> {
+    const allMessages = options?.system
+      ? [{ role: 'system' as const, content: options.system }, ...messages]
+      : messages
+
+    const model = options?.model ?? this.model
+    const response = await this.client.chat.completions.create({
+      model,
+      max_tokens: options?.maxTokens ?? this.maxTokens,
+      messages: allMessages,
+      ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+    })
+
+    return {
+      text: response.choices?.[0]?.message?.content ?? '',
+      model: response.model ?? model,
+      usage: {
+        inputTokens: response.usage?.prompt_tokens,
+        outputTokens: response.usage?.completion_tokens,
+      },
+    }
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const [vector] = await this.embedMany([text])
+    if (!vector) throw new Error('Embedding provider returned no vector')
+    return vector
+  }
+
+  async embedMany(texts: string[]): Promise<number[][]> {
+    const response = await this.client.embeddings.create({
+      model: this.config.embeddingModel ?? DEFAULT_EMBEDDING_MODEL,
+      input: texts,
+    })
+    const items = (response.data ?? []) as Array<{ index?: number; embedding: number[] }>
+    if (items.length !== texts.length) {
+      throw new Error(`OpenAI returned ${items.length} embeddings for ${texts.length} inputs`)
+    }
+    // The API does not guarantee response order matches input order — sort by `index`.
+    return items
+      .slice()
+      .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+      .map(d => d.embedding)
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import type { NixxieAiService } from '@nixxie-cms/core'
+import { AnthropicProvider } from './AnthropicProvider'
+import { OpenAiProvider } from './OpenAiProvider'
+import type { AiConfig } from './types'
+
+export function createAi(config: AiConfig): NixxieAiService {
+  switch (config.provider ?? 'anthropic') {
+    case 'anthropic':
+      return new AnthropicProvider(config)
+    case 'openai':
+      return new OpenAiProvider(config)
+    default: {
+      const exhaustive: never = config.provider as never
+      throw new Error(`Unknown AI provider: ${exhaustive}`)
+    }
+  }
+}
+
+export { AnthropicProvider, OpenAiProvider }
+export type { AiConfig, AiProvider } from './types'
+export type {
+  NixxieAiService,
+  NixxieAiMessage,
+  NixxieAiCompleteOptions,
+  NixxieAiCompletion,
+} from '@nixxie-cms/core'

package/src/types.ts

@@ -0,0 +1,33 @@
+import type {
+  NixxieAiCompleteOptions,
+  NixxieAiCompletion,
+  NixxieAiMessage,
+  NixxieAiService,
+} from '@nixxie-cms/core'
+
+export type { NixxieAiCompleteOptions, NixxieAiCompletion, NixxieAiMessage, NixxieAiService }
+
+export type AiProvider = 'anthropic' | 'openai'
+
+export type AiConfig = {
+  /** LLM provider. Default: 'anthropic'. */
+  provider?: AiProvider
+  /** API key for the provider. */
+  apiKey: string
+  /**
+   * Default model for completions. Defaults to 'claude-opus-4-8' (Anthropic) or 'gpt-4o' (OpenAI).
+   */
+  model?: string
+  /** Override the API base URL (proxies, gateways, Azure, etc.). */
+  baseUrl?: string
+  /** Default max output tokens. Default: 4096. */
+  maxTokens?: number
+  /**
+   * Model used for `embed`/`embedMany`. Anthropic has no native embeddings endpoint, so for the
+   * Anthropic provider embeddings are produced via Voyage AI (set `voyageApiKey`). Defaults to
+   * 'voyage-3' (Voyage) or 'text-embedding-3-small' (OpenAI).
+   */
+  embeddingModel?: string
+  /** Voyage AI key, used for embeddings when `provider` is 'anthropic'. */
+  voyageApiKey?: string
+}