@dudousxd/nestjs-agent-rag 0.8.0 → 0.10.0

package/README.md

@@ -96,6 +96,61 @@ Either way, retrieved passages carry a `source` and surface as citations through
 tool-call machinery (rendered in the chat UI, shown in the `-telescope` Agent tab). Each retrieval
 also emits an `aviary:agent:retrieved` diagnostics event.
 
+## Retrieval telemetry
+
+A tool-call row says a retrieval *happened*. It cannot say how long it took, how much came back, how
+good the scores were, which store answered, or whether it found nothing at all — a retrieval that
+returns zero passages and one that returns five perfect ones are the same row with the same `ok`
+status. So retrieval also publishes its own event, on `aviary:rag:retrieval`:
+
+```ts
+// envelope: { durationMs, ts, traceId }  ·  payload:
+{
+  retriever: 'embedding' | 'keyword' | 'lexical' | 'hybrid' | 'filtered' | 'reranking' | 'unknown',
+  store?: 'memory' | 'pg' | 'redis',   // absent for an in-process retriever
+  collection?: string,                 // pg table / RediSearch index, or your own label
+  topK: number,
+  chunks: number,
+  zeroHit: boolean,
+  topScore?: number,                   // 4dp; absent on a zero-hit
+  meanScore?: number,
+  failed: boolean,
+  error?: string,
+}
+```
+
+Counts, durations and kinds only — never the query text, never passage text.
+
+`createRetrievalTool` instruments the retriever it wraps **by default**, so agentic retrieval needs
+no wiring. Wrap it yourself for inject mode, or for any code path that calls `retrieve` directly:
+
+```ts
+import { instrumentRetriever } from '@dudousxd/nestjs-agent-rag';
+
+const retriever = instrumentRetriever(
+  new HybridRetriever([new EmbeddingRetriever(embedder, store), new LexicalRetriever(store)]),
+  // optional: name the collection per call, when one index holds many
+  { collection: (filter) => (typeof filter?.collectionId === 'string' ? filter.collectionId : undefined) },
+);
+```
+
+Three things worth knowing:
+
+- **A composed retrieval is ONE event.** The outermost instrumented retriever reports; anything
+  instrumented inside it stays silent. `RerankingRetriever` over a `HybridRetriever` over two legs is
+  one retrieval, reported as `retriever: 'reranking'` with the duration and scores the caller got.
+  Wrapping a leg as well as the composite is safe — it will not double-count.
+- **It costs nothing when nobody listens.** `emit` is gated on `channel.hasSubscribers`, and the
+  wrapper checks the same gate before it reads a clock or touches a score, so an install with no
+  Telescope (or no subscriber at all) delegates straight through.
+- **It never changes behaviour.** Passages come back verbatim; a throwing retriever is reported as
+  `failed` and rethrown unchanged.
+
+`@dudousxd/nestjs-agent-telescope` subscribes to this channel and renders the **Retrieval** and
+**Retrieval sources** sections of the Agent tab. Anything else can subscribe too —
+`RAG_RETRIEVAL_CHANNEL` is the exported wire contract, and a host that needs retrieval history to
+outlive a restart persists it from there.
+
 ## pgvector store
 
 `PgVectorStore` takes an injected `PgClient` — adapt your own `pg` / `postgres.js`:
@@ -323,11 +378,15 @@ library upgrade. The interface is open, so it can be added later without changin
 - `HybridRetriever(retrievers, { k?, fetchTopK?, weights? })` — RRF fusion of the two.
 - `MemoryVectorStore` / `PgVectorStore` / `RedisVectorStore` — `VectorStore` adapters:
   `upsert(records)`, `search(embedding, opts)`, `remove(documentId)`,
-  `updateMetadata(documentId, patch)`, `listDocuments(filter?)`.
+  `updateMetadata(documentId, patch)`, `listDocuments(filter?)`,
+  `listChunks(documentId, { limit?, offset? })`.
 - `applyMetadataPatch(metadata, patch)` — the `MetadataPatch` merge semantics, exported so your own
   `VectorStore` can implement `updateMetadata` with exactly the same ones.
 - `isLexicalVectorStore(store)` — type guard for the optional `LexicalVectorStore` capability.
-- `createRetrievalTool(retriever, { name?, description?, topK? })` — the agentic-retrieval tool.
+- `createRetrievalTool(retriever, { name?, description?, topK?, telemetry? })` — the
+  agentic-retrieval tool. `telemetry` defaults to on; pass `false` to opt out.
+- `instrumentRetriever(retriever, { describe?, collection? })` — wrap any `Retriever` so each
+  retrieval publishes on `aviary:rag:retrieval` (`RAG_RETRIEVAL_CHANNEL`).
 
 ## Collection maintenance
 
@@ -363,6 +422,33 @@ would mean stamping the document id as an indexed field at write time, and chunk
 change carry no such field — the search would find none of them and `remove` would silently stop
 deleting. The methods above need no new field, so they have no migration.
 
+## Reading chunks back
+
+Everything above enumerates *documents*. The text itself is otherwise write-only: `search` needs an
+embedding, `searchText` needs a query, and both return what **matched**, in relevance order, capped
+at `topK`. Neither answers "show me what was indexed for this document, in order" — the question you
+ask when retrieval returned the wrong passage and you need to know whether the chunker cut badly or
+the retriever chose badly.
+
+```ts
+const chunks = await store.listChunks('handbook.pdf', { limit: 20 });
+// [{ id: 'handbook.pdf#0', index: 0, text: 'Chapter 1 …', metadata: { collection: 'handbook' } }, …]
+```
+
+Ordered by `index` (the `n` of `${documentId}#<n>`, numerically — `#10` after `#2`), so paging with
+`limit`/`offset` walks the document front to back. A document stored under a bare id is chunk `0`. An
+unknown `documentId` yields `[]`.
+
+Document-scoped rather than filter-scoped, matching `remove` and `updateMetadata`: ordering only
+means something once a document is picked, so enumerate with `listDocumentIds(filter)` first when you
+need to sweep. Two things it deliberately is not:
+
+- **not an access-control seam** — it takes no filter and applies none, so a consumer that gates
+  retrieval on a metadata field must resolve that gate itself before calling, exactly as before
+  `remove`. It is shaped for an operator/debug surface, not for serving end users;
+- **not a hot path** — on Redis it costs one keyspace `SCAN`, the same as `remove`. Fine for one
+  document on demand, wrong inside a loop over a corpus.
+
 ### Why these are required and `searchText` is optional
 
 A method is **required on `VectorStore`** when every backend can implement it from what it already

package/dist/index.cjs

@@ -28,17 +28,27 @@ __export(index_exports, {
   LexicalRetriever: () => LexicalRetriever,
   MemoryVectorStore: () => MemoryVectorStore,
   PgVectorStore: () => PgVectorStore,
+  RAG_DIAGNOSTIC_LIB: () => RAG_DIAGNOSTIC_LIB,
+  RAG_RETRIEVAL_CHANNEL: () => RAG_RETRIEVAL_CHANNEL,
+  RAG_RETRIEVAL_EVENT: () => RAG_RETRIEVAL_EVENT,
   RedisVectorSchemaMismatchError: () => RedisVectorSchemaMismatchError,
   RedisVectorStore: () => RedisVectorStore,
   RerankingRetriever: () => RerankingRetriever,
   UnsafeRemovalError: () => UnsafeRemovalError,
   applyMetadataPatch: () => applyMetadataPatch,
   chunkDocuments: () => chunkDocuments,
+  chunkIndexOf: () => chunkIndexOf,
   chunkText: () => chunkText,
   createRetrievalTool: () => createRetrievalTool,
+  describeRetrieval: () => describeRetrieval,
+  describeSharedSource: () => describeSharedSource,
+  describeSource: () => describeSource,
+  describesRetrieval: () => describesRetrieval,
   documentIdOf: () => documentIdOf,
+  emitRagRetrieval: () => emitRagRetrieval,
   ingestChunks: () => ingestChunks,
   ingestDocuments: () => ingestDocuments,
+  instrumentRetriever: () => instrumentRetriever,
   isLexicalVectorStore: () => isLexicalVectorStore
 });
 module.exports = __toCommonJS(index_exports);
@@ -133,6 +143,11 @@ var UnsafeRemovalError = class extends Error {
     this.name = "UnsafeRemovalError";
   }
 };
+function chunkIndexOf(chunkId) {
+  const match = /#(\d+)$/.exec(chunkId);
+  return match?.[1] === void 0 ? 0 : Number(match[1]);
+}
+__name(chunkIndexOf, "chunkIndexOf");
 function documentIdOf(chunkId) {
   return chunkId.replace(/#\d+$/, "");
 }
@@ -202,6 +217,16 @@ var MemoryVectorStore = class {
     __name(this, "MemoryVectorStore");
   }
   records = /* @__PURE__ */ new Map();
+  /**
+  * Telemetry self-description. No `collection`: there is no namespace to name — the corpus IS this
+  * instance, and two `MemoryVectorStore`s in one process are two corpora with nothing to tell them
+  * apart on a dashboard.
+  */
+  describeRetrieval() {
+    return {
+      store: "memory"
+    };
+  }
   async upsert(records) {
     for (const record of records) {
       this.records.set(record.id, record);
@@ -257,6 +282,34 @@ var MemoryVectorStore = class {
       ...documents.values()
     ];
   }
+  /**
+  * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+  *
+  * Insertion order is not document order — `upsert` stores whatever the caller passed, and a
+  * re-ingest that rewrites chunk 3 alone moves it to the end of the Map. So this sorts by the index
+  * parsed from the id, the same thing the SQL and Redis adapters order by, rather than trusting the
+  * Map. A reference adapter that returned "usually ordered" would let a consumer ship a bug that
+  * only shows up on the store tests are NOT written against.
+  */
+  async listChunks(documentId, options) {
+    const chunks = [];
+    for (const record of this.records.values()) {
+      if (documentIdOf(record.id) !== documentId) {
+        continue;
+      }
+      chunks.push({
+        id: record.id,
+        index: chunkIndexOf(record.id),
+        text: record.text,
+        ...record.metadata !== void 0 ? {
+          metadata: record.metadata
+        } : {}
+      });
+    }
+    chunks.sort((a, b) => a.index - b.index);
+    const offset = options?.offset ?? 0;
+    return options?.limit === void 0 ? chunks.slice(offset) : chunks.slice(offset, offset + options.limit);
+  }
   async listDocumentIds(filter) {
     if (filterMatchesNothing(filter)) {
       return [];
@@ -368,6 +421,13 @@ var PgVectorStore = class {
     this.table = options.table ?? "agent_rag_chunks";
     this.dimensions = options.dimensions ?? 1536;
   }
+  /** Telemetry self-description — the table is the namespace a retrieval was served from. */
+  describeRetrieval() {
+    return {
+      store: "pg",
+      collection: this.table
+    };
+  }
   /** Idempotent DDL: the `vector` extension, the chunks table, and the cosine HNSW index. */
   async ensureSchema() {
     await this.client.query("CREATE EXTENSION IF NOT EXISTS vector");
@@ -443,6 +503,44 @@ var PgVectorStore = class {
       } : {}
     }));
   }
+  /**
+  * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+  *
+  * The order is computed from the id rather than stored: `#12` must sort after `#2`, which a plain
+  * `ORDER BY id` gets wrong on every document past ten chunks because it compares text. So the
+  * trailing number is extracted and cast to `int`, and a bare id (a single-chunk document, which
+  * carries no `#n` suffix) collapses to `0` — the same rule `chunkIndexOf` applies in the other two
+  * adapters.
+  *
+  * `embedding` is left out of the projection: it is the widest column in the table and useless to a
+  * caller reading text back.
+  */
+  async listChunks(documentId, options) {
+    const params = [
+      documentId
+    ];
+    let sql = `SELECT id, ${CHUNK_INDEX_FROM_ID} AS chunk_index, text, metadata
+       FROM ${this.table}
+       WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1
+       ORDER BY chunk_index`;
+    if (options?.limit !== void 0) {
+      params.push(options.limit);
+      sql += ` LIMIT $${params.length}`;
+    }
+    if (options?.offset !== void 0) {
+      params.push(options.offset);
+      sql += ` OFFSET $${params.length}`;
+    }
+    const rows = await this.client.query(sql, params);
+    return rows.map((row) => ({
+      id: row.id,
+      index: Number(row.chunk_index),
+      text: row.text,
+      ...row.metadata !== null ? {
+        metadata: row.metadata
+      } : {}
+    }));
+  }
   /** {@link listDocuments} without the metadata: one `DISTINCT` over the derived document id. */
   async listDocumentIds(filter) {
     if (filterMatchesNothing(filter)) {
@@ -553,6 +651,7 @@ function buildWhere(filter, startIndex) {
 }
 __name(buildWhere, "buildWhere");
 var DOCUMENT_ID_FROM_CHUNK = "regexp_replace(id, '#[0-9]+$', '')";
+var CHUNK_INDEX_FROM_ID = "COALESCE((substring(id from '#([0-9]+)$'))::int, 0)";
 function toVectorLiteral(embedding) {
   return `[${embedding.join(",")}]`;
 }
@@ -591,6 +690,17 @@ var RedisVectorStore = class {
     this.lexicalScorer = options.lexicalScorer ?? "BM25";
   }
   /**
+  * Telemetry self-description — the RediSearch INDEX, not the key prefix: the index is what both
+  * legs query, and two stores sharing one index (the dense and lexical halves of a hybrid) must
+  * report the same namespace or `describeSharedSource` would see them disagree and drop the store.
+  */
+  describeRetrieval() {
+    return {
+      store: "redis",
+      collection: this.index
+    };
+  }
+  /**
   * Idempotent, and drift-aware: create the HNSW/cosine index if `FT.INFO` says it doesn't exist —
   * and if it DOES exist, compare what's there against this store's configuration instead of
   * assuming they agree. An index that outlives a config change is the normal case (schemas live in
@@ -845,6 +955,58 @@ var RedisVectorStore = class {
       ...keys
     ];
   }
+  /**
+  * The chunks of one document, in document order. See {@link VectorStore.listChunks}.
+  *
+  * Reads the hashes directly (`HMGET text metadata_json`) rather than going through `FT.SEARCH`.
+  * Two reasons, and the second is the one that matters: the query language has no way to ask for
+  * "every chunk of this document" — `id` is the key name, not an indexed field — and `FT.SEARCH`
+  * caps at `LIMIT`, so paging a document through it would mean ordering by a field the index does
+  * not hold. `chunkKeys` is the same enumeration {@link RedisVectorStore.remove} and
+  * {@link RedisVectorStore.updateMetadata} already use, so "the chunks this returns" and "the chunks
+  * a delete would take" cannot drift apart.
+  *
+  * It inherits that method's cost too: one keyspace `SCAN` per call. Acceptable here because this
+  * is an inspection path (one document, on demand) and not something retrieval runs — but it is why
+  * this must not be put on a hot path or called in a loop over a corpus.
+  *
+  * `embedding` is deliberately not fetched: it is by far the largest field on the hash and nothing
+  * a caller reading text back can do with it.
+  */
+  async listChunks(documentId, options) {
+    const keys = await this.chunkKeys(documentId);
+    const ordered = keys.map((key) => ({
+      key,
+      id: key.slice(this.prefix.length)
+    })).map((entry) => ({
+      ...entry,
+      index: chunkIndexOf(entry.id)
+    })).sort((a, b) => a.index - b.index);
+    const offset = options?.offset ?? 0;
+    const page = options?.limit === void 0 ? ordered.slice(offset) : ordered.slice(offset, offset + options.limit);
+    const chunks = [];
+    for (const entry of page) {
+      const reply = await this.client.sendCommand([
+        "HMGET",
+        entry.key,
+        "text",
+        "metadata_json"
+      ]);
+      const fields = Array.isArray(reply) ? reply : [];
+      const text = fields[0] === null || fields[0] === void 0 ? void 0 : toStr(fields[0]);
+      if (text === void 0) {
+        continue;
+      }
+      const raw = fields[1] === null || fields[1] === void 0 ? void 0 : toStr(fields[1]);
+      chunks.push({
+        id: entry.id,
+        index: entry.index,
+        text,
+        ...parseMetadata(raw)
+      });
+    }
+    return chunks;
+  }
   async listDocuments(filter) {
     if (filterMatchesNothing(filter)) {
       return [];
@@ -1367,6 +1529,31 @@ function parseMetadata(raw) {
 }
 __name(parseMetadata, "parseMetadata");
 
+// src/retrieval-descriptor.ts
+function describesRetrieval(value) {
+  return typeof value === "object" && value !== null && typeof Reflect.get(value, "describeRetrieval") === "function";
+}
+__name(describesRetrieval, "describesRetrieval");
+function describeRetrieval(candidate) {
+  return describesRetrieval(candidate) ? candidate.describeRetrieval() : {};
+}
+__name(describeRetrieval, "describeRetrieval");
+function describeSource(base) {
+  const { retriever: _ignored, ...source } = describeRetrieval(base);
+  return source;
+}
+__name(describeSource, "describeSource");
+function describeSharedSource(legs) {
+  const sources = legs.map(describeSource);
+  const [first] = sources;
+  if (first === void 0) {
+    return {};
+  }
+  const agrees = sources.every((source) => source.store === first.store && source.collection === first.collection);
+  return agrees ? first : {};
+}
+__name(describeSharedSource, "describeSharedSource");
+
 // src/embedding-retriever.ts
 var EmbeddingRetriever = class {
   static {
@@ -1380,6 +1567,13 @@ var EmbeddingRetriever = class {
     this.store = store;
     this.options = options;
   }
+  /** Telemetry self-description — the dense strategy, over whatever store it was handed. */
+  describeRetrieval() {
+    return {
+      retriever: "embedding",
+      ...describeSource(this.store)
+    };
+  }
   async retrieve(query, options = {}) {
     const [embedding] = await this.embedder.embed([
       query
@@ -1412,6 +1606,16 @@ var KeywordRetriever = class {
     this.k1 = options.k1 ?? 1.5;
     this.b = options.b ?? 0.75;
   }
+  /**
+  * Telemetry self-description. No `store`: this retriever holds its own copy of the corpus in
+  * process, so attributing its retrievals to whichever vector store happens to hold the same chunks
+  * would credit a backend that was never queried.
+  */
+  describeRetrieval() {
+    return {
+      retriever: "keyword"
+    };
+  }
   /** How many chunks are currently indexed. */
   get size() {
     return this.docs.size;
@@ -1529,6 +1733,13 @@ var LexicalRetriever = class {
   constructor(store) {
     this.store = store;
   }
+  /** Telemetry self-description — the store's own lexical index, so the store is the same one. */
+  describeRetrieval() {
+    return {
+      retriever: "lexical",
+      ...describeSource(this.store)
+    };
+  }
   async retrieve(query, options = {}) {
     return this.store.searchText(query, {
       topK: options.topK ?? 5,
@@ -1550,6 +1761,13 @@ var HybridRetriever = class {
     this.retrievers = retrievers;
     this.options = options;
   }
+  /** Telemetry self-description — the store only when every leg agrees; see `describeSharedSource`. */
+  describeRetrieval() {
+    return {
+      retriever: "hybrid",
+      ...describeSharedSource(this.retrievers)
+    };
+  }
   async retrieve(query, options = {}) {
     const k = this.options.k ?? 60;
     const fetchTopK = this.options.fetchTopK ?? 20;
@@ -1598,6 +1816,13 @@ var RerankingRetriever = class {
     this.reranker = reranker;
     this.options = options;
   }
+  /** Telemetry self-description — the two-stage strategy, over the base's store. */
+  describeRetrieval() {
+    return {
+      retriever: "reranking",
+      ...describeSource(this.base)
+    };
+  }
   async retrieve(query, options = {}) {
     const candidates = await this.base.retrieve(query, {
       topK: this.options.fetchTopK ?? 20,
@@ -1622,6 +1847,13 @@ var FilteredRetriever = class {
     this.base = base;
     this.filter = filter;
   }
+  /** Telemetry self-description — this scope, over the base's store. */
+  describeRetrieval() {
+    return {
+      retriever: "filtered",
+      ...describeSource(this.base)
+    };
+  }
   async retrieve(query, options = {}) {
     return this.base.retrieve(query, {
       ...options,
@@ -1671,6 +1903,108 @@ async function ingestDocuments(documents, options) {
 }
 __name(ingestDocuments, "ingestDocuments");
 
+// src/retrieval-telemetry.ts
+var import_node_async_hooks = require("async_hooks");
+var import_nestjs_diagnostics = require("@dudousxd/nestjs-diagnostics");
+var RAG_DIAGNOSTIC_LIB = "rag";
+var RAG_RETRIEVAL_EVENT = "retrieval";
+var RAG_RETRIEVAL_CHANNEL = (0, import_nestjs_diagnostics.channelName)(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT);
+function emitRagRetrieval(event, durationMs) {
+  (0, import_nestjs_diagnostics.emit)(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT, event, {
+    durationMs
+  });
+}
+__name(emitRagRetrieval, "emitRagRetrieval");
+var DEFAULT_TOP_K = 5;
+var inRetrieval = new import_node_async_hooks.AsyncLocalStorage();
+function round4(value) {
+  return Math.round(value * 1e4) / 1e4;
+}
+__name(round4, "round4");
+function scoreStats(passages) {
+  const scores = passages.map((passage) => passage.score).filter((score) => Number.isFinite(score));
+  if (scores.length === 0) {
+    return {};
+  }
+  const sum = scores.reduce((total, score) => total + score, 0);
+  return {
+    topScore: round4(Math.max(...scores)),
+    meanScore: round4(sum / scores.length)
+  };
+}
+__name(scoreStats, "scoreStats");
+var InstrumentedRetriever = class InstrumentedRetriever2 {
+  static {
+    __name(this, "InstrumentedRetriever");
+  }
+  base;
+  options;
+  constructor(base, options = {}) {
+    this.base = base;
+    this.options = options;
+  }
+  /** Transparent to detection: wrapping a retriever must not turn it into an `unknown` one. */
+  describeRetrieval() {
+    return {
+      ...describeRetrieval(this.base),
+      ...this.options.describe
+    };
+  }
+  async retrieve(query, options = {}) {
+    if (!(0, import_nestjs_diagnostics.getChannel)(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT).hasSubscribers) {
+      return this.base.retrieve(query, options);
+    }
+    if (inRetrieval.getStore() === true) {
+      return this.base.retrieve(query, options);
+    }
+    const descriptor = this.describeRetrieval();
+    const topK = options.topK ?? DEFAULT_TOP_K;
+    const startedAt = Date.now();
+    try {
+      const passages = await inRetrieval.run(true, () => this.base.retrieve(query, options));
+      emitRagRetrieval({
+        retriever: descriptor.retriever ?? "unknown",
+        ...descriptor.store !== void 0 ? {
+          store: descriptor.store
+        } : {},
+        ...this.collectionOf(options.filter, descriptor),
+        topK,
+        chunks: passages.length,
+        zeroHit: passages.length === 0,
+        ...scoreStats(passages),
+        failed: false
+      }, Date.now() - startedAt);
+      return passages;
+    } catch (error) {
+      emitRagRetrieval({
+        retriever: descriptor.retriever ?? "unknown",
+        ...descriptor.store !== void 0 ? {
+          store: descriptor.store
+        } : {},
+        ...this.collectionOf(options.filter, descriptor),
+        topK,
+        chunks: 0,
+        zeroHit: true,
+        failed: true,
+        error: error instanceof Error ? error.message : String(error)
+      }, Date.now() - startedAt);
+      throw error;
+    }
+  }
+  /** The host's collection for this call, else the store namespace, else nothing. */
+  collectionOf(filter, descriptor) {
+    const { collection } = this.options;
+    const resolved = typeof collection === "function" ? collection(filter) : collection ?? descriptor.collection;
+    return resolved !== void 0 ? {
+      collection: resolved
+    } : {};
+  }
+};
+function instrumentRetriever(retriever, options = {}) {
+  return new InstrumentedRetriever(retriever, options);
+}
+__name(instrumentRetriever, "instrumentRetriever");
+
 // src/retrieval-tool.ts
 function isQueryInput(value) {
   return typeof value === "object" && value !== null && "query" in value && typeof value.query === "string";
@@ -1697,6 +2031,8 @@ var querySchema = {
 };
 function createRetrievalTool(retriever, options = {}) {
   const topK = options.topK;
+  const { telemetry = true } = options;
+  const instrumented = telemetry === false ? retriever : instrumentRetriever(retriever, telemetry === true ? {} : telemetry);
   return {
     spec: {
       name: options.name ?? "search_knowledge",
@@ -1709,7 +2045,7 @@ function createRetrievalTool(retriever, options = {}) {
         if (!isQueryInput(input)) {
           throw new Error("retrieval tool expects { query: string }");
         }
-        const passages = await retriever.retrieve(input.query, topK !== void 0 ? {
+        const passages = await instrumented.retrieve(input.query, topK !== void 0 ? {
           topK
         } : {});
         return {
@@ -1729,17 +2065,27 @@ __name(createRetrievalTool, "createRetrievalTool");
   LexicalRetriever,
   MemoryVectorStore,
   PgVectorStore,
+  RAG_DIAGNOSTIC_LIB,
+  RAG_RETRIEVAL_CHANNEL,
+  RAG_RETRIEVAL_EVENT,
   RedisVectorSchemaMismatchError,
   RedisVectorStore,
   RerankingRetriever,
   UnsafeRemovalError,
   applyMetadataPatch,
   chunkDocuments,
+  chunkIndexOf,
   chunkText,
   createRetrievalTool,
+  describeRetrieval,
+  describeSharedSource,
+  describeSource,
+  describesRetrieval,
   documentIdOf,
+  emitRagRetrieval,
   ingestChunks,
   ingestDocuments,
+  instrumentRetriever,
   isLexicalVectorStore
 });
 //# sourceMappingURL=index.cjs.map