@absolutejs/rag 0.1.2 → 0.2.0

package/dist/src/index.d.ts

@@ -1,6 +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 { 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/embeddingBudget.d.ts

@@ -0,0 +1,36 @@
+import type { RAGEmbeddingFunction, RAGEmbeddingProvider } from "../../types/engine";
+/** Persistence for embedding reuse. The host owns storage (Postgres, Redis,
+ *  an LRU) — this package only decides WHAT to remember and when to skip. */
+export type RAGEmbeddingCache = {
+    /** Previously embedded vector for this exact text, if any. */
+    get: (key: string) => Promise<number[] | null> | number[] | null;
+    set: (key: string, embedding: number[]) => Promise<void> | void;
+};
+/** 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>;
+/** 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 type RAGEmbeddingHealth = {
+    /** Last error message seen, cleared by the next success. */
+    lastError: string | null;
+    /** When the provider last said the allowance is spent. */
+    quotaExhaustedAt: Date | null;
+    /** Embeddings served from cache since process start. */
+    reused: number;
+    /** Embeddings actually paid for since process start. */
+    embedded: number;
+};
+export type RAGBudgetedEmbedding = RAGEmbeddingProvider & {
+    health: () => RAGEmbeddingHealth;
+};
+export type WithEmbeddingBudgetOptions = {
+    cache?: RAGEmbeddingCache;
+    /** 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;
+};
+/** Wrap an embedding function so repeated text is not re-embedded and quota
+ *  exhaustion is observable instead of silent. */
+export declare const withEmbeddingBudget: (provider: RAGEmbeddingProvider | RAGEmbeddingFunction, options?: WithEmbeddingBudgetOptions) => RAGBudgetedEmbedding;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/rag",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "homepage": "https://github.com/absolutejs/rag",
   "bugs": {
     "url": "https://github.com/absolutejs/rag/issues"
@@ -197,7 +197,7 @@
     "lint": "eslint . --max-warnings 0",
     "format": "prettier --write .",
     "test": "bun test",
-    "release": "bun publish --access public"
+    "release": "bun run build && bun publish --access public"
   },
   "publishConfig": {
     "access": "public"