@absolutejs/rag 0.5.0 → 0.6.1

package/dist/src/index.d.ts

@@ -30,3 +30,5 @@ export type { AIHTMXRenderConfig, RAGAnswerWorkflowState, RAGBackendCapabilities
 export type { RAGJobState, RAGJobStateStore, RAGPostgresNativeDiagnostics, RAGRetrievalComparisonCandidateInput, RAGRetrievalComparisonHistoryResponse, RAGRetrievalComparisonHistoryStore, RAGRetrievalComparisonRequest, RAGRetrievalComparisonResponse, RAGRetrievalComparisonRun, RAGSearchTraceGroupHistoryResponse, RAGSearchTraceHistoryResponse, RAGSearchTracePrunePreviewResponse, RAGSearchTracePruneHistoryResponse, RAGSearchTracePruneResponse, RAGSearchTracePruneInput, RAGSearchTracePrunePreview, RAGSearchTracePruneResult, RAGSearchTracePruneHistoryStore, RAGSearchTracePruneRun, RAGSearchTraceRetentionRuntime, RAGSearchTraceRetentionSchedule, RAGSearchTraceStats, RAGSearchTraceStatsResponse, } from "../types/engine";
 export type * from "@absolutejs/ai";
 export type * from "../types/engine";
+export { corpusTextHash, planRAGCorpus, reconcileRAGCorpus, } from "./retrieval/corpus";
+export type { RAGCorpusApply, RAGCorpusDocument, RAGCorpusPlan, RAGCorpusRecord, RAGCorpusResult, RAGCorpusStore, } from "./retrieval/corpus";

package/dist/src/retrieval/corpus.d.ts

@@ -0,0 +1,81 @@
+/** One embedded chunk, as the host has it recorded. */
+export type RAGCorpusRecord = {
+    chunkId: string;
+    /** Hash of the exact text that was embedded, so a content change is
+     *  detectable without storing the text twice. */
+    textHash: string;
+};
+/** One chunk the owner should have embedded right now. */
+export type RAGCorpusDocument = {
+    chunkId: string;
+    text: string;
+};
+/**
+ * Host-owned persistence for what is embedded, scoped by owner.
+ *
+ * `Owner` is whatever identifies the subject in the host's model — a profile
+ * id, a tenant id, a workspace key.
+ */
+export type RAGCorpusStore<Owner = string> = {
+    /** Every chunk currently recorded as embedded for this owner. */
+    list: (owner: Owner) => Promise<RAGCorpusRecord[]> | RAGCorpusRecord[];
+    /** Record chunks as embedded. Must be an upsert on chunkId. */
+    remember: (owner: Owner, records: RAGCorpusRecord[]) => Promise<void> | void;
+    /** Forget chunks. Called only AFTER their vectors are gone, so a crash
+     *  in between leaves a re-deletable record rather than an orphan. */
+    forget: (owner: Owner, chunkIds: string[]) => Promise<void> | void;
+};
+/** What a reconcile would do, without doing it. */
+export type RAGCorpusPlan = {
+    /** New or content-changed — these cost embedding tokens. */
+    embed: RAGCorpusDocument[];
+    /** Recorded for this owner but no longer desired — delete their vectors. */
+    remove: string[];
+    /** Already embedded with identical text; skipped, and free. */
+    unchanged: number;
+};
+/** SHA-256 of the text, as `RAGCorpusRecord.textHash`. */
+export declare const corpusTextHash: (text: string) => Promise<string>;
+/**
+ * Diff desired against stored. Pure — no embedding, no deletion, no I/O beyond
+ * the store's `list`, so a host can show the cost of a pass before paying it.
+ *
+ * A duplicate chunkId in `desired` is a host bug that would otherwise embed the
+ * same id twice and leave whichever landed last; the first occurrence wins and
+ * the rest are dropped.
+ */
+export declare const planRAGCorpus: <Owner = string>(store: RAGCorpusStore<Owner>, owner: Owner, desired: RAGCorpusDocument[]) => Promise<RAGCorpusPlan>;
+export type RAGCorpusApply<Owner = string> = {
+    /**
+     * Embed + upsert these chunks.
+     *
+     * Return a COUNT only when the whole plan was written — the count is then
+     * taken at its word and every planned chunk is recorded as embedded. If the
+     * pass can stop early (a budget ceiling, an abort signal, a partial failure
+     * it chooses to swallow), return the chunk ids actually written instead.
+     *
+     * Getting this wrong is silent and permanent: a chunk recorded as embedded
+     * that was not will match `unchanged` on every later pass, so it is never
+     * embedded again until its source text happens to change. Reporting ids is
+     * always safe; reporting a count is a promise the caller cannot verify.
+     */
+    embed: (docs: RAGCorpusDocument[], owner: Owner) => Promise<number | readonly string[]> | number | readonly string[];
+    /** Delete these chunk ids from the vector store. */
+    remove: (chunkIds: string[], owner: Owner) => Promise<void> | void;
+};
+export type RAGCorpusResult = {
+    embedded: number;
+    removed: number;
+    unchanged: number;
+};
+/**
+ * Bring an owner's embedded corpus in line with what they should have.
+ *
+ * Ordering is deliberate. Deletions run FIRST and their records are forgotten
+ * only after the vectors are gone: a crash mid-pass then leaves a record whose
+ * vector may already be deleted, which a later pass simply deletes again
+ * (harmless), rather than a vector whose record is gone — which nothing could
+ * ever find. Embedding records its digests after the write for the same reason,
+ * so an interrupted run never claims to have embedded something it did not.
+ */
+export declare const reconcileRAGCorpus: <Owner = string>(store: RAGCorpusStore<Owner>, owner: Owner, desired: RAGCorpusDocument[], apply: RAGCorpusApply<Owner>) => Promise<RAGCorpusResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rag",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "homepage": "https://github.com/absolutejs/rag",
   "bugs": {
     "url": "https://github.com/absolutejs/rag/issues"
@@ -236,4 +236,4 @@
       ]
     }
   }
-}
+}