@dudousxd/nestjs-agent-rag

RAG for the agent. It's framework-agnostic (depends only on -core): you bring an embedding model and, for pgvector or Redis, a driver. Ships chunking, ingestion, dense / lexical / hybrid / reranking Retrievers, three VectorStore adapters (in-memory, pgvector, RediSearch), dependency-free HTTP embedding and rerank clients, retrieval telemetry, and tree navigation for long documents.

For the full walkthrough (agentic vs inject mode, citations, how it plugs into the loop) see the RAG guide. This page is the package reference.

InstallCopy Anchor Link

pnpm add @dudousxd/nestjs-agent-rag @dudousxd/nestjs-agent-core

APICopy Anchor Link

Building blocksCopy Anchor Link

import {
  EmbeddingRetriever,
  MemoryVectorStore,
  ingestDocuments,
} from '@dudousxd/nestjs-agent-rag';
import { aiSdkEmbedding } from '@dudousxd/nestjs-agent-ai-sdk';
import { openai } from '@ai-sdk/openai';

const embedder = aiSdkEmbedding(openai.embedding('text-embedding-3-small'));
const store = new MemoryVectorStore();

await ingestDocuments(
  [{ id: 'refund-policy', text: '…', source: 'docs/refunds' }],
  { embedder, store, chunkSize: 800 },
);

const retriever = new EmbeddingRetriever(embedder, store);

pgvectorCopy Anchor Link

PgVectorStore takes a pg Pool, a Drizzle database (drizzle(pool) / drizzle(sql)), a postgres.js sql, or a hand-written PgClient ({ query(sql, params) → rows }). The package pulls in no driver of its own; toPgClient does the adapting.

import { Pool } from 'pg';
import { PgVectorStore } from '@dudousxd/nestjs-agent-rag';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });
const store = new PgVectorStore(pool, { dimensions: 1536 }); // or new PgVectorStore(db) with Drizzle
await store.ensureSchema(); // CREATE EXTENSION vector + table + HNSW cosine index

store.schemaStatements() returns the same DDL as strings, for a migration instead of a boot-time side effect. Other options (all off by default):

NUL bytes are stripped from every text/jsonb binding (Postgres rejects them). Every filtered statement goes through the protected whereConditions(filter, params), so a subclass can map filters onto its own columns in one place.

Full-text search on PostgresCopy Anchor Link

PgLexicalVectorStore is the same store plus searchText (a LexicalVectorStore), so LexicalRetriever and HybridRetriever work on Postgres as on RediSearch:

import {
  EmbeddingRetriever, HybridRetriever, LexicalRetriever, PgLexicalVectorStore,
} from '@dudousxd/nestjs-agent-rag';

const store = new PgLexicalVectorStore(pool, {
  dimensions: 1536,
  fullText: { config: 'simple' }, // or { column: 'tsv' } for a tsvector column you maintain
});
const hybrid = new HybridRetriever([
  new EmbeddingRetriever(embedder, store),
  new LexicalRetriever(store),
]);

fullText options: config (text-search configuration, default simple; must match the index), column (your own tsvector column; without it ensureSchema adds a GIN index over to_tsvector(config, text)), anyTermFallback (default true), stopWords (default DEFAULT_STOP_WORDS — English, Portuguese, Spanish; false keeps every word).

A question is searched by its meaningful terms: stop words of the language(s) it is written in are dropped, and rows holding any remaining term are ranked by the sum of the matched terms' IDF (BM25 without term frequencies), ts_rank_cd breaking ties. Quoted phrases and -word go through websearch_to_tsquery as written first; anyTermFallback: false keeps only that (every word must appear). keywordTerms, hasSearchSyntax and anyTermTsquery are exported for other stores. On a populated table, create the GIN index in a migration (schemaStatements() prints it).

HTTP embeddings and rerankerCopy Anchor Link

No SDK needed for the two HTTP contracts most providers and self-hosted servers speak:

import { HttpReranker, RerankingRetriever, openAiEmbeddings } from '@dudousxd/nestjs-agent-rag';

// Any OpenAI-compatible POST /embeddings: OpenAI, a gateway, Ollama, TEI, vLLM…
const embedder = openAiEmbeddings({
  baseUrl: 'http://tei:8080/v1', // default https://api.openai.com/v1
  model: 'BAAI/bge-m3',
  apiKey: process.env.EMBEDDINGS_API_KEY, // optional
  onUsage: (tokens) => meter.add(tokens), // optional
});

// Cohere / Jina / Voyage / TEI-style POST /rerank
const reranker = new HttpReranker({
  url: 'https://api.cohere.com/v2/rerank',
  model: 'rerank-v3.5',
  apiKey: process.env.COHERE_API_KEY,
});
const precise = new RerankingRetriever(retriever, reranker, { fetchTopK: 30 });

openAiEmbeddings defaults: batchSize 64, maxInputChars 24 000 (longer inputs are truncated; Infinity disables), timeoutMs 120 000. A batch the server refuses as too large (HTTP 413, or TEI's batch size N > maximum allowed batch size M; see isBatchTooLarge) is split in halves and retried, later requests to the same server and model start at the size that worked, and each split is reported through onWarn. HttpReranker's format is 'auto' (default; sends both documents and texts), 'cohere' or 'tei'; timeoutMs defaults to 30 000. Both throw HttpModelError (with the HTTP status) on failure.

TelemetryCopy Anchor Link

Each retrieval can publish one aviary:rag:retrieval diagnostics event (RAG_RETRIEVAL_CHANNEL): { retriever, store?, collection?, topK, chunks, zeroHit, topScore?, meanScore?, failed, error? }, with the duration on the envelope. Counts, durations and kinds only — never query or passage text.

createRetrievalTool instruments the retriever it wraps by default. For inject mode or any code that calls retrieve directly, wrap it once:

import { instrumentRetriever } from '@dudousxd/nestjs-agent-rag';

const retriever = instrumentRetriever(hybrid, {
  // optional: name the collection per call when one index holds many
  collection: (filter) => (typeof filter?.collectionId === 'string' ? filter.collectionId : undefined),
});

A composed retrieval is one event: the outermost instrumented retriever reports, inner ones stay silent. With no subscriber the wrapper delegates straight through; a throwing retriever is reported as failed and rethrown unchanged. Telescope subscribes and renders the Retrieval and Retrieval sources sections of its Agent tab.

Tree navigation (long documents)Copy Anchor Link

For long structured documents (regulations, contracts, 10-Ks, manuals), chunk search tends to find the right document and lose the right page. PageIndex-style tree navigation builds a table-of-contents tree per long document at ingestion, and at query time an LLM walks the outline to the sections that answer. It costs LLM calls and seconds per query, so the intended shape is hybrid first, tree navigation only inside the top long documents.

import {
  PgDocumentTreeStore, TreeNavigationRetriever, TwoStageRetriever,
  createNavigateDocumentTool, indexDocumentTree, openAiChatTreeLlm,
} from '@dudousxd/nestjs-agent-rag';

const trees = new PgDocumentTreeStore(pool); // same clients as PgVectorStore
await trees.ensureSchema();                  // or trees.schemaStatements() in a migration
const llm = openAiChatTreeLlm({ model: 'gpt-4.1-mini', apiKey }); // or treeLlmFromModelProvider(provider)

// At ingestion, next to chunk + embed. Skips short docs (default < 20 pages and < 60k chars).
await indexDocumentTree(
  { pages, title: file.name }, // or { sections: [{ title, level, text, page }] }, optional outline
  { store: trees, documentId: file.id, llm, metadata: { ownerId }, source: file.name },
);

const navigator = new TreeNavigationRetriever({ store: trees, llm });
// First stage picks documents; long ones among the top `considerDocuments` (3) get navigated
// (at most `navigateDocuments`, 2); short ones keep their chunks.
const retriever = new TwoStageRetriever(hybrid, navigator, { navigateDocuments: 2 });

// …or let the model open a long document itself: navigate_document({ documentId, question })
provideAgentTool(createNavigateDocumentTool(navigator, { filter: (ctx) => ({ ownerId: ctx.actor.id }) }));

• Building uses the cheapest structure that works: the passed outline, then section titles or detected headings, then LLM structuring only for documents with no usable structure, and page groups as the never-failing fallback. A hard per-document budget (maxCalls, maxInputTokens, maxOutputTokens, timeoutMs, callTimeoutMs) is checked before every call, with no retries. Builds are fingerprinted: an unchanged document costs no LLM call; a changed one re-summarizes only changed sections. Without llm the build is LLM-free.
• Navigating: an outline under singlePassMaxChars is navigated in one call; larger ones by a bounded beam (beamWidth, maxSteps) under a per-navigation budget. Passages carry documentId, nodeId, title, pageStart/pageEnd and path in their metadata; navigate() / search() also return the step-by-step trail.
• Access control: DocumentTreeStore filters have the vector stores' semantics (scalar equality, array match-any, empty-array deny), and the navigator, TwoStageRetriever and the tool pass the caller's filter to every tree read.
• LLM adapters (TreeLlm): openAiChatTreeLlm (any OpenAI-compatible /chat/completions), treeLlmFromModelProvider, cachedTreeLlm(llm, cache?), and the deterministic keywordTreeLlm() for tests. MemoryDocumentTreeStore is the in-memory store.