@adonis-agora/agent 0.35.0 → 0.37.0

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

@@ -0,0 +1,179 @@
+import type { ModelProvider } from '../../spi/model-provider.js';
+/**
+ * The structured side of every tree-LLM request: what is being asked, as data. The prompt says the
+ * same thing in prose; `task` exists so a deterministic fake (tests, offline dev — see
+ * {@link import('./keyword-tree-llm.js').keywordTreeLlm}) can answer without parsing prose, and so a
+ * host can log or route requests by kind.
+ */
+export type TreeLlmTask = {
+    kind: 'structure';
+    /** The window of pages the LLM is asked to find section starts in. */
+    units: {
+        unit: number;
+        page?: number;
+        text: string;
+    }[];
+} | {
+    kind: 'summarize';
+    title: string;
+    text: string;
+} | {
+    kind: 'describe';
+    title?: string;
+    outline: {
+        title: string;
+        summary?: string;
+    }[];
+} | {
+    kind: 'navigate';
+    query: string;
+    /** `single-pass`: the whole tree is shown; `beam`: one level of candidates at a time. */
+    mode: 'single-pass' | 'beam';
+    candidates: TreeLlmCandidate[];
+    /** Max nodes the answer may name. */
+    maxNodes: number;
+} | {
+    kind: 'select';
+    query: string;
+    documents: {
+        id: string;
+        title?: string;
+        description?: string;
+    }[];
+    maxDocuments: number;
+};
+/** A node as shown to the navigating LLM. */
+export interface TreeLlmCandidate {
+    id: string;
+    title: string;
+    summary?: string;
+    pages?: string;
+    /** Present on beam candidates: whether the node can be expanded. */
+    hasChildren?: boolean;
+    /** Present in single-pass mode: depth (0 = top level). */
+    depth?: number;
+}
+export interface TreeLlmRequest {
+    task: TreeLlmTask;
+    system: string;
+    prompt: string;
+    /** A cap for the reply. Adapters pass it as `max_tokens` when they can. */
+    maxOutputTokens: number;
+    /** Aborted when the call's timeout or the build/navigation deadline passes. */
+    signal: AbortSignal;
+}
+export interface TreeLlmResponse {
+    text: string;
+    /** Provider-reported usage. When absent, the budget estimates ~4 characters per token. */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+    };
+}
+/**
+ * The only LLM surface tree building and navigation need: one prompt in, one text reply out. Replies
+ * are expected to be JSON (for structure / navigate / select) or plain text (summaries); parsing is
+ * lenient (code fences, prose around the object). Bring any model:
+ * {@link treeLlmFromModelProvider} (the agent's own `ModelProvider`), {@link openAiChatTreeLlm}
+ * (any OpenAI-compatible `/chat/completions`), or a function of your own. Use a deterministic
+ * setting (temperature 0) — trees are cached by content, so a flaky model makes rebuilds noisy.
+ */
+export type TreeLlm = (request: TreeLlmRequest) => Promise<TreeLlmResponse>;
+/**
+ * Hard limits for one document build or one navigation. Every LLM call is checked against them
+ * **before** it is made (with the prompt's estimated size), so a budget is never overshot by more
+ * than one reply, and nothing retries past it: the failure mode this exists for is an indexer that
+ * burned ~1,240 calls on one PDF it could not structure.
+ */
+export interface TreeBudget {
+    /** Max LLM calls. */
+    maxCalls?: number;
+    /** Max input (prompt) tokens across all calls, estimated at ~4 chars/token before each call. */
+    maxInputTokens?: number;
+    /** Max output tokens across all calls. */
+    maxOutputTokens?: number;
+    /** Wall-clock deadline for the whole operation, ms. */
+    timeoutMs?: number;
+    /** Per-call timeout, ms. Default: whatever is left of `timeoutMs`. */
+    callTimeoutMs?: number;
+}
+/** Thrown internally when a budget or deadline would be exceeded; callers turn it into a fallback. */
+export declare class TreeBudgetExceededError extends Error {
+    readonly limit: 'calls' | 'inputTokens' | 'outputTokens' | 'timeout';
+    constructor(limit: 'calls' | 'inputTokens' | 'outputTokens' | 'timeout');
+}
+/** ~4 characters per token: the budget's estimate when a provider reports no usage. */
+export declare function estimateTokens(text: string): number;
+/** Tracks spend against a {@link TreeBudget} and runs calls under it. Not exported from the package. */
+export declare class BudgetedLlm {
+    private readonly llm;
+    private readonly budget;
+    private readonly outerSignal?;
+    calls: number;
+    inputTokens: number;
+    outputTokens: number;
+    exhausted: boolean;
+    private readonly deadline;
+    constructor(llm: TreeLlm, budget: Required<Pick<TreeBudget, 'maxCalls' | 'maxInputTokens' | 'maxOutputTokens'>> & TreeBudget, outerSignal?: AbortSignal | undefined);
+    /** Time left before the deadline, ms (`Infinity` without one). */
+    remainingMs(): number;
+    /** Would a call with this prompt fit? Does not reserve anything; a `false` marks the budget exhausted. */
+    fits(prompt: string, maxOutputTokens: number): boolean;
+    private limitHit;
+    /**
+     * Make one call, or throw {@link TreeBudgetExceededError} without calling. Provider errors
+     * propagate (after being counted). Never retries.
+     */
+    call(task: TreeLlmTask, system: string, prompt: string, maxOutputTokens: number): Promise<string>;
+}
+/**
+ * Pull the JSON object out of a model reply: bare, fenced in ```json, or surrounded by prose.
+ * Returns `undefined` when there is none (never throws).
+ */
+export declare function parseJsonReply(text: string): Record<string, unknown> | undefined;
+/** The strings in a JSON array value (numbers stringified); anything else yields `[]`. */
+export declare function stringList(value: unknown): string[];
+/**
+ * A {@link TreeLlm} over the agent's own {@link ModelProvider}: one `runTurn` with no tools and a
+ * discarding sink. Usage comes from the provider's report.
+ */
+export declare function treeLlmFromModelProvider(provider: ModelProvider): TreeLlm;
+export interface OpenAiChatTreeLlmOptions {
+    model: string;
+    /** Base URL up to and including `/v1`. Default `https://api.openai.com/v1`. */
+    baseUrl?: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    /** Default 0 — trees are cached by content, determinism keeps rebuilds quiet. */
+    temperature?: number;
+    /**
+     * Send `response_format: { type: 'json_object' }` on JSON tasks. Default `false`: not every
+     * OpenAI-compatible server accepts it, and replies are parsed leniently anyway.
+     */
+    jsonMode?: boolean;
+    /** Extra body fields (a reasoning switch, provider routing). */
+    body?: Record<string, unknown>;
+    fetch?: typeof fetch;
+}
+/**
+ * A {@link TreeLlm} over any OpenAI-compatible `POST /v1/chat/completions` — OpenAI, a gateway,
+ * vLLM, Ollama, DeepSeek, Qwen… — with no SDK dependency. Throws `HttpModelError` on a non-2xx.
+ */
+export declare function openAiChatTreeLlm(options: OpenAiChatTreeLlmOptions): TreeLlm;
+/** A get/set cache — a `Map`, an LRU, a Redis wrapper. Values are whole replies. */
+export interface TreeLlmCache {
+    get(key: string): TreeLlmResponse | undefined | Promise<TreeLlmResponse | undefined>;
+    set(key: string, value: TreeLlmResponse): unknown;
+}
+/**
+ * Memoize a {@link TreeLlm} by the exact request (task kind, system prompt, prompt, output cap).
+ * With a deterministic model that makes a rebuild of an unchanged section, or a repeated question,
+ * free. Cached replies report zero usage, so they cost nothing against a budget but a call slot.
+ */
+export declare function cachedTreeLlm(llm: TreeLlm, cache?: TreeLlmCache): TreeLlm;
+/**
+ * A fast, deterministic, non-cryptographic 64-bit hash (two independent 32-bit FNV-1a/murmur-mixed
+ * lanes) as 16 hex chars — content fingerprints and cache keys, not security.
+ */
+export declare function stableHash(text: string): string;
+//# sourceMappingURL=llm.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llm.d.ts","sourceRoot":"","sources":["../../../../src/rag/tree/llm.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/tree/llm.js

@@ -0,0 +1,264 @@
+import { errorMessageOf, HttpModelError } from '../openai-embeddings.js';
+/** Thrown internally when a budget or deadline would be exceeded; callers turn it into a fallback. */
+export class TreeBudgetExceededError extends Error {
+    limit;
+    constructor(limit) {
+        super(`tree LLM budget exhausted (${limit})`);
+        this.limit = limit;
+        this.name = 'TreeBudgetExceededError';
+    }
+}
+/** ~4 characters per token: the budget's estimate when a provider reports no usage. */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/** Tracks spend against a {@link TreeBudget} and runs calls under it. Not exported from the package. */
+export class 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 !== undefined ? 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) === undefined;
+        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';
+        }
+        // A reply may be shorter than its cap; only refuse when nothing at all is left.
+        if (this.outputTokens + Math.min(maxOutputTokens, 16) > this.budget.maxOutputTokens) {
+            return 'outputTokens';
+        }
+        if (this.remainingMs() <= 0 || this.outerSignal?.aborted) {
+            return 'timeout';
+        }
+        return undefined;
+    }
+    /**
+     * 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 !== undefined) {
+            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());
+        // Reserve the estimate now so concurrent calls cannot all pass the check on the same headroom;
+        // it is corrected to the reported usage when the reply arrives.
+        const reservedInput = estimateTokens(system + prompt);
+        this.inputTokens += reservedInput;
+        this.outputTokens += outputCap;
+        const controller = new AbortController();
+        const onOuterAbort = () => controller.abort(this.outerSignal?.reason);
+        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) {
+            // A failed call keeps its input estimate (the provider may have billed it) but no output.
+            this.outputTokens -= outputCap;
+            if (error instanceof TreeBudgetExceededError) {
+                this.exhausted = true;
+            }
+            throw error;
+        }
+        finally {
+            if (timer !== undefined) {
+                clearTimeout(timer);
+            }
+            this.outerSignal?.removeEventListener('abort', onOuterAbort);
+        }
+    }
+}
+/**
+ * Pull the JSON object out of a model reply: bare, fenced in ```json, or surrounded by prose.
+ * Returns `undefined` when there is none (never throws).
+ */
+export function parseJsonReply(text) {
+    const tryParse = (candidate) => {
+        try {
+            const value = JSON.parse(candidate);
+            return value !== null && typeof value === 'object' && !Array.isArray(value)
+                ? value
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const trimmed = text.trim();
+    const direct = tryParse(trimmed);
+    if (direct !== undefined) {
+        return direct;
+    }
+    const fenced = /```(?:json)?\s*([\s\S]*?)```/i.exec(trimmed);
+    if (fenced?.[1] !== undefined) {
+        const inner = tryParse(fenced[1].trim());
+        if (inner !== undefined) {
+            return inner;
+        }
+    }
+    const start = trimmed.indexOf('{');
+    const end = trimmed.lastIndexOf('}');
+    if (start >= 0 && end > start) {
+        return tryParse(trimmed.slice(start, end + 1));
+    }
+    return undefined;
+}
+/** The strings in a JSON array value (numbers stringified); anything else yields `[]`. */
+export function stringList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => (typeof item === 'number' ? String(item) : item))
+        .filter((item) => typeof item === 'string');
+}
+const NOOP_SINK = {
+    write() { },
+    end() { },
+};
+/**
+ * A {@link TreeLlm} over the agent's own {@link ModelProvider}: one `runTurn` with no tools and a
+ * discarding sink. Usage comes from the provider's report.
+ */
+export 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 },
+        };
+    };
+}
+/**
+ * A {@link TreeLlm} over any OpenAI-compatible `POST /v1/chat/completions` — OpenAI, a gateway,
+ * vLLM, Ollama, DeepSeek, Qwen… — with no SDK dependency. Throws `HttpModelError` on a non-2xx.
+ */
+export function openAiChatTreeLlm(options) {
+    const url = `${(options.baseUrl ?? 'https://api.openai.com/v1').replace(/\/+$/, '')}/chat/completions`;
+    const doFetch = options.fetch ?? fetch;
+    return async (request) => {
+        const json = 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 && json ? { 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 };
+    };
+}
+/**
+ * Memoize a {@link TreeLlm} by the exact request (task kind, system prompt, prompt, output cap).
+ * With a deterministic model that makes a rebuild of an unchanged section, or a repeated question,
+ * free. Cached replies report zero usage, so they cost nothing against a budget but a call slot.
+ */
+export function cachedTreeLlm(llm, cache = new Map()) {
+    return async (request) => {
+        const key = stableHash(`${request.task.kind}\u0000${request.maxOutputTokens}\u0000${request.system}\u0000${request.prompt}`);
+        const hit = await cache.get(key);
+        if (hit !== undefined) {
+            return { text: hit.text, usage: { inputTokens: 0, outputTokens: 0 } };
+        }
+        const response = await llm(request);
+        await cache.set(key, response);
+        return response;
+    };
+}
+/**
+ * A fast, deterministic, non-cryptographic 64-bit hash (two independent 32-bit FNV-1a/murmur-mixed
+ * lanes) as 16 hex chars — content fingerprints and cache keys, not security.
+ */
+export function stableHash(text) {
+    let h1 = 0x811c9dc5;
+    let h2 = 0x01000193 ^ text.length;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        h1 = Math.imul(h1 ^ c, 0x01000193);
+        h2 = Math.imul(h2 ^ c, 0x5bd1e995);
+        h2 ^= h2 >>> 13;
+    }
+    h1 = Math.imul(h1 ^ (h1 >>> 16), 0x85ebca6b);
+    h2 = Math.imul(h2 ^ (h2 >>> 15), 0xc2b2ae35);
+    return (h1 >>> 0).toString(16).padStart(8, '0') + (h2 >>> 0).toString(16).padStart(8, '0');
+}
+//# sourceMappingURL=llm.js.map

package/dist/src/rag/tree/llm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm.js","sourceRoot":"","sources":["../../../../src/rag/tree/llm.ts"],"names":[],"mappings":"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"}

package/dist/src/rag/tree/navigate-tool.d.ts

@@ -0,0 +1,58 @@
+import { type BrandedFunctionalTool } from '../../ai-tool-ref.js';
+import type { Passage } from '../../spi/retriever.js';
+import type { AiToolCtx } from '../../spi/tool.js';
+import type { TreeBudget } from './llm.js';
+import type { NavigatedNode, NavigationStep, TreeNavigationRetriever } from './navigate.js';
+export interface NavigateDocumentToolOptions {
+    /** Tool name the model sees. Default `navigate_document`. */
+    name?: string;
+    description?: string;
+    /**
+     * The access filter for this call, from the tool context — e.g. `(ctx) => ({ tenant: ctx.actor.tenantRef })`.
+     * Applied to the tree read, with the vector stores' semantics. Omit only for single-tenant corpora.
+     */
+    filter?: (ctx: AiToolCtx) => Record<string, unknown> | undefined;
+    /** Per-call navigation budget (overrides the navigator's). */
+    budget?: TreeBudget;
+    /** Roles allowed to invoke. Omit to inherit the config's `defaultRoles`. */
+    roles?: string[];
+    /** Authz ability for an ability-aware `RolesPolicy`. */
+    ability?: string;
+}
+export interface NavigateDocumentInput {
+    documentId: string;
+    question: string;
+}
+export interface NavigateDocumentOutput {
+    documentId: string;
+    /** `false` when the document has no tree (short documents don't get one) or the caller may not read it. */
+    found: boolean;
+    passages: Passage[];
+    /** The sections chosen and the path to each. */
+    nodes: NavigatedNode[];
+    /** The walk, step by step, with the model's reasoning. */
+    steps: NavigationStep[];
+    stoppedBy?: string;
+    note?: string;
+}
+/**
+ * The agentic half of two-stage retrieval: `navigate_document(documentId, question)`, a `read`-kind
+ * tool the model calls **after** a search put a long document among its hits — it walks that
+ * document's table of contents to the sections that answer and returns their text, with the path and
+ * reasoning (the citation surface: section titles and page ranges).
+ *
+ * `documentId` may also be a chunk id from a search result (`doc#12`); the chunk suffix is dropped.
+ * A document with no tree answers `found: false` with a note, so the model falls back to the
+ * passages it already has instead of retrying.
+ *
+ * Returns a {@link defineTool} tool: export it from an `app/agent_tools` module, or pass it to
+ * `defineConfig({ tools })`.
+ *
+ * ```ts
+ * export const navigateDocument = createNavigateDocumentTool(navigator, {
+ *   filter: (ctx) => ({ tenant: ctx.actor.tenantRef }),
+ * })
+ * ```
+ */
+export declare function createNavigateDocumentTool(navigator: TreeNavigationRetriever, options?: NavigateDocumentToolOptions): BrandedFunctionalTool;
+//# sourceMappingURL=navigate-tool.d.ts.map

package/dist/src/rag/tree/navigate-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigate-tool.d.ts","sourceRoot":"","sources":["../../../../src/rag/tree/navigate-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,qBAAqB,EAAc,MAAM,sBAAsB,CAAC;AAC9E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE5F,MAAM,WAAW,2BAA2B;IAC1C,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACjE,8DAA8D;IAC9D,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,2GAA2G;IAC3G,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,gDAAgD;IAChD,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,0DAA0D;IAC1D,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA2BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,uBAAuB,EAClC,OAAO,GAAE,2BAAgC,GACxC,qBAAqB,CAuDvB"}

package/dist/src/rag/tree/navigate-tool.js

@@ -0,0 +1,95 @@
+import { defineTool } from '../../ai-tool-ref.js';
+import { documentIdOf } from '../vector-store.js';
+function isInput(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.documentId === 'string' &&
+        typeof value.question === 'string');
+}
+const inputSchema = {
+    '~standard': {
+        version: 1,
+        vendor: 'adonis-agora-agent',
+        validate(value) {
+            return isInput(value)
+                ? { value: { documentId: value.documentId, question: value.question } }
+                : {
+                    issues: [
+                        { message: 'navigate_document expects { documentId: string, question: string }' },
+                    ],
+                };
+        },
+    },
+};
+/**
+ * The agentic half of two-stage retrieval: `navigate_document(documentId, question)`, a `read`-kind
+ * tool the model calls **after** a search put a long document among its hits — it walks that
+ * document's table of contents to the sections that answer and returns their text, with the path and
+ * reasoning (the citation surface: section titles and page ranges).
+ *
+ * `documentId` may also be a chunk id from a search result (`doc#12`); the chunk suffix is dropped.
+ * A document with no tree answers `found: false` with a note, so the model falls back to the
+ * passages it already has instead of retrying.
+ *
+ * Returns a {@link defineTool} tool: export it from an `app/agent_tools` module, or pass it to
+ * `defineConfig({ tools })`.
+ *
+ * ```ts
+ * export const navigateDocument = createNavigateDocumentTool(navigator, {
+ *   filter: (ctx) => ({ tenant: ctx.actor.tenantRef }),
+ * })
+ * ```
+ */
+export function createNavigateDocumentTool(navigator, options = {}) {
+    return defineTool({
+        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.',
+        input: inputSchema,
+        ...(options.roles !== undefined ? { roles: options.roles } : {}),
+        ...(options.ability !== undefined ? { ability: options.ability } : {}),
+    }, async (input, ctx) => {
+        if (!isInput(input)) {
+            throw new Error('navigate_document expects { documentId: string, question: string }');
+        }
+        const filter = options.filter?.(ctx);
+        const navigateOptions = {
+            ...(filter !== undefined ? { filter } : {}),
+            ...(options.budget !== undefined ? { 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 === undefined || 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 !== undefined ? { stoppedBy: navigation.stoppedBy } : {}),
+            ...(navigation.nodes.length === 0
+                ? { note: 'No section of this document looked relevant to the question.' }
+                : {}),
+        };
+    });
+}
+//# sourceMappingURL=navigate-tool.js.map

package/dist/src/rag/tree/navigate-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigate-tool.js","sourceRoot":"","sources":["../../../../src/rag/tree/navigate-tool.ts"],"names":[],"mappings":"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"}