@absolutejs/rag 0.6.2 → 0.7.0

package/dist/src/index.d.ts

@@ -1,7 +1,7 @@
 export { ragChat, ragChat as ragPlugin } from "./chat/chat";
 export { createRAGHTMXConfig, createRAGHTMXWorkflowRenderConfig, } from "./presentation/htmxConfig";
 export { createRAGEmbeddingProvider, resolveRAGEmbeddingProvider, validateRAGEmbeddingDimensions, } from "./retrieval/embedding";
-export { embeddingCacheKey, isEmbeddingQuotaError, withEmbeddingBudget, type RAGBudgetedEmbedding, type RAGEmbeddingCache, type RAGEmbeddingHealth, type WithEmbeddingBudgetOptions, } from "./retrieval/embeddingBudget";
+export { classifyEmbeddingError, createRAGEmbeddingError, embeddingCacheKey, isEmbeddingQuotaError, isRetryableEmbeddingError, withEmbeddingBudget, type RAGBudgetedEmbedding, type RAGEmbeddingCache, type RAGEmbeddingHealth, type RAGEmbeddingError, type RAGEmbeddingErrorKind, type WithEmbeddingBudgetOptions, } from "./retrieval/embeddingBudget";
 export { applyRAGReranking, createHeuristicRAGReranker, createRAGReranker, resolveRAGReranker, } from "./retrieval/reranking";
 export { createCohereRAGReranker, createJinaRAGReranker, createVoyageRAGReranker, } from "./providers/rerankerProviders";
 export { applyRAGQueryTransform, createHeuristicRAGQueryTransform, createRAGQueryTransform, resolveRAGQueryTransform, } from "./retrieval/queryTransforms";

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

@@ -40,9 +40,8 @@ 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.
+ * Identical duplicate chunk ids are collapsed. Conflicting text for the same
+ * id is rejected because silently choosing either value corrupts reconciliation.
  */
 export declare const planRAGCorpus: <Owner = string>(store: RAGCorpusStore<Owner>, owner: Owner, desired: RAGCorpusDocument[]) => Promise<RAGCorpusPlan>;
 export type RAGCorpusApply<Owner = string> = {

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

@@ -8,10 +8,24 @@ export type RAGEmbeddingCache = {
 };
 /** Stable cache key for a piece of text under one model + input type. A
  *  passage and a query embed differently, so they must not share an entry. */
-export declare const embeddingCacheKey: (text: string, model?: string, kind?: string) => Promise<string>;
+export declare const embeddingCacheKey: (text: string, model?: string, kind?: string, identity?: string) => Promise<string>;
+export type RAGEmbeddingErrorKind = "allowance" | "rate_limit" | "input" | "transient" | "unknown";
+export type RAGEmbeddingError = Error & {
+    embeddingErrorKind: RAGEmbeddingErrorKind;
+    retryAfterMs?: number;
+    status?: number;
+};
+export declare const createRAGEmbeddingError: (input: {
+    message: string;
+    kind?: RAGEmbeddingErrorKind;
+    retryAfterMs?: number;
+    status?: number;
+}) => RAGEmbeddingError;
+export declare const classifyEmbeddingError: (error: unknown) => RAGEmbeddingErrorKind;
 /** Whether a provider error means "you are out of embedding allowance",
  *  as opposed to a transient failure worth retrying. */
 export declare const isEmbeddingQuotaError: (error: unknown) => boolean;
+export declare const isRetryableEmbeddingError: (error: unknown) => boolean;
 export type RAGEmbeddingHealth = {
     /** Last error message seen, cleared by the next success. */
     lastError: string | null;
@@ -21,6 +35,12 @@ export type RAGEmbeddingHealth = {
     reused: number;
     /** Embeddings actually paid for since process start. */
     embedded: number;
+    attempted: number;
+    failed: number;
+    inFlight: number;
+    cacheFailures: number;
+    rateLimitedAt: Date | null;
+    recoveredAt: Date | null;
 };
 export type RAGBudgetedEmbedding = RAGEmbeddingProvider & {
     health: () => RAGEmbeddingHealth;
@@ -30,6 +50,11 @@ export type WithEmbeddingBudgetOptions = {
     /** Notified the first time the allowance is reported spent — wire this to
      *  an alert, because a degraded index is otherwise invisible. */
     onQuotaExhausted?: (error: unknown) => void;
+    onCacheError?: (error: unknown, operation: "get" | "set") => void;
+    /** Additional provider/revision identity included in every cache key. */
+    cacheNamespace?: string;
+    /** Admission hook for host-owned token budgets. Throw to reject the call. */
+    beforeEmbed?: (input: Parameters<RAGEmbeddingFunction>[0]) => Promise<void> | void;
 };
 /** Wrap an embedding function so repeated text is not re-embedded and quota
  *  exhaustion is observable instead of silent. */

package/dist/types/engine.d.ts

@@ -296,6 +296,8 @@ export type RAGEmbeddingProvider = {
     embed: RAGEmbeddingFunction;
     dimensions?: number;
     defaultModel?: string;
+    /** Stable provider/model revision identity used by embedding caches. */
+    cacheNamespace?: string;
 };
 export type RAGEmbeddingProviderLike = RAGEmbeddingFunction | RAGEmbeddingProvider;
 export type RAGContentFormat = "text" | "markdown" | "html" | "jsonl" | "tsv" | "csv" | "xml" | "yaml";
@@ -605,6 +607,9 @@ export type RAGHybridSearchOptions = {
 };
 export type RAGUpsertInput = {
     chunks: RAGDocumentChunk[];
+    signal?: AbortSignal;
+    embeddingConcurrency?: number;
+    upsertBatchSize?: number;
 };
 export type RAGDocumentIngestInput = {
     documents: RAGIngestDocument[];
@@ -4243,6 +4248,9 @@ export type RAGIngestSourceInput = {
      * set is removed even if the new ingest produces fewer chunks.
      */
     previousChunkCount?: number;
+    signal?: AbortSignal;
+    embeddingConcurrency?: number;
+    upsertBatchSize?: number;
 };
 export type RAGIngestSourceResult = {
     sourceId: string;

package/dist/types/retrieval.d.ts

@@ -35,4 +35,5 @@ export type CreateRAGEmbeddingProviderOptions = {
     embed: RAGEmbeddingFunction;
     dimensions?: number;
     defaultModel?: string;
+    cacheNamespace?: string;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rag",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "homepage": "https://github.com/absolutejs/rag",
   "bugs": {
     "url": "https://github.com/absolutejs/rag/issues"