@dudousxd/nestjs-agent-rag 0.9.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`:
@@ -328,7 +383,10 @@ library upgrade. The interface is open, so it can be added later without changin
 - `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
 

package/dist/index.cjs

@@ -28,6 +28,9 @@ __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,
@@ -37,9 +40,15 @@ __export(index_exports, {
   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);
@@ -208,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);
@@ -402,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");
@@ -664,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
@@ -1492,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 {
@@ -1505,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
@@ -1537,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;
@@ -1654,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,
@@ -1675,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;
@@ -1723,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,
@@ -1747,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,
@@ -1796,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";
@@ -1822,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",
@@ -1834,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 {
@@ -1854,6 +2065,9 @@ __name(createRetrievalTool, "createRetrievalTool");
   LexicalRetriever,
   MemoryVectorStore,
   PgVectorStore,
+  RAG_DIAGNOSTIC_LIB,
+  RAG_RETRIEVAL_CHANNEL,
+  RAG_RETRIEVAL_EVENT,
   RedisVectorSchemaMismatchError,
   RedisVectorStore,
   RerankingRetriever,
@@ -1863,9 +2077,15 @@ __name(createRetrievalTool, "createRetrievalTool");
   chunkIndexOf,
   chunkText,
   createRetrievalTool,
+  describeRetrieval,
+  describeSharedSource,
+  describeSource,
+  describesRetrieval,
   documentIdOf,
+  emitRagRetrieval,
   ingestChunks,
   ingestDocuments,
+  instrumentRetriever,
   isLexicalVectorStore
 });
 //# sourceMappingURL=index.cjs.map