@nixxie-cms/ai-rag 1.0.0

package/src/providers/GeminiRagProvider.ts

@@ -0,0 +1,147 @@
+import type { RagProviderConfig } from '../types'
+import type {
+  EmbeddingProvider,
+  GenerationProvider,
+  RagGenerateOptions,
+  RagGenerateResult,
+  RagMessage,
+  RagStreamChunk,
+} from './types'
+
+const DEFAULT_MODEL = 'gemini-2.0-flash'
+const DEFAULT_EMBEDDING_MODEL = 'text-embedding-004'
+const DEFAULT_BASE = 'https://generativelanguage.googleapis.com/v1beta'
+
+/** Google Gemini provider over the public REST API — generation, streaming and embeddings. */
+export class GeminiRagProvider implements GenerationProvider, EmbeddingProvider {
+  readonly name = 'gemini'
+  readonly defaultModel = DEFAULT_MODEL
+  private apiKey: string
+  private model: string
+  private embeddingModel: string
+  private base: string
+  private extra: Record<string, unknown>
+
+  constructor(config: RagProviderConfig) {
+    if (!config.apiKey) throw new Error('[@nixxie-cms/ai-rag] Gemini requires `apiKey`.')
+    this.apiKey = config.apiKey
+    this.model = config.model ?? DEFAULT_MODEL
+    this.embeddingModel = config.model ?? DEFAULT_EMBEDDING_MODEL
+    this.base = (config.baseUrl ?? DEFAULT_BASE).replace(/\/$/, '')
+    this.extra = config.extra ?? {}
+  }
+
+  private buildBody(messages: RagMessage[], options?: RagGenerateOptions) {
+    return {
+      contents: messages.map(m => ({
+        role: m.role === 'assistant' ? 'model' : 'user',
+        parts: [{ text: m.content }],
+      })),
+      ...(options?.system
+        ? { systemInstruction: { parts: [{ text: options.system }] } }
+        : {}),
+      generationConfig: {
+        ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+        ...(options?.maxTokens !== undefined ? { maxOutputTokens: options.maxTokens } : {}),
+        ...(options?.topP !== undefined ? { topP: options.topP } : {}),
+      },
+      ...this.extra,
+      ...(options?.extra ?? {}),
+    }
+  }
+
+  private extractText(data: any): string {
+    const parts = data?.candidates?.[0]?.content?.parts ?? []
+    return parts.map((p: any) => p.text ?? '').join('')
+  }
+
+  async generate(messages: RagMessage[], options?: RagGenerateOptions): Promise<RagGenerateResult> {
+    const model = options?.model ?? this.model
+    const res = await fetch(
+      `${this.base}/models/${model}:generateContent?key=${this.apiKey}`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(this.buildBody(messages, options)),
+      }
+    )
+    if (!res.ok) throw new Error(`[@nixxie-cms/ai-rag] Gemini generate failed (${res.status}): ${await res.text()}`)
+    const data: any = await res.json()
+    return {
+      text: this.extractText(data),
+      model,
+      usage: {
+        inputTokens: data?.usageMetadata?.promptTokenCount,
+        outputTokens: data?.usageMetadata?.candidatesTokenCount,
+      },
+    }
+  }
+
+  async *stream(
+    messages: RagMessage[],
+    options?: RagGenerateOptions
+  ): AsyncIterable<RagStreamChunk> {
+    const model = options?.model ?? this.model
+    const res = await fetch(
+      `${this.base}/models/${model}:streamGenerateContent?alt=sse&key=${this.apiKey}`,
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(this.buildBody(messages, options)),
+      }
+    )
+    if (!res.ok || !res.body) {
+      throw new Error(`[@nixxie-cms/ai-rag] Gemini stream failed (${res.status}): ${await res.text()}`)
+    }
+    let usage: any
+    for await (const data of parseSseJson(res.body)) {
+      const text = this.extractText(data)
+      if (text) yield { delta: text }
+      if (data?.usageMetadata) usage = data.usageMetadata
+    }
+    yield {
+      done: true,
+      model,
+      usage: { inputTokens: usage?.promptTokenCount, outputTokens: usage?.candidatesTokenCount },
+    }
+  }
+
+  async embed(texts: string[], model?: string): Promise<number[][]> {
+    const m = model ?? this.embeddingModel
+    const res = await fetch(`${this.base}/models/${m}:batchEmbedContents?key=${this.apiKey}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        requests: texts.map(text => ({
+          model: `models/${m}`,
+          content: { parts: [{ text }] },
+        })),
+      }),
+    })
+    if (!res.ok) throw new Error(`[@nixxie-cms/ai-rag] Gemini embed failed (${res.status}): ${await res.text()}`)
+    const data: any = await res.json()
+    return (data.embeddings ?? []).map((e: any) => e.values as number[])
+  }
+}
+
+/** Parse a `text/event-stream` of JSON `data:` lines into objects. */
+async function* parseSseJson(body: any): AsyncIterable<any> {
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for await (const piece of body as AsyncIterable<Uint8Array>) {
+    buffer += typeof piece === 'string' ? piece : decoder.decode(piece, { stream: true })
+    let idx
+    while ((idx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, idx).trim()
+      buffer = buffer.slice(idx + 1)
+      if (!line.startsWith('data:')) continue
+      const payload = line.slice(5).trim()
+      if (!payload || payload === '[DONE]') continue
+      try {
+        yield JSON.parse(payload)
+      } catch {
+        // Partial frame — ignore; the next chunk will complete it.
+      }
+    }
+  }
+}

package/src/providers/OllamaRagProvider.ts

@@ -0,0 +1,157 @@
+import type { RagProviderConfig } from '../types'
+import type {
+  EmbeddingProvider,
+  GenerationProvider,
+  RagGenerateOptions,
+  RagGenerateResult,
+  RagMessage,
+  RagStreamChunk,
+} from './types'
+
+const DEFAULT_MODEL = 'llama3.1'
+const DEFAULT_EMBEDDING_MODEL = 'nomic-embed-text'
+const DEFAULT_BASE = 'http://localhost:11434'
+
+/**
+ * Ollama provider for local (or remote) open models — generation, streaming and embeddings.
+ * Runs any Ollama model family (Llama, Mistral, Phi, Gemma, Qwen, …). No API key needed for a
+ * local server; point `baseUrl` at your Ollama host if it isn't on localhost.
+ */
+export class OllamaRagProvider implements GenerationProvider, EmbeddingProvider {
+  readonly name = 'ollama'
+  readonly defaultModel = DEFAULT_MODEL
+  private base: string
+  private model: string
+  private embeddingModel: string
+  private apiKey?: string
+  private extra: Record<string, unknown>
+
+  constructor(config: RagProviderConfig) {
+    this.base = (config.baseUrl ?? DEFAULT_BASE).replace(/\/$/, '')
+    this.model = config.model ?? DEFAULT_MODEL
+    this.embeddingModel = config.model ?? DEFAULT_EMBEDDING_MODEL
+    this.apiKey = config.apiKey
+    this.extra = config.extra ?? {}
+  }
+
+  private headers() {
+    return {
+      'Content-Type': 'application/json',
+      ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+    }
+  }
+
+  private buildBody(messages: RagMessage[], options: RagGenerateOptions | undefined, stream: boolean) {
+    return {
+      model: options?.model ?? this.model,
+      stream,
+      messages: [
+        ...(options?.system ? [{ role: 'system', content: options.system }] : []),
+        ...messages.map(m => ({ role: m.role, content: m.content })),
+      ],
+      options: {
+        ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+        ...(options?.maxTokens !== undefined ? { num_predict: options.maxTokens } : {}),
+        ...(options?.topP !== undefined ? { top_p: options.topP } : {}),
+      },
+      ...this.extra,
+      ...(options?.extra ?? {}),
+    }
+  }
+
+  async generate(messages: RagMessage[], options?: RagGenerateOptions): Promise<RagGenerateResult> {
+    const res = await fetch(`${this.base}/api/chat`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify(this.buildBody(messages, options, false)),
+    })
+    if (!res.ok) throw new Error(`[@nixxie-cms/ai-rag] Ollama generate failed (${res.status}): ${await res.text()}`)
+    const data: any = await res.json()
+    return {
+      text: data?.message?.content ?? '',
+      model: data?.model ?? options?.model ?? this.model,
+      usage: { inputTokens: data?.prompt_eval_count, outputTokens: data?.eval_count },
+    }
+  }
+
+  async *stream(
+    messages: RagMessage[],
+    options?: RagGenerateOptions
+  ): AsyncIterable<RagStreamChunk> {
+    const res = await fetch(`${this.base}/api/chat`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify(this.buildBody(messages, options, true)),
+    })
+    if (!res.ok || !res.body) {
+      throw new Error(`[@nixxie-cms/ai-rag] Ollama stream failed (${res.status}): ${await res.text()}`)
+    }
+    let usage: any
+    // Ollama streams newline-delimited JSON objects.
+    for await (const obj of parseNdJson(res.body)) {
+      const delta = obj?.message?.content
+      if (delta) yield { delta }
+      if (obj?.done) usage = obj
+    }
+    yield {
+      done: true,
+      model: options?.model ?? this.model,
+      usage: { inputTokens: usage?.prompt_eval_count, outputTokens: usage?.eval_count },
+    }
+  }
+
+  async embed(texts: string[], model?: string): Promise<number[][]> {
+    const m = model ?? this.embeddingModel
+    // /api/embed accepts a batch; older servers only support /api/embeddings (single).
+    const res = await fetch(`${this.base}/api/embed`, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify({ model: m, input: texts }),
+    })
+    if (res.ok) {
+      const data: any = await res.json()
+      if (Array.isArray(data?.embeddings)) return data.embeddings as number[][]
+    }
+    // Fallback: one request per text against the legacy endpoint.
+    const out: number[][] = []
+    for (const text of texts) {
+      const r = await fetch(`${this.base}/api/embeddings`, {
+        method: 'POST',
+        headers: this.headers(),
+        body: JSON.stringify({ model: m, prompt: text }),
+      })
+      if (!r.ok) throw new Error(`[@nixxie-cms/ai-rag] Ollama embed failed (${r.status}): ${await r.text()}`)
+      const d: any = await r.json()
+      out.push(d.embedding as number[])
+    }
+    return out
+  }
+}
+
+/** Parse newline-delimited JSON from a stream body. */
+async function* parseNdJson(body: any): AsyncIterable<any> {
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for await (const piece of body as AsyncIterable<Uint8Array>) {
+    buffer += typeof piece === 'string' ? piece : decoder.decode(piece, { stream: true })
+    let idx
+    while ((idx = buffer.indexOf('\n')) !== -1) {
+      const line = buffer.slice(0, idx).trim()
+      buffer = buffer.slice(idx + 1)
+      if (!line) continue
+      try {
+        yield JSON.parse(line)
+      } catch {
+        // Ignore partial lines.
+      }
+    }
+  }
+  const tail = buffer.trim()
+  if (tail) {
+    try {
+      yield JSON.parse(tail)
+    } catch {
+      /* ignore */
+    }
+  }
+}

package/src/providers/OpenAiRagProvider.ts

@@ -0,0 +1,108 @@
+import type { RagProviderConfig } from '../types'
+import type {
+  EmbeddingProvider,
+  GenerationProvider,
+  RagGenerateOptions,
+  RagGenerateResult,
+  RagMessage,
+  RagStreamChunk,
+} 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(
+      '[@nixxie-cms/ai-rag] The OpenAI provider requires the openai package. Run: npm install openai'
+    )
+  }
+}
+
+/** OpenAI (GPT) provider — generation, streaming and embeddings. */
+export class OpenAiRagProvider implements GenerationProvider, EmbeddingProvider {
+  readonly name = 'openai'
+  readonly defaultModel = DEFAULT_MODEL
+  private client: any
+  private model: string
+  private embeddingModel: string
+  private extra: Record<string, unknown>
+
+  constructor(config: RagProviderConfig) {
+    if (!config.apiKey) throw new Error('[@nixxie-cms/ai-rag] OpenAI requires `apiKey`.')
+    const OpenAI = loadOpenAi()
+    this.client = new OpenAI({ apiKey: config.apiKey, baseURL: config.baseUrl })
+    this.model = config.model ?? DEFAULT_MODEL
+    this.embeddingModel = config.model ?? DEFAULT_EMBEDDING_MODEL
+    this.extra = config.extra ?? {}
+  }
+
+  private buildMessages(messages: RagMessage[], system?: string) {
+    return [
+      ...(system ? [{ role: 'system' as const, content: system }] : []),
+      ...messages.map(m => ({ role: m.role, content: m.content })),
+    ]
+  }
+
+  async generate(messages: RagMessage[], options?: RagGenerateOptions): Promise<RagGenerateResult> {
+    const res = await this.client.chat.completions.create({
+      model: options?.model ?? this.model,
+      messages: this.buildMessages(messages, options?.system),
+      ...(options?.maxTokens !== undefined ? { max_tokens: options.maxTokens } : {}),
+      ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+      ...(options?.topP !== undefined ? { top_p: options.topP } : {}),
+      ...this.extra,
+      ...(options?.extra ?? {}),
+    })
+    return {
+      text: res.choices?.[0]?.message?.content ?? '',
+      model: res.model ?? options?.model ?? this.model,
+      usage: {
+        inputTokens: res.usage?.prompt_tokens,
+        outputTokens: res.usage?.completion_tokens,
+      },
+    }
+  }
+
+  async *stream(
+    messages: RagMessage[],
+    options?: RagGenerateOptions
+  ): AsyncIterable<RagStreamChunk> {
+    const stream = await this.client.chat.completions.create({
+      model: options?.model ?? this.model,
+      messages: this.buildMessages(messages, options?.system),
+      stream: true,
+      stream_options: { include_usage: true },
+      ...(options?.maxTokens !== undefined ? { max_tokens: options.maxTokens } : {}),
+      ...(options?.temperature !== undefined ? { temperature: options.temperature } : {}),
+      ...(options?.topP !== undefined ? { top_p: options.topP } : {}),
+      ...this.extra,
+      ...(options?.extra ?? {}),
+    })
+    let usage: any
+    for await (const part of stream) {
+      const delta = part.choices?.[0]?.delta?.content
+      if (delta) yield { delta }
+      if (part.usage) usage = part.usage
+    }
+    yield {
+      done: true,
+      model: options?.model ?? this.model,
+      usage: { inputTokens: usage?.prompt_tokens, outputTokens: usage?.completion_tokens },
+    }
+  }
+
+  async embed(texts: string[], model?: string): Promise<number[][]> {
+    const res = await this.client.embeddings.create({
+      model: model ?? this.embeddingModel,
+      input: texts,
+    })
+    const items = (res.data ?? []) as Array<{ index?: number; embedding: number[] }>
+    return items
+      .slice()
+      .sort((a, b) => (a.index ?? 0) - (b.index ?? 0))
+      .map(d => d.embedding)
+  }
+}

package/src/providers/ServiceRagProvider.ts

@@ -0,0 +1,44 @@
+import type { NixxieAiService } from '@nixxie-cms/core'
+import type {
+  EmbeddingProvider,
+  GenerationProvider,
+  RagGenerateOptions,
+  RagGenerateResult,
+  RagMessage,
+  RagStreamChunk,
+} from './types'
+
+/**
+ * Adapts an existing `NixxieAiService` (e.g. `context.services.ai` from @nixxie-cms/ai)
+ * into a RAG provider. Streaming is emulated by emitting the full answer as one delta,
+ * since `NixxieAiService` has no streaming surface.
+ */
+export class ServiceRagProvider implements GenerationProvider, EmbeddingProvider {
+  readonly name = 'service'
+  readonly defaultModel = 'service'
+
+  constructor(private service: NixxieAiService) {}
+
+  async generate(messages: RagMessage[], options?: RagGenerateOptions): Promise<RagGenerateResult> {
+    const res = await this.service.chat(messages, {
+      model: options?.model,
+      system: options?.system,
+      temperature: options?.temperature,
+      maxTokens: options?.maxTokens,
+    })
+    return { text: res.text, model: res.model, usage: res.usage }
+  }
+
+  async *stream(
+    messages: RagMessage[],
+    options?: RagGenerateOptions
+  ): AsyncIterable<RagStreamChunk> {
+    const res = await this.generate(messages, options)
+    if (res.text) yield { delta: res.text }
+    yield { done: true, model: res.model, usage: res.usage }
+  }
+
+  async embed(texts: string[]): Promise<number[][]> {
+    return this.service.embedMany(texts)
+  }
+}

package/src/providers/index.ts

@@ -0,0 +1,67 @@
+import type { RagEmbeddingConfig, RagGenerationConfig, RagProviderName } from '../types'
+import { AnthropicRagProvider } from './AnthropicRagProvider'
+import { GeminiRagProvider } from './GeminiRagProvider'
+import { OllamaRagProvider } from './OllamaRagProvider'
+import { OpenAiRagProvider } from './OpenAiRagProvider'
+import { ServiceRagProvider } from './ServiceRagProvider'
+import type { EmbeddingProvider, GenerationProvider } from './types'
+
+/** Build the generation provider from config (default provider: anthropic). */
+export function resolveGenerationProvider(config: RagGenerationConfig = {}): GenerationProvider {
+  if (config.service) return new ServiceRagProvider(config.service)
+  const provider: RagProviderName = config.provider ?? 'anthropic'
+  switch (provider) {
+    case 'anthropic':
+      return new AnthropicRagProvider(config)
+    case 'openai':
+      return new OpenAiRagProvider(config)
+    case 'gemini':
+      return new GeminiRagProvider(config)
+    case 'ollama':
+      return new OllamaRagProvider(config)
+    default: {
+      const exhaustive: never = provider
+      throw new Error(`[@nixxie-cms/ai-rag] Unknown generation provider: ${exhaustive}`)
+    }
+  }
+}
+
+/** Build the embedding provider from config (default provider: openai). */
+export function resolveEmbeddingProvider(config: RagEmbeddingConfig = {}): EmbeddingProvider {
+  if (config.service) return new ServiceRagProvider(config.service)
+  const provider: RagProviderName = config.provider ?? 'openai'
+  switch (provider) {
+    case 'openai':
+      return new OpenAiRagProvider(config)
+    case 'gemini':
+      return new GeminiRagProvider(config)
+    case 'ollama':
+      return new OllamaRagProvider(config)
+    case 'anthropic':
+      throw new Error(
+        '[@nixxie-cms/ai-rag] Anthropic has no native embeddings endpoint. Use `openai`, ' +
+          '`gemini` or `ollama` for the `embedding` provider (you can still use Anthropic for generation).'
+      )
+    default: {
+      const exhaustive: never = provider
+      throw new Error(`[@nixxie-cms/ai-rag] Unknown embedding provider: ${exhaustive}`)
+    }
+  }
+}
+
+export {
+  AnthropicRagProvider,
+  OpenAiRagProvider,
+  GeminiRagProvider,
+  OllamaRagProvider,
+  ServiceRagProvider,
+}
+export type {
+  GenerationProvider,
+  EmbeddingProvider,
+  RagMessage,
+  RagGenerateOptions,
+  RagGenerateResult,
+  RagStreamChunk,
+  RagUsage,
+} from './types'

package/src/providers/types.ts

@@ -0,0 +1,44 @@
+/** A single chat turn handed to a provider. */
+export type RagMessage = { role: 'user' | 'assistant'; content: string }
+
+export type RagGenerateOptions = {
+  model?: string
+  system?: string
+  temperature?: number
+  maxTokens?: number
+  topP?: number
+  /** Provider-specific extras merged into the request body. */
+  extra?: Record<string, unknown>
+}
+
+export type RagUsage = { inputTokens?: number; outputTokens?: number }
+
+export type RagGenerateResult = {
+  text: string
+  model: string
+  usage?: RagUsage
+}
+
+/** One streamed delta. The final chunk carries `done: true` and any usage. */
+export type RagStreamChunk = {
+  delta?: string
+  done?: boolean
+  usage?: RagUsage
+  model?: string
+}
+
+/** A provider that can answer (and ideally stream) a chat. */
+export interface GenerationProvider {
+  readonly name: string
+  readonly defaultModel: string
+  generate(messages: RagMessage[], options?: RagGenerateOptions): Promise<RagGenerateResult>
+  /** Optional native streaming. When absent, the service emulates it from `generate`. */
+  stream?(messages: RagMessage[], options?: RagGenerateOptions): AsyncIterable<RagStreamChunk>
+}
+
+/** A provider that can turn text into embedding vectors. */
+export interface EmbeddingProvider {
+  readonly name: string
+  readonly defaultModel: string
+  embed(texts: string[], model?: string): Promise<number[][]>
+}

package/src/semaphore.ts

@@ -0,0 +1,26 @@
+/** A minimal counting semaphore used to cap concurrent generations. */
+export class Semaphore {
+  private available: number
+  private waiters: Array<() => void> = []
+
+  constructor(permits: number) {
+    this.available = Math.max(1, permits)
+  }
+
+  /** Acquire a permit, resolving to a `release` function to call when done. */
+  async acquire(): Promise<() => void> {
+    if (this.available > 0) {
+      this.available--
+      return () => this.release()
+    }
+    await new Promise<void>(resolve => this.waiters.push(resolve))
+    this.available--
+    return () => this.release()
+  }
+
+  private release(): void {
+    this.available++
+    const next = this.waiters.shift()
+    if (next) next()
+  }
+}

package/src/similarity.ts

@@ -0,0 +1,31 @@
+/** Dot product of two equal-length vectors. */
+export function dot(a: number[], b: number[]): number {
+  let sum = 0
+  const n = Math.min(a.length, b.length)
+  for (let i = 0; i < n; i++) sum += a[i]! * b[i]!
+  return sum
+}
+
+/** Euclidean norm of a vector. */
+export function norm(a: number[]): number {
+  return Math.sqrt(dot(a, a))
+}
+
+/**
+ * Cosine similarity mapped from [-1, 1] into [0, 1] so it can be used as a relevance
+ * score and compared against a `minScore` threshold. Returns 0 for a zero vector.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  const denom = norm(a) * norm(b)
+  if (denom === 0) return 0
+  const cos = dot(a, b) / denom
+  // Clamp for floating-point drift, then rescale to [0, 1].
+  return (Math.max(-1, Math.min(1, cos)) + 1) / 2
+}
+
+/** Pre-normalise a vector to unit length (lets retrieval use a plain dot product). */
+export function normalize(a: number[]): number[] {
+  const n = norm(a)
+  if (n === 0) return a.slice()
+  return a.map(x => x / n)
+}