@halo-sdk/rag 1.0.0 → 2.0.0

package/dist/embedders.d.ts

@@ -0,0 +1,37 @@
+import type { Embedder } from "./index.js";
+/**
+ * Dependency-free, deterministic embedder using the hashing trick (signed
+ * feature hashing). It maps each word token to a bucket and accumulates a
+ * signed count, then L2-normalizes. No model, no network — good for demos,
+ * tests, and small corpora where lexical overlap is enough. For semantic
+ * retrieval, swap in {@link OpenAICompatibleEmbedder} or your own `Embedder`.
+ */
+export declare class HashEmbedder implements Embedder {
+    private readonly _dim;
+    constructor(opts?: {
+        dimensions?: number;
+    });
+    embed(texts: string[]): Promise<number[][]>;
+    private _embedOne;
+}
+export interface OpenAICompatibleEmbedderOptions {
+    apiKey: string;
+    /** Embedding model id, e.g. `text-embedding-3-small`. */
+    model: string;
+    /** API base. Default OpenAI; point at any OpenAI-compatible `/embeddings`. */
+    baseUrl?: string;
+}
+/**
+ * Calls an OpenAI-compatible `/embeddings` endpoint (OpenAI, or DeepSeek/others
+ * that expose the same shape). Real semantic vectors, at the cost of a network
+ * round-trip and an API key. Implements the same {@link Embedder} seam, so it
+ * drops into `VectorRetriever` unchanged.
+ */
+export declare class OpenAICompatibleEmbedder implements Embedder {
+    private readonly _apiKey;
+    private readonly _model;
+    private readonly _baseUrl;
+    constructor(opts: OpenAICompatibleEmbedderOptions);
+    embed(texts: string[]): Promise<number[][]>;
+}
+//# sourceMappingURL=embedders.d.ts.map

package/dist/embedders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedders.d.ts","sourceRoot":"","sources":["../src/embedders.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;GAMG;AACH,qBAAa,YAAa,YAAW,QAAQ;IAC3C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAI1C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IAI3C,OAAO,CAAC,SAAS;CAclB;AAYD,MAAM,WAAW,+BAA+B;IAC9C,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD;;;;;GAKG;AACH,qBAAa,wBAAyB,YAAW,QAAQ;IACvD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,IAAI,EAAE,+BAA+B;IAM3C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;CAgBlD"}

package/dist/embedders.js

@@ -0,0 +1,74 @@
+/**
+ * Dependency-free, deterministic embedder using the hashing trick (signed
+ * feature hashing). It maps each word token to a bucket and accumulates a
+ * signed count, then L2-normalizes. No model, no network — good for demos,
+ * tests, and small corpora where lexical overlap is enough. For semantic
+ * retrieval, swap in {@link OpenAICompatibleEmbedder} or your own `Embedder`.
+ */
+export class HashEmbedder {
+    _dim;
+    constructor(opts) {
+        this._dim = Math.max(8, opts?.dimensions ?? 256);
+    }
+    embed(texts) {
+        return Promise.resolve(texts.map((t) => this._embedOne(t)));
+    }
+    _embedOne(text) {
+        const vec = Array.from({ length: this._dim }, () => 0);
+        const tokens = text.toLowerCase().match(/\w+/g) ?? [];
+        for (const tok of tokens) {
+            const h = fnv1a(tok);
+            const idx = h % this._dim;
+            const sign = (h & 1) === 0 ? 1 : -1;
+            vec[idx] = (vec[idx] ?? 0) + sign;
+        }
+        let norm = 0;
+        for (const v of vec)
+            norm += v * v;
+        norm = Math.sqrt(norm) || 1;
+        return vec.map((v) => v / norm);
+    }
+}
+/** FNV-1a 32-bit hash → non-negative integer. */
+function fnv1a(str) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < str.length; i++) {
+        h ^= str.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/**
+ * Calls an OpenAI-compatible `/embeddings` endpoint (OpenAI, or DeepSeek/others
+ * that expose the same shape). Real semantic vectors, at the cost of a network
+ * round-trip and an API key. Implements the same {@link Embedder} seam, so it
+ * drops into `VectorRetriever` unchanged.
+ */
+export class OpenAICompatibleEmbedder {
+    _apiKey;
+    _model;
+    _baseUrl;
+    constructor(opts) {
+        this._apiKey = opts.apiKey;
+        this._model = opts.model;
+        this._baseUrl = (opts.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+    }
+    async embed(texts) {
+        if (texts.length === 0)
+            return [];
+        const resp = await fetch(`${this._baseUrl}/embeddings`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${this._apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ model: this._model, input: texts }),
+        });
+        if (!resp.ok) {
+            throw new Error(`Embeddings ${resp.status}: ${await resp.text().catch(() => "")}`);
+        }
+        const json = (await resp.json());
+        return (json.data ?? []).map((d) => d.embedding);
+    }
+}
+//# sourceMappingURL=embedders.js.map

package/dist/embedders.js.map

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

package/dist/index.cjs

@@ -21,13 +21,76 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CacheAwareRag: () => CacheAwareRag,
+  HashEmbedder: () => HashEmbedder,
   MemoryVectorStore: () => MemoryVectorStore,
+  OpenAICompatibleEmbedder: () => OpenAICompatibleEmbedder,
   VectorRetriever: () => VectorRetriever,
   cosineSimilarity: () => cosineSimilarity,
   jaccardSimilarity: () => jaccardSimilarity
 });
 module.exports = __toCommonJS(index_exports);
 var import_core = require("@halo-sdk/core");
+
+// src/embedders.ts
+var HashEmbedder = class {
+  _dim;
+  constructor(opts) {
+    this._dim = Math.max(8, opts?.dimensions ?? 256);
+  }
+  embed(texts) {
+    return Promise.resolve(texts.map((t) => this._embedOne(t)));
+  }
+  _embedOne(text) {
+    const vec = Array.from({ length: this._dim }, () => 0);
+    const tokens = text.toLowerCase().match(/\w+/g) ?? [];
+    for (const tok of tokens) {
+      const h = fnv1a(tok);
+      const idx = h % this._dim;
+      const sign = (h & 1) === 0 ? 1 : -1;
+      vec[idx] = (vec[idx] ?? 0) + sign;
+    }
+    let norm = 0;
+    for (const v of vec) norm += v * v;
+    norm = Math.sqrt(norm) || 1;
+    return vec.map((v) => v / norm);
+  }
+};
+function fnv1a(str) {
+  let h = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var OpenAICompatibleEmbedder = class {
+  _apiKey;
+  _model;
+  _baseUrl;
+  constructor(opts) {
+    this._apiKey = opts.apiKey;
+    this._model = opts.model;
+    this._baseUrl = (opts.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const resp = await fetch(`${this._baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this._apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ model: this._model, input: texts })
+    });
+    if (!resp.ok) {
+      throw new Error(`Embeddings ${resp.status}: ${await resp.text().catch(() => "")}`);
+    }
+    const json = await resp.json();
+    return (json.data ?? []).map((d) => d.embedding);
+  }
+};
+
+// src/index.ts
 function cosineSimilarity(a, b) {
   let dot = 0;
   let na = 0;
@@ -123,7 +186,9 @@ function jaccardSimilarity(a, b) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CacheAwareRag,
+  HashEmbedder,
   MemoryVectorStore,
+  OpenAICompatibleEmbedder,
   VectorRetriever,
   cosineSimilarity,
   jaccardSimilarity

package/dist/index.cjs.map

@@ -1 +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":[]}
+{"version":3,"sources":["../src/index.ts","../src/embedders.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 { HashEmbedder, OpenAICompatibleEmbedder } from \"./embedders.js\";\nexport type { OpenAICompatibleEmbedderOptions } from \"./embedders.js\";\n\nexport type { CacheSegment };\n","import type { Embedder } from \"./index.js\";\n\n/**\n * Dependency-free, deterministic embedder using the hashing trick (signed\n * feature hashing). It maps each word token to a bucket and accumulates a\n * signed count, then L2-normalizes. No model, no network — good for demos,\n * tests, and small corpora where lexical overlap is enough. For semantic\n * retrieval, swap in {@link OpenAICompatibleEmbedder} or your own `Embedder`.\n */\nexport class HashEmbedder implements Embedder {\n  private readonly _dim: number;\n\n  constructor(opts?: { dimensions?: number }) {\n    this._dim = Math.max(8, opts?.dimensions ?? 256);\n  }\n\n  embed(texts: string[]): Promise<number[][]> {\n    return Promise.resolve(texts.map((t) => this._embedOne(t)));\n  }\n\n  private _embedOne(text: string): number[] {\n    const vec = Array.from({ length: this._dim }, () => 0);\n    const tokens = text.toLowerCase().match(/\\w+/g) ?? [];\n    for (const tok of tokens) {\n      const h = fnv1a(tok);\n      const idx = h % this._dim;\n      const sign = (h & 1) === 0 ? 1 : -1;\n      vec[idx] = (vec[idx] ?? 0) + sign;\n    }\n    let norm = 0;\n    for (const v of vec) norm += v * v;\n    norm = Math.sqrt(norm) || 1;\n    return vec.map((v) => v / norm);\n  }\n}\n\n/** FNV-1a 32-bit hash → non-negative integer. */\nfunction fnv1a(str: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < str.length; i++) {\n    h ^= str.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n\nexport interface OpenAICompatibleEmbedderOptions {\n  apiKey: string;\n  /** Embedding model id, e.g. `text-embedding-3-small`. */\n  model: string;\n  /** API base. Default OpenAI; point at any OpenAI-compatible `/embeddings`. */\n  baseUrl?: string;\n}\n\ninterface EmbeddingResponse {\n  data?: { embedding: number[] }[];\n}\n\n/**\n * Calls an OpenAI-compatible `/embeddings` endpoint (OpenAI, or DeepSeek/others\n * that expose the same shape). Real semantic vectors, at the cost of a network\n * round-trip and an API key. Implements the same {@link Embedder} seam, so it\n * drops into `VectorRetriever` unchanged.\n */\nexport class OpenAICompatibleEmbedder implements Embedder {\n  private readonly _apiKey: string;\n  private readonly _model: string;\n  private readonly _baseUrl: string;\n\n  constructor(opts: OpenAICompatibleEmbedderOptions) {\n    this._apiKey = opts.apiKey;\n    this._model = opts.model;\n    this._baseUrl = (opts.baseUrl ?? \"https://api.openai.com/v1\").replace(/\\/+$/, \"\");\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const resp = await fetch(`${this._baseUrl}/embeddings`, {\n      method: \"POST\",\n      headers: {\n        Authorization: `Bearer ${this._apiKey}`,\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({ model: this._model, input: texts }),\n    });\n    if (!resp.ok) {\n      throw new Error(`Embeddings ${resp.status}: ${await resp.text().catch(() => \"\")}`);\n    }\n    const json = (await resp.json()) as EmbeddingResponse;\n    return (json.data ?? []).map((d) => d.embedding);\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -92,5 +92,7 @@ export declare class CacheAwareRag {
 }
 /** Token-set Jaccard similarity (lowercased word tokens). */
 export declare function jaccardSimilarity(a: string, b: string): number;
+export { HashEmbedder, OpenAICompatibleEmbedder } from "./embedders.js";
+export type { OpenAICompatibleEmbedderOptions } from "./embedders.js";
 export type { CacheSegment };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -1,5 +1,66 @@
 // src/index.ts
 import { StableContext } from "@halo-sdk/core";
+
+// src/embedders.ts
+var HashEmbedder = class {
+  _dim;
+  constructor(opts) {
+    this._dim = Math.max(8, opts?.dimensions ?? 256);
+  }
+  embed(texts) {
+    return Promise.resolve(texts.map((t) => this._embedOne(t)));
+  }
+  _embedOne(text) {
+    const vec = Array.from({ length: this._dim }, () => 0);
+    const tokens = text.toLowerCase().match(/\w+/g) ?? [];
+    for (const tok of tokens) {
+      const h = fnv1a(tok);
+      const idx = h % this._dim;
+      const sign = (h & 1) === 0 ? 1 : -1;
+      vec[idx] = (vec[idx] ?? 0) + sign;
+    }
+    let norm = 0;
+    for (const v of vec) norm += v * v;
+    norm = Math.sqrt(norm) || 1;
+    return vec.map((v) => v / norm);
+  }
+};
+function fnv1a(str) {
+  let h = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+var OpenAICompatibleEmbedder = class {
+  _apiKey;
+  _model;
+  _baseUrl;
+  constructor(opts) {
+    this._apiKey = opts.apiKey;
+    this._model = opts.model;
+    this._baseUrl = (opts.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+  }
+  async embed(texts) {
+    if (texts.length === 0) return [];
+    const resp = await fetch(`${this._baseUrl}/embeddings`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this._apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ model: this._model, input: texts })
+    });
+    if (!resp.ok) {
+      throw new Error(`Embeddings ${resp.status}: ${await resp.text().catch(() => "")}`);
+    }
+    const json = await resp.json();
+    return (json.data ?? []).map((d) => d.embedding);
+  }
+};
+
+// src/index.ts
 function cosineSimilarity(a, b) {
   let dot = 0;
   let na = 0;
@@ -94,7 +155,9 @@ function jaccardSimilarity(a, b) {
 }
 export {
   CacheAwareRag,
+  HashEmbedder,
   MemoryVectorStore,
+  OpenAICompatibleEmbedder,
   VectorRetriever,
   cosineSimilarity,
   jaccardSimilarity

package/dist/index.js.map

@@ -1 +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":[]}
+{"version":3,"sources":["../src/index.ts","../src/embedders.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 { HashEmbedder, OpenAICompatibleEmbedder } from \"./embedders.js\";\nexport type { OpenAICompatibleEmbedderOptions } from \"./embedders.js\";\n\nexport type { CacheSegment };\n","import type { Embedder } from \"./index.js\";\n\n/**\n * Dependency-free, deterministic embedder using the hashing trick (signed\n * feature hashing). It maps each word token to a bucket and accumulates a\n * signed count, then L2-normalizes. No model, no network — good for demos,\n * tests, and small corpora where lexical overlap is enough. For semantic\n * retrieval, swap in {@link OpenAICompatibleEmbedder} or your own `Embedder`.\n */\nexport class HashEmbedder implements Embedder {\n  private readonly _dim: number;\n\n  constructor(opts?: { dimensions?: number }) {\n    this._dim = Math.max(8, opts?.dimensions ?? 256);\n  }\n\n  embed(texts: string[]): Promise<number[][]> {\n    return Promise.resolve(texts.map((t) => this._embedOne(t)));\n  }\n\n  private _embedOne(text: string): number[] {\n    const vec = Array.from({ length: this._dim }, () => 0);\n    const tokens = text.toLowerCase().match(/\\w+/g) ?? [];\n    for (const tok of tokens) {\n      const h = fnv1a(tok);\n      const idx = h % this._dim;\n      const sign = (h & 1) === 0 ? 1 : -1;\n      vec[idx] = (vec[idx] ?? 0) + sign;\n    }\n    let norm = 0;\n    for (const v of vec) norm += v * v;\n    norm = Math.sqrt(norm) || 1;\n    return vec.map((v) => v / norm);\n  }\n}\n\n/** FNV-1a 32-bit hash → non-negative integer. */\nfunction fnv1a(str: string): number {\n  let h = 0x811c9dc5;\n  for (let i = 0; i < str.length; i++) {\n    h ^= str.charCodeAt(i);\n    h = Math.imul(h, 0x01000193);\n  }\n  return h >>> 0;\n}\n\nexport interface OpenAICompatibleEmbedderOptions {\n  apiKey: string;\n  /** Embedding model id, e.g. `text-embedding-3-small`. */\n  model: string;\n  /** API base. Default OpenAI; point at any OpenAI-compatible `/embeddings`. */\n  baseUrl?: string;\n}\n\ninterface EmbeddingResponse {\n  data?: { embedding: number[] }[];\n}\n\n/**\n * Calls an OpenAI-compatible `/embeddings` endpoint (OpenAI, or DeepSeek/others\n * that expose the same shape). Real semantic vectors, at the cost of a network\n * round-trip and an API key. Implements the same {@link Embedder} seam, so it\n * drops into `VectorRetriever` unchanged.\n */\nexport class OpenAICompatibleEmbedder implements Embedder {\n  private readonly _apiKey: string;\n  private readonly _model: string;\n  private readonly _baseUrl: string;\n\n  constructor(opts: OpenAICompatibleEmbedderOptions) {\n    this._apiKey = opts.apiKey;\n    this._model = opts.model;\n    this._baseUrl = (opts.baseUrl ?? \"https://api.openai.com/v1\").replace(/\\/+$/, \"\");\n  }\n\n  async embed(texts: string[]): Promise<number[][]> {\n    if (texts.length === 0) return [];\n    const resp = await fetch(`${this._baseUrl}/embeddings`, {\n      method: \"POST\",\n      headers: {\n        Authorization: `Bearer ${this._apiKey}`,\n        \"Content-Type\": \"application/json\",\n      },\n      body: JSON.stringify({ model: this._model, input: texts }),\n    });\n    if (!resp.ok) {\n      throw new Error(`Embeddings ${resp.status}: ${await resp.text().catch(() => \"\")}`);\n    }\n    const json = (await resp.json()) as EmbeddingResponse;\n    return (json.data ?? []).map((d) => d.embedding);\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@halo-sdk/rag",
-  "version": "1.0.0",
+  "version": "2.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",
@@ -35,10 +35,10 @@
   "devDependencies": {
     "typescript": "^5.8.0",
     "vitest": "^3.0.0",
-    "@halo-sdk/core": "1.1.0"
+    "@halo-sdk/core": "1.2.0"
   },
   "peerDependencies": {
-    "@halo-sdk/core": ">=1.1.0"
+    "@halo-sdk/core": ">=1.2.0"
   },
   "scripts": {
     "build": "tsc --build --emitDeclarationOnly && tsup",