@lunora/ai 1.0.0-alpha.56 → 1.0.0-alpha.57

package/dist/packem_shared/ragSyncTriggers-BY8QgX4d.mjs

@@ -0,0 +1 @@
+const f=t=>{const u=t.delayMs??0,r=(i,d)=>t.id===void 0?d:t.id(i),c=i=>i===void 0?void 0:t.text(i),o=async(i,d)=>{await i.scheduler.runAfter(u,t.action,d)};return{afterDelete:async(i,d)=>{const e=d.previous??d.doc;await o(i,{deleted:!0,id:e===void 0?d.id:r(e,d.id)})},afterInsert:async(i,d)=>{const e=c(d.doc);e===void 0||d.doc===void 0||await o(i,{id:r(d.doc,d.id),text:e})},afterUpdate:async(i,d)=>{if(d.doc===void 0)return;const e=c(d.doc),v=c(d.previous),a=r(d.doc,d.id),s=d.previous===void 0?a:r(d.previous,d.id);if(s!==a)await o(i,{deleted:!0,id:s});else if(e===v)return;await(e===void 0?o(i,{deleted:!0,id:a}):o(i,{id:a,text:e}))}}};export{f as ragSyncTriggers};

package/dist/rag/index.d.mts

@@ -555,4 +555,107 @@ declare const hybridRank: (vectorResults: ReadonlyArray<RetrievedChunk>, textRes
  * @experimental
  */
 declare const bm25LexicalStore: () => RagLexicalStore;
-export { type IndexInput, type IndexResult, type LexicalMatch, type Rag, type RagConfig, type RagContext, type RagEmbedder, type RagLexicalStore, type RagNamedFilter, type RagSource, type RagTextStore, type RagToolOptions, type RagVectorMatch, type RagVectorMatches, type RagVectorQueryInput, type RagVectorRecord, type RagVectorUpsertInput, type RagVectors, type RemoveInput, type RetrieveOptions, type RetrieveResult, type RetrievedChunk, type StoredRagChunk, bm25LexicalStore, contentHash, defineRag, fixedWindowChunks, guessMimeTypeFromExtension, hybridRank };
+/**
+ * Keep a RAG index in step with a table, so the table IS the index.
+ *
+ * `rag.index(...)` is a manual call, which means an app that edits a document
+ * has to remember to re-index it — and a forgotten call is invisible: retrieval
+ * keeps answering, just from stale text. The fix is to hang the re-index off the
+ * write itself.
+ *
+ * Embedding is network I/O, so it cannot run inside the mutation that wrote the
+ * row. The bridge is the two seams that already exist: a table `.triggers()`
+ * handler runs in the write path and can `ctx.scheduler.runAfter(...)`, so the
+ * trigger records the intent and an internal ACTION does the embedding a moment
+ * later. That is what {@link ragSyncTriggers} wires up.
+ *
+ * Re-indexing unchanged text is already cheap — `rag.index` short-circuits on a
+ * content hash — but this skips scheduling entirely when an update didn't touch
+ * the indexed text, so an unrelated column edit costs nothing at all.
+ */
+/**
+ * A dispatchable function reference — the `internal.docs.reindex` you pass as
+ * `action`. Typed structurally (rather than `unknown`) so passing the wrong
+ * thing is a compile error: mis-wiring the action is the mistake this API is
+ * most likely to see, and it would otherwise surface as a silent no-op.
+ */
+interface RagSyncActionReference {
+  readonly __lunoraRef: string;
+}
+/** Structural slice of `ctx.scheduler` — enough to defer the re-index. */
+interface RagSyncScheduler {
+  runAfter: (delayMs: number, target: unknown, args?: Record<string, unknown>) => Promise<string>;
+}
+/** Structural slice of the `TriggerCtx` a `.triggers()` handler receives. */
+interface RagSyncTriggerContext {
+  readonly scheduler: RagSyncScheduler;
+}
+/** The trigger events this helper handles, narrowed to what it reads. */
+interface RagSyncEvent {
+  readonly doc?: Record<string, unknown>;
+  readonly id: string;
+  readonly previous?: Record<string, unknown>;
+}
+/** What the scheduled action receives — one document to re-index, or one to drop. */
+interface RagSyncArgs extends Record<string, unknown> {
+  /** `true` when the source row was deleted: call `rag.remove({ id })`. */
+  deleted?: boolean;
+  /** The source id — the same `id` you pass to `rag.index`/`rag.remove`. */
+  id: string;
+  /** The text to embed. Absent on a delete. */
+  text?: string;
+}
+interface RagSyncOptions<Document extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * The internal action to dispatch — it receives {@link RagSyncArgs} and calls
+   * `rag.index` / `rag.remove`. An action, not a mutation: embedding is network
+   * I/O and never runs in the deterministic write path.
+   */
+  action: RagSyncActionReference;
+  /**
+   * How long to wait before re-indexing. A small delay coalesces nothing by
+   * itself, but it keeps the embed off the write's own tail latency. Default
+   * `0` — as soon as the mutation commits.
+   */
+  delayMs?: number;
+  /** The source id to index under. Defaults to the row's own id. */
+  id?: (document: Document) => string;
+  /** The text to embed. Return `undefined` to skip the row (a draft, an empty body). */
+  text: (document: Document) => string | undefined;
+}
+/** One trigger definition, structurally — matches what `.triggers((t) => …)` returns. */
+type RagSyncHandler = (context: RagSyncTriggerContext, event: RagSyncEvent) => Promise<void>;
+/**
+ * Build the three write-path handlers that keep a RAG index in step with a
+ * table. Wire them into the table's `.triggers()`:
+ *
+ * ```ts
+ * const sync = ragSyncTriggers({ action: internal.docs.reindex, text: (doc) => doc.body });
+ *
+ * export const schema = defineSchema({
+ *     docs: defineTable({ body: v.string(), title: v.string() }).triggers((t) => ({
+ *         ragDelete: t.afterDelete(sync.afterDelete),
+ *         ragInsert: t.afterInsert(sync.afterInsert),
+ *         ragUpdate: t.afterUpdate(sync.afterUpdate),
+ *     })),
+ * });
+ * ```
+ *
+ * The action on the other end is three lines:
+ *
+ * ```ts
+ * export const reindex = internalAction.input({ deleted: v.optional(v.boolean()), id: v.string(), text: v.optional(v.string()) }).action(
+ *     async ({ args, ctx }) => {
+ *         const rag = docsRag(ctx);
+ *
+ *         await (args.deleted === true || args.text === undefined ? rag.remove({ id: args.id }) : rag.index({ id: args.id, text: args.text }));
+ *     },
+ * );
+ * ```
+ */
+declare const ragSyncTriggers: <Document extends Record<string, unknown> = Record<string, unknown>>(options: RagSyncOptions<Document>) => {
+  afterDelete: RagSyncHandler;
+  afterInsert: RagSyncHandler;
+  afterUpdate: RagSyncHandler;
+};
+export { type IndexInput, type IndexResult, type LexicalMatch, type Rag, type RagConfig, type RagContext, type RagEmbedder, type RagLexicalStore, type RagNamedFilter, type RagSource, type RagSyncActionReference, type RagSyncArgs, type RagSyncOptions, type RagTextStore, type RagToolOptions, type RagVectorMatch, type RagVectorMatches, type RagVectorQueryInput, type RagVectorRecord, type RagVectorUpsertInput, type RagVectors, type RemoveInput, type RetrieveOptions, type RetrieveResult, type RetrievedChunk, type StoredRagChunk, bm25LexicalStore, contentHash, defineRag, fixedWindowChunks, guessMimeTypeFromExtension, hybridRank, ragSyncTriggers };

package/dist/rag/index.d.ts

@@ -555,4 +555,107 @@ declare const hybridRank: (vectorResults: ReadonlyArray<RetrievedChunk>, textRes
  * @experimental
  */
 declare const bm25LexicalStore: () => RagLexicalStore;
-export { type IndexInput, type IndexResult, type LexicalMatch, type Rag, type RagConfig, type RagContext, type RagEmbedder, type RagLexicalStore, type RagNamedFilter, type RagSource, type RagTextStore, type RagToolOptions, type RagVectorMatch, type RagVectorMatches, type RagVectorQueryInput, type RagVectorRecord, type RagVectorUpsertInput, type RagVectors, type RemoveInput, type RetrieveOptions, type RetrieveResult, type RetrievedChunk, type StoredRagChunk, bm25LexicalStore, contentHash, defineRag, fixedWindowChunks, guessMimeTypeFromExtension, hybridRank };
+/**
+ * Keep a RAG index in step with a table, so the table IS the index.
+ *
+ * `rag.index(...)` is a manual call, which means an app that edits a document
+ * has to remember to re-index it — and a forgotten call is invisible: retrieval
+ * keeps answering, just from stale text. The fix is to hang the re-index off the
+ * write itself.
+ *
+ * Embedding is network I/O, so it cannot run inside the mutation that wrote the
+ * row. The bridge is the two seams that already exist: a table `.triggers()`
+ * handler runs in the write path and can `ctx.scheduler.runAfter(...)`, so the
+ * trigger records the intent and an internal ACTION does the embedding a moment
+ * later. That is what {@link ragSyncTriggers} wires up.
+ *
+ * Re-indexing unchanged text is already cheap — `rag.index` short-circuits on a
+ * content hash — but this skips scheduling entirely when an update didn't touch
+ * the indexed text, so an unrelated column edit costs nothing at all.
+ */
+/**
+ * A dispatchable function reference — the `internal.docs.reindex` you pass as
+ * `action`. Typed structurally (rather than `unknown`) so passing the wrong
+ * thing is a compile error: mis-wiring the action is the mistake this API is
+ * most likely to see, and it would otherwise surface as a silent no-op.
+ */
+interface RagSyncActionReference {
+  readonly __lunoraRef: string;
+}
+/** Structural slice of `ctx.scheduler` — enough to defer the re-index. */
+interface RagSyncScheduler {
+  runAfter: (delayMs: number, target: unknown, args?: Record<string, unknown>) => Promise<string>;
+}
+/** Structural slice of the `TriggerCtx` a `.triggers()` handler receives. */
+interface RagSyncTriggerContext {
+  readonly scheduler: RagSyncScheduler;
+}
+/** The trigger events this helper handles, narrowed to what it reads. */
+interface RagSyncEvent {
+  readonly doc?: Record<string, unknown>;
+  readonly id: string;
+  readonly previous?: Record<string, unknown>;
+}
+/** What the scheduled action receives — one document to re-index, or one to drop. */
+interface RagSyncArgs extends Record<string, unknown> {
+  /** `true` when the source row was deleted: call `rag.remove({ id })`. */
+  deleted?: boolean;
+  /** The source id — the same `id` you pass to `rag.index`/`rag.remove`. */
+  id: string;
+  /** The text to embed. Absent on a delete. */
+  text?: string;
+}
+interface RagSyncOptions<Document extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * The internal action to dispatch — it receives {@link RagSyncArgs} and calls
+   * `rag.index` / `rag.remove`. An action, not a mutation: embedding is network
+   * I/O and never runs in the deterministic write path.
+   */
+  action: RagSyncActionReference;
+  /**
+   * How long to wait before re-indexing. A small delay coalesces nothing by
+   * itself, but it keeps the embed off the write's own tail latency. Default
+   * `0` — as soon as the mutation commits.
+   */
+  delayMs?: number;
+  /** The source id to index under. Defaults to the row's own id. */
+  id?: (document: Document) => string;
+  /** The text to embed. Return `undefined` to skip the row (a draft, an empty body). */
+  text: (document: Document) => string | undefined;
+}
+/** One trigger definition, structurally — matches what `.triggers((t) => …)` returns. */
+type RagSyncHandler = (context: RagSyncTriggerContext, event: RagSyncEvent) => Promise<void>;
+/**
+ * Build the three write-path handlers that keep a RAG index in step with a
+ * table. Wire them into the table's `.triggers()`:
+ *
+ * ```ts
+ * const sync = ragSyncTriggers({ action: internal.docs.reindex, text: (doc) => doc.body });
+ *
+ * export const schema = defineSchema({
+ *     docs: defineTable({ body: v.string(), title: v.string() }).triggers((t) => ({
+ *         ragDelete: t.afterDelete(sync.afterDelete),
+ *         ragInsert: t.afterInsert(sync.afterInsert),
+ *         ragUpdate: t.afterUpdate(sync.afterUpdate),
+ *     })),
+ * });
+ * ```
+ *
+ * The action on the other end is three lines:
+ *
+ * ```ts
+ * export const reindex = internalAction.input({ deleted: v.optional(v.boolean()), id: v.string(), text: v.optional(v.string()) }).action(
+ *     async ({ args, ctx }) => {
+ *         const rag = docsRag(ctx);
+ *
+ *         await (args.deleted === true || args.text === undefined ? rag.remove({ id: args.id }) : rag.index({ id: args.id, text: args.text }));
+ *     },
+ * );
+ * ```
+ */
+declare const ragSyncTriggers: <Document extends Record<string, unknown> = Record<string, unknown>>(options: RagSyncOptions<Document>) => {
+  afterDelete: RagSyncHandler;
+  afterInsert: RagSyncHandler;
+  afterUpdate: RagSyncHandler;
+};
+export { type IndexInput, type IndexResult, type LexicalMatch, type Rag, type RagConfig, type RagContext, type RagEmbedder, type RagLexicalStore, type RagNamedFilter, type RagSource, type RagSyncActionReference, type RagSyncArgs, type RagSyncOptions, type RagTextStore, type RagToolOptions, type RagVectorMatch, type RagVectorMatches, type RagVectorQueryInput, type RagVectorRecord, type RagVectorUpsertInput, type RagVectors, type RemoveInput, type RetrieveOptions, type RetrieveResult, type RetrievedChunk, type StoredRagChunk, bm25LexicalStore, contentHash, defineRag, fixedWindowChunks, guessMimeTypeFromExtension, hybridRank, ragSyncTriggers };

package/dist/rag/index.mjs

@@ -1 +1 @@
-import{default as r}from"../packem_shared/fixedWindowChunks-XJRXHEoz.mjs";import{default as a}from"../packem_shared/defineRag-Drf-Vn0B.mjs";import{contentHash as s,guessMimeTypeFromExtension as d}from"../packem_shared/contentHash-BIn6ECP8.mjs";import{default as n}from"../packem_shared/hybridRank-U6PmGuz1.mjs";import{default as i}from"../packem_shared/bm25LexicalStore-RA9sesFC.mjs";export{i as bm25LexicalStore,s as contentHash,a as defineRag,r as fixedWindowChunks,d as guessMimeTypeFromExtension,n as hybridRank};
+import{default as o}from"../packem_shared/fixedWindowChunks-XJRXHEoz.mjs";import{default as a}from"../packem_shared/defineRag-Drf-Vn0B.mjs";import{contentHash as s,guessMimeTypeFromExtension as m}from"../packem_shared/contentHash-BIn6ECP8.mjs";import{default as x}from"../packem_shared/hybridRank-U6PmGuz1.mjs";import{default as i}from"../packem_shared/bm25LexicalStore-RA9sesFC.mjs";import{ragSyncTriggers as u}from"../packem_shared/ragSyncTriggers-BY8QgX4d.mjs";export{i as bm25LexicalStore,s as contentHash,a as defineRag,o as fixedWindowChunks,m as guessMimeTypeFromExtension,x as hybridRank,u as ragSyncTriggers};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/ai",
-  "version": "1.0.0-alpha.56",
+  "version": "1.0.0-alpha.57",
   "description": "Workers AI helper for Lunora: provider-agnostic AI SDK access from functions, Workers AI by default",
   "keywords": [
     "ai",
@@ -53,7 +53,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/errors": "1.0.0-alpha.20",
+    "@lunora/errors": "1.0.0-alpha.21",
     "ai": "7.0.37",
     "workers-ai-provider": "4.0.0"
   },