@dudousxd/nestjs-agent-rag 0.12.0 → 0.13.0

package/dist/index.cjs

@@ -29,7 +29,9 @@ __export(index_exports, {
   HybridRetriever: () => HybridRetriever,
   KeywordRetriever: () => KeywordRetriever,
   LexicalRetriever: () => LexicalRetriever,
+  MemoryDocumentTreeStore: () => MemoryDocumentTreeStore,
   MemoryVectorStore: () => MemoryVectorStore,
+  PgDocumentTreeStore: () => PgDocumentTreeStore,
   PgLexicalVectorStore: () => PgLexicalVectorStore,
   PgVectorStore: () => PgVectorStore,
   RAG_DIAGNOSTIC_LIB: () => RAG_DIAGNOSTIC_LIB,
@@ -38,34 +40,52 @@ __export(index_exports, {
   RedisVectorSchemaMismatchError: () => RedisVectorSchemaMismatchError,
   RedisVectorStore: () => RedisVectorStore,
   RerankingRetriever: () => RerankingRetriever,
+  TreeBudgetExceededError: () => TreeBudgetExceededError,
+  TreeNavigationRetriever: () => TreeNavigationRetriever,
+  TwoStageRetriever: () => TwoStageRetriever,
   UnsafeRemovalError: () => UnsafeRemovalError,
   anyTermTsquery: () => anyTermTsquery,
   applyMetadataPatch: () => applyMetadataPatch,
+  buildDocumentTree: () => buildDocumentTree,
+  cachedTreeLlm: () => cachedTreeLlm,
   chunkDocuments: () => chunkDocuments,
   chunkIndexOf: () => chunkIndexOf,
   chunkText: () => chunkText,
+  createNavigateDocumentTool: () => createNavigateDocumentTool,
   createRetrievalTool: () => createRetrievalTool,
   describeRetrieval: () => describeRetrieval,
   describeSharedSource: () => describeSharedSource,
   describeSource: () => describeSource,
   describesRetrieval: () => describesRetrieval,
+  detectHeadings: () => detectHeadings,
   documentIdOf: () => documentIdOf,
   emitRagRetrieval: () => emitRagRetrieval,
+  estimateTokens: () => estimateTokens,
   hasSearchSyntax: () => hasSearchSyntax,
+  indexDocumentTree: () => indexDocumentTree,
+  indexTree: () => indexTree,
   ingestChunks: () => ingestChunks,
   ingestDocuments: () => ingestDocuments,
   instrumentRetriever: () => instrumentRetriever,
+  isBatchTooLarge: () => isBatchTooLarge,
   isLexicalVectorStore: () => isLexicalVectorStore,
   keywordTerms: () => keywordTerms,
+  keywordTreeLlm: () => keywordTreeLlm,
+  openAiChatTreeLlm: () => openAiChatTreeLlm,
   openAiEmbeddings: () => openAiEmbeddings,
-  toPgClient: () => toPgClient
+  parseJsonReply: () => parseJsonReply,
+  spanText: () => spanText,
+  stableHash: () => stableHash,
+  toPgClient: () => toPgClient,
+  treeLlmFromModelProvider: () => treeLlmFromModelProvider,
+  walkTree: () => walkTree
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/chunk.ts
 function chunkText(text, options = {}) {
   const chunkSize = options.chunkSize ?? 800;
-  const overlap = options.overlap ?? 100;
+  const overlap2 = options.overlap ?? 100;
   const normalized = text.trim();
   if (normalized.length === 0) {
     return [];
@@ -97,7 +117,7 @@ function chunkText(text, options = {}) {
     if (breakAt >= normalized.length) {
       break;
     }
-    start = Math.max(breakAt - overlap, start + 1);
+    start = Math.max(breakAt - overlap2, start + 1);
   }
   return chunks;
 }
@@ -124,12 +144,12 @@ function chunkByRecord(text, chunkSize, separator) {
       }));
       continue;
     }
-    const candidate = current.length > 0 ? `${current}${separator}${trimmed}` : trimmed;
-    if (candidate.length > chunkSize) {
+    const candidate2 = current.length > 0 ? `${current}${separator}${trimmed}` : trimmed;
+    if (candidate2.length > chunkSize) {
       flush();
       current = trimmed;
     } else {
-      current = candidate;
+      current = candidate2;
     }
   }
   flush();
@@ -479,16 +499,16 @@ function keywordTerms(query, max = 24, stopWords = DEFAULT_STOP_WORDS) {
   const best = Math.max(0, ...counts.map(([, n]) => n));
   if (best === 0) return tokens.slice(0, max);
   const stop = counts.filter(([, n]) => n === best).map(([s]) => s);
-  const terms = tokens.filter((t) => !stop.some((s) => s.has(t)));
-  return (terms.length > 0 ? terms : tokens).slice(0, max);
+  const terms2 = tokens.filter((t) => !stop.some((s) => s.has(t)));
+  return (terms2.length > 0 ? terms2 : tokens).slice(0, max);
 }
 __name(keywordTerms, "keywordTerms");
 function hasSearchSyntax(query) {
   return /"[^"]+"/.test(query) || /(^|\s)-[\p{L}\p{N}]/u.test(query);
 }
 __name(hasSearchSyntax, "hasSearchSyntax");
-function anyTermTsquery(terms) {
-  return terms.map((t) => `'${t.replace(/'/g, "")}'`).join(" | ");
+function anyTermTsquery(terms2) {
+  return terms2.map((t) => `'${t.replace(/'/g, "")}'`).join(" | ");
 }
 __name(anyTermTsquery, "anyTermTsquery");
 
@@ -985,8 +1005,8 @@ var PgLexicalVectorStore = class extends PgVectorStore {
         return strict;
       }
     }
-    const terms = keywordTerms(query, 24, this.stopWords);
-    return terms.length === 0 ? [] : this.runRankedTermSearch(terms, options);
+    const terms2 = keywordTerms(query, 24, this.stopWords);
+    return terms2.length === 0 ? [] : this.runRankedTermSearch(terms2, options);
   }
   /** `websearch_to_tsquery` on the query as written: every word, quoted phrases, `-exclusions`. */
   async runTextSearch(query, options) {
@@ -1012,12 +1032,12 @@ var PgLexicalVectorStore = class extends PgVectorStore {
   * once, and `ts_rank_cd` only for the rows ranked within `topK` (ties included): a question full
   * of common words can match most of the table.
   */
-  async runRankedTermSearch(terms, options) {
+  async runRankedTermSearch(terms2, options) {
     const any = `to_tsquery('${this.tsConfig}', $1)`;
     const params = [
-      anyTermTsquery(terms),
+      anyTermTsquery(terms2),
       options.topK,
-      terms
+      terms2
     ];
     const conditions = [
       `${this.tsvector()} @@ ${any}`,
@@ -1721,12 +1741,12 @@ var RedisVectorStore = class {
     if (filterMatchesNothing(options.filter)) {
       return [];
     }
-    const terms = tokenizeQuery(query);
-    if (terms.length === 0) {
+    const terms2 = tokenizeQuery(query);
+    if (terms2.length === 0) {
       return [];
     }
     const filterQuery = buildFilter(options.filter);
-    const textQuery = `@text:(${terms.join("|")})`;
+    const textQuery = `@text:(${terms2.join("|")})`;
     const reply = await this.client.sendCommand([
       "FT.SEARCH",
       this.index,
@@ -1980,8 +2000,8 @@ 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() : {};
+function describeRetrieval(candidate2) {
+  return describesRetrieval(candidate2) ? candidate2.describeRetrieval() : {};
 }
 __name(describeRetrieval, "describeRetrieval");
 function describeSource(base) {
@@ -2514,53 +2534,94 @@ var HttpModelError = class extends Error {
     this.name = "HttpModelError";
   }
 };
+function isBatchTooLarge(error) {
+  if (!(error instanceof HttpModelError)) {
+    return false;
+  }
+  if (error.status === 413) {
+    return true;
+  }
+  return (error.status === 400 || error.status === 422) && /batch.?size|too many inputs|maximum allowed batch|payload too large|max.*(inputs|batch)/i.test(error.message);
+}
+__name(isBatchTooLarge, "isBatchTooLarge");
+var learnedBatchLimits = /* @__PURE__ */ new Map();
 function openAiEmbeddings(options) {
   const url = `${(options.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "")}/embeddings`;
-  const batchSize = Math.max(1, Math.floor(options.batchSize ?? 64));
+  const limitKey = `${url} ${options.model}`;
+  const configured = Math.max(1, Math.floor(options.batchSize ?? 64));
+  let batchSize = Math.min(configured, learnedBatchLimits.get(limitKey) ?? configured);
   const maxInputChars = options.maxInputChars ?? 24e3;
   const timeoutMs = options.timeoutMs ?? 12e4;
   const doFetch = options.fetch ?? fetch;
+  const request = /* @__PURE__ */ __name(async (input) => {
+    const response = await doFetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...options.apiKey ? {
+          authorization: `Bearer ${options.apiKey}`
+        } : {},
+        ...options.headers
+      },
+      body: JSON.stringify({
+        model: options.model,
+        input,
+        ...options.dimensions !== void 0 ? {
+          dimensions: options.dimensions
+        } : {}
+      }),
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const body = await response.text();
+    if (!response.ok) {
+      throw new HttpModelError(response.status, `Embeddings request failed (${response.status}): ${errorMessageOf(body)}`);
+    }
+    const json2 = parseJson(body);
+    const items = [
+      ...json2?.data ?? []
+    ].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+    if (items.length !== input.length || !items.every((item) => Array.isArray(item.embedding))) {
+      throw new HttpModelError(502, `Embeddings returned ${items.length} vectors for ${input.length} inputs`);
+    }
+    const tokens = json2?.usage?.total_tokens ?? json2?.usage?.prompt_tokens;
+    if (typeof tokens === "number" && Number.isFinite(tokens)) {
+      options.onUsage?.(tokens);
+    }
+    return items.map((item) => item.embedding);
+  }, "request");
+  const requestSplitting = /* @__PURE__ */ __name(async (input) => {
+    if (input.length > batchSize) {
+      const vectors = [];
+      for (let start = 0; start < input.length; start += batchSize) {
+        vectors.push(...await requestSplitting(input.slice(start, start + batchSize)));
+      }
+      return vectors;
+    }
+    try {
+      return await request(input);
+    } catch (error) {
+      if (!isBatchTooLarge(error) || input.length <= 1) {
+        throw error;
+      }
+      const half = Math.ceil(input.length / 2);
+      if (half < batchSize) {
+        batchSize = half;
+        learnedBatchLimits.set(limitKey, half);
+        options.onWarn?.(`embeddings server ${url} refused a batch of ${input.length} inputs (${error.message}); retrying in batches of ${half}. Raise the server's batch limit (TEI: --max-client-batch-size) or lower batchSize.`);
+      }
+      return [
+        ...await requestSplitting(input.slice(0, half)),
+        ...await requestSplitting(input.slice(half))
+      ];
+    }
+  }, "requestSplitting");
   return {
     async embed(texts) {
       const vectors = [];
-      for (let start = 0; start < texts.length; start += batchSize) {
+      for (let start = 0; start < texts.length; ) {
         const input = texts.slice(start, start + batchSize).map((text) => (text.length > maxInputChars ? text.slice(0, maxInputChars) : text) || " ");
-        const response = await doFetch(url, {
-          method: "POST",
-          headers: {
-            "content-type": "application/json",
-            ...options.apiKey ? {
-              authorization: `Bearer ${options.apiKey}`
-            } : {},
-            ...options.headers
-          },
-          body: JSON.stringify({
-            model: options.model,
-            input,
-            ...options.dimensions !== void 0 ? {
-              dimensions: options.dimensions
-            } : {}
-          }),
-          signal: AbortSignal.timeout(timeoutMs)
-        });
-        const body = await response.text();
-        if (!response.ok) {
-          throw new HttpModelError(response.status, `Embeddings request failed (${response.status}): ${errorMessageOf(body)}`);
-        }
-        const json = parseJson(body);
-        const items = [
-          ...json?.data ?? []
-        ].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
-        if (items.length !== input.length || !items.every((item) => Array.isArray(item.embedding))) {
-          throw new HttpModelError(502, `Embeddings returned ${items.length} vectors for ${input.length} inputs`);
-        }
-        for (const item of items) {
-          vectors.push(item.embedding);
-        }
-        const tokens = json?.usage?.total_tokens ?? json?.usage?.prompt_tokens;
-        if (typeof tokens === "number" && Number.isFinite(tokens)) {
-          options.onUsage?.(tokens);
-        }
+        vectors.push(...await requestSplitting(input));
+        start += input.length;
       }
       return vectors;
     }
@@ -2576,8 +2637,8 @@ function parseJson(body) {
 }
 __name(parseJson, "parseJson");
 function errorMessageOf(body) {
-  const json = parseJson(body);
-  const message = typeof json?.error === "string" ? json.error : json?.error?.message ?? json?.message ?? void 0;
+  const json2 = parseJson(body);
+  const message = typeof json2?.error === "string" ? json2.error : json2?.error?.message ?? json2?.message ?? void 0;
   return typeof message === "string" ? message : body.slice(0, 300);
 }
 __name(errorMessageOf, "errorMessageOf");
@@ -2652,20 +2713,2284 @@ var HttpReranker = class {
   }
 };
 function itemsOf(body) {
-  let json;
+  let json2;
   try {
-    json = JSON.parse(body);
+    json2 = JSON.parse(body);
   } catch {
     return void 0;
   }
-  if (Array.isArray(json)) {
-    return json;
+  if (Array.isArray(json2)) {
+    return json2;
   }
-  const wrapped = json;
+  const wrapped = json2;
   const items = wrapped?.results ?? wrapped?.data;
   return Array.isArray(items) ? items : void 0;
 }
 __name(itemsOf, "itemsOf");
+
+// src/tree/types.ts
+function* walkTree(nodes, path = []) {
+  for (const node of nodes) {
+    yield {
+      node,
+      path
+    };
+    yield* walkTree(node.children, [
+      ...path,
+      node
+    ]);
+  }
+}
+__name(walkTree, "walkTree");
+function indexTree(tree) {
+  const index = /* @__PURE__ */ new Map();
+  for (const entry of walkTree(tree.nodes)) {
+    index.set(entry.node.id, entry);
+  }
+  return index;
+}
+__name(indexTree, "indexTree");
+
+// src/tree/headings.ts
+var MARKDOWN = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+var KEYWORD_LEVEL = {
+  part: 1,
+  chapter: 1,
+  title: 1,
+  appendix: 1,
+  annex: 1,
+  exhibit: 1,
+  schedule: 1,
+  subpart: 2,
+  article: 2,
+  item: 2,
+  section: 3
+};
+var KEYWORD = /^(PART|Part|CHAPTER|Chapter|TITLE|APPENDIX|Appendix|ANNEX|Annex|EXHIBIT|Exhibit|SCHEDULE|Schedule|SUBPART|Subpart|ARTICLE|Article|ITEM|Item|SECTION|Section)\s+([0-9]{1,4}[A-Z]?(?:[.\-–][0-9A-Z]{1,4}){0,3}|[IVXLC]{1,6}|[A-Z])\b\.?(?:\s*[—–:\-.]\s*|\s+)?(.{0,110})$/;
+var NUMBERED = /^(\d{1,3}(?:\.\d{1,4}){1,4})([-–]\d{1,4})?\.?\s+([A-Z[][^\n]{1,100})$/;
+function clean(title) {
+  return title.replace(/\s+/g, " ").replace(/[\s.:—–-]+$/, "").trim();
+}
+__name(clean, "clean");
+function looksLikeBody(rest) {
+  return /(\d\)?|[%$])\s*$/.test(rest) || rest.split(" ").length > 16;
+}
+__name(looksLikeBody, "looksLikeBody");
+var DANGLING = new Set("a an the of to in for and or as by with on at from that which is are be than under".split(" "));
+function dangling(title) {
+  if (/[,;(]$/.test(title)) {
+    return true;
+  }
+  const last = title.split(/\s+/).pop()?.toLowerCase() ?? "";
+  return DANGLING.has(last);
+}
+__name(dangling, "dangling");
+function detectHeadings(texts, markdownOnly = false) {
+  const headings = [];
+  let inFence = false;
+  let run = [];
+  const dropped = /* @__PURE__ */ new Set();
+  const closeRun = /* @__PURE__ */ __name(() => {
+    if (run.length >= 5) {
+      run.forEach((entry, position) => {
+        const heading = headings[entry.index];
+        const keep = position === run.length - 1 || position === 0 && entry.keyword && heading !== void 0 && heading.level === 1;
+        if (!keep) {
+          dropped.add(entry.index);
+        }
+      });
+    }
+    run = [];
+  }, "closeRun");
+  texts.forEach((text, unit) => {
+    let seenText = false;
+    const lines = text.split("\n").map((raw) => raw.trim());
+    for (let at = 0; at < lines.length; at++) {
+      let line = lines[at] ?? "";
+      if (line.startsWith("```")) {
+        inFence = !inFence;
+        seenText = true;
+        closeRun();
+        continue;
+      }
+      if (line === "") {
+        continue;
+      }
+      if (inFence || line.length > 140) {
+        seenText = true;
+        closeRun();
+        continue;
+      }
+      const atUnitStart = !seenText;
+      seenText = true;
+      const markdown = MARKDOWN.exec(line);
+      if (markdown?.[1] !== void 0 && markdown[2] !== void 0) {
+        closeRun();
+        const title = clean(markdown[2].replace(/\*\*/g, ""));
+        if (title !== "") {
+          headings.push({
+            title,
+            level: markdown[1].length,
+            unit,
+            atUnitStart
+          });
+        }
+        continue;
+      }
+      if (markdownOnly) {
+        continue;
+      }
+      const candidate2 = KEYWORD.test(line) || NUMBERED.test(line);
+      if (candidate2) {
+        for (let joined = 0; joined < 2; joined++) {
+          const next = lines[at + 1];
+          if (!/[a-z]-$/.test(line) || next === void 0 || next === "" || next.length > 80) {
+            break;
+          }
+          line = `${line.slice(0, -1)}${next}`;
+          at += 1;
+        }
+      }
+      const keyword = KEYWORD.exec(line);
+      if (keyword?.[1] !== void 0 && keyword[2] !== void 0) {
+        const rest = keyword[3] ?? "";
+        const allCaps = keyword[1] === keyword[1].toUpperCase();
+        if (!looksLikeBody(rest) && !/^[a-z,;)]/.test(rest) && (rest !== "" || allCaps) && !dangling(clean(line))) {
+          const level = KEYWORD_LEVEL[keyword[1].toLowerCase()] ?? 2;
+          run.push({
+            index: headings.length,
+            keyword: true
+          });
+          headings.push({
+            title: clean(line),
+            level,
+            unit,
+            atUnitStart
+          });
+          continue;
+        }
+      }
+      const numbered = NUMBERED.exec(line);
+      if (numbered?.[1] !== void 0 && numbered[3] !== void 0 && !looksLikeBody(numbered[3]) && !dangling(clean(numbered[3]))) {
+        const level = Math.min(6, numbered[1].split(".").length + 1 + (numbered[2] ? 1 : 0));
+        run.push({
+          index: headings.length,
+          keyword: false
+        });
+        headings.push({
+          title: clean(line),
+          level,
+          unit,
+          atUnitStart
+        });
+        continue;
+      }
+      if (!candidate2 && /[A-Za-z]{3,}/.test(line) && !isPageFurniture(line) && !isTitleCase(line)) {
+        closeRun();
+      }
+    }
+  });
+  closeRun();
+  return dropContentsDuplicates(dropRunningHeaders(headings.filter((_, index) => !dropped.has(index)), texts.length));
+}
+__name(detectHeadings, "detectHeadings");
+function dropContentsDuplicates(headings) {
+  const last = /* @__PURE__ */ new Map();
+  headings.forEach((heading, index) => {
+    if (/\d/.test(heading.title)) {
+      last.set(heading.title.toLowerCase(), index);
+    }
+  });
+  return headings.filter((heading, index) => {
+    const key = heading.title.toLowerCase();
+    return !last.has(key) || last.get(key) === index;
+  });
+}
+__name(dropContentsDuplicates, "dropContentsDuplicates");
+function isTitleCase(line) {
+  if (line.length > 70 || /\.\s*$/.test(line)) {
+    return false;
+  }
+  const words2 = line.split(/\s+/).filter((word) => /^[A-Za-z]{4,}/.test(word));
+  return words2.length > 0 && words2.filter((word) => /^[A-Z]/.test(word)).length / words2.length >= 0.6;
+}
+__name(isTitleCase, "isTitleCase");
+function isPageFurniture(line) {
+  return line.length < 50 && /^[\d\s\-–—.()]*(\d+\s*CFR|Federal Acquisition Regulation|Page \d+)/i.test(line);
+}
+__name(isPageFurniture, "isPageFurniture");
+function runningLines(texts) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const text of texts) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const raw of text.split("\n")) {
+      const key = raw.trim().replace(/\d+/g, "#").toLowerCase();
+      if (key && !seen.has(key)) {
+        seen.add(key);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+      }
+    }
+  }
+  const threshold = Math.max(3, Math.ceil(texts.length * 0.2));
+  return new Set([
+    ...counts
+  ].filter(([, count]) => count >= threshold).map(([key]) => key));
+}
+__name(runningLines, "runningLines");
+function dropRunningHeaders(headings, unitCount) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const heading of headings) {
+    const key = heading.title.toLowerCase();
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const threshold = Math.max(3, Math.ceil(unitCount * 0.2));
+  return headings.filter((heading) => {
+    const key = heading.title.toLowerCase();
+    if ((counts.get(key) ?? 0) >= threshold) {
+      if (seen.has(key)) {
+        return false;
+      }
+    }
+    seen.add(key);
+    return true;
+  });
+}
+__name(dropRunningHeaders, "dropRunningHeaders");
+
+// src/tree/llm.ts
+var TreeBudgetExceededError = class extends Error {
+  static {
+    __name(this, "TreeBudgetExceededError");
+  }
+  limit;
+  constructor(limit) {
+    super(`tree LLM budget exhausted (${limit})`), this.limit = limit;
+    this.name = "TreeBudgetExceededError";
+  }
+};
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+__name(estimateTokens, "estimateTokens");
+var BudgetedLlm = class {
+  static {
+    __name(this, "BudgetedLlm");
+  }
+  llm;
+  budget;
+  outerSignal;
+  calls = 0;
+  inputTokens = 0;
+  outputTokens = 0;
+  exhausted = false;
+  deadline;
+  constructor(llm, budget, outerSignal) {
+    this.llm = llm;
+    this.budget = budget;
+    this.outerSignal = outerSignal;
+    this.deadline = budget.timeoutMs !== void 0 ? Date.now() + budget.timeoutMs : Number.POSITIVE_INFINITY;
+  }
+  /** Time left before the deadline, ms (`Infinity` without one). */
+  remainingMs() {
+    return this.deadline - Date.now();
+  }
+  /** Would a call with this prompt fit? Does not reserve anything; a `false` marks the budget exhausted. */
+  fits(prompt, maxOutputTokens) {
+    const fits = this.limitHit(prompt, maxOutputTokens) === void 0;
+    if (!fits) {
+      this.exhausted = true;
+    }
+    return fits;
+  }
+  limitHit(prompt, maxOutputTokens) {
+    if (this.calls >= this.budget.maxCalls) {
+      return "calls";
+    }
+    if (this.inputTokens + estimateTokens(prompt) > this.budget.maxInputTokens) {
+      return "inputTokens";
+    }
+    if (this.outputTokens + Math.min(maxOutputTokens, 16) > this.budget.maxOutputTokens) {
+      return "outputTokens";
+    }
+    if (this.remainingMs() <= 0 || this.outerSignal?.aborted) {
+      return "timeout";
+    }
+    return void 0;
+  }
+  /**
+  * Make one call, or throw {@link TreeBudgetExceededError} without calling. Provider errors
+  * propagate (after being counted). Never retries.
+  */
+  async call(task, system, prompt, maxOutputTokens) {
+    const limit = this.limitHit(system + prompt, maxOutputTokens);
+    if (limit !== void 0) {
+      this.exhausted = true;
+      throw new TreeBudgetExceededError(limit);
+    }
+    const outputCap = Math.max(16, Math.min(maxOutputTokens, this.budget.maxOutputTokens - this.outputTokens));
+    const timeoutMs = Math.min(this.budget.callTimeoutMs ?? Number.POSITIVE_INFINITY, this.remainingMs());
+    const reservedInput = estimateTokens(system + prompt);
+    this.inputTokens += reservedInput;
+    this.outputTokens += outputCap;
+    const controller = new AbortController();
+    const onOuterAbort = /* @__PURE__ */ __name(() => controller.abort(this.outerSignal?.reason), "onOuterAbort");
+    this.outerSignal?.addEventListener("abort", onOuterAbort, {
+      once: true
+    });
+    let timer;
+    this.calls += 1;
+    try {
+      const response = await Promise.race([
+        this.llm({
+          task,
+          system,
+          prompt,
+          maxOutputTokens: outputCap,
+          signal: controller.signal
+        }),
+        new Promise((_, reject) => {
+          if (Number.isFinite(timeoutMs)) {
+            timer = setTimeout(() => {
+              controller.abort(new TreeBudgetExceededError("timeout"));
+              reject(new TreeBudgetExceededError("timeout"));
+            }, Math.max(0, timeoutMs));
+          }
+        })
+      ]);
+      this.inputTokens += (response.usage?.inputTokens ?? reservedInput) - reservedInput;
+      this.outputTokens += (response.usage?.outputTokens ?? estimateTokens(response.text)) - outputCap;
+      return response.text;
+    } catch (error) {
+      this.outputTokens -= outputCap;
+      if (error instanceof TreeBudgetExceededError) {
+        this.exhausted = true;
+      }
+      throw error;
+    } finally {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+      this.outerSignal?.removeEventListener("abort", onOuterAbort);
+    }
+  }
+};
+function parseJsonReply(text) {
+  const tryParse = /* @__PURE__ */ __name((candidate2) => {
+    try {
+      const value = JSON.parse(candidate2);
+      return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+    } catch {
+      return void 0;
+    }
+  }, "tryParse");
+  const trimmed = text.trim();
+  const direct = tryParse(trimmed);
+  if (direct !== void 0) {
+    return direct;
+  }
+  const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed);
+  if (fenced?.[1] !== void 0) {
+    const inner = tryParse(fenced[1].trim());
+    if (inner !== void 0) {
+      return inner;
+    }
+  }
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    return tryParse(trimmed.slice(start, end + 1));
+  }
+  return void 0;
+}
+__name(parseJsonReply, "parseJsonReply");
+function stringList(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((item) => typeof item === "number" ? String(item) : item).filter((item) => typeof item === "string");
+}
+__name(stringList, "stringList");
+var NOOP_SINK = {
+  write() {
+  },
+  end() {
+  },
+  fail() {
+  }
+};
+function treeLlmFromModelProvider(provider) {
+  return async (request) => {
+    const result = await provider.runTurn({
+      system: request.system,
+      messages: [
+        {
+          role: "user",
+          content: request.prompt
+        }
+      ],
+      tools: [],
+      sink: NOOP_SINK,
+      abortSignal: request.signal
+    });
+    return {
+      text: result.text,
+      usage: {
+        inputTokens: result.usage.inputTokens,
+        outputTokens: result.usage.outputTokens
+      }
+    };
+  };
+}
+__name(treeLlmFromModelProvider, "treeLlmFromModelProvider");
+function openAiChatTreeLlm(options) {
+  const url = `${(options.baseUrl ?? "https://api.openai.com/v1").replace(/\/+$/, "")}/chat/completions`;
+  const doFetch = options.fetch ?? fetch;
+  return async (request) => {
+    const json2 = request.task.kind !== "summarize";
+    const response = await doFetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...options.apiKey ? {
+          authorization: `Bearer ${options.apiKey}`
+        } : {},
+        ...options.headers
+      },
+      body: JSON.stringify({
+        model: options.model,
+        messages: [
+          {
+            role: "system",
+            content: request.system
+          },
+          {
+            role: "user",
+            content: request.prompt
+          }
+        ],
+        temperature: options.temperature ?? 0,
+        max_tokens: request.maxOutputTokens,
+        ...options.jsonMode && json2 ? {
+          response_format: {
+            type: "json_object"
+          }
+        } : {},
+        ...options.body
+      }),
+      signal: request.signal
+    });
+    const body = await response.text();
+    if (!response.ok) {
+      throw new HttpModelError(response.status, `Chat completion failed (${response.status}): ${errorMessageOf(body)}`);
+    }
+    const parsed = parseJsonReply(body);
+    const content = parsed?.choices?.[0]?.message?.content;
+    if (typeof content !== "string") {
+      throw new HttpModelError(502, "Chat completion returned no message content");
+    }
+    const usage = {};
+    if (typeof parsed?.usage?.prompt_tokens === "number") {
+      usage.inputTokens = parsed.usage.prompt_tokens;
+    }
+    if (typeof parsed?.usage?.completion_tokens === "number") {
+      usage.outputTokens = parsed.usage.completion_tokens;
+    }
+    return {
+      text: content,
+      usage
+    };
+  };
+}
+__name(openAiChatTreeLlm, "openAiChatTreeLlm");
+function cachedTreeLlm(llm, cache = /* @__PURE__ */ new Map()) {
+  return async (request) => {
+    const key = stableHash(`${request.task.kind}\0${request.maxOutputTokens}\0${request.system}\0${request.prompt}`);
+    const hit = await cache.get(key);
+    if (hit !== void 0) {
+      return {
+        text: hit.text,
+        usage: {
+          inputTokens: 0,
+          outputTokens: 0
+        }
+      };
+    }
+    const response = await llm(request);
+    await cache.set(key, response);
+    return response;
+  };
+}
+__name(cachedTreeLlm, "cachedTreeLlm");
+function stableHash(text) {
+  let h1 = 2166136261;
+  let h2 = 16777619 ^ text.length;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    h1 = Math.imul(h1 ^ c, 16777619);
+    h2 = Math.imul(h2 ^ c, 1540483477);
+    h2 ^= h2 >>> 13;
+  }
+  h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+  h2 = Math.imul(h2 ^ h2 >>> 15, 3266489909);
+  return (h1 >>> 0).toString(16).padStart(8, "0") + (h2 >>> 0).toString(16).padStart(8, "0");
+}
+__name(stableHash, "stableHash");
+
+// src/tree/build.ts
+var DEFAULT_BUDGET = {
+  maxCalls: 60,
+  maxInputTokens: 4e5,
+  maxOutputTokens: 4e4,
+  timeoutMs: 3e5,
+  callTimeoutMs: 6e4
+};
+var STRUCTURE_SYSTEM = "You extract the table of contents of a document. You answer with JSON only, no prose.";
+var SUMMARY_SYSTEM = "You summarize sections of a document so a reader can decide whether a section answers their question. Be specific: name the topics, clauses, figures and defined terms it covers.";
+function toUnits(input) {
+  if (input.pages !== void 0 && input.sections !== void 0) {
+    throw new Error("buildDocumentTree: give `pages` or `sections`, not both");
+  }
+  if (input.sections !== void 0) {
+    const units = input.sections.map((section, index) => ({
+      index,
+      text: section.text,
+      ...section.page !== void 0 ? {
+        page: section.page
+      } : {}
+    }));
+    const titled = input.sections.some((section) => section.title?.trim());
+    const declared = titled ? input.sections.flatMap((section, unit) => section.title?.trim() ? [
+      {
+        title: section.title.trim(),
+        level: Math.max(1, Math.min(6, section.level ?? 1)),
+        unit,
+        atUnitStart: true
+      }
+    ] : []) : void 0;
+    return {
+      units,
+      declared,
+      kind: "sections"
+    };
+  }
+  const pages2 = input.pages ?? [];
+  return {
+    units: pages2.map((text, index) => ({
+      index,
+      text,
+      page: index + 1
+    })),
+    declared: void 0,
+    kind: "pages"
+  };
+}
+__name(toUnits, "toUnits");
+function outlineHeadings(input, units) {
+  const headings = [];
+  for (const entry of input.outline ?? []) {
+    let unit = entry.unit;
+    if (unit === void 0 && entry.page !== void 0) {
+      unit = units.findIndex((candidate2) => candidate2.page === entry.page);
+      if (unit < 0) {
+        unit = entry.page - 1;
+      }
+    }
+    if (unit === void 0 || unit < 0 || unit >= units.length || !entry.title.trim()) {
+      continue;
+    }
+    headings.push({
+      title: entry.title.trim(),
+      level: Math.max(1, Math.min(6, Math.floor(entry.level))),
+      unit,
+      atUnitStart: false
+    });
+  }
+  return headings.sort((a, b) => a.unit - b.unit);
+}
+__name(outlineHeadings, "outlineHeadings");
+function nestHeadings(headings, unitCount) {
+  const roots = [];
+  const stack = [];
+  headings.forEach((heading, index) => {
+    let end = unitCount - 1;
+    for (let next = index + 1; next < headings.length; next++) {
+      const candidate2 = headings[next];
+      if (candidate2 !== void 0 && candidate2.level <= heading.level) {
+        end = candidate2.atUnitStart ? candidate2.unit - 1 : candidate2.unit;
+        break;
+      }
+    }
+    const node = {
+      title: heading.title,
+      unitStart: heading.unit,
+      unitEnd: Math.max(heading.unit, end),
+      children: []
+    };
+    while (stack.length > 0 && (stack[stack.length - 1]?.level ?? 0) >= heading.level) {
+      stack.pop();
+    }
+    const parent = stack[stack.length - 1];
+    if (parent === void 0) {
+      roots.push(node);
+    } else {
+      parent.node.children.push(node);
+      parent.node.unitEnd = Math.max(parent.node.unitEnd, node.unitEnd);
+    }
+    stack.push({
+      node,
+      level: heading.level
+    });
+  });
+  const first = roots[0];
+  if (first !== void 0 && first.unitStart > 0) {
+    roots.unshift({
+      title: "Front matter",
+      unitStart: 0,
+      unitEnd: first.unitStart - 1,
+      children: []
+    });
+  }
+  return roots;
+}
+__name(nestHeadings, "nestHeadings");
+function firstLine(text, running) {
+  const line = text.split("\n").map((candidate2) => candidate2.trim()).find((candidate2) => /[A-Za-z]{3,}/.test(candidate2) && !running.has(candidate2.replace(/\d+/g, "#").toLowerCase()));
+  return line === void 0 ? "" : line.length > 80 ? `${line.slice(0, 77)}\u2026` : line;
+}
+__name(firstLine, "firstLine");
+function rangeLabel(units, start, end) {
+  const first = units[start];
+  const last = units[end];
+  if (first?.page !== void 0 && last?.page !== void 0) {
+    return first.page === last.page ? `Page ${first.page}` : `Pages ${first.page}\u2013${last.page}`;
+  }
+  return start === end ? `Section ${start + 1}` : `Sections ${start + 1}\u2013${end + 1}`;
+}
+__name(rangeLabel, "rangeLabel");
+function groupNodes(units, start, end, groupSize, maxChildren, levelsLeft, running) {
+  let level = [];
+  for (let from = start; from <= end; from += groupSize) {
+    const to = Math.min(end, from + groupSize - 1);
+    const lead = firstLine(units[from]?.text ?? "", running);
+    level.push({
+      title: `${rangeLabel(units, from, to)}${lead ? `: ${lead}` : ""}`,
+      unitStart: from,
+      unitEnd: to,
+      children: []
+    });
+  }
+  let depth = 1;
+  while (level.length > maxChildren && depth < levelsLeft) {
+    const parents = [];
+    const per = Math.max(maxChildren, Math.ceil(level.length / maxChildren));
+    for (let index = 0; index < level.length; index += per) {
+      const children = level.slice(index, index + per);
+      const from = children[0]?.unitStart ?? start;
+      const to = children[children.length - 1]?.unitEnd ?? end;
+      parents.push({
+        title: rangeLabel(units, from, to),
+        unitStart: from,
+        unitEnd: to,
+        children
+      });
+    }
+    level = parents;
+    depth += 1;
+  }
+  return level;
+}
+__name(groupNodes, "groupNodes");
+function descendantTitles(nodes, into = []) {
+  for (const { node } of walkDraft(nodes)) {
+    if (into.length < 30) {
+      into.push(node.title);
+    }
+  }
+  return into;
+}
+__name(descendantTitles, "descendantTitles");
+function shape(nodes, units, depth, options) {
+  const shaped = nodes.map((node) => {
+    if (depth >= options.maxDepth || node.unitStart === node.unitEnd && node.children.length > 0) {
+      const keyItems = descendantTitles(node.children, [
+        ...node.keyItems ?? []
+      ]);
+      return {
+        ...node,
+        ...keyItems.length > 0 ? {
+          keyItems
+        } : {},
+        children: []
+      };
+    }
+    let children = node.children;
+    const only = children[0];
+    if (children.length === 1 && only !== void 0 && only.unitStart === node.unitStart && only.unitEnd === node.unitEnd) {
+      children = only.children;
+    }
+    if (children.length === 0 && node.unitEnd - node.unitStart + 1 > options.maxLeafUnits) {
+      children = groupNodes(units, node.unitStart, node.unitEnd, options.groupSize, options.maxChildren, options.maxDepth - depth, options.running);
+    }
+    return {
+      ...node,
+      children: shape(children, units, depth + 1, options)
+    };
+  });
+  const merged = [];
+  for (const node of shaped) {
+    const previous = merged[merged.length - 1];
+    if (previous !== void 0 && previous.children.length === 0 && node.children.length === 0 && previous.unitStart === node.unitStart && previous.unitEnd === node.unitEnd) {
+      previous.keyItems = [
+        ...previous.keyItems ?? [],
+        node.title,
+        ...node.keyItems ?? []
+      ].slice(0, 30);
+      continue;
+    }
+    merged.push(node);
+  }
+  return merged;
+}
+__name(shape, "shape");
+function* walkDraft(nodes) {
+  for (const node of nodes) {
+    yield {
+      node
+    };
+    yield* walkDraft(node.children);
+  }
+}
+__name(walkDraft, "walkDraft");
+function spanText(units, start, end) {
+  const parts = [];
+  for (let index = Math.max(0, start); index <= end && index < units.length; index++) {
+    parts.push(units[index]?.text ?? "");
+  }
+  return parts.join("\n\n");
+}
+__name(spanText, "spanText");
+function ownTexts(units, node) {
+  const first = node.children[0];
+  const end = first === void 0 ? node.unitEnd : Math.max(node.unitStart, first.unitStart - 1);
+  const texts = [];
+  for (let index = node.unitStart; index <= end && index < units.length; index++) {
+    texts.push(units[index]?.text ?? "");
+  }
+  const head = texts[0];
+  if (head !== void 0) {
+    const probe = node.title.slice(0, 30);
+    const at = probe.length >= 4 ? head.indexOf(probe) : -1;
+    if (at > 0) {
+      texts[0] = head.slice(at);
+    }
+  }
+  return texts;
+}
+__name(ownTexts, "ownTexts");
+function excerptOf(texts, max) {
+  const total = texts.reduce((sum, text) => sum + text.length, 0);
+  if (total <= max) {
+    return texts.join("\n\n");
+  }
+  const per = Math.max(400, Math.floor(max / texts.length));
+  const parts = [];
+  let used = 0;
+  for (const text of texts) {
+    if (used >= max) {
+      break;
+    }
+    const part = text.length > per ? `${text.slice(0, per)}\u2026` : text;
+    parts.push(part);
+    used += part.length;
+  }
+  return parts.join("\n\n");
+}
+__name(excerptOf, "excerptOf");
+function collapse(text, max) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+__name(collapse, "collapse");
+async function llmHeadings(llm, units, options) {
+  const perUnit = Math.max(500, Math.floor(options.windowChars / 4));
+  const windows = [];
+  let current = [];
+  let size = 0;
+  for (const unit of units) {
+    const length = Math.min(unit.text.length, perUnit);
+    if (current.length > 0 && size + length > options.windowChars) {
+      windows.push(current);
+      current = [];
+      size = 0;
+    }
+    current.push(unit);
+    size += length;
+  }
+  if (current.length > 0) {
+    windows.push(current);
+  }
+  if (windows.length > options.maxCalls) {
+    throw new Error(`document needs ${windows.length} structuring calls, more than maxStructureCalls (${options.maxCalls})`);
+  }
+  const headings = [];
+  for (const window of windows) {
+    const shown = window.map((unit) => ({
+      unit: unit.index,
+      ...unit.page !== void 0 ? {
+        page: unit.page
+      } : {},
+      text: unit.text.length > perUnit ? `${unit.text.slice(0, perUnit)}\u2026` : unit.text
+    }));
+    const body = shown.map((unit) => `<unit ${unit.unit}>
+${unit.text}
+</unit ${unit.unit}>`).join("\n");
+    const prompt = `Below is part of a document, split into numbered units (pages or sections).
+List the headings of the sections that START in these units, in reading order, with their nesting level (1 = top-level chapter/part, 2 = its subsections, ...) and the unit number they start in.
+Only list real headings (titles of parts, chapters, sections, clauses, items), not running page headers, table rows or sentences. If no section starts here, return an empty list.
+
+${body}
+
+Reply with JSON only: {"sections": [{"title": "...", "level": 1, "unit": 0}]}`;
+    const reply = parseJsonReply(await llm.call({
+      kind: "structure",
+      units: shown
+    }, STRUCTURE_SYSTEM, prompt, 2e3));
+    const sections = reply?.sections;
+    if (!Array.isArray(sections)) {
+      throw new Error("structuring reply had no `sections` list");
+    }
+    const first = window[0]?.index ?? 0;
+    const last = window[window.length - 1]?.index ?? first;
+    for (const entry of sections) {
+      if (entry === null || typeof entry !== "object") {
+        continue;
+      }
+      const { title, level, unit } = entry;
+      const at = typeof unit === "number" ? unit : Number(unit);
+      if (typeof title !== "string" || !title.trim() || !Number.isInteger(at) || at < first || at > last) {
+        continue;
+      }
+      const previous = headings[headings.length - 1];
+      if (previous !== void 0 && at < previous.unit) {
+        continue;
+      }
+      headings.push({
+        title: collapse(title, 160),
+        level: Math.max(1, Math.min(6, Math.floor(typeof level === "number" ? level : 1))),
+        unit: at,
+        atUnitStart: false
+      });
+    }
+  }
+  return headings;
+}
+__name(llmHeadings, "llmHeadings");
+async function mapLimit(items, limit, work) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({
+    length: Math.max(1, Math.min(limit, items.length))
+  }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await work(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+__name(mapLimit, "mapLimit");
+async function buildDocumentTree(input, options) {
+  const started = Date.now();
+  const { units, declared, kind } = toUnits(input);
+  const maxDepth = Math.max(1, options.maxDepth ?? 4);
+  const groupSize = Math.max(1, options.groupSize ?? 5);
+  const maxLeafUnits = Math.max(groupSize, options.maxLeafUnits ?? 10);
+  const maxChildren = Math.max(2, options.maxChildren ?? 12);
+  const minHeadings = Math.max(1, options.minHeadings ?? 3);
+  const llmEnabled = options.llm !== void 0;
+  const summaries = options.summaries ?? llmEnabled;
+  const describe = options.describe ?? llmEnabled;
+  const llmStructure = options.llmStructure ?? llmEnabled;
+  const detect = options.detectHeadings ?? true;
+  const summaryMinChars = options.summaryMinChars ?? 600;
+  const summaryInputChars = options.summaryInputChars ?? 8e3;
+  const unitHashes = units.map((unit) => stableHash(unit.text));
+  const fingerprint = stableHash(JSON.stringify({
+    v: 1,
+    kind,
+    title: input.title ?? null,
+    outline: input.outline ?? null,
+    sections: input.sections?.map((section) => [
+      section.title ?? null,
+      section.level ?? null,
+      section.page ?? null
+    ]) ?? null,
+    units: unitHashes,
+    maxDepth,
+    groupSize,
+    maxLeafUnits,
+    maxChildren,
+    minHeadings,
+    detect,
+    summaries,
+    describe,
+    llmStructure: llmStructure && llmEnabled,
+    summaryMinChars,
+    summaryInputChars
+  }));
+  if (options.previous?.fingerprint === fingerprint) {
+    const { metadata: _metadata, source: _source, ...previous } = options.previous;
+    const metadata = options.metadata ?? options.previous.metadata;
+    const source = options.source ?? options.previous.source;
+    return {
+      tree: {
+        ...previous,
+        ...metadata !== void 0 ? {
+          metadata
+        } : {},
+        ...source !== void 0 ? {
+          source
+        } : {}
+      },
+      units,
+      unchanged: true
+    };
+  }
+  const budget = new BudgetedLlm(options.llm ?? (() => Promise.reject(new Error("no llm"))), {
+    ...DEFAULT_BUDGET,
+    ...options.budget
+  }, options.signal);
+  let fallbackReason;
+  let structure = "flat";
+  let headings = [];
+  const running = runningLines(units.map((unit) => unit.text));
+  const outline = outlineHeadings(input, units);
+  if (outline.length >= Math.min(minHeadings, 2)) {
+    structure = "outline";
+    headings = outline;
+  } else if (declared !== void 0 && declared.length >= 1) {
+    structure = "headings";
+    headings = declared;
+  } else if (detect !== false && units.length > 0) {
+    const found = detectHeadings(units.map((unit) => unit.text), detect === "markdown");
+    if (found.length >= minHeadings) {
+      structure = "headings";
+      headings = found;
+    }
+  }
+  if (structure === "flat" && llmStructure && llmEnabled && units.length > 1) {
+    try {
+      const found = await llmHeadings(budget, units, {
+        windowChars: options.structureWindowChars ?? 24e3,
+        maxCalls: Math.max(1, options.maxStructureCalls ?? 12)
+      });
+      if (found.length >= Math.min(minHeadings, 2)) {
+        structure = "llm";
+        headings = found;
+      } else {
+        fallbackReason = "LLM found no usable structure";
+      }
+    } catch (error) {
+      fallbackReason = error instanceof TreeBudgetExceededError ? `LLM structuring stopped: ${error.message}` : `LLM structuring failed: ${error.message}`;
+    }
+  }
+  const draft = structure === "flat" ? units.length === 0 ? [] : groupNodes(units, 0, units.length - 1, groupSize, maxChildren, maxDepth, running) : nestHeadings(headings, units.length);
+  const shaped = shape(draft, units, 1, {
+    maxDepth,
+    maxLeafUnits,
+    groupSize,
+    maxChildren,
+    running
+  });
+  let counter = 0;
+  const finalize = /* @__PURE__ */ __name((nodes2) => nodes2.map((node) => {
+    counter += 1;
+    const id = String(counter).padStart(4, "0");
+    const pageStart = units[node.unitStart]?.page;
+    const pageEnd = units[node.unitEnd]?.page;
+    return {
+      id,
+      title: node.title,
+      unitStart: node.unitStart,
+      unitEnd: node.unitEnd,
+      ...pageStart !== void 0 ? {
+        pageStart
+      } : {},
+      ...pageEnd !== void 0 ? {
+        pageEnd
+      } : {},
+      ...node.keyItems !== void 0 ? {
+        keyItems: node.keyItems
+      } : {},
+      contentHash: stableHash(`${node.title}\0${unitHashes.slice(node.unitStart, node.unitEnd + 1).join(",")}`),
+      children: finalize(node.children)
+    };
+  }), "finalize");
+  const nodes = finalize(shaped);
+  const previousSummaries = /* @__PURE__ */ new Map();
+  if (options.previous !== void 0) {
+    for (const { node } of walkTree(options.previous.nodes)) {
+      if (node.summary !== void 0 && (node.summarySource === "llm" || node.summarySource === "reused")) {
+        previousSummaries.set(node.contentHash, node.summary);
+      }
+    }
+  }
+  const breadthFirst = [];
+  for (let queue = [
+    ...nodes
+  ]; queue.length > 0; ) {
+    const node = queue.shift();
+    breadthFirst.push(node);
+    queue = queue.concat(node.children);
+  }
+  let reusedSummaries = 0;
+  const pending = [];
+  for (const node of breadthFirst) {
+    const reused = previousSummaries.get(node.contentHash);
+    const own = ownTexts(units, node).join("\n\n");
+    if (reused !== void 0) {
+      node.summary = reused;
+      node.summarySource = "reused";
+      reusedSummaries += 1;
+    } else if (own.trim().length < summaryMinChars && node.children.length === 0) {
+      const text = collapse(own, summaryMinChars);
+      if (text) {
+        node.summary = text;
+        node.summarySource = "text";
+      }
+    } else if (summaries && llmEnabled) {
+      pending.push(node);
+    } else {
+      const text = collapse(own, 300);
+      if (text) {
+        node.summary = text;
+        node.summarySource = "text";
+      }
+    }
+  }
+  let summariesCut = false;
+  await mapLimit(pending, Math.max(1, options.concurrency ?? 4), async (node) => {
+    const own = ownTexts(units, node);
+    const childTitles = [
+      ...node.children.map((child) => child.title),
+      ...node.keyItems ?? []
+    ].map((title) => `- ${title}`).join("\n");
+    const excerpt = excerptOf(own, summaryInputChars);
+    const prompt = `Summarize this section of ${input.title ? `"${input.title}"` : "a document"} in 2-4 sentences (at most 80 words). Name the specific topics, requirements, clauses, figures and defined terms it covers, so a reader can tell whether it answers their question.
+
+Section title: ${node.title}
+${childTitles ? `Subsections:
+${childTitles}
+` : ""}
+Section text:
+${excerpt}
+
+Reply with the summary only.`;
+    if (!summariesCut && budget.fits(SUMMARY_SYSTEM + prompt, 300)) {
+      try {
+        const reply = await budget.call({
+          kind: "summarize",
+          title: node.title,
+          text: excerpt
+        }, SUMMARY_SYSTEM, prompt, 300);
+        const json2 = parseJsonReply(reply);
+        const summary = typeof json2?.summary === "string" ? json2.summary : reply;
+        if (summary.trim()) {
+          node.summary = collapse(summary, 800);
+          node.summarySource = "llm";
+          return;
+        }
+      } catch (error) {
+        if (error instanceof TreeBudgetExceededError) {
+          summariesCut = true;
+        }
+        fallbackReason ??= `summary failed: ${error.message}`;
+      }
+    } else {
+      summariesCut = true;
+    }
+    const text = collapse(own.join("\n\n"), 300);
+    if (text) {
+      node.summary = text;
+      node.summarySource = "text";
+    }
+  });
+  if (summariesCut) {
+    fallbackReason ??= "LLM budget exhausted before every node was summarized";
+  }
+  let description;
+  const outlineForDescription = nodes.slice(0, 40).map((node) => ({
+    title: node.title,
+    ...node.summary !== void 0 ? {
+      summary: node.summary
+    } : {}
+  }));
+  if (describe && llmEnabled && nodes.length > 0) {
+    const prompt = `Write a one-paragraph description (at most 80 words) of the document ${input.title ? `"${input.title}"` : ""} from its table of contents below, so a reader can tell which questions it can answer.
+
+${outlineForDescription.map((entry) => `- ${entry.title}${entry.summary ? `: ${entry.summary}` : ""}`).join("\n")}
+
+Reply with the description only.`;
+    if (budget.fits(SUMMARY_SYSTEM + prompt, 300)) {
+      try {
+        description = collapse(await budget.call({
+          kind: "describe",
+          ...input.title !== void 0 ? {
+            title: input.title
+          } : {},
+          outline: outlineForDescription
+        }, SUMMARY_SYSTEM, prompt, 300), 1e3);
+      } catch (error) {
+        fallbackReason ??= `description failed: ${error.message}`;
+      }
+    }
+  }
+  if (description === void 0 && options.previous?.description !== void 0 && reusedSummaries > 0) {
+    description = options.previous.description;
+  }
+  const tree = {
+    documentId: options.documentId,
+    version: 1,
+    ...input.title !== void 0 ? {
+      title: input.title
+    } : {},
+    ...description ? {
+      description
+    } : {},
+    structure,
+    fingerprint,
+    unitCount: units.length,
+    nodes,
+    stats: {
+      llmCalls: budget.calls,
+      inputTokens: budget.inputTokens,
+      outputTokens: budget.outputTokens,
+      durationMs: Date.now() - started,
+      ...fallbackReason !== void 0 ? {
+        fallbackReason
+      } : {},
+      budgetExhausted: budget.exhausted,
+      reusedSummaries
+    },
+    ...options.metadata !== void 0 ? {
+      metadata: options.metadata
+    } : {},
+    ...options.source !== void 0 ? {
+      source: options.source
+    } : {},
+    builtAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  return {
+    tree,
+    units,
+    unchanged: false
+  };
+}
+__name(buildDocumentTree, "buildDocumentTree");
+
+// src/tree/keyword-tree-llm.ts
+var STOP = new Set("the and for are was were with that this from which what when where who whom how does did has have had not but its into under over than then there their about any all can may must shall should would could will our your they them his her per each other such only also more most".split(" "));
+function terms(text) {
+  return new Set((text.toLowerCase().match(/[\p{L}\p{N}][\p{L}\p{N}.\-]*[\p{L}\p{N}]|[\p{L}\p{N}]{3,}/gu) ?? []).filter((term) => term.length >= 3 && !STOP.has(term)));
+}
+__name(terms, "terms");
+function overlap(query, text) {
+  let score = 0;
+  for (const term of terms(text)) {
+    if (query.has(term)) {
+      score += 1;
+    }
+  }
+  return score;
+}
+__name(overlap, "overlap");
+function keywordTreeLlm() {
+  return async (request) => {
+    const { task } = request;
+    let text;
+    switch (task.kind) {
+      case "navigate": {
+        const query = terms(task.query);
+        const ranked = task.candidates.map((candidate2, order) => ({
+          candidate: candidate2,
+          order,
+          score: overlap(query, `${candidate2.title} ${candidate2.summary ?? ""}`)
+        })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score || (b.candidate.depth ?? 0) - (a.candidate.depth ?? 0) || a.order - b.order).slice(0, task.maxNodes).map((entry) => entry.candidate);
+        text = task.mode === "single-pass" ? JSON.stringify({
+          thinking: "keyword overlap",
+          read: ranked.map((c) => c.id)
+        }) : JSON.stringify({
+          thinking: "keyword overlap",
+          expand: ranked.filter((c) => c.hasChildren).map((c) => c.id),
+          read: ranked.filter((c) => !c.hasChildren).map((c) => c.id)
+        });
+        break;
+      }
+      case "select": {
+        const query = terms(task.query);
+        const ranked = task.documents.map((document) => ({
+          id: document.id,
+          score: overlap(query, `${document.title ?? ""} ${document.description ?? ""}`)
+        })).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score).slice(0, task.maxDocuments).map((entry) => entry.id);
+        text = JSON.stringify({
+          thinking: "keyword overlap",
+          documents: ranked
+        });
+        break;
+      }
+      case "summarize": {
+        const flat = task.text.replace(/\s+/g, " ").trim();
+        const sentence = /^.*?[.!?](\s|$)/.exec(flat)?.[0] ?? flat;
+        text = `${task.title}: ${sentence.slice(0, 200).trim()}`;
+        break;
+      }
+      case "describe":
+        text = `${task.title ?? "Document"} covering ${task.outline.map((entry) => entry.title).join(", ")}.`;
+        break;
+      case "structure": {
+        const sections = [];
+        for (const unit of task.units) {
+          for (const line of unit.text.split("\n")) {
+            const trimmed = line.trim();
+            const markdown = /^(#{1,6})\s+(.+)$/.exec(trimmed);
+            if (markdown?.[1] !== void 0 && markdown[2] !== void 0) {
+              sections.push({
+                title: markdown[2],
+                level: markdown[1].length,
+                unit: unit.unit
+              });
+            } else if (/^[A-Z][A-Z0-9 ,.'&-]{3,80}$/.test(trimmed) && /[A-Z]{3}/.test(trimmed)) {
+              sections.push({
+                title: trimmed,
+                level: 1,
+                unit: unit.unit
+              });
+            }
+          }
+        }
+        text = JSON.stringify({
+          sections
+        });
+        break;
+      }
+    }
+    return {
+      text,
+      usage: {
+        inputTokens: Math.ceil(request.prompt.length / 4),
+        outputTokens: Math.ceil(text.length / 4)
+      }
+    };
+  };
+}
+__name(keywordTreeLlm, "keywordTreeLlm");
+
+// src/tree/store.ts
+function headerOf(tree) {
+  return {
+    documentId: tree.documentId,
+    ...tree.title !== void 0 ? {
+      title: tree.title
+    } : {},
+    ...tree.description !== void 0 ? {
+      description: tree.description
+    } : {},
+    structure: tree.structure,
+    fingerprint: tree.fingerprint,
+    unitCount: tree.unitCount,
+    ...tree.metadata !== void 0 ? {
+      metadata: tree.metadata
+    } : {},
+    ...tree.source !== void 0 ? {
+      source: tree.source
+    } : {},
+    builtAt: tree.builtAt
+  };
+}
+__name(headerOf, "headerOf");
+function passes(tree, filter) {
+  if (filter === void 0 || Object.keys(filter).length === 0) {
+    return true;
+  }
+  if (filterMatchesNothing(filter)) {
+    return false;
+  }
+  return matchesFilter(tree.metadata, filter);
+}
+__name(passes, "passes");
+var MemoryDocumentTreeStore = class {
+  static {
+    __name(this, "MemoryDocumentTreeStore");
+  }
+  trees = /* @__PURE__ */ new Map();
+  async put(tree, units) {
+    this.trees.set(tree.documentId, {
+      tree: structuredClone(tree),
+      units: units.map((unit) => ({
+        ...unit
+      }))
+    });
+  }
+  async get(documentId, filter) {
+    const entry = this.trees.get(documentId);
+    return entry !== void 0 && passes(entry.tree, filter) ? structuredClone(entry.tree) : void 0;
+  }
+  async getMany(documentIds, filter) {
+    const trees = [];
+    for (const id of new Set(documentIds)) {
+      const tree = await this.get(id, filter);
+      if (tree !== void 0) {
+        trees.push(tree);
+      }
+    }
+    return trees;
+  }
+  async list(options = {}) {
+    const ids = options.documentIds !== void 0 ? new Set(options.documentIds) : void 0;
+    const headers = [
+      ...this.trees.values()
+    ].filter(({ tree }) => (ids === void 0 || ids.has(tree.documentId)) && passes(tree, options.filter)).map(({ tree }) => headerOf(tree)).sort((a, b) => a.documentId.localeCompare(b.documentId));
+    return options.limit !== void 0 ? headers.slice(0, options.limit) : headers;
+  }
+  async readUnits(documentId, start, end) {
+    const units = this.trees.get(documentId)?.units ?? [];
+    return units.slice(Math.max(0, start), Math.max(0, end + 1)).map((unit) => ({
+      ...unit
+    }));
+  }
+  async remove(documentId) {
+    this.trees.delete(documentId);
+  }
+};
+
+// src/tree/pg-tree-store.ts
+var IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
+function json(value) {
+  if (value === null || value === void 0) {
+    return void 0;
+  }
+  return typeof value === "string" ? JSON.parse(value) : value;
+}
+__name(json, "json");
+var PgDocumentTreeStore = class {
+  static {
+    __name(this, "PgDocumentTreeStore");
+  }
+  client;
+  table;
+  unitsTable;
+  insertBatchSize;
+  constructor(client, options = {}) {
+    this.client = toPgClient(client);
+    this.table = options.table ?? "agent_rag_trees";
+    this.unitsTable = options.unitsTable ?? `${this.table}_units`;
+    for (const name of [
+      this.table,
+      this.unitsTable
+    ]) {
+      if (!IDENTIFIER.test(name)) {
+        throw new Error(`PgDocumentTreeStore: invalid table name ${JSON.stringify(name)}`);
+      }
+    }
+    this.insertBatchSize = Math.max(1, Math.floor(options.insertBatchSize ?? 200));
+  }
+  /** The idempotent DDL {@link PgDocumentTreeStore.ensureSchema} runs, in order — for a migration. */
+  schemaStatements() {
+    const index = this.table.replace(".", "_");
+    return [
+      `CREATE TABLE IF NOT EXISTS ${this.table} (
+        document_id TEXT PRIMARY KEY,
+        title TEXT,
+        description TEXT,
+        structure TEXT NOT NULL,
+        fingerprint TEXT NOT NULL,
+        unit_count INTEGER NOT NULL,
+        source TEXT,
+        metadata JSONB,
+        tree JSONB NOT NULL,
+        built_at TIMESTAMPTZ NOT NULL
+      )`,
+      `CREATE INDEX IF NOT EXISTS ${index}_metadata_idx ON ${this.table} USING gin (metadata)`,
+      `CREATE TABLE IF NOT EXISTS ${this.unitsTable} (
+        document_id TEXT NOT NULL,
+        idx INTEGER NOT NULL,
+        page INTEGER,
+        text TEXT NOT NULL,
+        PRIMARY KEY (document_id, idx)
+      )`
+    ];
+  }
+  async ensureSchema() {
+    for (const statement of this.schemaStatements()) {
+      await this.client.query(statement);
+    }
+  }
+  /**
+  * 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.
+  */
+  whereConditions(filter, params) {
+    return buildWhere(filter, params);
+  }
+  /** Replace the tree and its units in one transaction (when the client has one). */
+  async put(tree, units) {
+    const clean2 = stripNulBytes(tree);
+    const { metadata, ...rest } = clean2;
+    const write = /* @__PURE__ */ __name(async (client) => {
+      await client.query(`DELETE FROM ${this.unitsTable} WHERE document_id = $1`, [
+        clean2.documentId
+      ]);
+      for (let start = 0; start < units.length; start += this.insertBatchSize) {
+        const batch = units.slice(start, start + this.insertBatchSize);
+        const params = [];
+        const rows = batch.map((unit) => {
+          params.push(clean2.documentId, unit.index, unit.page ?? null, stripNulBytes(unit.text));
+          const at = params.length;
+          return `($${at - 3}, $${at - 2}, $${at - 1}, $${at})`;
+        });
+        await client.query(`INSERT INTO ${this.unitsTable} (document_id, idx, page, text) VALUES ${rows.join(", ")}`, params);
+      }
+      await client.query(`INSERT INTO ${this.table}
+           (document_id, title, description, structure, fingerprint, unit_count, source, metadata, tree, built_at)
+         VALUES ($1, $2, $3, $4, $5, $6, $7, $8::jsonb, $9::jsonb, $10)
+         ON CONFLICT (document_id) DO UPDATE SET
+           title = EXCLUDED.title, description = EXCLUDED.description, structure = EXCLUDED.structure,
+           fingerprint = EXCLUDED.fingerprint, unit_count = EXCLUDED.unit_count, source = EXCLUDED.source,
+           metadata = EXCLUDED.metadata, tree = EXCLUDED.tree, built_at = EXCLUDED.built_at`, [
+        clean2.documentId,
+        clean2.title ?? null,
+        clean2.description ?? null,
+        clean2.structure,
+        clean2.fingerprint,
+        clean2.unitCount,
+        clean2.source ?? null,
+        metadata === void 0 ? null : JSON.stringify(metadata),
+        JSON.stringify(rest),
+        clean2.builtAt
+      ]);
+    }, "write");
+    const transaction = this.client.transaction?.bind(this.client);
+    await (transaction !== void 0 ? transaction(write) : write(this.client));
+  }
+  async get(documentId, filter) {
+    return (await this.getMany([
+      documentId
+    ], filter))[0];
+  }
+  async getMany(documentIds, filter) {
+    if (documentIds.length === 0) {
+      return [];
+    }
+    const params = [
+      [
+        ...new Set(documentIds)
+      ]
+    ];
+    const conditions = [
+      "document_id = ANY($1::text[])",
+      ...this.whereConditions(filter, params)
+    ];
+    const rows = await this.client.query(`SELECT document_id, metadata, tree FROM ${this.table} WHERE ${conditions.join(" AND ")}`, params);
+    return rows.map((row) => {
+      const tree = json(row.tree);
+      const metadata = json(row.metadata);
+      return {
+        ...tree,
+        ...metadata !== void 0 ? {
+          metadata
+        } : {}
+      };
+    });
+  }
+  async list(options = {}) {
+    const params = [];
+    const conditions = this.whereConditions(options.filter, params);
+    if (options.documentIds !== void 0) {
+      params.push([
+        ...options.documentIds
+      ]);
+      conditions.push(`document_id = ANY($${params.length}::text[])`);
+    }
+    let limit = "";
+    if (options.limit !== void 0) {
+      params.push(Math.max(0, Math.floor(options.limit)));
+      limit = `LIMIT $${params.length}`;
+    }
+    const rows = await this.client.query(`SELECT document_id, title, description, structure, fingerprint, unit_count, source, metadata, built_at
+         FROM ${this.table}
+         ${conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : ""}
+         ORDER BY document_id ${limit}`, params);
+    return rows.map((row) => {
+      const metadata = json(row.metadata);
+      return headerOf({
+        documentId: row.document_id,
+        version: 1,
+        ...row.title !== null ? {
+          title: row.title
+        } : {},
+        ...row.description !== null ? {
+          description: row.description
+        } : {},
+        structure: row.structure,
+        fingerprint: row.fingerprint,
+        unitCount: Number(row.unit_count),
+        nodes: [],
+        stats: {
+          llmCalls: 0,
+          inputTokens: 0,
+          outputTokens: 0,
+          durationMs: 0,
+          budgetExhausted: false,
+          reusedSummaries: 0
+        },
+        ...metadata !== void 0 ? {
+          metadata
+        } : {},
+        ...row.source !== null ? {
+          source: row.source
+        } : {},
+        builtAt: row.built_at instanceof Date ? row.built_at.toISOString() : String(row.built_at)
+      });
+    });
+  }
+  async readUnits(documentId, start, end) {
+    const rows = await this.client.query(`SELECT idx, page, text FROM ${this.unitsTable}
+        WHERE document_id = $1 AND idx BETWEEN $2 AND $3 ORDER BY idx`, [
+      documentId,
+      Math.max(0, start),
+      end
+    ]);
+    return rows.map((row) => ({
+      index: Number(row.idx),
+      text: row.text,
+      ...row.page !== null ? {
+        page: Number(row.page)
+      } : {}
+    }));
+  }
+  async remove(documentId) {
+    const work = /* @__PURE__ */ __name(async (client) => {
+      await client.query(`DELETE FROM ${this.unitsTable} WHERE document_id = $1`, [
+        documentId
+      ]);
+      await client.query(`DELETE FROM ${this.table} WHERE document_id = $1`, [
+        documentId
+      ]);
+    }, "work");
+    const transaction = this.client.transaction?.bind(this.client);
+    await (transaction !== void 0 ? transaction(work) : work(this.client));
+  }
+};
+
+// src/tree/index-document.ts
+async function indexDocumentTree(input, options) {
+  const { store, minUnits = 20, minChars = 6e4, ...build } = options;
+  const { units } = toUnits(input);
+  const chars = units.reduce((total, unit) => total + unit.text.length, 0);
+  if (units.length < minUnits && chars < minChars) {
+    await store.remove(options.documentId);
+    return {
+      status: "skipped",
+      reason: `${units.length} units / ${chars} chars is below the threshold (${minUnits} units or ${minChars} chars)`
+    };
+  }
+  const previous = await store.get(options.documentId);
+  const built = await buildDocumentTree(input, {
+    ...build,
+    ...previous !== void 0 ? {
+      previous
+    } : {}
+  });
+  if (built.unchanged) {
+    const metadataMoved = JSON.stringify(previous?.metadata ?? null) !== JSON.stringify(built.tree.metadata ?? null) || previous?.source !== built.tree.source;
+    if (metadataMoved) {
+      await store.put(built.tree, built.units);
+    }
+    return {
+      status: "unchanged",
+      tree: built.tree
+    };
+  }
+  await store.put(built.tree, built.units);
+  return {
+    status: "built",
+    tree: built.tree
+  };
+}
+__name(indexDocumentTree, "indexDocumentTree");
+
+// src/tree/navigate.ts
+var NAVIGATE_SYSTEM = "You navigate the table of contents of a document to find where a question is answered. You answer with JSON only.";
+var DEFAULT_BUDGET2 = {
+  maxCalls: 6,
+  maxInputTokens: 6e4,
+  maxOutputTokens: 4e3,
+  timeoutMs: 6e4
+};
+function pages(node) {
+  if (node.pageStart === void 0) {
+    return void 0;
+  }
+  return node.pageEnd === void 0 || node.pageEnd === node.pageStart ? `p. ${node.pageStart}` : `pp. ${node.pageStart}-${node.pageEnd}`;
+}
+__name(pages, "pages");
+function candidate(node, summaryChars, depth) {
+  const shownPages = pages(node);
+  let summary = node.summary;
+  if (summary !== void 0 && summary.length > summaryChars) {
+    summary = `${summary.slice(0, Math.max(0, summaryChars - 1))}\u2026`;
+  }
+  if (node.keyItems !== void 0 && node.keyItems.length > 0 && summaryChars > 0) {
+    summary = `${summary ?? ""}${summary ? " " : ""}Includes: ${node.keyItems.slice(0, 12).join("; ")}`;
+  }
+  return {
+    id: node.id,
+    title: node.title,
+    ...summary && summaryChars > 0 ? {
+      summary
+    } : {},
+    ...shownPages !== void 0 ? {
+      pages: shownPages
+    } : {},
+    ...depth !== void 0 ? {
+      depth
+    } : {
+      hasChildren: node.children.length > 0
+    }
+  };
+}
+__name(candidate, "candidate");
+function render(candidates) {
+  return candidates.map((entry) => {
+    const indent = "  ".repeat(entry.depth ?? 0);
+    const meta = [
+      entry.pages,
+      entry.hasChildren ? "has subsections" : void 0
+    ].filter(Boolean).join(", ");
+    return `${indent}[${entry.id}] ${entry.title}${meta ? ` (${meta})` : ""}${entry.summary ? ` \u2014 ${entry.summary}` : ""}`;
+  }).join("\n");
+}
+__name(render, "render");
+function fit(nodes, maxChars) {
+  let last;
+  for (const summaryChars of [
+    400,
+    160,
+    0
+  ]) {
+    const candidates = nodes.map(({ node, depth }) => candidate(node, summaryChars, depth));
+    const text = render(candidates);
+    last = {
+      candidates,
+      text
+    };
+    if (text.length <= maxChars) {
+      break;
+    }
+  }
+  return last;
+}
+__name(fit, "fit");
+var TreeNavigationRetriever = class {
+  static {
+    __name(this, "TreeNavigationRetriever");
+  }
+  options;
+  store;
+  llm;
+  constructor(options) {
+    this.options = options;
+    this.store = options.store;
+    this.llm = options.llm;
+  }
+  describeRetrieval() {
+    return {
+      retriever: "tree-navigation"
+    };
+  }
+  async retrieve(query, options = {}) {
+    const result = await this.search(query, options.filter !== void 0 ? {
+      filter: options.filter
+    } : {});
+    return result.passages.slice(0, options.topK ?? result.passages.length);
+  }
+  /** {@link retrieve} with the audit trail: which documents, which nodes, why. */
+  async search(query, options = {}) {
+    const maxDocuments = Math.max(1, this.options.maxDocuments ?? 3);
+    const maxCandidates = Math.max(maxDocuments, this.options.maxSelectionCandidates ?? 200);
+    const headers = await this.store.list({
+      ...options.filter !== void 0 ? {
+        filter: options.filter
+      } : {},
+      limit: maxCandidates
+    });
+    if (headers.length <= maxDocuments) {
+      return this.navigate(query, headers.map((header) => header.documentId), options);
+    }
+    const budget = new BudgetedLlm(this.llm, {
+      ...DEFAULT_BUDGET2,
+      ...this.options.budget,
+      ...options.budget
+    }, options.signal);
+    const documents = headers.map((header) => ({
+      id: header.documentId,
+      ...header.title !== void 0 ? {
+        title: header.title
+      } : {},
+      ...header.description !== void 0 ? {
+        description: header.description.slice(0, 600)
+      } : {}
+    }));
+    const prompt = `Select the documents that may contain the answer to the question, most relevant first, at most ${maxDocuments}.
+
+Question: ${query}
+
+Documents:
+${documents.map((document) => `[${document.id}] ${document.title ?? ""}${document.description ? ` \u2014 ${document.description}` : ""}`).join("\n")}
+
+Reply with JSON only: {"thinking": "<why>", "documents": ["<document id>", ...]} \u2014 an empty list if none is relevant.`;
+    const known = new Set(documents.map((document) => document.id));
+    try {
+      const reply = parseJsonReply(await budget.call({
+        kind: "select",
+        query,
+        documents,
+        maxDocuments
+      }, NAVIGATE_SYSTEM, prompt, 800));
+      const selected = [
+        ...new Set(stringList(reply?.documents ?? reply?.answer).filter((id) => known.has(id)))
+      ].slice(0, maxDocuments);
+      const result = await this.navigate(query, selected, options);
+      const reasoning = typeof reply?.thinking === "string" ? reply.thinking.slice(0, 2e3) : void 0;
+      return {
+        ...result,
+        selection: {
+          candidates: documents.length,
+          selected,
+          ...reasoning !== void 0 ? {
+            reasoning
+          } : {}
+        }
+      };
+    } catch (error) {
+      return {
+        passages: [],
+        documents: [],
+        selection: {
+          candidates: documents.length,
+          selected: [],
+          error: error.message
+        }
+      };
+    }
+  }
+  /**
+  * 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'`.
+  */
+  async navigate(query, documentIds, options = {}) {
+    const ids = [
+      ...new Set(documentIds)
+    ];
+    const trees = new Map((await this.store.getMany(ids, options.filter)).map((tree) => [
+      tree.documentId,
+      tree
+    ]));
+    const navigations = await mapLimit(ids, Math.max(1, this.options.concurrency ?? 3), async (id) => {
+      const tree = trees.get(id);
+      if (tree === void 0) {
+        return {
+          navigation: {
+            documentId: id,
+            mode: "single-pass",
+            steps: [],
+            nodes: [],
+            llmCalls: 0,
+            inputTokens: 0,
+            outputTokens: 0,
+            stoppedBy: "not-found"
+          },
+          passages: []
+        };
+      }
+      const navigation = await this.walk(query, tree, options);
+      return {
+        navigation,
+        passages: await this.passagesOf(tree, navigation)
+      };
+    });
+    const maxContextChars = this.options.maxContextChars ?? 48e3;
+    let used = 0;
+    const passages = [];
+    for (const entry of navigations) {
+      for (const passage of entry.passages) {
+        if (used >= maxContextChars) {
+          break;
+        }
+        const text = passage.text.slice(0, maxContextChars - used);
+        used += text.length;
+        passages.push({
+          ...passage,
+          text
+        });
+      }
+    }
+    return {
+      passages,
+      documents: navigations.map((entry) => entry.navigation)
+    };
+  }
+  async walk(query, tree, options) {
+    const budget = new BudgetedLlm(this.llm, {
+      ...DEFAULT_BUDGET2,
+      ...this.options.budget,
+      ...options.budget
+    }, options.signal);
+    const maxNodes = Math.max(1, this.options.maxNodes ?? 5);
+    const singlePassMaxChars = this.options.singlePassMaxChars ?? 4e4;
+    const index = indexTree(tree);
+    const whole = [
+      ...walkTree(tree.nodes)
+    ].map(({ node, path }) => ({
+      node,
+      depth: path.length
+    }));
+    const outline = fit(whole, Number.POSITIVE_INFINITY);
+    const title = tree.title ?? tree.source ?? tree.documentId;
+    const steps = [];
+    const chosen = [];
+    let stoppedBy;
+    let error;
+    const mode = outline.text.length <= singlePassMaxChars ? "single-pass" : "beam";
+    const stop = /* @__PURE__ */ __name((caught) => {
+      if (caught instanceof TreeBudgetExceededError) {
+        stoppedBy = caught.limit === "timeout" ? "timeout" : "budget";
+      } else {
+        stoppedBy = "error";
+      }
+      error = caught.message;
+    }, "stop");
+    if (mode === "single-pass") {
+      const prompt = `Find the sections of the document that are likely to contain the answer to the question. Prefer the most specific (deepest) sections; list at most ${maxNodes}, most relevant first.
+
+Question: ${query}
+
+Document: ${title}${tree.description ? `
+About: ${tree.description}` : ""}
+Table of contents ([id] title (pages) \u2014 summary):
+${outline.text}
+
+Reply with JSON only: {"thinking": "<which sections answer and why>", "read": ["<id>", ...]} \u2014 an empty list if none does.`;
+      try {
+        const reply = requireJson(await budget.call({
+          kind: "navigate",
+          query,
+          mode,
+          candidates: outline.candidates,
+          maxNodes
+        }, NAVIGATE_SYSTEM, prompt, 1500));
+        const read = [
+          ...new Set(stringList(reply?.read ?? reply?.node_list ?? reply?.nodes))
+        ].map((id) => resolveId(index, id)).filter((id) => id !== void 0).slice(0, maxNodes);
+        chosen.push(...read);
+        steps.push({
+          step: 1,
+          shown: outline.candidates.map((entry) => entry.id),
+          expanded: [],
+          read,
+          ...reasoningOf(reply)
+        });
+      } catch (caught) {
+        stop(caught);
+      }
+    } else {
+      const beamWidth = Math.max(1, this.options.beamWidth ?? 4);
+      const maxSteps = Math.max(1, this.options.maxSteps ?? 4);
+      let frontier = tree.nodes;
+      let pendingExpand = [];
+      for (let step = 1; frontier.length > 0 && chosen.length < maxNodes; step++) {
+        if (step > maxSteps) {
+          stoppedBy = "maxSteps";
+          break;
+        }
+        const shown = fit(frontier.map((node) => ({
+          node
+        })), singlePassMaxChars);
+        const path = index.get(frontier[0]?.id ?? "")?.path ?? [];
+        const where = path.length > 0 ? `
+You are inside: ${path.map((node) => node.title).join(" > ")}` : "";
+        const prompt = `Find where the question is answered in the document by walking its table of contents.
+For each relevant section below, either "expand" it (open its subsections, only for sections that have subsections) or "read" it (its text answers the question). Choose at most ${beamWidth} in total, most relevant first; choose none if nothing here is relevant.
+
+Question: ${query}
+
+Document: ${title}${tree.description ? `
+About: ${tree.description}` : ""}${where}
+Sections ([id] title (pages) \u2014 summary):
+${shown.text}
+
+Reply with JSON only: {"thinking": "<why>", "expand": ["<id>", ...], "read": ["<id>", ...]}`;
+        let reply;
+        try {
+          reply = requireJson(await budget.call({
+            kind: "navigate",
+            query,
+            mode,
+            candidates: shown.candidates,
+            maxNodes: beamWidth
+          }, NAVIGATE_SYSTEM, prompt, 1200));
+        } catch (caught) {
+          stop(caught);
+          break;
+        }
+        const onFrontier = new Set(frontier.map((node) => node.id));
+        const pick = /* @__PURE__ */ __name((value) => [
+          ...new Set(stringList(value))
+        ].map((id) => resolveId(index, id)).filter((id) => id !== void 0 && onFrontier.has(id)), "pick");
+        let expand = pick(reply?.expand);
+        let read = pick(reply?.read);
+        read = [
+          ...read,
+          ...expand.filter((id) => (index.get(id)?.node.children.length ?? 0) === 0)
+        ];
+        expand = expand.filter((id) => (index.get(id)?.node.children.length ?? 0) > 0);
+        const limited = [
+          ...expand,
+          ...read
+        ].slice(0, beamWidth);
+        expand = expand.filter((id) => limited.includes(id));
+        read = [
+          ...new Set(read.filter((id) => limited.includes(id)))
+        ];
+        steps.push({
+          step,
+          shown: shown.candidates.map((entry) => entry.id),
+          expanded: expand,
+          read,
+          ...reasoningOf(reply)
+        });
+        chosen.push(...read);
+        pendingExpand = expand;
+        frontier = expand.flatMap((id) => index.get(id)?.node.children ?? []);
+        if (frontier.length === 0) {
+          pendingExpand = [];
+        }
+      }
+      if (stoppedBy !== void 0) {
+        chosen.push(...pendingExpand);
+      }
+    }
+    const unique = [
+      ...new Set(chosen)
+    ];
+    const specific = unique.filter((id) => !unique.some((other) => other !== id && index.get(other)?.path.some((node) => node.id === id)));
+    const nodes = specific.slice(0, maxNodes).flatMap((id) => {
+      const entry = index.get(id);
+      if (entry === void 0) {
+        return [];
+      }
+      const { node, path } = entry;
+      return [
+        {
+          nodeId: node.id,
+          title: node.title,
+          path: [
+            ...path,
+            node
+          ].map((step) => ({
+            id: step.id,
+            title: step.title
+          })),
+          ...node.pageStart !== void 0 ? {
+            pageStart: node.pageStart
+          } : {},
+          ...node.pageEnd !== void 0 ? {
+            pageEnd: node.pageEnd
+          } : {},
+          unitStart: node.unitStart,
+          unitEnd: node.unitEnd
+        }
+      ];
+    });
+    return {
+      documentId: tree.documentId,
+      ...tree.title !== void 0 ? {
+        title: tree.title
+      } : {},
+      mode,
+      steps,
+      nodes,
+      llmCalls: budget.calls,
+      inputTokens: budget.inputTokens,
+      outputTokens: budget.outputTokens,
+      ...stoppedBy !== void 0 ? {
+        stoppedBy
+      } : {},
+      ...error !== void 0 ? {
+        error
+      } : {}
+    };
+  }
+  async passagesOf(tree, navigation) {
+    const maxPassageChars = this.options.maxPassageChars ?? 12e3;
+    const maxUnits = Math.max(1, this.options.maxUnitsPerNode ?? 25);
+    const reasoning = navigation.steps.map((step) => step.reasoning).filter((text) => text !== void 0).join("\n");
+    const passages = [];
+    for (const [rank, node] of navigation.nodes.entries()) {
+      const units = await this.store.readUnits(tree.documentId, node.unitStart, Math.min(node.unitEnd, node.unitStart + maxUnits - 1));
+      let text = units.map((unit) => unit.text).join("\n\n");
+      if (text.length > maxPassageChars) {
+        text = `${text.slice(0, maxPassageChars - 1)}\u2026`;
+      }
+      passages.push({
+        id: `${tree.documentId}#node:${node.nodeId}`,
+        text,
+        // Rank within the document's choice; not a similarity.
+        score: 1 / (rank + 1),
+        source: tree.source ?? tree.title ?? tree.documentId,
+        metadata: {
+          ...tree.metadata,
+          documentId: tree.documentId,
+          nodeId: node.nodeId,
+          title: node.title,
+          ...node.pageStart !== void 0 ? {
+            pageStart: node.pageStart
+          } : {},
+          ...node.pageEnd !== void 0 ? {
+            pageEnd: node.pageEnd
+          } : {},
+          path: node.path,
+          retrieval: "tree-navigation",
+          ...reasoning ? {
+            reasoning: reasoning.slice(0, 2e3)
+          } : {}
+        }
+      });
+    }
+    return passages;
+  }
+};
+function resolveId(index, raw) {
+  const id = raw.trim().replace(/^\[|\]$/g, "");
+  if (index.has(id)) {
+    return id;
+  }
+  if (/^\d+$/.test(id)) {
+    const padded = id.padStart(4, "0");
+    if (index.has(padded)) {
+      return padded;
+    }
+  }
+  return void 0;
+}
+__name(resolveId, "resolveId");
+function requireJson(reply) {
+  const json2 = parseJsonReply(reply);
+  if (json2 === void 0) {
+    throw new Error(`navigation reply was not JSON: ${JSON.stringify(reply.slice(0, 120))}`);
+  }
+  return json2;
+}
+__name(requireJson, "requireJson");
+function reasoningOf(reply) {
+  const thinking = reply?.thinking ?? reply?.reasoning;
+  return typeof thinking === "string" && thinking.trim() ? {
+    reasoning: thinking.slice(0, 2e3)
+  } : {};
+}
+__name(reasoningOf, "reasoningOf");
+
+// src/tree/two-stage.ts
+function defaultDocumentIdOf(passage) {
+  const fromMetadata = passage.metadata?.documentId;
+  return typeof fromMetadata === "string" ? fromMetadata : documentIdOf(passage.id);
+}
+__name(defaultDocumentIdOf, "defaultDocumentIdOf");
+var TwoStageRetriever = class {
+  static {
+    __name(this, "TwoStageRetriever");
+  }
+  firstStage;
+  navigator;
+  options;
+  constructor(firstStage, navigator, options = {}) {
+    this.firstStage = firstStage;
+    this.navigator = navigator;
+    this.options = options;
+  }
+  describeRetrieval() {
+    return {
+      retriever: "two-stage"
+    };
+  }
+  async retrieve(query, options = {}) {
+    return (await this.search(query, options)).passages;
+  }
+  /** {@link retrieve} with the navigations that were run. */
+  async search(query, options = {}) {
+    const topK = options.topK ?? 5;
+    const docOf = this.options.documentIdOf ?? defaultDocumentIdOf;
+    const first = await this.firstStage.retrieve(query, {
+      topK: Math.max(topK, this.options.fetchTopK ?? 20),
+      ...options.filter !== void 0 ? {
+        filter: options.filter
+      } : {}
+    });
+    const ranked = [];
+    for (const passage of first) {
+      const id = docOf(passage);
+      if (!ranked.includes(id)) {
+        ranked.push(id);
+      }
+    }
+    const considered = ranked.slice(0, Math.max(1, this.options.considerDocuments ?? 3));
+    const withTrees = new Set((await this.navigator.store.list({
+      documentIds: considered,
+      ...options.filter !== void 0 ? {
+        filter: options.filter
+      } : {}
+    })).map((header) => header.documentId));
+    const toNavigate = considered.filter((id) => withTrees.has(id)).slice(0, Math.max(0, this.options.navigateDocuments ?? 2));
+    const navigated = /* @__PURE__ */ new Map();
+    let navigations = [];
+    if (toNavigate.length > 0) {
+      const result = await this.navigator.navigate(query, toNavigate, {
+        ...options.filter !== void 0 ? {
+          filter: options.filter
+        } : {},
+        ...this.options.budget !== void 0 ? {
+          budget: this.options.budget
+        } : {}
+      });
+      navigations = result.documents;
+      for (const passage of result.passages) {
+        const id = String(passage.metadata?.documentId ?? "");
+        navigated.set(id, [
+          ...navigated.get(id) ?? [],
+          passage
+        ]);
+      }
+      for (const navigation of navigations) {
+        this.options.onNavigation?.(navigation);
+      }
+    }
+    const merged = [];
+    const emitted = /* @__PURE__ */ new Set();
+    for (const passage of first) {
+      const id = docOf(passage);
+      const replacement = navigated.get(id);
+      if (replacement === void 0 || replacement.length === 0) {
+        merged.push(passage);
+        continue;
+      }
+      if (!emitted.has(id)) {
+        emitted.add(id);
+        merged.push(...replacement);
+      }
+      if (this.options.keepFirstStageChunks) {
+        merged.push(passage);
+      }
+    }
+    return {
+      passages: merged.slice(0, topK),
+      navigations
+    };
+  }
+};
+
+// src/tree/navigate-tool.ts
+function isInput(value) {
+  return typeof value === "object" && value !== null && typeof value.documentId === "string" && typeof value.question === "string";
+}
+__name(isInput, "isInput");
+var inputSchema = {
+  "~standard": {
+    version: 1,
+    vendor: "nestjs-agent-rag",
+    validate(value) {
+      return isInput(value) ? {
+        value: {
+          documentId: value.documentId,
+          question: value.question
+        }
+      } : {
+        issues: [
+          {
+            message: "navigate_document expects { documentId: string, question: string }"
+          }
+        ]
+      };
+    }
+  }
+};
+function createNavigateDocumentTool(navigator, options = {}) {
+  return {
+    spec: {
+      name: options.name ?? "navigate_document",
+      kind: "read",
+      description: options.description ?? "Read inside one long document (regulation, contract, filing, manual) by navigating its table of contents to the sections that answer a question. Use it after a search returned a long document: pass that document id and the question. Returns the matching sections with titles and page ranges for citation.",
+      inputSchema
+    },
+    handler: {
+      async execute(input, ctx) {
+        if (!isInput(input)) {
+          throw new Error("navigate_document expects { documentId: string, question: string }");
+        }
+        const filter = options.filter?.(ctx);
+        const navigateOptions = {
+          ...filter !== void 0 ? {
+            filter
+          } : {},
+          ...options.budget !== void 0 ? {
+            budget: options.budget
+          } : {}
+        };
+        let documentId = input.documentId.trim();
+        let result = await navigator.navigate(input.question, [
+          documentId
+        ], navigateOptions);
+        let navigation = result.documents[0];
+        if (navigation?.stoppedBy === "not-found") {
+          const bare = documentIdOf(documentId.replace(/#node:\d+$/, ""));
+          if (bare !== documentId) {
+            documentId = bare;
+            result = await navigator.navigate(input.question, [
+              documentId
+            ], navigateOptions);
+            navigation = result.documents[0];
+          }
+        }
+        if (navigation === void 0 || navigation.stoppedBy === "not-found") {
+          return {
+            documentId,
+            found: false,
+            passages: [],
+            nodes: [],
+            steps: [],
+            note: "This document has no navigable table of contents (it is short, not indexed, or not accessible). Use the search passages instead."
+          };
+        }
+        return {
+          documentId,
+          found: true,
+          passages: result.passages,
+          nodes: navigation.nodes,
+          steps: navigation.steps,
+          ...navigation.stoppedBy !== void 0 ? {
+            stoppedBy: navigation.stoppedBy
+          } : {},
+          ...navigation.nodes.length === 0 ? {
+            note: "No section of this document looked relevant to the question."
+          } : {}
+        };
+      }
+    }
+  };
+}
+__name(createNavigateDocumentTool, "createNavigateDocumentTool");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_STOP_WORDS,
@@ -2676,7 +5001,9 @@ __name(itemsOf, "itemsOf");
   HybridRetriever,
   KeywordRetriever,
   LexicalRetriever,
+  MemoryDocumentTreeStore,
   MemoryVectorStore,
+  PgDocumentTreeStore,
   PgLexicalVectorStore,
   PgVectorStore,
   RAG_DIAGNOSTIC_LIB,
@@ -2685,26 +5012,44 @@ __name(itemsOf, "itemsOf");
   RedisVectorSchemaMismatchError,
   RedisVectorStore,
   RerankingRetriever,
+  TreeBudgetExceededError,
+  TreeNavigationRetriever,
+  TwoStageRetriever,
   UnsafeRemovalError,
   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,
-  toPgClient
+  parseJsonReply,
+  spanText,
+  stableHash,
+  toPgClient,
+  treeLlmFromModelProvider,
+  walkTree
 });
 //# sourceMappingURL=index.cjs.map