@dudousxd/nestjs-agent-rag 0.9.0 → 0.10.0

package/dist/index.d.cts

@@ -319,6 +319,68 @@ declare function chunkIndexOf(chunkId: string): number;
 /** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */
 declare function documentIdOf(chunkId: string): string;
 
+/**
+ * What a retrieval was served BY — the static half of retrieval telemetry, separated from the
+ * emitting half (`retrieval-telemetry.ts`) so a store or a retriever can describe itself without
+ * importing anything that emits. That separation is not tidiness: `retrieval-telemetry.ts` imports
+ * the retrievers' shapes to detect them, and the retrievers import their descriptor kind, so putting
+ * both halves in one module would make every retriever ↔ telemetry edge a cycle.
+ */
+/** Which retrieval strategy answered. `unknown` is a retriever this package did not ship. */
+type RetrieverKind = 'embedding' | 'keyword' | 'lexical' | 'hybrid' | 'filtered' | 'reranking' | 'unknown';
+/** Which backend held the chunks. Omitted entirely for a retriever that holds its own (keyword). */
+type VectorStoreKind = 'memory' | 'pg' | 'redis';
+/**
+ * A retriever's (or a store's) self-description, as it appears on a retrieval event. Every field is
+ * optional because the describer is answering only for the layer it *is*: a store knows its backend
+ * and namespace but not which strategy queried it; `KeywordRetriever` knows its strategy but has no
+ * store at all.
+ */
+interface RetrievalDescriptor {
+    retriever?: RetrieverKind;
+    store?: VectorStoreKind;
+    /**
+     * The namespace the chunks live in — `PgVectorStore`'s table, `RedisVectorStore`'s RediSearch
+     * index. This is the STORE-level namespace, not a per-query metadata scope: a host that partitions
+     * one index into logical collections with a metadata filter (the usual multi-tenant shape) reports
+     * that through `InstrumentRetrieverOptions.collection`, which overrides this.
+     */
+    collection?: string;
+}
+/**
+ * The optional capability a store or retriever implements to appear on a retrieval event as
+ * something other than `unknown`. Deliberately NOT a member of `VectorStore` or of core's
+ * `Retriever`: both are implemented outside this package, and adding a required member to either
+ * would break every existing implementation on upgrade — for a field that only observability reads.
+ */
+interface DescribesRetrieval {
+    describeRetrieval(): RetrievalDescriptor;
+}
+/** Structural guard, so a `VectorStore`/`Retriever` is narrowed to the capability without a cast. */
+declare function describesRetrieval(value: unknown): value is DescribesRetrieval;
+/** A candidate's descriptor, or an empty one when it does not carry the capability. */
+declare function describeRetrieval(candidate: unknown): RetrievalDescriptor;
+/**
+ * The store half of a wrapped retriever's descriptor: the base's `store`/`collection` with its
+ * `retriever` dropped, so the wrapper can stamp its own strategy on top.
+ *
+ * `new FilteredRetriever(new EmbeddingRetriever(embedder, pg), scope)` therefore reports
+ * `{ retriever: 'filtered', store: 'pg', collection: 'agent_rag_chunks' }` rather than losing the
+ * store: which backend answered is the thing a "retrievals by store" panel exists to show, and a
+ * production wiring is almost always two or three wrappers deep.
+ */
+declare function describeSource(base: unknown): Omit<RetrievalDescriptor, 'retriever'>;
+/**
+ * The store half shared by EVERY leg of a composed retriever, or nothing when they disagree.
+ *
+ * A hybrid whose legs are the dense and lexical halves of the same RediSearch index (the shape
+ * `LexicalRetriever` exists for) genuinely was served by that one store, and reporting it is what
+ * makes the store breakdown add up. A hybrid fusing pgvector with an in-process BM25 index was not
+ * served by either alone, and picking the first leg would silently attribute every such retrieval to
+ * a store that answered half of it.
+ */
+declare function describeSharedSource(legs: readonly unknown[]): Omit<RetrievalDescriptor, 'retriever'>;
+
 /**
  * An in-process {@link VectorStore} — cosine similarity over a Map, no infra. The reference adapter
  * for tests and small/embedded corpora; for production scale use `PgVectorStore` (or your own).
@@ -331,6 +393,12 @@ declare function documentIdOf(chunkId: string): string;
  */
 declare class MemoryVectorStore implements VectorStore {
     private readonly records;
+    /**
+     * 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(): RetrievalDescriptor;
     upsert(records: VectorRecord[]): Promise<void>;
     remove(documentId: string): Promise<void>;
     /**
@@ -411,6 +479,8 @@ declare class PgVectorStore implements VectorStore {
     private readonly table;
     private readonly dimensions;
     constructor(client: PgClient, options?: PgVectorStoreOptions);
+    /** Telemetry self-description — the table is the namespace a retrieval was served from. */
+    describeRetrieval(): RetrievalDescriptor;
     /** Idempotent DDL: the `vector` extension, the chunks table, and the cosine HNSW index. */
     ensureSchema(): Promise<void>;
     upsert(records: VectorRecord[]): Promise<void>;
@@ -531,6 +601,12 @@ declare class RedisVectorStore implements LexicalVectorStore {
     private readonly filterableFields;
     private readonly lexicalScorer;
     constructor(client: RedisSearchClient, options?: RedisVectorStoreOptions);
+    /**
+     * 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(): RetrievalDescriptor;
     /**
      * 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
@@ -740,6 +816,8 @@ declare class EmbeddingRetriever implements Retriever {
     private readonly store;
     private readonly options;
     constructor(embedder: EmbeddingProvider, store: VectorStore, options?: EmbeddingRetrieverOptions);
+    /** Telemetry self-description — the dense strategy, over whatever store it was handed. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -799,6 +877,12 @@ declare class KeywordRetriever implements Retriever {
     private readonly k1;
     private readonly b;
     constructor(options?: KeywordRetrieverOptions);
+    /**
+     * 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(): RetrievalDescriptor;
     /** How many chunks are currently indexed. */
     get size(): number;
     /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */
@@ -844,6 +928,8 @@ declare class KeywordRetriever implements Retriever {
 declare class LexicalRetriever implements Retriever {
     private readonly store;
     constructor(store: LexicalVectorStore);
+    /** Telemetry self-description — the store's own lexical index, so the store is the same one. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -895,6 +981,8 @@ declare class HybridRetriever implements Retriever {
     private readonly retrievers;
     private readonly options;
     constructor(retrievers: Retriever[], options?: HybridRetrieverOptions);
+    /** Telemetry self-description — the store only when every leg agrees; see `describeSharedSource`. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -913,6 +1001,8 @@ declare class RerankingRetriever implements Retriever {
     private readonly reranker;
     private readonly options;
     constructor(base: Retriever, reranker: Reranker, options?: RerankingRetrieverOptions);
+    /** Telemetry self-description — the two-stage strategy, over the base's store. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
@@ -929,15 +1019,178 @@ declare class FilteredRetriever implements Retriever {
     private readonly base;
     private readonly filter;
     constructor(base: Retriever, filter: Record<string, unknown>);
+    /** Telemetry self-description — this scope, over the base's store. */
+    describeRetrieval(): RetrievalDescriptor;
     retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
 }
 
+/**
+ * Retrieval telemetry: one diagnostics event per retrieval, carrying how long it took, how much came
+ * back, how good it was, and what served it.
+ *
+ * Until this existed, retrieval reached Telescope only as the *tool call* that wrapped it (see
+ * `retrieval-tool.ts`), which says a retrieval happened and nothing else. The questions an operator
+ * actually arrives with — is retrieval slow, is it returning nothing, is one collection colder than
+ * the rest, did the scores collapse after a model swap — are all invisible in a tool-call row,
+ * because a tool call that returns zero passages and one that returns five perfect ones are the same
+ * row with the same `ok` status.
+ *
+ * ## One seam, not six
+ *
+ * Instrumentation is a WRAPPER over the core `Retriever` SPI ({@link instrumentRetriever}), not code
+ * inside each retriever. Every retriever in this package — and every retriever outside it — is the
+ * same one-method interface, so one wrapper covers all of them, including ones this package has
+ * never heard of. The alternative, an `emit` inside each of the six `retrieve` methods, would have
+ * had to be repeated in each, skipped by third-party retrievers entirely, and would have double- and
+ * triple-counted the composed ones (a hybrid over two legs emitting three events for one retrieval).
+ *
+ * ## How a composed retrieval reports
+ *
+ * **The outermost instrumented retriever in a call tree emits; anything instrumented inside it stays
+ * silent.** A retrieval is one question the caller asked, so it is one event no matter how many
+ * retrievers cooperated to answer it: `RerankingRetriever` over a `HybridRetriever` over a dense and
+ * a lexical leg is ONE retrieval, reported as `retriever: 'reranking'` with the duration of the
+ * whole thing and the scores the caller actually got back.
+ *
+ * The suppression is enforced with an {@link AsyncLocalStorage} flag rather than by asking hosts to
+ * wrap carefully, because the wrapping that double-counts is the natural one: a host that wraps its
+ * top-level retriever and *also* wraps the dense leg it shares with another code path has not made a
+ * mistake, and would otherwise get two events per retrieval, a zero-hit rate computed over a mixture
+ * of legs and composites, and a retrieval count roughly twice its query count.
+ *
+ * ## Opt-out safety, and what the hot path pays
+ *
+ * The event goes out on `aviary:rag:retrieval` via `@dudousxd/nestjs-diagnostics`, whose `emit` is
+ * gated on `channel.hasSubscribers` and never throws. This wrapper checks that same gate BEFORE it
+ * does anything at all — no clock read, no `AsyncLocalStorage.run`, no score arithmetic — and
+ * delegates straight through when nothing is listening. A host that wires this package without
+ * Telescope (or any subscriber) pays two `Map` lookups and a boolean per retrieval, and nothing else
+ * changes: the wrapper returns the base retriever's passages verbatim, and rethrows its errors
+ * unchanged.
+ *
+ * ## Why this channel is not merged into the typed `ChannelRegistry`
+ *
+ * `@dudousxd/nestjs-agent-rag-media` already emits `media.ingested`/`media.removed`/`media.skipped`/
+ * `media.failed` on the same `rag` lib, and flip's host app emits `rag:search` on it. Declaring
+ * `ChannelRegistry['rag'] = { retrieval: RagRetrievalEvent }` here would narrow `EventOf<'rag'>` to
+ * this one key process-wide and turn every one of those sibling emits into a compile error in any
+ * project that installs both packages. The payload stays typed where it matters — {@link emitRagRetrieval}
+ * takes {@link RagRetrievalEvent} — and the wire contract is documented below instead.
+ */
+/** The diagnostics lib segment. Shared with `@dudousxd/nestjs-agent-rag-media`'s `media.*` events. */
+declare const RAG_DIAGNOSTIC_LIB = "rag";
+/** The diagnostics event segment. */
+declare const RAG_RETRIEVAL_EVENT = "retrieval";
+/**
+ * The full channel name a subscriber listens on: `aviary:rag:retrieval`. This is the wire contract —
+ * `@dudousxd/nestjs-agent-telescope` subscribes to this exact string rather than importing this
+ * package, which is what keeps the telescope extension free of a dependency on the retrieval stack
+ * (and lets a host that uses neither still observe retrieval with a bare `diagnostics_channel`
+ * subscription).
+ */
+declare const RAG_RETRIEVAL_CHANNEL: string;
+/**
+ * The payload of one retrieval event. Counts, durations, kinds and scores only — never the query
+ * text and never passage text. Both are user content, and this lands in an ops store with a short
+ * retention window and a Slack-facing redaction budget; everything here is safe to put on a
+ * dashboard and is what tells the failure modes apart anyway.
+ *
+ * The DURATION is not in here: it rides the envelope (`emit`'s `opts.durationMs`), which is the field
+ * Telescope's OTel exporter turns into a latency histogram. Putting it in the payload instead would
+ * have made retrieval latency a number somebody reads out of a JSON blob rather than a graph.
+ */
+interface RagRetrievalEvent {
+    /** Which strategy answered — the OUTERMOST one, for a composed retriever. */
+    retriever: RetrieverKind;
+    /** Which backend held the chunks. Absent for an in-process retriever, or when legs disagree. */
+    store?: VectorStoreKind;
+    /** Store namespace (pg table / RediSearch index), or the host's logical collection. */
+    collection?: string;
+    /** What the caller asked for, so `chunks < topK` is readable as "the corpus ran out". */
+    topK: number;
+    /** How many passages came back. */
+    chunks: number;
+    /**
+     * `chunks === 0`. Carried as its own flag rather than left to be derived, because the zero-hit RATE
+     * is the headline number and deriving it means every consumer re-deriving the same predicate.
+     */
+    zeroHit: boolean;
+    /** Best score in the result, rounded to 4dp. Absent on a zero-hit. */
+    topScore?: number;
+    /** Mean score across the result, rounded to 4dp. Absent on a zero-hit. */
+    meanScore?: number;
+    /**
+     * The retrieval threw. Reported rather than dropped because a failed retrieval and an empty one
+     * look identical from the agent's side — both become "I couldn't find anything" — so a channel
+     * that only carried successes would go quiet exactly when retrieval broke.
+     */
+    failed: boolean;
+    /** The error message, when `failed`. */
+    error?: string;
+}
+/** Publish one retrieval event. `durationMs` rides the envelope; see {@link RagRetrievalEvent}. */
+declare function emitRagRetrieval(event: RagRetrievalEvent, durationMs: number): void;
+interface InstrumentRetrieverOptions {
+    /**
+     * Override the auto-detected {@link RetrievalDescriptor}, field by field. Needed for a retriever or
+     * store from outside this package (which reports `retriever: 'unknown'` and no store), and for a
+     * host that wants its own naming.
+     */
+    describe?: RetrievalDescriptor;
+    /**
+     * The logical collection this retrieval searched, when the store namespace is not it. Pass a
+     * function to read it off the call's metadata filter — the multi-tenant shape, where one index
+     * holds every collection and the filter picks one:
+     *
+     * ```ts
+     * instrumentRetriever(retriever, {
+     *   collection: (filter) => (typeof filter?.collectionId === 'string' ? filter.collectionId : undefined),
+     * })
+     * ```
+     *
+     * Returning `undefined` falls back to the store namespace, which is the right answer for a query
+     * scoped to many collections at once: a breakdown panel needs ONE label per retrieval, and
+     * inventing a synthetic `"a+b+c"` bucket would produce a chart whose slices are combinations
+     * rather than collections.
+     */
+    collection?: string | ((filter: Record<string, unknown> | undefined) => string | undefined);
+}
+/**
+ * Wrap a retriever so every `retrieve` publishes a {@link RagRetrievalEvent} on
+ * {@link RAG_RETRIEVAL_CHANNEL}. Wrap the retriever you actually hand to the agent — the outermost
+ * one — and nothing else needs changing:
+ *
+ * ```ts
+ * const retriever = instrumentRetriever(
+ *   new HybridRetriever([new EmbeddingRetriever(embedder, store), new LexicalRetriever(store)]),
+ * );
+ * ```
+ *
+ * {@link createRetrievalTool} already does this for the tool it builds, so agentic retrieval is
+ * instrumented with no host change at all; call this directly for inject-mode retrieval
+ * (`AgentModule.forRoot({ retrieval })`) or for a host that calls `retrieve` itself. Wrapping twice
+ * is harmless — see the composed-retrieval section above.
+ */
+declare function instrumentRetriever(retriever: Retriever, options?: InstrumentRetrieverOptions): Retriever;
+
 interface RetrievalToolOptions {
     /** Tool name the model sees. Default `search_knowledge`. */
     name?: string;
     description?: string;
     /** Passages per search. Default lets the retriever decide (typically 5). */
     topK?: number;
+    /**
+     * Retrieval telemetry (`aviary:rag:retrieval` — duration, chunk count, score distribution, store
+     * and collection). **On by default**, because this tool is the once-per-retrieval seam in agentic
+     * mode: instrumenting here is what makes the RAG panels work for a host that only ever calls
+     * `createRetrievalTool`, with no wiring at all. It costs nothing when nobody subscribes (see
+     * {@link instrumentRetriever}), and cannot double-count when the host has already wrapped the
+     * retriever itself.
+     *
+     * Pass `false` to opt a single tool out — a host that reports retrieval its own way, or one whose
+     * corpus is small enough that the events are noise.
+     */
+    telemetry?: boolean | InstrumentRetrieverOptions;
 }
 /** A functional tool (`{ spec, handler }`) — pass it to nestjs `provideAgentTool`. */
 interface RetrievalTool {
@@ -949,10 +1202,14 @@ interface RetrievalTool {
  * decides it needs context. Its output `{ passages }` persists as the tool call's result, so sources
  * flow to the frontend and telescope through the normal tool-call machinery (the citation surface).
  *
+ * The retrieval ITSELF is also instrumented (`aviary:rag:retrieval`) unless `telemetry: false` — the
+ * tool-call row says a retrieval happened, the retrieval event says how long it took, how much came
+ * back and how good it was. See {@link instrumentRetriever}.
+ *
  * ```ts
  * providers: [provideAgentTool(createRetrievalTool(retriever))]
  * ```
  */
 declare function createRetrievalTool(retriever: Retriever, options?: RetrievalToolOptions): RetrievalTool;
 
-export { type ChunkOptions, type ChunkRecord, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalTool, type RetrievalToolOptions, type StoredChunk, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, documentIdOf, ingestChunks, ingestDocuments, isLexicalVectorStore };
+export { type ChunkOptions, type ChunkRecord, type DescribesRetrieval, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HybridRetriever, type HybridRetrieverOptions, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, type InstrumentRetrieverOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryVectorStore, type MetadataPatch, type PgClient, PgVectorStore, type PgVectorStoreOptions, RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_CHANNEL, RAG_RETRIEVAL_EVENT, type RagRetrievalEvent, type RedisSearchClient, RedisVectorSchemaMismatchError, RedisVectorStore, type RedisVectorStoreOptions, RerankingRetriever, type RerankingRetrieverOptions, type RetrievalDescriptor, type RetrievalTool, type RetrievalToolOptions, type RetrieverKind, type StoredChunk, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, type VectorStoreKind, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, documentIdOf, emitRagRetrieval, ingestChunks, ingestDocuments, instrumentRetriever, isLexicalVectorStore };