@dudousxd/nestjs-agent-rag 0.12.0 → 0.13.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Passage, Retriever, EmbeddingProvider, RetrieveOptions, Reranker, ToolSpec, ToolHandler, RerankOptions } from '@dudousxd/nestjs-agent-core';
+import { Passage, Retriever, EmbeddingProvider, RetrieveOptions, Reranker, ToolSpec, ToolHandler, RerankOptions, ModelProvider, AiToolCtx } from '@dudousxd/nestjs-agent-core';
 
 interface ChunkOptions {
     /** Target max characters per chunk. Default 800. */
@@ -327,7 +327,7 @@ declare function documentIdOf(chunkId: string): string;
  * 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';
+type RetrieverKind = 'embedding' | 'keyword' | 'lexical' | 'hybrid' | 'filtered' | 'reranking' | 'tree-navigation' | 'two-stage' | 'unknown';
 /** Which backend held the chunks. Omitted entirely for a retriever that holds its own (keyword). */
 type VectorStoreKind = 'memory' | 'pg' | 'redis';
 /**
@@ -1448,7 +1448,12 @@ interface OpenAiEmbeddingsOptions {
     apiKey?: string;
     /** Output width for models that support shortening (`text-embedding-3-*`), sent as `dimensions`. */
     dimensions?: number;
-    /** Inputs per request. Default 64. */
+    /**
+     * Inputs per request. Default 64. When the server refuses a request for its size (see
+     * {@link isBatchTooLarge}) the batch is split in halves and retried, and later requests use the
+     * size that worked — so a server whose limit is below this (TEI's `--max-client-batch-size`
+     * defaults to 32) costs one refused request, not a failed ingestion.
+     */
     batchSize?: number;
     /**
      * Inputs longer than this many characters are truncated before sending, so one oversized chunk
@@ -1462,15 +1467,28 @@ interface OpenAiEmbeddingsOptions {
     timeoutMs?: number;
     /** Called with the provider-reported token count of every request — for cost accounting. */
     onUsage?: (tokens: number) => void;
+    /**
+     * Called when the server refused a batch for its size and it was split — a misconfiguration worth
+     * surfacing: raise the server's limit (TEI: `--max-client-batch-size`) or lower `batchSize`.
+     */
+    onWarn?: (message: string) => void;
     /** `fetch` to use. Default the global one. */
     fetch?: typeof fetch;
 }
+/**
+ * Did the server refuse this request for its **size** — too many inputs (TEI's
+ * `--max-client-batch-size`: `batch size 64 > maximum allowed batch size 32`) or too large a
+ * payload? Those are fixed by sending fewer inputs per request; anything else (auth, a bad model,
+ * one input over the context window) is not, and is rethrown as is.
+ */
+declare function isBatchTooLarge(error: unknown): boolean;
 /**
  * An {@link EmbeddingProvider} over any OpenAI-compatible `POST /v1/embeddings` endpoint, with no SDK
  * dependency: OpenAI itself, or a gateway/local server speaking the same protocol (TEI, Ollama,
  * vLLM, LocalAI…). For a Vercel AI SDK model use `aiSdkEmbedding` from `-ai-sdk` instead.
  *
- * Batches by {@link OpenAiEmbeddingsOptions.batchSize}, restores input order from each item's
+ * Batches by {@link OpenAiEmbeddingsOptions.batchSize} — splitting and retrying a batch the server
+ * refuses as too large, and remembering the size that worked — restores input order from each item's
  * `index`, and fails loudly (an {@link HttpModelError}) on a non-2xx answer or a vector count that
  * doesn't match the inputs. Empty strings are sent as a single space, since OpenAI rejects them.
  *
@@ -1525,4 +1543,788 @@ declare class HttpReranker implements Reranker {
     rerank(query: string, passages: Passage[], options?: RerankOptions): Promise<Passage[]>;
 }
 
-export { type ChunkOptions, type ChunkRecord, DEFAULT_STOP_WORDS, type DescribesRetrieval, type DrizzleLike, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HttpModelError, HttpReranker, type HttpRerankerOptions, 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 NodePgQueryable, type OpenAiEmbeddingsOptions, type PgClient, type PgClientSource, type PgFullTextOptions, PgLexicalVectorStore, PgVectorStore, type PgVectorStoreOptions, type PostgresJsSql, 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, anyTermTsquery, applyMetadataPatch, chunkDocuments, chunkIndexOf, chunkText, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, documentIdOf, emitRagRetrieval, hasSearchSyntax, ingestChunks, ingestDocuments, instrumentRetriever, isLexicalVectorStore, keywordTerms, openAiEmbeddings, toPgClient };
+/**
+ * The data model of tree navigation retrieval: a hierarchical table of contents per long document
+ * (PageIndex-style: sections with page ranges and summaries), built once at ingestion and read by an
+ * LLM at query time to walk to the relevant sections instead of ranking hundreds of look-alike chunks.
+ */
+/**
+ * One addressable piece of a document's text, in reading order — a PDF page, or a section of a
+ * markdown/HTML document. Tree nodes point at ranges of units, and navigation reads the text of the
+ * units a chosen node spans. `index` is the unit's zero-based position; `page` its 1-based page
+ * number when the document has pages.
+ */
+interface TreeUnit {
+    index: number;
+    text: string;
+    /** 1-based page number (PDF). Defaults to `index + 1` for page input; absent for section input. */
+    page?: number;
+}
+/**
+ * A heading the document declares about itself: a PDF outline (bookmark) entry, a markdown header,
+ * a section boundary your extractor already knows. `unit` is the zero-based unit it starts in;
+ * `page` (1-based) is accepted instead for page input. `level` 1 is top level.
+ */
+interface TreeHeading {
+    title: string;
+    level: number;
+    unit?: number;
+    page?: number;
+}
+/** A section as produced by an extractor that already splits on headings. */
+interface TreeSection {
+    text: string;
+    title?: string;
+    /** Heading depth, 1 = top level. Sections without a level are treated as level 1. */
+    level?: number;
+    /** 1-based page the section starts on, when known. */
+    page?: number;
+}
+/**
+ * What {@link import('./build.js').buildDocumentTree} builds from. Give exactly one of `pages`
+ * (one string per page, in order) or `sections` (heading-split text). `outline`, when present, is the
+ * cheapest and most reliable structure there is (a PDF's bookmarks) and is used before any heuristic.
+ */
+interface DocumentTreeInput {
+    pages?: string[];
+    sections?: TreeSection[];
+    /** Headings the document declares (PDF outline/bookmarks), in reading order. */
+    outline?: TreeHeading[];
+    /** Document title, shown to the navigating LLM and used as the citation source. */
+    title?: string;
+}
+/** How the structure of a tree was obtained, cheapest first. */
+type TreeStructureSource = 
+/** From {@link DocumentTreeInput.outline}. */
+'outline'
+/** From section titles/levels or headings detected in the text — no LLM. */
+ | 'headings'
+/** An LLM proposed the sections (the document had no usable outline). */
+ | 'llm'
+/** Fallback: fixed-size page groups. Always succeeds; used when everything above failed or was skipped. */
+ | 'flat';
+/** Where a node's summary came from. */
+type TreeSummarySource = 'llm' | 'text' | 'reused';
+interface DocumentTreeNode {
+    /** Stable within the tree: `0001`, `0002`… in depth-first order (PageIndex's scheme). */
+    id: string;
+    title: string;
+    /** What the section covers — what the navigating LLM reads to decide whether to go in. */
+    summary?: string;
+    summarySource?: TreeSummarySource;
+    /** First and last unit (inclusive, zero-based) the node spans, children included. */
+    unitStart: number;
+    unitEnd: number;
+    /** First and last page (1-based, inclusive) when the document has pages. */
+    pageStart?: number;
+    pageEnd?: number;
+    /**
+     * Titles of descendants removed to respect `maxDepth` — kept because they are routing information:
+     * the pages are still reachable by reading this node, the titles tell the navigator they are here.
+     */
+    keyItems?: string[];
+    /** Hash of the node's title and the text it spans; an incremental rebuild reuses a summary when it matches. */
+    contentHash: string;
+    children: DocumentTreeNode[];
+}
+/** What a build cost and how it ended — persisted with the tree, so an operator can see it. */
+interface TreeBuildStats {
+    llmCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    durationMs: number;
+    /** Set when the structure step fell back (to `flat`) or summaries were cut short, and why. */
+    fallbackReason?: string;
+    /** True when the per-document budget or timeout ran out at some point during the build. */
+    budgetExhausted: boolean;
+    /** Summaries carried over unchanged from the previous tree (incremental rebuild). */
+    reusedSummaries: number;
+}
+interface DocumentTree {
+    documentId: string;
+    /** Format version of this structure. */
+    version: 1;
+    title?: string;
+    /** One-paragraph description of the whole document (LLM, when budget allows). */
+    description?: string;
+    structure: TreeStructureSource;
+    /**
+     * Hash of the input text and every build option that shapes the tree. Equal fingerprint ⇒ the
+     * build would produce the same tree, so it is skipped (see `previous` in the build options).
+     */
+    fingerprint: string;
+    unitCount: number;
+    /** Top-level nodes. */
+    nodes: DocumentTreeNode[];
+    stats: TreeBuildStats;
+    /**
+     * Document metadata used for access filtering, exactly like chunk metadata in a vector store
+     * (tenant, audience, collection…). Stores apply `filter` to it with the vector stores' semantics.
+     */
+    metadata?: Record<string, unknown>;
+    /** Citation-facing origin (title, URL), copied onto returned passages. */
+    source?: string;
+    /** ISO timestamp of the build. */
+    builtAt: string;
+}
+/** Walk a tree depth-first (pre-order). */
+declare function walkTree(nodes: readonly DocumentTreeNode[], path?: readonly DocumentTreeNode[]): Generator<{
+    node: DocumentTreeNode;
+    path: readonly DocumentTreeNode[];
+}>;
+/** Index a tree's nodes by id, each with its ancestors. */
+declare function indexTree(tree: Pick<DocumentTree, 'nodes'>): Map<string, {
+    node: DocumentTreeNode;
+    path: readonly DocumentTreeNode[];
+}>;
+
+/**
+ * Deterministic structure detection — the cheap path that runs before any LLM. Finds headings in
+ * page text: markdown headers, and the numbered/keyword headings long structured documents use
+ * (`PART 52`, `Subpart 9.1`, `Item 7.`, `52.236-5 Material and Workmanship.`, `3.2 Scope`).
+ */
+/** A heading found in (or declared for) the document, before nesting. */
+interface DetectedHeading {
+    title: string;
+    level: number;
+    unit: number;
+    /** The heading is the first text of its unit, so the previous section ends in the unit before. */
+    atUnitStart: boolean;
+}
+/**
+ * Detect headings in each unit's text. `markdownOnly` restricts detection to markdown headers (for
+ * text you know is markdown, where a numbered line is more likely a list item).
+ *
+ * Besides running headers (below), it drops **table-of-contents listings**: five or more
+ * consecutive keyword/numbered heading lines with no body text between them are a contents page
+ * (a regulation part opens with one), not sections — only a leading top-level heading of the run
+ * (`PART 2—…`) and its last line (the first real heading, which body text follows) are kept. Markdown headers are explicit and never dropped this way.
+ */
+declare function detectHeadings(texts: readonly string[], markdownOnly?: boolean): DetectedHeading[];
+
+/**
+ * The structured side of every tree-LLM request: what is being asked, as data. The prompt says the
+ * same thing in prose; `task` exists so a deterministic fake (tests, offline dev — see
+ * {@link import('./keyword-tree-llm.js').keywordTreeLlm}) can answer without parsing prose, and so a
+ * host can log or route requests by kind.
+ */
+type TreeLlmTask = {
+    kind: 'structure';
+    /** The window of pages the LLM is asked to find section starts in. */
+    units: {
+        unit: number;
+        page?: number;
+        text: string;
+    }[];
+} | {
+    kind: 'summarize';
+    title: string;
+    text: string;
+} | {
+    kind: 'describe';
+    title?: string;
+    outline: {
+        title: string;
+        summary?: string;
+    }[];
+} | {
+    kind: 'navigate';
+    query: string;
+    /** `single-pass`: the whole tree is shown; `beam`: one level of candidates at a time. */
+    mode: 'single-pass' | 'beam';
+    candidates: TreeLlmCandidate[];
+    /** Max nodes the answer may name. */
+    maxNodes: number;
+} | {
+    kind: 'select';
+    query: string;
+    documents: {
+        id: string;
+        title?: string;
+        description?: string;
+    }[];
+    maxDocuments: number;
+};
+/** A node as shown to the navigating LLM. */
+interface TreeLlmCandidate {
+    id: string;
+    title: string;
+    summary?: string;
+    pages?: string;
+    /** Present on beam candidates: whether the node can be expanded. */
+    hasChildren?: boolean;
+    /** Present in single-pass mode: depth (0 = top level). */
+    depth?: number;
+}
+interface TreeLlmRequest {
+    task: TreeLlmTask;
+    system: string;
+    prompt: string;
+    /** A cap for the reply. Adapters pass it as `max_tokens` when they can. */
+    maxOutputTokens: number;
+    /** Aborted when the call's timeout or the build/navigation deadline passes. */
+    signal: AbortSignal;
+}
+interface TreeLlmResponse {
+    text: string;
+    /** Provider-reported usage. When absent, the budget estimates ~4 characters per token. */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}
+/**
+ * The only LLM surface tree building and navigation need: one prompt in, one text reply out. Replies
+ * are expected to be JSON (for structure / navigate / select) or plain text (summaries); parsing is
+ * lenient (code fences, prose around the object). Bring any model:
+ * {@link treeLlmFromModelProvider} (the agent's own `ModelProvider`), {@link openAiChatTreeLlm}
+ * (any OpenAI-compatible `/chat/completions`), or a function of your own. Use a deterministic
+ * setting (temperature 0) — trees are cached by content, so a flaky model makes rebuilds noisy.
+ */
+type TreeLlm = (request: TreeLlmRequest) => Promise<TreeLlmResponse>;
+/**
+ * Hard limits for one document build or one navigation. Every LLM call is checked against them
+ * **before** it is made (with the prompt's estimated size), so a budget is never overshot by more
+ * than one reply, and nothing retries past it: the failure mode this exists for is an indexer that
+ * burned ~1,240 calls on one PDF it could not structure.
+ */
+interface TreeBudget {
+    /** Max LLM calls. */
+    maxCalls?: number;
+    /** Max input (prompt) tokens across all calls, estimated at ~4 chars/token before each call. */
+    maxInputTokens?: number;
+    /** Max output tokens across all calls. */
+    maxOutputTokens?: number;
+    /** Wall-clock deadline for the whole operation, ms. */
+    timeoutMs?: number;
+    /** Per-call timeout, ms. Default: whatever is left of `timeoutMs`. */
+    callTimeoutMs?: number;
+}
+/** Thrown internally when a budget or deadline would be exceeded; callers turn it into a fallback. */
+declare class TreeBudgetExceededError extends Error {
+    readonly limit: 'calls' | 'inputTokens' | 'outputTokens' | 'timeout';
+    constructor(limit: 'calls' | 'inputTokens' | 'outputTokens' | 'timeout');
+}
+/** ~4 characters per token: the budget's estimate when a provider reports no usage. */
+declare function estimateTokens(text: string): number;
+/**
+ * Pull the JSON object out of a model reply: bare, fenced in ```json, or surrounded by prose.
+ * Returns `undefined` when there is none (never throws).
+ */
+declare function parseJsonReply(text: string): Record<string, unknown> | undefined;
+/**
+ * A {@link TreeLlm} over the agent's own {@link ModelProvider}: one `runTurn` with no tools and a
+ * discarding sink. Usage comes from the provider's report.
+ */
+declare function treeLlmFromModelProvider(provider: ModelProvider): TreeLlm;
+interface OpenAiChatTreeLlmOptions {
+    model: string;
+    /** Base URL up to and including `/v1`. Default `https://api.openai.com/v1`. */
+    baseUrl?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    /** Default 0 — trees are cached by content, determinism keeps rebuilds quiet. */
+    temperature?: number;
+    /**
+     * Send `response_format: { type: 'json_object' }` on JSON tasks. Default `false`: not every
+     * OpenAI-compatible server accepts it, and replies are parsed leniently anyway.
+     */
+    jsonMode?: boolean;
+    /** Extra body fields (a reasoning switch, provider routing). */
+    body?: Record<string, unknown>;
+    fetch?: typeof fetch;
+}
+/**
+ * A {@link TreeLlm} over any OpenAI-compatible `POST /v1/chat/completions` — OpenAI, a gateway,
+ * vLLM, Ollama, DeepSeek, Qwen… — with no SDK dependency. Throws `HttpModelError` on a non-2xx.
+ */
+declare function openAiChatTreeLlm(options: OpenAiChatTreeLlmOptions): TreeLlm;
+/** A get/set cache — a `Map`, an LRU, a Redis wrapper. Values are whole replies. */
+interface TreeLlmCache {
+    get(key: string): TreeLlmResponse | undefined | Promise<TreeLlmResponse | undefined>;
+    set(key: string, value: TreeLlmResponse): unknown;
+}
+/**
+ * Memoize a {@link TreeLlm} by the exact request (task kind, system prompt, prompt, output cap).
+ * With a deterministic model that makes a rebuild of an unchanged section, or a repeated question,
+ * free. Cached replies report zero usage, so they cost nothing against a budget but a call slot.
+ */
+declare function cachedTreeLlm(llm: TreeLlm, cache?: TreeLlmCache): TreeLlm;
+/**
+ * A fast, deterministic, non-cryptographic 64-bit hash (two independent 32-bit FNV-1a/murmur-mixed
+ * lanes) as 16 hex chars — content fingerprints and cache keys, not security.
+ */
+declare function stableHash(text: string): string;
+
+interface BuildDocumentTreeOptions {
+    documentId: string;
+    /**
+     * The model for summaries, the document description, and structuring documents with no usable
+     * outline. Omit it and the build is LLM-free: outline/headings or page groups, with the start of
+     * each section's text as its summary.
+     */
+    llm?: TreeLlm;
+    /** Deepest level kept (1 = top-level sections only). Deeper headings become `keyItems`. Default 4. */
+    maxDepth?: number;
+    /**
+     * Hard per-document limits for every LLM call of the build. Defaults: 60 calls, 400k input
+     * tokens, 40k output tokens, 5 minutes overall, 60 s per call. Running out is not an error: the
+     * structure step falls back to page groups, and remaining summaries use the section's own text.
+     */
+    budget?: TreeBudget;
+    /** Summarize nodes with the LLM. Default `true` when `llm` is set. */
+    summaries?: boolean;
+    /** A node whose text is shorter than this is its own summary (no LLM call). Default 600 chars. */
+    summaryMinChars?: number;
+    /** Text of a node sent to the summarizer, at most. Default 8 000 chars. */
+    summaryInputChars?: number;
+    /** Concurrent summary calls. Default 4. */
+    concurrency?: number;
+    /** Write a one-paragraph description of the document. Default `true` when `llm` is set. */
+    describe?: boolean;
+    /**
+     * Find headings in the text (markdown headers, `PART 52`, `Item 7.`, `3.2 Scope`…) when there is
+     * no outline and sections carry no titles. `'markdown'` only trusts markdown headers. Default `true`.
+     */
+    detectHeadings?: boolean | 'markdown';
+    /** At least this many headings for a detected structure to be used. Default 3. */
+    minHeadings?: number;
+    /** Ask the LLM for the structure when nothing deterministic worked. Default `true` when `llm` is set. */
+    llmStructure?: boolean;
+    /** Characters of text per structuring call. Default 24 000. */
+    structureWindowChars?: number;
+    /**
+     * Structuring calls allowed. A document needing more windows than this is not sent at all —
+     * it goes straight to page groups instead of spending a budget it cannot finish. Default 12.
+     */
+    maxStructureCalls?: number;
+    /** Units per page-group node (flat trees, and splitting long leaves). Default 5. */
+    groupSize?: number;
+    /** A leaf spanning more units than this is split into page groups. Default 10. */
+    maxLeafUnits?: number;
+    /** Children per level before page groups are grouped again (flat trees). Default 12. */
+    maxChildren?: number;
+    /** The previous tree of this document: an unchanged input returns it as is; changed nodes are re-summarized, the rest reuse their summaries. */
+    previous?: DocumentTree;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    signal?: AbortSignal;
+}
+interface BuiltDocumentTree {
+    tree: DocumentTree;
+    /** The units the node ranges index — persist them with the tree ({@link import('./store.js').DocumentTreeStore.put}). */
+    units: TreeUnit[];
+    /** `true` when `previous` had the same fingerprint and was returned without building. */
+    unchanged: boolean;
+}
+/** The text a node spans (children included), joined in reading order. */
+declare function spanText(units: readonly TreeUnit[], start: number, end: number): string;
+/**
+ * Build a document's navigation tree: a hierarchical table of contents whose nodes carry a title,
+ * the page (or section) range they span, and a summary.
+ *
+ * Structure, cheapest first, never looping:
+ *
+ * 1. the `outline` the input declares (PDF bookmarks);
+ * 2. section titles/levels (`sections` input), or headings detected in the text;
+ * 3. the LLM, window by window (only when a document has no usable outline, and only if every
+ *    window fits `maxStructureCalls` and the budget up front);
+ * 4. page groups — always works; the fallback for any failure above.
+ *
+ * Then summaries: top levels first (they matter most for navigation), each node's text sent once,
+ * within the budget; what the budget leaves unsummarized gets the start of its own text. With a
+ * `previous` tree, an unchanged input is returned as is (zero calls), and nodes whose title and text
+ * are unchanged keep their summary.
+ *
+ * The result is deterministic for a deterministic model: node ids are depth-first positions, and
+ * nothing depends on timing except which summaries a timed-out build got to.
+ */
+declare function buildDocumentTree(input: DocumentTreeInput, options: BuildDocumentTreeOptions): Promise<BuiltDocumentTree>;
+
+/**
+ * A deterministic stand-in for the tree LLM — no model, no network — for tests and offline
+ * development. It answers from the structured {@link TreeLlmRequest.task}, never the prose:
+ *
+ * - `navigate` / `select`: ranks candidates by how many of the question's terms their title and
+ *   summary share, keeps those sharing any (deepest first on ties in single-pass mode); in a beam,
+ *   candidates with subsections are expanded, the rest read;
+ * - `summarize`: the section's first sentence; `describe`: the top-level titles;
+ * - `structure`: lines in ALL CAPS (or markdown headers) become level-1 sections.
+ *
+ * Wrap it to count calls, inject failures or slow replies when testing budgets.
+ */
+declare function keywordTreeLlm(): TreeLlm;
+
+/** A stored tree without its nodes — what listing and document selection need. */
+interface DocumentTreeHeader {
+    documentId: string;
+    title?: string;
+    description?: string;
+    structure: DocumentTree['structure'];
+    fingerprint: string;
+    unitCount: number;
+    metadata?: Record<string, unknown>;
+    source?: string;
+    builtAt: string;
+}
+/**
+ * Where navigation trees live: one tree per document plus the units (pages/sections) its node
+ * ranges point at, so navigation can read a node's text without going back to the source file.
+ *
+ * `filter` has **exactly** the vector stores' semantics (see `VectorStore`): every key must match
+ * the tree's `metadata`, an array value is match-any, and an empty array denies. It is an access
+ * boundary — a navigator given a tenant filter must not read another tenant's tree — so every read
+ * that takes one applies it. `readUnits` takes none: call it only for a tree a filtered `get` just
+ * returned (which is what the navigator does).
+ */
+interface DocumentTreeStore {
+    /** Store (replace) a document's tree and units. */
+    put(tree: DocumentTree, units: TreeUnit[]): Promise<void>;
+    /** A document's tree, when it exists **and** passes `filter`. */
+    get(documentId: string, filter?: Record<string, unknown>): Promise<DocumentTree | undefined>;
+    /** The trees of those of `documentIds` that exist and pass `filter` (any order). */
+    getMany(documentIds: readonly string[], filter?: Record<string, unknown>): Promise<DocumentTree[]>;
+    /** Headers (no nodes) of every tree passing `filter`, or of the listed `documentIds` only. */
+    list(options?: {
+        filter?: Record<string, unknown>;
+        documentIds?: readonly string[];
+        limit?: number;
+    }): Promise<DocumentTreeHeader[]>;
+    /** Units `start..end` (inclusive) of a document, in order. */
+    readUnits(documentId: string, start: number, end: number): Promise<TreeUnit[]>;
+    /** Drop a document's tree and units. Unknown ids are a no-op. */
+    remove(documentId: string): Promise<void>;
+}
+/** An in-process {@link DocumentTreeStore} — tests, and single-process apps with small corpora. */
+declare class MemoryDocumentTreeStore implements DocumentTreeStore {
+    private readonly trees;
+    put(tree: DocumentTree, units: TreeUnit[]): Promise<void>;
+    get(documentId: string, filter?: Record<string, unknown>): Promise<DocumentTree | undefined>;
+    getMany(documentIds: readonly string[], filter?: Record<string, unknown>): Promise<DocumentTree[]>;
+    list(options?: {
+        filter?: Record<string, unknown>;
+        documentIds?: readonly string[];
+        limit?: number;
+    }): Promise<DocumentTreeHeader[]>;
+    readUnits(documentId: string, start: number, end: number): Promise<TreeUnit[]>;
+    remove(documentId: string): Promise<void>;
+}
+
+interface PgDocumentTreeStoreOptions {
+    /** Trees table. Default `agent_rag_trees`. */
+    table?: string;
+    /** Units (page/section text) table. Default `${table}_units`, i.e. `agent_rag_trees_units`. */
+    unitsTable?: string;
+    /** Unit rows per multi-row `INSERT`. Default 200. */
+    insertBatchSize?: number;
+}
+/**
+ * A Postgres {@link DocumentTreeStore}: one row per tree (the header columns, `metadata` as `jsonb`
+ * for filtering, the nodes as `jsonb`) and one row per unit of text. Filters compile to the same SQL
+ * as `PgVectorStore`'s — scalar `@>`, array match-any, empty array denies — so the filter you pass
+ * the vector store works here unchanged.
+ *
+ * Takes the same clients as `PgVectorStore`: a `pg` `Pool`, a Drizzle database, a `postgres.js`
+ * `sql`, or a {@link PgClient}. Call {@link PgDocumentTreeStore.ensureSchema} at boot, or copy
+ * {@link PgDocumentTreeStore.schemaStatements} into a migration. Needs no extension.
+ *
+ * Subclassing: every filtered statement goes through {@link PgDocumentTreeStore.whereConditions}, like
+ * `PgVectorStore.whereConditions`, so a subclass can map a filter onto its own columns.
+ */
+declare class PgDocumentTreeStore implements DocumentTreeStore {
+    protected readonly client: PgClient;
+    protected readonly table: string;
+    protected readonly unitsTable: string;
+    private readonly insertBatchSize;
+    constructor(client: PgClientSource, options?: PgDocumentTreeStoreOptions);
+    /** The idempotent DDL {@link PgDocumentTreeStore.ensureSchema} runs, in order — for a migration. */
+    schemaStatements(): string[];
+    ensureSchema(): Promise<void>;
+    /**
+     * The SQL conditions a metadata `filter` compiles to (ANDed), appending bindings to `params`.
+     * Override to map a filter onto your own columns. Return `['false']` to deny.
+     */
+    protected whereConditions(filter: Record<string, unknown> | undefined, params: unknown[]): string[];
+    /** Replace the tree and its units in one transaction (when the client has one). */
+    put(tree: DocumentTree, units: TreeUnit[]): Promise<void>;
+    get(documentId: string, filter?: Record<string, unknown>): Promise<DocumentTree | undefined>;
+    getMany(documentIds: readonly string[], filter?: Record<string, unknown>): Promise<DocumentTree[]>;
+    list(options?: {
+        filter?: Record<string, unknown>;
+        documentIds?: readonly string[];
+        limit?: number;
+    }): Promise<DocumentTreeHeader[]>;
+    readUnits(documentId: string, start: number, end: number): Promise<TreeUnit[]>;
+    remove(documentId: string): Promise<void>;
+}
+
+interface IndexDocumentTreeOptions extends Omit<BuildDocumentTreeOptions, 'previous'> {
+    store: DocumentTreeStore;
+    /**
+     * Only documents with at least this many units (pages, or sections) get a tree; a shorter one is
+     * skipped and any tree it had is removed. Default 20 — tree navigation pays off on long
+     * structured documents and costs latency and LLM spend for nothing on short notes.
+     */
+    minUnits?: number;
+    /** …or at least this many characters, whichever is met first. Default 60 000 (~15k tokens). */
+    minChars?: number;
+}
+type IndexDocumentTreeResult = {
+    status: 'skipped';
+    reason: string;
+} | {
+    status: 'unchanged';
+    tree: DocumentTree;
+} | {
+    status: 'built';
+    tree: DocumentTree;
+};
+/**
+ * Build (or rebuild) a document's tree and store it — the call to make at upload/ingestion time,
+ * next to chunking and embedding. Short documents are skipped (see `minUnits`/`minChars`); an
+ * unchanged document costs one store read and no LLM call; a changed one reuses the summaries of
+ * its unchanged sections. Never throws for a document the LLM cannot structure: the tree falls back
+ * to page groups and `tree.stats.fallbackReason` says why. Store errors do propagate.
+ */
+declare function indexDocumentTree(input: DocumentTreeInput, options: IndexDocumentTreeOptions): Promise<IndexDocumentTreeResult>;
+
+interface TreeNavigationRetrieverOptions {
+    store: DocumentTreeStore;
+    llm: TreeLlm;
+    /**
+     * A tree whose outline (titles, pages, summaries) fits in this many characters is navigated in
+     * **one** call that sees the whole outline — PageIndex's tree search, the variant measured in the
+     * benchmark. Bigger trees are walked level by level (a beam). Default 40 000 (~10k tokens).
+     */
+    singlePassMaxChars?: number;
+    /** Nodes the navigator may expand or read per beam step. Default 4. */
+    beamWidth?: number;
+    /** Beam levels, at most. Nodes still marked "expand" at the last level are read whole. Default 4. */
+    maxSteps?: number;
+    /** Nodes returned per document, at most. Default 5. */
+    maxNodes?: number;
+    /**
+     * Hard per-document limits for one navigation. Defaults: 6 calls, 60k input tokens, 4k output
+     * tokens, 60 s. Running out mid-walk returns what was chosen so far (the nodes last marked for
+     * expansion are read whole) and records `stoppedBy: 'budget'`.
+     */
+    budget?: TreeBudget;
+    /** Characters of text per returned node. Default 12 000. */
+    maxPassageChars?: number;
+    /** Units (pages/sections) read per returned node, at most. Default 25. */
+    maxUnitsPerNode?: number;
+    /** Characters across all passages of one navigation (every document). Default 48 000 (~12k tokens). */
+    maxContextChars?: number;
+    /**
+     * {@link TreeNavigationRetriever.retrieve} with no first stage: documents navigated per query. When
+     * more trees pass the filter, the LLM picks this many from their titles and descriptions
+     * (PageIndex's document selection). Default 3.
+     */
+    maxDocuments?: number;
+    /** Trees shown to document selection, at most. Default 200. */
+    maxSelectionCandidates?: number;
+    /** Documents navigated in parallel. Default 3. */
+    concurrency?: number;
+}
+/** One step of a navigation, for the audit trail. */
+interface NavigationStep {
+    step: number;
+    /** Node ids shown to the LLM this step. */
+    shown: string[];
+    /** Node ids it chose to open further. */
+    expanded: string[];
+    /** Node ids it chose to read. */
+    read: string[];
+    /** The LLM's stated reasoning, verbatim (capped). */
+    reasoning?: string;
+}
+/** A node navigation chose, with the path that led to it. */
+interface NavigatedNode {
+    nodeId: string;
+    title: string;
+    /** Ancestors from the top level down, then the node itself. */
+    path: {
+        id: string;
+        title: string;
+    }[];
+    pageStart?: number;
+    pageEnd?: number;
+    unitStart: number;
+    unitEnd: number;
+}
+/** The auditable record of navigating one document. */
+interface DocumentNavigation {
+    documentId: string;
+    title?: string;
+    mode: 'single-pass' | 'beam';
+    steps: NavigationStep[];
+    nodes: NavigatedNode[];
+    llmCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    /** Why the walk stopped early, when it did. */
+    stoppedBy?: 'budget' | 'timeout' | 'maxSteps' | 'error' | 'not-found';
+    error?: string;
+}
+interface NavigationResult {
+    passages: Passage[];
+    documents: DocumentNavigation[];
+    /** Set when {@link TreeNavigationRetriever.retrieve} had the LLM pick the documents. */
+    selection?: {
+        candidates: number;
+        selected: string[];
+        reasoning?: string;
+        error?: string;
+    };
+}
+interface NavigateOptions {
+    /** Access filter applied to every tree read (vector-store semantics). */
+    filter?: Record<string, unknown>;
+    /** Overrides the retriever's per-document budget. */
+    budget?: TreeBudget;
+    signal?: AbortSignal;
+}
+/**
+ * Tree navigation retrieval ("vectorless", reasoning-based — PageIndex's method): an LLM reads a
+ * document's table of contents (titles, page ranges, summaries — no body text) and picks the
+ * sections that answer the question; their text comes back as passages, with the path taken and the
+ * model's reasoning recorded so the choice is auditable.
+ *
+ * A small tree is navigated in one call over the whole outline. A large one is walked level by
+ * level: the model sees one level of candidates, opens (`expand`) the promising ones and takes
+ * (`read`) the ones that already answer, until it reaches leaves, runs out of `maxSteps`, or runs
+ * out of its hard per-document {@link TreeBudget} — in which case it returns what it had.
+ *
+ * It pays off on **long structured documents** (regulations, contracts, filings, manuals) where
+ * chunk ranking struggles among hundreds of look-alike passages; on short notes it costs seconds and
+ * LLM spend for nothing. Compose it behind a first stage with {@link TwoStageRetriever}, or give it
+ * to the agent as a tool with {@link createNavigateDocumentTool}.
+ *
+ * As a plain `Retriever`, `retrieve(query, { filter })` navigates the trees that pass `filter`:
+ * all of them when there are at most `maxDocuments`, otherwise the ones the LLM picks from their
+ * descriptions.
+ */
+declare class TreeNavigationRetriever implements Retriever {
+    private readonly options;
+    readonly store: DocumentTreeStore;
+    private readonly llm;
+    constructor(options: TreeNavigationRetrieverOptions);
+    describeRetrieval(): RetrievalDescriptor;
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+    /** {@link retrieve} with the audit trail: which documents, which nodes, why. */
+    search(query: string, options?: NavigateOptions): Promise<NavigationResult>;
+    /**
+     * Navigate the given documents (in parallel, up to `concurrency`) and return their passages in
+     * the order given, within `maxContextChars`. Documents without a tree, or whose tree fails
+     * `filter`, yield no passages and `stoppedBy: 'not-found'`.
+     */
+    navigate(query: string, documentIds: readonly string[], options?: NavigateOptions): Promise<NavigationResult>;
+    private walk;
+    private passagesOf;
+}
+
+interface TwoStageRetrieverOptions {
+    /** Passages pulled from the first stage. Default 20. */
+    fetchTopK?: number;
+    /**
+     * Only the first this-many distinct documents of the first stage are considered for navigation.
+     * Default 3 — past the top few, a document is more likely a large irrelevant tree (the costliest
+     * failure measured: navigating FAR Part 52 because it ranked fourth) than the answer.
+     */
+    considerDocuments?: number;
+    /** Of those, navigate at most this many (the ones that have a tree). Default 2. */
+    navigateDocuments?: number;
+    /** Per-document navigation budget (overrides the navigator's). */
+    budget?: TreeBudget;
+    /** Keep the first stage's chunks of a navigated document after its tree passages. Default `false`. */
+    keepFirstStageChunks?: boolean;
+    /**
+     * The document a first-stage passage belongs to. Default: `metadata.documentId` when it is a
+     * string, else the chunk id without its `#<n>` suffix (the id scheme `chunkDocuments` produces).
+     */
+    documentIdOf?: (passage: Passage) => string;
+    /** Called with each navigation's audit trail (log it, trace it, show it). */
+    onNavigation?: (navigation: DocumentNavigation) => void;
+}
+/**
+ * Hybrid first stage, tree navigation second — the design the benchmark recommends: keep fast
+ * chunk search (hybrid/lexical/dense, 0.3 s, no LLM) for picking **documents**, and navigate the
+ * table of contents only inside the top **long** documents, where chunk ranking is what fails.
+ *
+ * 1. The first stage retrieves `fetchTopK` passages.
+ * 2. Among its first `considerDocuments` distinct documents, those with a tree in the navigator's
+ *    store (build trees only for long documents, see `indexDocumentTree`'s `minUnits`) are long;
+ *    the first `navigateDocuments` of them are navigated, in parallel, each on its own budget.
+ * 3. The output keeps the first stage's order: a navigated document's section passages take the
+ *    place of its chunks (at its best chunk's rank); short documents keep their chunks. A navigation
+ *    that fails or finds nothing leaves that document's chunks in place — never worse than stage one.
+ *
+ * `filter` is passed to both stages, so the access boundary holds on either path.
+ */
+declare class TwoStageRetriever implements Retriever {
+    private readonly firstStage;
+    private readonly navigator;
+    private readonly options;
+    constructor(firstStage: Retriever, navigator: TreeNavigationRetriever, options?: TwoStageRetrieverOptions);
+    describeRetrieval(): RetrievalDescriptor;
+    retrieve(query: string, options?: RetrieveOptions): Promise<Passage[]>;
+    /** {@link retrieve} with the navigations that were run. */
+    search(query: string, options?: RetrieveOptions): Promise<{
+        passages: Passage[];
+        navigations: DocumentNavigation[];
+    }>;
+}
+
+interface NavigateDocumentToolOptions {
+    /** Tool name the model sees. Default `navigate_document`. */
+    name?: string;
+    description?: string;
+    /**
+     * The access filter for this call, from the tool context — e.g. `(ctx) => ({ tenant: ctx.actor.tenantRef })`.
+     * Applied to the tree read, with the vector stores' semantics. Omit only for single-tenant corpora.
+     */
+    filter?: (ctx: AiToolCtx) => Record<string, unknown> | undefined;
+    /** Per-call navigation budget (overrides the navigator's). */
+    budget?: TreeBudget;
+}
+interface NavigateDocumentInput {
+    documentId: string;
+    question: string;
+}
+interface NavigateDocumentOutput {
+    documentId: string;
+    /** `false` when the document has no tree (short documents don't get one) or the caller may not read it. */
+    found: boolean;
+    passages: Passage[];
+    /** The sections chosen and the path to each. */
+    nodes: NavigatedNode[];
+    /** The walk, step by step, with the model's reasoning. */
+    steps: NavigationStep[];
+    stoppedBy?: string;
+    note?: string;
+}
+/** A functional tool (`{ spec, handler }`) — pass it to nestjs `provideAgentTool`. */
+interface NavigateDocumentTool {
+    spec: ToolSpec;
+    handler: ToolHandler;
+}
+/**
+ * The agentic half of two-stage retrieval: `navigate_document(documentId, question)`, a `read`-kind
+ * tool the model calls **after** `search_knowledge` put a long document among its hits — it walks
+ * that document's table of contents to the sections that answer and returns their text, with the
+ * path and reasoning (the citation surface: section titles and page ranges).
+ *
+ * `documentId` may also be a chunk id from a search result (`doc#12`); the chunk suffix is dropped.
+ * A document with no tree answers `found: false` with a note, so the model falls back to the
+ * passages it already has instead of retrying.
+ *
+ * ```ts
+ * providers: [
+ *   provideAgentTool(createRetrievalTool(hybrid)),
+ *   provideAgentTool(createNavigateDocumentTool(navigator, { filter: (ctx) => ({ tenant: ctx.actor.tenantRef }) })),
+ * ]
+ * ```
+ */
+declare function createNavigateDocumentTool(navigator: TreeNavigationRetriever, options?: NavigateDocumentToolOptions): NavigateDocumentTool;
+
+export { type BuildDocumentTreeOptions, type BuiltDocumentTree, type ChunkOptions, type ChunkRecord, DEFAULT_STOP_WORDS, type DescribesRetrieval, type DetectedHeading, type DocumentNavigation, type DocumentTree, type DocumentTreeHeader, type DocumentTreeInput, type DocumentTreeNode, type DocumentTreeStore, type DrizzleLike, EmbeddingRetriever, type EmbeddingRetrieverOptions, FilteredRetriever, HttpModelError, HttpReranker, type HttpRerankerOptions, HybridRetriever, type HybridRetrieverOptions, type IndexDocumentTreeOptions, type IndexDocumentTreeResult, type IndexedDocument, type IngestChunksOptions, type IngestDocument, type IngestOptions, type InstrumentRetrieverOptions, KeywordRetriever, type KeywordRetrieverOptions, LexicalRetriever, type LexicalVectorStore, type ListChunksOptions, MemoryDocumentTreeStore, MemoryVectorStore, type MetadataPatch, type NavigateDocumentInput, type NavigateDocumentOutput, type NavigateDocumentTool, type NavigateDocumentToolOptions, type NavigateOptions, type NavigatedNode, type NavigationResult, type NavigationStep, type NodePgQueryable, type OpenAiChatTreeLlmOptions, type OpenAiEmbeddingsOptions, type PgClient, type PgClientSource, PgDocumentTreeStore, type PgDocumentTreeStoreOptions, type PgFullTextOptions, PgLexicalVectorStore, PgVectorStore, type PgVectorStoreOptions, type PostgresJsSql, 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, type TreeBudget, TreeBudgetExceededError, type TreeBuildStats, type TreeHeading, type TreeLlm, type TreeLlmCache, type TreeLlmCandidate, type TreeLlmRequest, type TreeLlmResponse, type TreeLlmTask, TreeNavigationRetriever, type TreeNavigationRetrieverOptions, type TreeSection, type TreeStructureSource, type TreeSummarySource, type TreeUnit, TwoStageRetriever, type TwoStageRetrieverOptions, UnsafeRemovalError, type VectorRecord, type VectorSearchOptions, type VectorStore, type VectorStoreKind, anyTermTsquery, applyMetadataPatch, buildDocumentTree, cachedTreeLlm, chunkDocuments, chunkIndexOf, chunkText, createNavigateDocumentTool, createRetrievalTool, describeRetrieval, describeSharedSource, describeSource, describesRetrieval, detectHeadings, documentIdOf, emitRagRetrieval, estimateTokens, hasSearchSyntax, indexDocumentTree, indexTree, ingestChunks, ingestDocuments, instrumentRetriever, isBatchTooLarge, isLexicalVectorStore, keywordTerms, keywordTreeLlm, openAiChatTreeLlm, openAiEmbeddings, parseJsonReply, spanText, stableHash, toPgClient, treeLlmFromModelProvider, walkTree };