@nixxie-cms/ai-rag 1.0.0

package/src/graphql.ts

@@ -0,0 +1,196 @@
+import { g } from '@nixxie-cms/core'
+import type {
+  NixxieAiRagService,
+  NixxieContext,
+  NixxieRagAnswer,
+  NixxieRagChunk,
+  NixxieRagCitation,
+  NixxieRagDocument,
+  NixxieRagIndexStats,
+} from '@nixxie-cms/core'
+
+/** How the GraphQL resolvers obtain the service (defaults to `context.services.aiRag`). */
+export type RagGraphqlOptions = {
+  /** Override the service lookup. By default reads `context.services.aiRag`. */
+  getService?: (context: NixxieContext) => NixxieAiRagService | null | undefined
+  /**
+   * Gate the mutating operations (ingest/remove/reindex). Returning false rejects the call.
+   * Reads (`ragAsk`, `ragRetrieve`) are always allowed — guard them with collection access if needed.
+   * @default requires a session
+   */
+  isAuthorized?: (context: NixxieContext) => boolean | Promise<boolean>
+}
+
+function serviceFrom(
+  context: NixxieContext,
+  options: RagGraphqlOptions
+): NixxieAiRagService {
+  const svc = (options.getService ?? (c => c.services.aiRag))(context)
+  if (!svc) {
+    throw new Error(
+      '[@nixxie-cms/ai-rag] No aiRag service is configured. Pass it to `config({ aiRag })` or `ragPlugin({ service })`.'
+    )
+  }
+  return svc
+}
+
+async function assertAuthorized(context: NixxieContext, options: RagGraphqlOptions): Promise<void> {
+  const check = options.isAuthorized ?? ((c: NixxieContext) => !!c.session)
+  if (!(await check(context))) {
+    throw new Error('[@nixxie-cms/ai-rag] Not authorized.')
+  }
+}
+
+/**
+ * Build the `extendGraphqlSchema` function that adds the assistant's queries and mutations:
+ *
+ * - `ragAsk(question, topK?, tags?)` → grounded answer with citations
+ * - `ragRetrieve(query, topK?, tags?)` → raw retrieved chunks
+ * - `ragAddDocument(...)` / `ragRemoveDocument(id)` / `ragReindex(force?)`
+ *
+ * `ragPlugin()` wires this automatically; use it directly only if you compose the schema yourself.
+ */
+export function ragGraphqlExtension(options: RagGraphqlOptions = {}) {
+  return g.extend(() => {
+    const Citation = g.object<NixxieRagCitation>()({
+      name: 'RagCitation',
+      fields: {
+        documentId: g.field({ type: g.nonNull(g.String), resolve: s => s.documentId }),
+        chunkId: g.field({ type: g.nonNull(g.String), resolve: s => s.chunkId }),
+        title: g.field({ type: g.String, resolve: s => s.title ?? null }),
+        source: g.field({ type: g.String, resolve: s => s.source ?? null }),
+        score: g.field({ type: g.nonNull(g.Float), resolve: s => s.score }),
+        snippet: g.field({ type: g.nonNull(g.String), resolve: s => s.snippet }),
+      },
+    })
+
+    const Chunk = g.object<NixxieRagChunk>()({
+      name: 'RagChunk',
+      fields: {
+        id: g.field({ type: g.nonNull(g.String), resolve: s => s.id }),
+        documentId: g.field({ type: g.nonNull(g.String), resolve: s => s.documentId }),
+        title: g.field({ type: g.String, resolve: s => s.title ?? null }),
+        source: g.field({ type: g.String, resolve: s => s.source ?? null }),
+        content: g.field({ type: g.nonNull(g.String), resolve: s => s.content }),
+        score: g.field({ type: g.nonNull(g.Float), resolve: s => s.score }),
+      },
+    })
+
+    const Answer = g.object<NixxieRagAnswer>()({
+      name: 'RagAnswer',
+      fields: {
+        text: g.field({ type: g.nonNull(g.String), resolve: s => s.text }),
+        grounded: g.field({ type: g.nonNull(g.Boolean), resolve: s => s.grounded }),
+        refused: g.field({ type: g.nonNull(g.Boolean), resolve: s => s.refused }),
+        model: g.field({ type: g.nonNull(g.String), resolve: s => s.model }),
+        sources: g.field({
+          type: g.nonNull(g.list(g.nonNull(Citation))),
+          resolve: s => s.sources,
+        }),
+      },
+    })
+
+    const Document = g.object<NixxieRagDocument>()({
+      name: 'RagDocument',
+      fields: {
+        id: g.field({ type: g.nonNull(g.String), resolve: s => s.id }),
+        title: g.field({ type: g.String, resolve: s => s.title ?? null }),
+        content: g.field({ type: g.nonNull(g.String), resolve: s => s.content }),
+        source: g.field({ type: g.String, resolve: s => s.source ?? null }),
+        tags: g.field({
+          type: g.list(g.nonNull(g.String)),
+          resolve: s => s.tags ?? null,
+        }),
+        status: g.field({ type: g.nonNull(g.String), resolve: s => s.status }),
+        chunkCount: g.field({ type: g.nonNull(g.Int), resolve: s => s.chunkCount }),
+        error: g.field({ type: g.String, resolve: s => s.error ?? null }),
+        indexedAt: g.field({
+          type: g.String,
+          resolve: s => s.indexedAt?.toISOString() ?? null,
+        }),
+        createdAt: g.field({
+          type: g.nonNull(g.String),
+          resolve: s => s.createdAt.toISOString(),
+        }),
+      },
+    })
+
+    const IndexStats = g.object<NixxieRagIndexStats>()({
+      name: 'RagIndexStats',
+      fields: {
+        documents: g.field({ type: g.nonNull(g.Int), resolve: s => s.documents }),
+        chunks: g.field({ type: g.nonNull(g.Int), resolve: s => s.chunks }),
+        errors: g.field({ type: g.nonNull(g.Int), resolve: s => s.errors }),
+        durationMs: g.field({ type: g.nonNull(g.Int), resolve: s => s.durationMs }),
+      },
+    })
+
+    return {
+      query: {
+        ragAsk: g.field({
+          type: g.nonNull(Answer),
+          args: {
+            question: g.arg({ type: g.nonNull(g.String) }),
+            topK: g.arg({ type: g.Int }),
+            tags: g.arg({ type: g.list(g.nonNull(g.String)) }),
+          },
+          resolve: async (_s, args, context) =>
+            serviceFrom(context, options).ask(args.question, {
+              topK: args.topK ?? undefined,
+              tags: (args.tags ?? undefined) as string[] | undefined,
+            }),
+        }),
+        ragRetrieve: g.field({
+          type: g.nonNull(g.list(g.nonNull(Chunk))),
+          args: {
+            query: g.arg({ type: g.nonNull(g.String) }),
+            topK: g.arg({ type: g.Int }),
+            tags: g.arg({ type: g.list(g.nonNull(g.String)) }),
+          },
+          resolve: async (_s, args, context) =>
+            serviceFrom(context, options).retrieve(args.query, {
+              topK: args.topK ?? undefined,
+              tags: (args.tags ?? undefined) as string[] | undefined,
+            }),
+        }),
+      },
+      mutation: {
+        ragAddDocument: g.field({
+          type: g.nonNull(Document),
+          args: {
+            content: g.arg({ type: g.nonNull(g.String) }),
+            title: g.arg({ type: g.String }),
+            source: g.arg({ type: g.String }),
+            tags: g.arg({ type: g.list(g.nonNull(g.String)) }),
+          },
+          resolve: async (_s, args, context) => {
+            await assertAuthorized(context, options)
+            return serviceFrom(context, options).addDocument({
+              content: args.content,
+              title: args.title ?? undefined,
+              source: args.source ?? undefined,
+              tags: (args.tags ?? undefined) as string[] | undefined,
+            })
+          },
+        }),
+        ragRemoveDocument: g.field({
+          type: g.nonNull(g.Boolean),
+          args: { id: g.arg({ type: g.nonNull(g.String) }) },
+          resolve: async (_s, args, context) => {
+            await assertAuthorized(context, options)
+            await serviceFrom(context, options).removeDocument(args.id)
+            return true
+          },
+        }),
+        ragReindex: g.field({
+          type: g.nonNull(IndexStats),
+          args: { force: g.arg({ type: g.Boolean }) },
+          resolve: async (_s, args, context) => {
+            await assertAuthorized(context, options)
+            return serviceFrom(context, options).reindex({ force: args.force ?? false })
+          },
+        }),
+      },
+    }
+  })
+}

package/src/guard.ts

@@ -0,0 +1,75 @@
+import type { NixxieRagChunk } from '@nixxie-cms/core'
+import type { GenerationProvider } from './providers/types'
+import type { RagGuardConfig } from './types'
+
+export const DEFAULT_REFUSAL =
+  "I don't have enough information in my knowledge base to answer that."
+
+/** Resolve guard config against defaults. */
+export function resolveGuard(config: RagGuardConfig = {}) {
+  const enabled = config.enabled ?? true
+  return {
+    enabled,
+    refuseWhenNoContext: enabled && (config.refuseWhenNoContext ?? true),
+    refusal: config.refusal ?? DEFAULT_REFUSAL,
+    requireCitations: enabled && (config.requireCitations ?? true),
+    groundingCheck: enabled && (config.groundingCheck ?? false),
+    groundingModel: config.groundingModel,
+    refuseWhenUngrounded: config.refuseWhenUngrounded ?? true,
+    allowModelKnowledge: config.allowModelKnowledge ?? false,
+  }
+}
+
+export type ResolvedGuard = ReturnType<typeof resolveGuard>
+
+/**
+ * Decide whether retrieval found enough relevant context to answer. When nothing clears the
+ * relevance bar and `refuseWhenNoContext` is on (and model knowledge isn't allowed), the
+ * assistant should refuse instead of guessing.
+ */
+export function shouldRefuseForNoContext(
+  chunks: NixxieRagChunk[],
+  guard: ResolvedGuard,
+  minScore: number
+): boolean {
+  if (!guard.refuseWhenNoContext || guard.allowModelKnowledge) return false
+  const best = chunks[0]?.score ?? 0
+  return chunks.length === 0 || best < minScore
+}
+
+/**
+ * Post-hoc grounding check: ask a (cheap) model whether the drafted answer is fully
+ * supported by the retrieved context. Returns whether it's grounded plus an optional reason.
+ * Best-effort — any failure is treated as "grounded" so the guard never hard-fails a request.
+ */
+export async function checkGrounding(
+  provider: GenerationProvider,
+  answer: string,
+  chunks: NixxieRagChunk[],
+  model: string | undefined
+): Promise<{ grounded: boolean; reason?: string }> {
+  if (!answer.trim() || chunks.length === 0) return { grounded: true }
+  const context = chunks
+    .map((c, i) => `[${i + 1}] ${c.content}`)
+    .join('\n\n')
+    .slice(0, 8000)
+
+  const system =
+    'You are a strict fact-checker. Decide if the ANSWER is fully supported by the CONTEXT. ' +
+    'Reply with a single JSON object: {"grounded": boolean, "reason": string}. ' +
+    'An answer that adds facts not present in the context is NOT grounded. A refusal or ' +
+    '"I don\'t know" counts as grounded.'
+
+  try {
+    const res = await provider.generate(
+      [{ role: 'user', content: `CONTEXT:\n${context}\n\nANSWER:\n${answer}` }],
+      { system, model, temperature: 0, maxTokens: 200 }
+    )
+    const match = res.text.match(/\{[\s\S]*\}/)
+    if (!match) return { grounded: true }
+    const parsed = JSON.parse(match[0]) as { grounded?: boolean; reason?: string }
+    return { grounded: parsed.grounded !== false, reason: parsed.reason }
+  } catch {
+    return { grounded: true }
+  }
+}

package/src/index.ts

@@ -0,0 +1,102 @@
+import { AiRagService } from './AiRagService'
+import type { AiRagConfig } from './types'
+
+/**
+ * Create a custom, RAG-trained assistant backed by a knowledge-base collection.
+ *
+ * Register it with `ragPlugin()` so the knowledge-base collections, HTTP + GraphQL surfaces
+ * and scheduled indexing are wired automatically:
+ *
+ * @example
+ * import { createAiRag, ragPlugin } from '@nixxie-cms/ai-rag'
+ * const aiRag = createAiRag({
+ *   generation: { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY! },
+ *   embedding: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+ *   retrieval: { topK: 6, minScore: 0.25 },
+ *   guard: { groundingCheck: true },
+ *   indexing: { schedule: '0 3 * * *' },
+ * })
+ * export default config({ db: { ... }, plugins: [ragPlugin({ service: aiRag })] })
+ *
+ * Then anywhere you have context:
+ *   await context.services.aiRag!.addDocument({ title, content })
+ *   const answer = await context.services.aiRag!.ask('How do refunds work?')
+ */
+export function createAiRag(config: AiRagConfig = {}): AiRagService {
+  return new AiRagService(config)
+}
+
+export { AiRagService } from './AiRagService'
+
+// Plugin + surfaces
+export { ragPlugin, type RagPluginOptions } from './plugin'
+export { installAiRagRoutes, type AiRagRoutesOptions } from './express'
+export { ragGraphqlExtension, type RagGraphqlOptions } from './graphql'
+export { ragAdminPage, type RagAdminPageOptions } from './admin-page'
+
+// Collections
+export { knowledgeBaseCollection, knowledgeChunkCollection } from './collection'
+
+// Providers (advanced / custom wiring)
+export {
+  resolveGenerationProvider,
+  resolveEmbeddingProvider,
+  AnthropicRagProvider,
+  OpenAiRagProvider,
+  GeminiRagProvider,
+  OllamaRagProvider,
+  ServiceRagProvider,
+} from './providers'
+export type {
+  GenerationProvider,
+  EmbeddingProvider,
+  RagMessage,
+  RagGenerateOptions,
+  RagGenerateResult,
+  RagStreamChunk,
+} from './providers'
+
+// Vector stores
+export { SqlVectorStore, InMemoryVectorStore } from './vector-store'
+
+// Retrieval primitives
+export { chunkText } from './chunking'
+export { cosineSimilarity, normalize } from './similarity'
+export { buildRagPrompt, renderContext, DEFAULT_SYSTEM_PROMPT } from './prompt'
+
+// Config + value types
+export type {
+  AiRagConfig,
+  RagProviderName,
+  RagProviderConfig,
+  RagGenerationConfig,
+  RagEmbeddingConfig,
+  RagRetrievalConfig,
+  RagChunkingConfig,
+  RagChunkingStrategy,
+  RagIndexingConfig,
+  RagGuardConfig,
+  RagChatConfig,
+  RagLimitsConfig,
+  RagCollectionsConfig,
+  VectorStore,
+  VectorRecord,
+  VectorQuery,
+  PromptBuildArgs,
+  PromptBuildResult,
+} from './types'
+
+// Re-exported service types from core
+export type {
+  NixxieAiRagService,
+  NixxieRagDocument,
+  NixxieRagDocumentInput,
+  NixxieRagDocumentQuery,
+  NixxieRagChunk,
+  NixxieRagCitation,
+  NixxieRagAnswer,
+  NixxieRagAskOptions,
+  NixxieRagRetrieveOptions,
+  NixxieRagStreamEvent,
+  NixxieRagIndexStats,
+} from '@nixxie-cms/core'

package/src/plugin.ts

@@ -0,0 +1,162 @@
+import type { NixxieContext, NixxiePlugin } from '@nixxie-cms/core/types'
+import type { AiRagService } from './AiRagService'
+import { knowledgeBaseCollection, knowledgeChunkCollection } from './collection'
+import { installAiRagRoutes, type AiRagRoutesOptions } from './express'
+import { ragGraphqlExtension, type RagGraphqlOptions } from './graphql'
+
+export type RagPluginOptions = {
+  /** The service created with `createAiRag()`. */
+  service: AiRagService
+  /**
+   * Add the knowledge-base + chunk collections to the schema.
+   * Disable if you register them yourself (e.g. to customise access control).
+   * @default true
+   */
+  collections?: boolean
+  /**
+   * Re-index a knowledge-base row whenever it's created/updated through the CMS, and drop
+   * its chunks when it's deleted. Overrides the service's `indexing.auto` for CMS writes.
+   * @default the service's `indexing.auto`
+   */
+  autoIndex?: boolean
+  /**
+   * Mount the HTTP routes (chat + streaming + document CRUD). Pass `false` to skip, or an
+   * options object to configure the path / auth.
+   * @default true (mounted at /api/ai-rag)
+   */
+  routes?: boolean | Omit<AiRagRoutesOptions, 'service'>
+  /**
+   * Add the GraphQL queries/mutations (ragAsk, ragRetrieve, ragAddDocument, …).
+   * Pass `false` to skip, or options to configure auth.
+   * @default true
+   */
+  graphql?: boolean | RagGraphqlOptions
+  /** Name of the scheduled reindex job registered with the jobs service. @default 'ai-rag-reindex' */
+  jobName?: string
+}
+
+/** Re-index on CMS create/update, purge chunks on delete. Skips the service's own status writes. */
+function autoIndexHooks(service: AiRagService) {
+  return {
+    afterOperation: async (args: any) => {
+      try {
+        if (args.operation === 'delete') {
+          const id = args.originalItem?.id
+          if (id != null) await service.purgeChunks(String(id))
+          return
+        }
+        const item = args.item
+        if (!item?.id) return
+        // Only (re)index when indexable content actually changed — the service's own
+        // status/chunkCount writes go through raw Prisma and never reach this hook, but
+        // this also avoids needless work on unrelated field edits.
+        const changed =
+          args.operation === 'create' ||
+          item.content !== args.originalItem?.content ||
+          item.title !== args.originalItem?.title
+        if (changed) await service.index(String(item.id))
+      } catch (err) {
+        console.error('[@nixxie-cms/ai-rag] Auto-index hook failed:', err)
+      }
+    },
+  }
+}
+
+function composeExtendExpress(
+  previous: ((app: any, context: NixxieContext) => void | Promise<void>) | undefined,
+  service: AiRagService,
+  routes: RagPluginOptions['routes']
+): (app: any, context: NixxieContext) => Promise<void> {
+  const routeOptions = (typeof routes === 'object' ? routes : {}) as AiRagRoutesOptions
+  return async (app: any, context: NixxieContext) => {
+    await previous?.(app, context)
+    if (routes !== false) installAiRagRoutes(app, context, { ...routeOptions, service })
+  }
+}
+
+function composeExtendGraphql(
+  previous: ((schema: any) => any) | undefined,
+  graphqlOption: RagPluginOptions['graphql']
+) {
+  if (graphqlOption === false) return previous
+  const ext = ragGraphqlExtension(typeof graphqlOption === 'object' ? graphqlOption : {})
+  return (schema: any) => ext(previous ? previous(schema) : schema)
+}
+
+/**
+ * One-call wiring for the RAG assistant. Registers the service, adds the knowledge-base
+ * collections (with auto-indexing hooks), mounts the HTTP + GraphQL surfaces and schedules
+ * re-indexing.
+ *
+ * @example
+ * import { createAiRag, ragPlugin } from '@nixxie-cms/ai-rag'
+ * const aiRag = createAiRag({
+ *   generation: { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY! },
+ *   embedding: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+ *   indexing: { schedule: '0 3 * * *' },
+ * })
+ * export default config({
+ *   db: { ... },
+ *   plugins: [ragPlugin({ service: aiRag })],
+ * })
+ */
+export function ragPlugin(options: RagPluginOptions): NixxiePlugin {
+  const { service } = options
+  const { documents, chunks } = service.collections
+  const autoIndex = options.autoIndex ?? true
+  const jobName = options.jobName ?? 'ai-rag-reindex'
+
+  const collections =
+    options.collections === false
+      ? undefined
+      : {
+          [documents]: autoIndex
+            ? { ...knowledgeBaseCollection(), hooks: autoIndexHooks(service) }
+            : knowledgeBaseCollection(),
+          [chunks]: knowledgeChunkCollection(),
+        }
+
+  return {
+    name: 'nixxie-ai-rag',
+    collections,
+    extendConfig: config => ({
+      ...config,
+      // Register the service so core initialises it and it's reachable via context.services.aiRag.
+      aiRag: config.aiRag ?? service,
+      graphql: {
+        ...config.graphql,
+        extendGraphqlSchema: composeExtendGraphql(
+          config.graphql?.extendGraphqlSchema,
+          options.graphql
+        ),
+      },
+      server: {
+        ...config.server,
+        extendExpressApp: composeExtendExpress(
+          config.server?.extendExpressApp,
+          service,
+          options.routes
+        ),
+      },
+    }),
+    onConnect: async context => {
+      // The service itself is initialised by core's service-init loop (because we set
+      // config.aiRag above). Here we only schedule the periodic full reindex, if requested.
+      const schedule = service.indexingSchedule
+      if (schedule && context.services.jobs) {
+        context.services.jobs.define({
+          name: jobName,
+          schedule,
+          handler: async () => {
+            await service.reindex()
+          },
+        })
+      } else if (schedule && !context.services.jobs) {
+        console.warn(
+          `[@nixxie-cms/ai-rag] indexing.schedule is set but no jobs service is configured — ` +
+            `add \`jobs: createJobs()\` from @nixxie-cms/jobs to enable scheduled re-indexing.`
+        )
+      }
+    },
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,62 @@
+import type { NixxieRagChunk } from '@nixxie-cms/core'
+import type { PromptBuildArgs, PromptBuildResult } from './types'
+
+export const DEFAULT_SYSTEM_PROMPT =
+  'You are a helpful assistant that answers questions strictly using the provided knowledge ' +
+  'base context. Be accurate and concise. If the context does not contain the answer, say you ' +
+  "don't know rather than guessing."
+
+export const ALLOW_KNOWLEDGE_SYSTEM_PROMPT =
+  'You are a helpful assistant. Prefer the provided knowledge base context when answering. If ' +
+  'the context is insufficient you may use your general knowledge, but make clear which parts ' +
+  'are not from the knowledge base.'
+
+/** Render retrieved chunks as a numbered, citable source block. */
+export function renderContext(chunks: NixxieRagChunk[], maxChars: number): string {
+  const lines: string[] = []
+  let used = 0
+  for (let i = 0; i < chunks.length; i++) {
+    const c = chunks[i]!
+    const header = `[${i + 1}]${c.title ? ` ${c.title}` : ''}${c.source ? ` (${c.source})` : ''}`
+    const body = c.content.trim()
+    const block = `${header}\n${body}`
+    if (used + block.length > maxChars && lines.length > 0) break
+    lines.push(block)
+    used += block.length
+  }
+  return lines.join('\n\n')
+}
+
+/**
+ * Default prompt assembly: a system prompt carrying the numbered context + citation rules,
+ * the trimmed history, and the user's question. Overridable via `generation.buildPrompt`.
+ */
+export function buildRagPrompt(
+  args: PromptBuildArgs,
+  options: { maxContextChars: number }
+): PromptBuildResult {
+  const contextBlock = renderContext(args.context, options.maxContextChars)
+  const rules: string[] = []
+  if (args.context.length > 0) {
+    rules.push('Answer using ONLY the numbered context below.')
+    if (args.requireCitations) {
+      rules.push('Cite the sources you used inline as [n] matching the context numbers.')
+    }
+    rules.push("If the context does not contain the answer, say you don't have that information.")
+  }
+
+  const system = [
+    args.systemPrompt,
+    rules.length ? `\nRules:\n- ${rules.join('\n- ')}` : '',
+    contextBlock ? `\nContext:\n${contextBlock}` : '\nContext: (none found)',
+  ]
+    .filter(Boolean)
+    .join('\n')
+
+  const messages: PromptBuildResult['messages'] = [
+    ...args.history,
+    { role: 'user', content: args.question },
+  ]
+
+  return { system, messages }
+}

package/src/providers/AnthropicRagProvider.ts

@@ -0,0 +1,91 @@
+import type { RagProviderConfig } from '../types'
+import type {
+  GenerationProvider,
+  RagGenerateOptions,
+  RagGenerateResult,
+  RagMessage,
+  RagStreamChunk,
+} 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(
+      '[@nixxie-cms/ai-rag] The Anthropic provider requires @anthropic-ai/sdk. Run: npm install @anthropic-ai/sdk'
+    )
+  }
+}
+
+/** Anthropic (Claude) generation provider with native streaming. */
+export class AnthropicRagProvider implements GenerationProvider {
+  readonly name = 'anthropic'
+  readonly defaultModel = DEFAULT_MODEL
+  private client: any
+  private model: string
+  private maxTokens: number
+  private extra: Record<string, unknown>
+
+  constructor(config: RagProviderConfig) {
+    if (!config.apiKey) throw new Error('[@nixxie-cms/ai-rag] Anthropic generation requires `apiKey`.')
+    const Anthropic = loadAnthropic()
+    this.client = new Anthropic({ apiKey: config.apiKey, baseURL: config.baseUrl })
+    this.model = config.model ?? DEFAULT_MODEL
+    this.maxTokens = 1024
+    this.extra = config.extra ?? {}
+  }
+
+  private buildBody(messages: RagMessage[], options?: RagGenerateOptions) {
+    return {
+      model: options?.model ?? this.model,
+      max_tokens: options?.maxTokens ?? this.maxTokens,
+      system: options?.system || undefined,
+      messages: messages.map(m => ({ role: m.role, content: m.content })),
+      ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+      ...(options?.topP !== undefined ? { top_p: options.topP } : {}),
+      ...this.extra,
+      ...(options?.extra ?? {}),
+    }
+  }
+
+  async generate(messages: RagMessage[], options?: RagGenerateOptions): Promise<RagGenerateResult> {
+    const res = await this.client.messages.create(this.buildBody(messages, options))
+    const text = (res.content ?? [])
+      .filter((b: any) => b.type === 'text')
+      .map((b: any) => b.text)
+      .join('')
+    return {
+      text,
+      model: res.model ?? options?.model ?? this.model,
+      usage: { inputTokens: res.usage?.input_tokens, outputTokens: res.usage?.output_tokens },
+    }
+  }
+
+  async *stream(
+    messages: RagMessage[],
+    options?: RagGenerateOptions
+  ): AsyncIterable<RagStreamChunk> {
+    const stream = await this.client.messages.create({
+      ...this.buildBody(messages, options),
+      stream: true,
+    })
+    let input = 0
+    let output = 0
+    for await (const event of stream) {
+      if (event.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
+        yield { delta: event.delta.text }
+      } else if (event.type === 'message_start') {
+        input = event.message?.usage?.input_tokens ?? input
+      } else if (event.type === 'message_delta') {
+        output = event.usage?.output_tokens ?? output
+      }
+    }
+    yield {
+      done: true,
+      model: options?.model ?? this.model,
+      usage: { inputTokens: input, outputTokens: output },
+    }
+  }
+}