@halo-sdk/rag 1.0.0

package/README.md

@@ -0,0 +1,31 @@
+# @halo-sdk/rag
+
+Cache-aware retrieval-augmented generation for Halo AI SDK.
+
+Most RAG implementations re-retrieve every turn and splice fresh documents into the prompt — which silently busts the provider's prefix cache on every message. `@halo-sdk/rag` produces a reusable cache segment with two cache-preserving policies:
+
+- **Sticky retrieval** — near-duplicate consecutive queries skip re-retrieval entirely; the segment (and the cache after it) is untouched.
+- **Append-only growth** — when a new result set extends the previous one, new docs are appended rather than rebuilding, so the already-cached prefix stays valid.
+
+## Usage
+
+```ts
+import { Halo } from "@halo-sdk/core";
+import { CacheAwareRag, VectorRetriever, MemoryVectorStore } from "@halo-sdk/rag";
+
+const store = new MemoryVectorStore();
+// store.add(docs, await embedder.embed(docs.map(d => d.text)))
+const retriever = new VectorRetriever(myEmbedder, store);
+
+const rag = new CacheAwareRag({ retriever, k: 4 });
+await rag.update("what is prompt caching?");
+
+const agent = halo.agent({
+  /* ... */
+});
+agent.setContextSegments([rag.segment]);
+```
+
+## Seams
+
+`Embedder`, `VectorStore`, and `Retriever` are interfaces — bring your own embedding model and vector DB. `MemoryVectorStore` (cosine) and `VectorRetriever` are included for tests, demos, and small corpora. Halo owns the cache-aware orchestration, not the embedding/storage.

package/dist/index.cjs

@@ -0,0 +1,131 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CacheAwareRag: () => CacheAwareRag,
+  MemoryVectorStore: () => MemoryVectorStore,
+  VectorRetriever: () => VectorRetriever,
+  cosineSimilarity: () => cosineSimilarity,
+  jaccardSimilarity: () => jaccardSimilarity
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@halo-sdk/core");
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+var MemoryVectorStore = class {
+  _items = [];
+  add(docs, embeddings) {
+    for (let i = 0; i < docs.length; i++) {
+      this._items.push({ doc: docs[i], embedding: embeddings[i] });
+    }
+  }
+  query(embedding, k) {
+    return this._items.map(({ doc, embedding: e }) => ({ ...doc, score: cosineSimilarity(embedding, e) })).sort((a, b) => b.score - a.score).slice(0, k);
+  }
+};
+var VectorRetriever = class {
+  constructor(_embedder, _store) {
+    this._embedder = _embedder;
+    this._store = _store;
+  }
+  _embedder;
+  _store;
+  async retrieve(query, k) {
+    const [queryEmbedding] = await this._embedder.embed([query]);
+    return [...await this._store.query(queryEmbedding, k)];
+  }
+};
+var CacheAwareRag = class {
+  segment;
+  _retriever;
+  _k;
+  _stickyThreshold;
+  _formatDoc;
+  _similarity;
+  _lastQuery = null;
+  _docIds = [];
+  constructor(opts) {
+    this._retriever = opts.retriever;
+    this._k = opts.k ?? 4;
+    this._stickyThreshold = opts.stickyThreshold ?? 0.85;
+    this._formatDoc = opts.formatDoc ?? ((d) => `[${d.id}] ${d.text}`);
+    this._similarity = opts.similarity ?? jaccardSimilarity;
+    this.segment = new import_core.StableContext({ id: opts.segmentId ?? "rag", kind: "rag", messages: [] });
+  }
+  /** Document ids currently in the segment, in order. */
+  get documentIds() {
+    return this._docIds;
+  }
+  /**
+   * Refresh the segment for `query`. Returns whether a retrieval actually ran
+   * (`false` = sticky reuse) and whether the cache was preserved (append-only or
+   * skip) vs. busted (rebuild).
+   */
+  async update(query) {
+    if (this._lastQuery !== null && this._docIds.length > 0 && this._similarity(query, this._lastQuery) >= this._stickyThreshold) {
+      return { retrieved: false, cachePreserved: true };
+    }
+    this._lastQuery = query;
+    const docs = await this._retriever.retrieve(query, this._k);
+    const newIds = docs.map((d) => d.id);
+    const isPrefix = this._docIds.length > 0 && this._docIds.length <= newIds.length && this._docIds.every((id, i) => id === newIds[i]);
+    if (isPrefix) {
+      const extra = docs.slice(this._docIds.length);
+      this.segment.append(extra.map((d) => this._toMessage(d)));
+      this._docIds = newIds;
+      return { retrieved: true, cachePreserved: true };
+    }
+    this.segment.setMessages(docs.map((d) => this._toMessage(d)));
+    this._docIds = newIds;
+    return { retrieved: true, cachePreserved: this._docIds.length === 0 };
+  }
+  _toMessage(doc) {
+    return { role: "user", content: this._formatDoc(doc), discardable: false };
+  }
+};
+function jaccardSimilarity(a, b) {
+  const ta = new Set(a.toLowerCase().match(/\w+/g) ?? []);
+  const tb = new Set(b.toLowerCase().match(/\w+/g) ?? []);
+  if (ta.size === 0 && tb.size === 0) return 1;
+  let inter = 0;
+  for (const t of ta) if (tb.has(t)) inter++;
+  const union = ta.size + tb.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CacheAwareRag,
+  MemoryVectorStore,
+  VectorRetriever,
+  cosineSimilarity,
+  jaccardSimilarity
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { StableContext, type CacheSegment, type ChatMessage } from \"@halo-sdk/core\";\n\n/** A retrievable document. */\nexport interface RagDocument {\n  id: string;\n  text: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** A document with a relevance score (higher = more relevant). */\nexport interface ScoredDocument extends RagDocument {\n  score: number;\n}\n\n// ── Seams (bring your own implementation) ──\n\n/** Turns text into vectors. Seam — wrap any embedding model. */\nexport interface Embedder {\n  embed(texts: string[]): Promise<number[][]>;\n}\n\n/** Stores + searches document vectors. Seam — wrap any vector DB. */\nexport interface VectorStore {\n  add(docs: RagDocument[], embeddings: number[][]): Promise<void> | void;\n  query(embedding: number[], k: number): Promise<ScoredDocument[]> | ScoredDocument[];\n}\n\n/** Produces relevant documents for a query. Seam — the top-level RAG interface. */\nexport interface Retriever {\n  retrieve(query: string, k: number): Promise<RagDocument[]>;\n}\n\n// ── In-memory defaults (dependency-free) ──\n\n/** Cosine similarity of two equal-length vectors. */\nexport function cosineSimilarity(a: number[], b: number[]): number {\n  let dot = 0;\n  let na = 0;\n  let nb = 0;\n  for (let i = 0; i < a.length; i++) {\n    dot += a[i]! * b[i]!;\n    na += a[i]! * a[i]!;\n    nb += b[i]! * b[i]!;\n  }\n  const denom = Math.sqrt(na) * Math.sqrt(nb);\n  return denom === 0 ? 0 : dot / denom;\n}\n\n/** A simple in-memory cosine vector store. Good for tests, demos, small corpora. */\nexport class MemoryVectorStore implements VectorStore {\n  private _items: { doc: RagDocument; embedding: number[] }[] = [];\n\n  add(docs: RagDocument[], embeddings: number[][]): void {\n    for (let i = 0; i < docs.length; i++) {\n      this._items.push({ doc: docs[i]!, embedding: embeddings[i]! });\n    }\n  }\n\n  query(embedding: number[], k: number): ScoredDocument[] {\n    return this._items\n      .map(({ doc, embedding: e }) => ({ ...doc, score: cosineSimilarity(embedding, e) }))\n      .sort((a, b) => b.score - a.score)\n      .slice(0, k);\n  }\n}\n\n/** Build a {@link Retriever} from an {@link Embedder} + {@link VectorStore}. */\nexport class VectorRetriever implements Retriever {\n  constructor(\n    private readonly _embedder: Embedder,\n    private readonly _store: VectorStore,\n  ) {}\n\n  async retrieve(query: string, k: number): Promise<RagDocument[]> {\n    const [queryEmbedding] = await this._embedder.embed([query]);\n    return [...(await this._store.query(queryEmbedding!, k))];\n  }\n}\n\n// ── Cache-aware orchestration (what Halo owns) ──\n\nexport interface CacheAwareRagOptions {\n  retriever: Retriever;\n  /** Docs to retrieve per query. Default 4. */\n  k?: number;\n  /**\n   * Sticky-retrieval threshold. If the new query's lexical similarity to the\n   * last one is ≥ this, retrieval is skipped and the cached segment is reused.\n   * Default 0.85. Set to 1 to always re-retrieve.\n   */\n  stickyThreshold?: number;\n  /** Segment id (for cache miss attribution). Default \"rag\". */\n  segmentId?: string;\n  /** Format a document into a context message. Default: `[doc id] text`. */\n  formatDoc?: (doc: RagDocument) => string;\n  /** Override the lexical similarity measure (default token Jaccard). */\n  similarity?: (a: string, b: string) => number;\n}\n\n/**\n * Cache-aware RAG: turns a {@link Retriever} into a reusable {@link CacheSegment}\n * with two cache-preserving policies:\n *\n * - **sticky retrieval** — when consecutive queries are near-duplicates, skip\n *   re-retrieval entirely so the segment (and the prefix cache after it) is\n *   untouched, and\n * - **append-only growth** — when a new result set extends the previous one,\n *   append the new docs instead of rebuilding, keeping the already-cached prefix\n *   valid; only a genuinely different result set rebuilds (and busts) the block.\n *\n * Attach `rag.segment` via `agent.setContextSegments([rag.segment])`.\n */\nexport class CacheAwareRag {\n  readonly segment: StableContext;\n\n  private readonly _retriever: Retriever;\n  private readonly _k: number;\n  private readonly _stickyThreshold: number;\n  private readonly _formatDoc: (doc: RagDocument) => string;\n  private readonly _similarity: (a: string, b: string) => number;\n\n  private _lastQuery: string | null = null;\n  private _docIds: string[] = [];\n\n  constructor(opts: CacheAwareRagOptions) {\n    this._retriever = opts.retriever;\n    this._k = opts.k ?? 4;\n    this._stickyThreshold = opts.stickyThreshold ?? 0.85;\n    this._formatDoc = opts.formatDoc ?? ((d) => `[${d.id}] ${d.text}`);\n    this._similarity = opts.similarity ?? jaccardSimilarity;\n    this.segment = new StableContext({ id: opts.segmentId ?? \"rag\", kind: \"rag\", messages: [] });\n  }\n\n  /** Document ids currently in the segment, in order. */\n  get documentIds(): readonly string[] {\n    return this._docIds;\n  }\n\n  /**\n   * Refresh the segment for `query`. Returns whether a retrieval actually ran\n   * (`false` = sticky reuse) and whether the cache was preserved (append-only or\n   * skip) vs. busted (rebuild).\n   */\n  async update(query: string): Promise<{ retrieved: boolean; cachePreserved: boolean }> {\n    if (\n      this._lastQuery !== null &&\n      this._docIds.length > 0 &&\n      this._similarity(query, this._lastQuery) >= this._stickyThreshold\n    ) {\n      return { retrieved: false, cachePreserved: true }; // sticky — segment untouched\n    }\n\n    this._lastQuery = query;\n    const docs = await this._retriever.retrieve(query, this._k);\n    const newIds = docs.map((d) => d.id);\n\n    // Append-only when the previous ids are an ordered prefix of the new ids.\n    const isPrefix =\n      this._docIds.length > 0 &&\n      this._docIds.length <= newIds.length &&\n      this._docIds.every((id, i) => id === newIds[i]);\n\n    if (isPrefix) {\n      const extra = docs.slice(this._docIds.length);\n      this.segment.append(extra.map((d) => this._toMessage(d)));\n      this._docIds = newIds;\n      return { retrieved: true, cachePreserved: true };\n    }\n\n    this.segment.setMessages(docs.map((d) => this._toMessage(d)));\n    this._docIds = newIds;\n    return { retrieved: true, cachePreserved: this._docIds.length === 0 };\n  }\n\n  private _toMessage(doc: RagDocument): ChatMessage {\n    return { role: \"user\", content: this._formatDoc(doc), discardable: false };\n  }\n}\n\n/** Token-set Jaccard similarity (lowercased word tokens). */\nexport function jaccardSimilarity(a: string, b: string): number {\n  const ta = new Set(a.toLowerCase().match(/\\w+/g) ?? []);\n  const tb = new Set(b.toLowerCase().match(/\\w+/g) ?? []);\n  if (ta.size === 0 && tb.size === 0) return 1;\n  let inter = 0;\n  for (const t of ta) if (tb.has(t)) inter++;\n  const union = ta.size + tb.size - inter;\n  return union === 0 ? 0 : inter / union;\n}\n\nexport type { CacheSegment };\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { StableContext, type CacheSegment } from "@halo-sdk/core";
+/** A retrievable document. */
+export interface RagDocument {
+    id: string;
+    text: string;
+    metadata?: Record<string, unknown>;
+}
+/** A document with a relevance score (higher = more relevant). */
+export interface ScoredDocument extends RagDocument {
+    score: number;
+}
+/** Turns text into vectors. Seam — wrap any embedding model. */
+export interface Embedder {
+    embed(texts: string[]): Promise<number[][]>;
+}
+/** Stores + searches document vectors. Seam — wrap any vector DB. */
+export interface VectorStore {
+    add(docs: RagDocument[], embeddings: number[][]): Promise<void> | void;
+    query(embedding: number[], k: number): Promise<ScoredDocument[]> | ScoredDocument[];
+}
+/** Produces relevant documents for a query. Seam — the top-level RAG interface. */
+export interface Retriever {
+    retrieve(query: string, k: number): Promise<RagDocument[]>;
+}
+/** Cosine similarity of two equal-length vectors. */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/** A simple in-memory cosine vector store. Good for tests, demos, small corpora. */
+export declare class MemoryVectorStore implements VectorStore {
+    private _items;
+    add(docs: RagDocument[], embeddings: number[][]): void;
+    query(embedding: number[], k: number): ScoredDocument[];
+}
+/** Build a {@link Retriever} from an {@link Embedder} + {@link VectorStore}. */
+export declare class VectorRetriever implements Retriever {
+    private readonly _embedder;
+    private readonly _store;
+    constructor(_embedder: Embedder, _store: VectorStore);
+    retrieve(query: string, k: number): Promise<RagDocument[]>;
+}
+export interface CacheAwareRagOptions {
+    retriever: Retriever;
+    /** Docs to retrieve per query. Default 4. */
+    k?: number;
+    /**
+     * Sticky-retrieval threshold. If the new query's lexical similarity to the
+     * last one is ≥ this, retrieval is skipped and the cached segment is reused.
+     * Default 0.85. Set to 1 to always re-retrieve.
+     */
+    stickyThreshold?: number;
+    /** Segment id (for cache miss attribution). Default "rag". */
+    segmentId?: string;
+    /** Format a document into a context message. Default: `[doc id] text`. */
+    formatDoc?: (doc: RagDocument) => string;
+    /** Override the lexical similarity measure (default token Jaccard). */
+    similarity?: (a: string, b: string) => number;
+}
+/**
+ * Cache-aware RAG: turns a {@link Retriever} into a reusable {@link CacheSegment}
+ * with two cache-preserving policies:
+ *
+ * - **sticky retrieval** — when consecutive queries are near-duplicates, skip
+ *   re-retrieval entirely so the segment (and the prefix cache after it) is
+ *   untouched, and
+ * - **append-only growth** — when a new result set extends the previous one,
+ *   append the new docs instead of rebuilding, keeping the already-cached prefix
+ *   valid; only a genuinely different result set rebuilds (and busts) the block.
+ *
+ * Attach `rag.segment` via `agent.setContextSegments([rag.segment])`.
+ */
+export declare class CacheAwareRag {
+    readonly segment: StableContext;
+    private readonly _retriever;
+    private readonly _k;
+    private readonly _stickyThreshold;
+    private readonly _formatDoc;
+    private readonly _similarity;
+    private _lastQuery;
+    private _docIds;
+    constructor(opts: CacheAwareRagOptions);
+    /** Document ids currently in the segment, in order. */
+    get documentIds(): readonly string[];
+    /**
+     * Refresh the segment for `query`. Returns whether a retrieval actually ran
+     * (`false` = sticky reuse) and whether the cache was preserved (append-only or
+     * skip) vs. busted (rebuild).
+     */
+    update(query: string): Promise<{
+        retrieved: boolean;
+        cachePreserved: boolean;
+    }>;
+    private _toMessage;
+}
+/** Token-set Jaccard similarity (lowercased word tokens). */
+export declare function jaccardSimilarity(a: string, b: string): number;
+export type { CacheSegment };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,102 @@
+// src/index.ts
+import { StableContext } from "@halo-sdk/core";
+function cosineSimilarity(a, b) {
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
+}
+var MemoryVectorStore = class {
+  _items = [];
+  add(docs, embeddings) {
+    for (let i = 0; i < docs.length; i++) {
+      this._items.push({ doc: docs[i], embedding: embeddings[i] });
+    }
+  }
+  query(embedding, k) {
+    return this._items.map(({ doc, embedding: e }) => ({ ...doc, score: cosineSimilarity(embedding, e) })).sort((a, b) => b.score - a.score).slice(0, k);
+  }
+};
+var VectorRetriever = class {
+  constructor(_embedder, _store) {
+    this._embedder = _embedder;
+    this._store = _store;
+  }
+  _embedder;
+  _store;
+  async retrieve(query, k) {
+    const [queryEmbedding] = await this._embedder.embed([query]);
+    return [...await this._store.query(queryEmbedding, k)];
+  }
+};
+var CacheAwareRag = class {
+  segment;
+  _retriever;
+  _k;
+  _stickyThreshold;
+  _formatDoc;
+  _similarity;
+  _lastQuery = null;
+  _docIds = [];
+  constructor(opts) {
+    this._retriever = opts.retriever;
+    this._k = opts.k ?? 4;
+    this._stickyThreshold = opts.stickyThreshold ?? 0.85;
+    this._formatDoc = opts.formatDoc ?? ((d) => `[${d.id}] ${d.text}`);
+    this._similarity = opts.similarity ?? jaccardSimilarity;
+    this.segment = new StableContext({ id: opts.segmentId ?? "rag", kind: "rag", messages: [] });
+  }
+  /** Document ids currently in the segment, in order. */
+  get documentIds() {
+    return this._docIds;
+  }
+  /**
+   * Refresh the segment for `query`. Returns whether a retrieval actually ran
+   * (`false` = sticky reuse) and whether the cache was preserved (append-only or
+   * skip) vs. busted (rebuild).
+   */
+  async update(query) {
+    if (this._lastQuery !== null && this._docIds.length > 0 && this._similarity(query, this._lastQuery) >= this._stickyThreshold) {
+      return { retrieved: false, cachePreserved: true };
+    }
+    this._lastQuery = query;
+    const docs = await this._retriever.retrieve(query, this._k);
+    const newIds = docs.map((d) => d.id);
+    const isPrefix = this._docIds.length > 0 && this._docIds.length <= newIds.length && this._docIds.every((id, i) => id === newIds[i]);
+    if (isPrefix) {
+      const extra = docs.slice(this._docIds.length);
+      this.segment.append(extra.map((d) => this._toMessage(d)));
+      this._docIds = newIds;
+      return { retrieved: true, cachePreserved: true };
+    }
+    this.segment.setMessages(docs.map((d) => this._toMessage(d)));
+    this._docIds = newIds;
+    return { retrieved: true, cachePreserved: this._docIds.length === 0 };
+  }
+  _toMessage(doc) {
+    return { role: "user", content: this._formatDoc(doc), discardable: false };
+  }
+};
+function jaccardSimilarity(a, b) {
+  const ta = new Set(a.toLowerCase().match(/\w+/g) ?? []);
+  const tb = new Set(b.toLowerCase().match(/\w+/g) ?? []);
+  if (ta.size === 0 && tb.size === 0) return 1;
+  let inter = 0;
+  for (const t of ta) if (tb.has(t)) inter++;
+  const union = ta.size + tb.size - inter;
+  return union === 0 ? 0 : inter / union;
+}
+export {
+  CacheAwareRag,
+  MemoryVectorStore,
+  VectorRetriever,
+  cosineSimilarity,
+  jaccardSimilarity
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { StableContext, type CacheSegment, type ChatMessage } from \"@halo-sdk/core\";\n\n/** A retrievable document. */\nexport interface RagDocument {\n  id: string;\n  text: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** A document with a relevance score (higher = more relevant). */\nexport interface ScoredDocument extends RagDocument {\n  score: number;\n}\n\n// ── Seams (bring your own implementation) ──\n\n/** Turns text into vectors. Seam — wrap any embedding model. */\nexport interface Embedder {\n  embed(texts: string[]): Promise<number[][]>;\n}\n\n/** Stores + searches document vectors. Seam — wrap any vector DB. */\nexport interface VectorStore {\n  add(docs: RagDocument[], embeddings: number[][]): Promise<void> | void;\n  query(embedding: number[], k: number): Promise<ScoredDocument[]> | ScoredDocument[];\n}\n\n/** Produces relevant documents for a query. Seam — the top-level RAG interface. */\nexport interface Retriever {\n  retrieve(query: string, k: number): Promise<RagDocument[]>;\n}\n\n// ── In-memory defaults (dependency-free) ──\n\n/** Cosine similarity of two equal-length vectors. */\nexport function cosineSimilarity(a: number[], b: number[]): number {\n  let dot = 0;\n  let na = 0;\n  let nb = 0;\n  for (let i = 0; i < a.length; i++) {\n    dot += a[i]! * b[i]!;\n    na += a[i]! * a[i]!;\n    nb += b[i]! * b[i]!;\n  }\n  const denom = Math.sqrt(na) * Math.sqrt(nb);\n  return denom === 0 ? 0 : dot / denom;\n}\n\n/** A simple in-memory cosine vector store. Good for tests, demos, small corpora. */\nexport class MemoryVectorStore implements VectorStore {\n  private _items: { doc: RagDocument; embedding: number[] }[] = [];\n\n  add(docs: RagDocument[], embeddings: number[][]): void {\n    for (let i = 0; i < docs.length; i++) {\n      this._items.push({ doc: docs[i]!, embedding: embeddings[i]! });\n    }\n  }\n\n  query(embedding: number[], k: number): ScoredDocument[] {\n    return this._items\n      .map(({ doc, embedding: e }) => ({ ...doc, score: cosineSimilarity(embedding, e) }))\n      .sort((a, b) => b.score - a.score)\n      .slice(0, k);\n  }\n}\n\n/** Build a {@link Retriever} from an {@link Embedder} + {@link VectorStore}. */\nexport class VectorRetriever implements Retriever {\n  constructor(\n    private readonly _embedder: Embedder,\n    private readonly _store: VectorStore,\n  ) {}\n\n  async retrieve(query: string, k: number): Promise<RagDocument[]> {\n    const [queryEmbedding] = await this._embedder.embed([query]);\n    return [...(await this._store.query(queryEmbedding!, k))];\n  }\n}\n\n// ── Cache-aware orchestration (what Halo owns) ──\n\nexport interface CacheAwareRagOptions {\n  retriever: Retriever;\n  /** Docs to retrieve per query. Default 4. */\n  k?: number;\n  /**\n   * Sticky-retrieval threshold. If the new query's lexical similarity to the\n   * last one is ≥ this, retrieval is skipped and the cached segment is reused.\n   * Default 0.85. Set to 1 to always re-retrieve.\n   */\n  stickyThreshold?: number;\n  /** Segment id (for cache miss attribution). Default \"rag\". */\n  segmentId?: string;\n  /** Format a document into a context message. Default: `[doc id] text`. */\n  formatDoc?: (doc: RagDocument) => string;\n  /** Override the lexical similarity measure (default token Jaccard). */\n  similarity?: (a: string, b: string) => number;\n}\n\n/**\n * Cache-aware RAG: turns a {@link Retriever} into a reusable {@link CacheSegment}\n * with two cache-preserving policies:\n *\n * - **sticky retrieval** — when consecutive queries are near-duplicates, skip\n *   re-retrieval entirely so the segment (and the prefix cache after it) is\n *   untouched, and\n * - **append-only growth** — when a new result set extends the previous one,\n *   append the new docs instead of rebuilding, keeping the already-cached prefix\n *   valid; only a genuinely different result set rebuilds (and busts) the block.\n *\n * Attach `rag.segment` via `agent.setContextSegments([rag.segment])`.\n */\nexport class CacheAwareRag {\n  readonly segment: StableContext;\n\n  private readonly _retriever: Retriever;\n  private readonly _k: number;\n  private readonly _stickyThreshold: number;\n  private readonly _formatDoc: (doc: RagDocument) => string;\n  private readonly _similarity: (a: string, b: string) => number;\n\n  private _lastQuery: string | null = null;\n  private _docIds: string[] = [];\n\n  constructor(opts: CacheAwareRagOptions) {\n    this._retriever = opts.retriever;\n    this._k = opts.k ?? 4;\n    this._stickyThreshold = opts.stickyThreshold ?? 0.85;\n    this._formatDoc = opts.formatDoc ?? ((d) => `[${d.id}] ${d.text}`);\n    this._similarity = opts.similarity ?? jaccardSimilarity;\n    this.segment = new StableContext({ id: opts.segmentId ?? \"rag\", kind: \"rag\", messages: [] });\n  }\n\n  /** Document ids currently in the segment, in order. */\n  get documentIds(): readonly string[] {\n    return this._docIds;\n  }\n\n  /**\n   * Refresh the segment for `query`. Returns whether a retrieval actually ran\n   * (`false` = sticky reuse) and whether the cache was preserved (append-only or\n   * skip) vs. busted (rebuild).\n   */\n  async update(query: string): Promise<{ retrieved: boolean; cachePreserved: boolean }> {\n    if (\n      this._lastQuery !== null &&\n      this._docIds.length > 0 &&\n      this._similarity(query, this._lastQuery) >= this._stickyThreshold\n    ) {\n      return { retrieved: false, cachePreserved: true }; // sticky — segment untouched\n    }\n\n    this._lastQuery = query;\n    const docs = await this._retriever.retrieve(query, this._k);\n    const newIds = docs.map((d) => d.id);\n\n    // Append-only when the previous ids are an ordered prefix of the new ids.\n    const isPrefix =\n      this._docIds.length > 0 &&\n      this._docIds.length <= newIds.length &&\n      this._docIds.every((id, i) => id === newIds[i]);\n\n    if (isPrefix) {\n      const extra = docs.slice(this._docIds.length);\n      this.segment.append(extra.map((d) => this._toMessage(d)));\n      this._docIds = newIds;\n      return { retrieved: true, cachePreserved: true };\n    }\n\n    this.segment.setMessages(docs.map((d) => this._toMessage(d)));\n    this._docIds = newIds;\n    return { retrieved: true, cachePreserved: this._docIds.length === 0 };\n  }\n\n  private _toMessage(doc: RagDocument): ChatMessage {\n    return { role: \"user\", content: this._formatDoc(doc), discardable: false };\n  }\n}\n\n/** Token-set Jaccard similarity (lowercased word tokens). */\nexport function jaccardSimilarity(a: string, b: string): number {\n  const ta = new Set(a.toLowerCase().match(/\\w+/g) ?? []);\n  const tb = new Set(b.toLowerCase().match(/\\w+/g) ?? []);\n  if (ta.size === 0 && tb.size === 0) return 1;\n  let inter = 0;\n  for (const t of ta) if (tb.has(t)) inter++;\n  const union = ta.size + tb.size - inter;\n  return union === 0 ? 0 : inter / union;\n}\n\nexport type { CacheSegment };\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@halo-sdk/rag",
+  "version": "1.0.0",
+  "description": "Cache-aware retrieval-augmented generation for Halo AI SDK — sticky retrieval + append-only growth that keeps the prefix cache warm",
+  "keywords": [
+    "ai",
+    "embeddings",
+    "llm",
+    "prefix-cache",
+    "rag",
+    "retrieval"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halo-sdk/halo-ai",
+    "directory": "packages/rag"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "@halo-sdk/core": "1.1.0"
+  },
+  "peerDependencies": {
+    "@halo-sdk/core": ">=1.1.0"
+  },
+  "scripts": {
+    "build": "tsc --build --emitDeclarationOnly && tsup",
+    "dev": "tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "publint": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}