@nixxie-cms/core 1.1.0 → 2.1.0

package/scripts/dist/nixxie-cms-core-scripts.esm.js

@@ -1,5 +1,5 @@
 import { cli } from '../cli/dist/nixxie-cms-core-scripts-cli.esm.js';
-import { E as ExitError } from '../../dist/express-0abbce07.esm.js';
+import { E as ExitError } from '../../dist/express-d0a4ce99.esm.js';
 import 'meow';
 import 'esbuild';
 import '@nodelib/fs.walk';
@@ -8,7 +8,7 @@ import 'node:fs/promises';
 import 'node:path';
 import 'node:util';
 import 'resolve';
-import '../../dist/system-4d2a2648.esm.js';
+import '../../dist/system-e591d821.esm.js';
 import 'node:crypto';
 import '../../dist/admin-meta-14c60fec.esm.js';
 import 'graphql';

package/src/fields/types/timestamp/views/__tests__/index.tsx

@@ -1,68 +1,68 @@
-import { controller } from '../index'
-
-const STUBCONFIG = {
-  listKey: 'timestamp',
-  fieldKey: 'timestamp',
-  label: 'foo',
-  description: '',
-  customViews: {},
-} as const
-
-describe('controller', () => {
-  describe('validate', () => {
-    it('null is OK if not required', () => {
-      const { validate } = controller({
-        ...STUBCONFIG,
-        fieldMeta: {
-          defaultValue: null,
-          updatedAt: false,
-        },
-      })
-      expect(
-        validate!(
-          {
-            kind: 'create',
-            value: null,
-          },
-          { isRequired: false }
-        )
-      ).toBe(true)
-    })
-    it('isRequired enforces required (null)', () => {
-      const { validate } = controller({
-        ...STUBCONFIG,
-        fieldMeta: {
-          defaultValue: null,
-          updatedAt: false,
-        },
-      })
-      expect(
-        validate!(
-          {
-            kind: 'create',
-            value: null,
-          },
-          { isRequired: true }
-        )
-      ).toBe('foo is required')
-    })
-    it('isRequired enforces required (value)', () => {
-      const { validate } = controller({
-        ...STUBCONFIG,
-        fieldMeta: {
-          defaultValue: null,
-          updatedAt: false,
-        },
-      })
-      expect(
-        validate!(
-          {
-            kind: 'create',
-            value: new Date().toJSON(),
-          },
-          { isRequired: true }
-        )
-      ).toBe(true)
-    })
-  })
-})
+import { controller } from '../index'
+
+const STUBCONFIG = {
+  listKey: 'timestamp',
+  fieldKey: 'timestamp',
+  label: 'foo',
+  description: '',
+  customViews: {},
+} as const
+
+describe('controller', () => {
+  describe('validate', () => {
+    it('null is OK if not required', () => {
+      const { validate } = controller({
+        ...STUBCONFIG,
+        fieldMeta: {
+          defaultValue: null,
+          updatedAt: false,
+        },
+      })
+      expect(
+        validate!(
+          {
+            kind: 'create',
+            value: null,
+          },
+          { isRequired: false }
+        )
+      ).toBe(true)
+    })
+    it('isRequired enforces required (null)', () => {
+      const { validate } = controller({
+        ...STUBCONFIG,
+        fieldMeta: {
+          defaultValue: null,
+          updatedAt: false,
+        },
+      })
+      expect(
+        validate!(
+          {
+            kind: 'create',
+            value: null,
+          },
+          { isRequired: true }
+        )
+      ).toBe(false)
+    })
+    it('isRequired enforces required (value)', () => {
+      const { validate } = controller({
+        ...STUBCONFIG,
+        fieldMeta: {
+          defaultValue: null,
+          updatedAt: false,
+        },
+      })
+      expect(
+        validate!(
+          {
+            kind: 'create',
+            value: new Date().toJSON(),
+          },
+          { isRequired: true }
+        )
+      ).toBe(true)
+    })
+  })
+})

package/src/lib/context/createContext.ts

@@ -93,6 +93,7 @@ export function createContext({
         search: config.search ?? null,
         notifications: config.notifications ?? null,
         ai: config.ai ?? null,
+        aiRag: config.aiRag ?? null,
         versioning: config.versioning ?? null,
         workflow: config.workflow ?? null,
         apiKeys: config.apiKeys ?? null,

package/src/schema.ts

@@ -220,6 +220,7 @@ export function buildConfig<TypeInfo extends BaseNixxieTypeInfo>(
     search: config.search,
     notifications: config.notifications,
     ai: config.ai,
+    aiRag: config.aiRag,
     versioning: config.versioning,
     workflow: config.workflow,
     apiKeys: config.apiKeys,

package/src/types/config/index.ts

@@ -10,6 +10,7 @@ import type { GraphQLSchema } from 'graphql'
 import type {
   BaseNixxieTypeInfo,
   DatabaseProvider,
+  NixxieAiRagService,
   NixxieAiService,
   NixxieApiKeysService,
   NixxieAuditService,
@@ -420,6 +421,25 @@ export type NixxieConfigPre<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieType
    */
   ai?: NixxieAiService
 
+  /**
+   * Custom RAG assistant created with `createAiRag()` from `@nixxie-cms/ai-rag`.
+   * Available as `context.services.aiRag`. Stores a knowledge base, indexes it into
+   * embeddings, and answers questions grounded in that content with citations and
+   * hallucination guarding. Prefer registering it via `ragPlugin()` so the knowledge-base
+   * collections, HTTP routes and scheduled indexing are wired automatically.
+   *
+   * @example
+   * ```ts
+   * 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! },
+   * })
+   * export default config({ aiRag, plugins: [ragPlugin({ service: aiRag })] })
+   * ```
+   */
+  aiRag?: NixxieAiRagService
+
   /**
    * Content revision history created with `createVersioning()` from
    * `@nixxie-cms/versioning`. Available as `context.services.versioning`.
@@ -560,6 +580,7 @@ export type NixxieConfig<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeInf
   search: NixxieSearchService | undefined
   notifications: NixxieNotificationsService | undefined
   ai: NixxieAiService | undefined
+  aiRag: NixxieAiRagService | undefined
   versioning: NixxieVersioningService | undefined
   workflow: NixxieWorkflowService | undefined
   apiKeys: NixxieApiKeysService | undefined

package/src/types/context.ts

@@ -562,6 +562,171 @@ export type NixxieAiService = {
   embedMany(texts: string[]): Promise<number[][]>
 }
 
+// ── AI RAG service (retrieval-augmented knowledge base) ──
+
+/** A source document stored in the knowledge base that the assistant is trained on. */
+export type NixxieRagDocumentInput = {
+  /** Short title/label for the document. */
+  title?: string
+  /** The body the assistant learns from. */
+  content: string
+  /** Origin of the content (URL, filename, list:itemId, …) — shown in citations. */
+  source?: string
+  /** Free-form tags used to scope retrieval (e.g. ['billing', 'public']). */
+  tags?: string[]
+  /** Arbitrary structured metadata returned alongside citations. */
+  metadata?: Record<string, unknown>
+}
+
+export type NixxieRagDocument = NixxieRagDocumentInput & {
+  id: string
+  /** Indexing lifecycle of the document's chunks. */
+  status: 'pending' | 'indexing' | 'indexed' | 'error' | 'disabled'
+  /** Number of chunks currently indexed for this document. */
+  chunkCount: number
+  /** Last error encountered while indexing, if any. */
+  error?: string
+  createdAt: Date
+  updatedAt: Date
+  indexedAt?: Date
+}
+
+export type NixxieRagDocumentQuery = {
+  take?: number
+  skip?: number
+  /** Only return documents matching ALL of these tags. */
+  tags?: string[]
+  status?: NixxieRagDocument['status']
+  /** Substring match against title/content/source. */
+  search?: string
+}
+
+/** A retrieved chunk with its similarity score, used to ground answers. */
+export type NixxieRagChunk = {
+  id: string
+  documentId: string
+  title?: string
+  source?: string
+  /** The chunk text. */
+  content: string
+  /** Cosine similarity to the query in [0, 1] (higher is more relevant). */
+  score: number
+  tags?: string[]
+  metadata?: Record<string, unknown>
+}
+
+export type NixxieRagRetrieveOptions = {
+  /** Number of chunks to return. Defaults to the configured `retrieval.topK`. */
+  topK?: number
+  /** Drop chunks scoring below this threshold. Defaults to `retrieval.minScore`. */
+  minScore?: number
+  /** Restrict retrieval to documents carrying ALL of these tags. */
+  tags?: string[]
+}
+
+/** A single source the answer was grounded on. */
+export type NixxieRagCitation = {
+  documentId: string
+  chunkId: string
+  title?: string
+  source?: string
+  score: number
+  /** Short excerpt of the cited chunk. */
+  snippet: string
+}
+
+export type NixxieRagAskOptions = NixxieRagRetrieveOptions & {
+  /** Override the generation model for this call. */
+  model?: string
+  /** Override sampling temperature for this call. */
+  temperature?: number
+  /** Override max output tokens for this call. */
+  maxTokens?: number
+  /** Append an extra instruction to the system prompt for this call. */
+  systemSuffix?: string
+  /** Pre-retrieved chunks to use instead of running retrieval (advanced). */
+  context?: NixxieRagChunk[]
+  /** Per-call override of the hallucination guard. */
+  guard?: boolean
+}
+
+/** The grounded answer returned by `ask`/`chat`. */
+export type NixxieRagAnswer = {
+  /** The assistant's answer text. */
+  text: string
+  /** The sources the answer was grounded on. */
+  sources: NixxieRagCitation[]
+  /** Whether the answer passed the grounding/hallucination check. */
+  grounded: boolean
+  /** True when the assistant refused because no relevant context was found. */
+  refused: boolean
+  model: string
+  usage?: { inputTokens?: number; outputTokens?: number }
+}
+
+/** A streamed token or lifecycle event from `stream`. */
+export type NixxieRagStreamEvent =
+  | { type: 'sources'; sources: NixxieRagCitation[] }
+  | { type: 'token'; token: string }
+  | { type: 'done'; answer: NixxieRagAnswer }
+  | { type: 'error'; error: string }
+
+export type NixxieRagIndexStats = {
+  /** Documents processed this run. */
+  documents: number
+  /** Chunks (re)embedded this run. */
+  chunks: number
+  /** Documents that failed to index. */
+  errors: number
+  /** Wall-clock duration in milliseconds. */
+  durationMs: number
+}
+
+/**
+ * A custom, RAG-trained assistant backed by a knowledge-base collection.
+ * Implemented by @nixxie-cms/ai-rag. Add/remove/retrieve KB content, (re)index it
+ * into embeddings, and ask grounded, citation-backed questions with hallucination guarding.
+ */
+export type NixxieAiRagService = NixxieInitableService & {
+  // ── Knowledge-base content ──
+  /** Add a document to the knowledge base (queued for indexing). */
+  addDocument(doc: NixxieRagDocumentInput): Promise<NixxieRagDocument>
+  /** Add many documents in one call. */
+  addDocuments(docs: NixxieRagDocumentInput[]): Promise<NixxieRagDocument[]>
+  /** Fetch a single document by id. */
+  getDocument(id: string): Promise<NixxieRagDocument | undefined>
+  /** List documents in the knowledge base. */
+  listDocuments(query?: NixxieRagDocumentQuery): Promise<NixxieRagDocument[]>
+  /** Patch a document's content/metadata (re-queues it for indexing). */
+  updateDocument(id: string, patch: Partial<NixxieRagDocumentInput>): Promise<NixxieRagDocument>
+  /** Remove a document and all of its indexed chunks. */
+  removeDocument(id: string): Promise<void>
+
+  // ── Indexing ──
+  /** (Re)index a single document now. */
+  index(documentId: string): Promise<void>
+  /** (Re)index documents. Pass `{ force: true }` to rebuild already-indexed docs. */
+  reindex(options?: { force?: boolean; tags?: string[] }): Promise<NixxieRagIndexStats>
+  /** Index every document still pending/changed. */
+  indexPending(): Promise<NixxieRagIndexStats>
+
+  // ── Retrieval & chat ──
+  /** Return the most relevant chunks for a query (no generation). */
+  retrieve(query: string, options?: NixxieRagRetrieveOptions): Promise<NixxieRagChunk[]>
+  /** Ask a one-shot question and get a grounded, cited answer. */
+  ask(question: string, options?: NixxieRagAskOptions): Promise<NixxieRagAnswer>
+  /** Multi-turn chat; the latest user turn drives retrieval. */
+  chat(messages: NixxieAiMessage[], options?: NixxieRagAskOptions): Promise<NixxieRagAnswer>
+  /** Streamed variant of `chat`, yielding sources, then tokens, then the final answer. */
+  stream(
+    messages: NixxieAiMessage[],
+    options?: NixxieRagAskOptions
+  ): AsyncIterable<NixxieRagStreamEvent>
+
+  /** Gracefully stop background indexing and flush pending work. */
+  close(): Promise<void>
+}
+
 // ── Versioning service ──
 
 export type NixxieVersionEntry = {
@@ -912,6 +1077,7 @@ export type NixxieContext<TypeInfo extends BaseNixxieTypeInfo = BaseNixxieTypeIn
     search: NixxieSearchService | null
     notifications: NixxieNotificationsService | null
     ai: NixxieAiService | null
+    aiRag: NixxieAiRagService | null
     versioning: NixxieVersioningService | null
     workflow: NixxieWorkflowService | null
     apiKeys: NixxieApiKeysService | null