@adonis-agora/agent 0.36.0 → 0.37.0

package/dist/src/rag/tree/build.d.ts

@@ -0,0 +1,96 @@
+import { type DetectedHeading } from './headings.js';
+import { type TreeBudget, type TreeLlm } from './llm.js';
+import type { DocumentTree, DocumentTreeInput, TreeUnit } from './types.js';
+export 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;
+}
+export 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;
+}
+/** Turn the input into units (pages or sections) plus any headings it declares. */
+export declare function toUnits(input: DocumentTreeInput): {
+    units: TreeUnit[];
+    declared: DetectedHeading[] | undefined;
+    kind: 'pages' | 'sections';
+};
+/** The text a node spans (children included), joined in reading order. */
+export declare function spanText(units: readonly TreeUnit[], start: number, end: number): string;
+/** Run `work` over `items` with at most `limit` in flight. */
+export declare function mapLimit<T, R>(items: readonly T[], limit: number, work: (item: T, index: number) => Promise<R>): Promise<R[]>;
+/**
+ * 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.
+ */
+export declare function buildDocumentTree(input: DocumentTreeInput, options: BuildDocumentTreeOptions): Promise<BuiltDocumentTree>;
+//# sourceMappingURL=build.d.ts.map

package/dist/src/rag/tree/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../../src/rag/tree/build.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAgC,MAAM,eAAe,CAAC;AACnF,OAAO,EAIL,KAAK,UAAU,EAEf,KAAK,OAAO,EACb,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EACV,YAAY,EACZ,iBAAiB,EAGjB,QAAQ,EACT,MAAM,YAAY,CAAC;AAGpB,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,sGAAsG;IACtG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,sEAAsE;IACtE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kGAAkG;IAClG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2EAA2E;IAC3E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,2CAA2C;IAC3C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IACtC,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,yGAAyG;IACzG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+DAA+D;IAC/D,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kFAAkF;IAClF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gJAAgJ;IAChJ,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,CAAC;IACnB,yHAAyH;IACzH,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,yFAAyF;IACzF,SAAS,EAAE,OAAO,CAAC;CACpB;AAeD,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,KAAK,EAAE,iBAAiB,GAAG;IACjD,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,QAAQ,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;IACxC,IAAI,EAAE,OAAO,GAAG,UAAU,CAAC;CAC5B,CAiCA;AAyOD,0EAA0E;AAC1E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAMvF;AAyID,8DAA8D;AAC9D,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAC3C,OAAO,CAAC,CAAC,EAAE,CAAC,CAWd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,iBAAiB,CAAC,CA2S5B"}