treedex 0.1.2 → 0.1.5

package/dist/index.d.ts

@@ -1,426 +0,0 @@
-/** Shared type definitions for TreeDex. */
-interface Page {
-    page_num: number;
-    text: string;
-    token_count: number;
-}
-interface TreeNode {
-    structure: string;
-    title: string;
-    physical_index: number;
-    nodes: TreeNode[];
-    start_index?: number;
-    end_index?: number;
-    node_id?: string;
-    text?: string;
-    [key: string]: unknown;
-}
-interface IndexData {
-    version: string;
-    framework: string;
-    tree: TreeNode[];
-    pages: Page[];
-}
-interface Stats {
-    total_pages: number;
-    total_tokens: number;
-    total_nodes: number;
-    leaf_nodes: number;
-    root_sections: number;
-}
-
-/**
- * LLM backends for TreeDex.
- *
- * Hierarchy:
- *     BaseLLM                     — abstract base, subclass for custom LLMs
- *     ├── GeminiLLM               — Google Gemini (lazy SDK)
- *     ├── OpenAILLM               — OpenAI (lazy SDK)
- *     ├── ClaudeLLM               — Anthropic Claude (lazy SDK)
- *     ├── MistralLLM              — Mistral AI (lazy SDK)
- *     ├── CohereLLM               — Cohere (lazy SDK)
- *     ├── OpenAICompatibleLLM     — Any OpenAI-compatible endpoint (fetch)
- *     │   ├── GroqLLM             — Groq (pre-configured URL)
- *     │   ├── TogetherLLM         — Together AI (pre-configured URL)
- *     │   ├── FireworksLLM        — Fireworks AI (pre-configured URL)
- *     │   ├── OpenRouterLLM       — OpenRouter (pre-configured URL)
- *     │   ├── DeepSeekLLM         — DeepSeek (pre-configured URL)
- *     │   ├── CerebrasLLM         — Cerebras (pre-configured URL)
- *     │   └── SambanovaLLM        — SambaNova (pre-configured URL)
- *     ├── HuggingFaceLLM          — HuggingFace Inference API (fetch)
- *     ├── OllamaLLM               — Ollama native /api/generate (fetch)
- *     ├── LiteLLM                 — litellm wrapper (100+ providers)
- *     └── FunctionLLM             — Wrap any callable(str) -> str
- *
- * Named providers lazy-import their SDKs.
- * OpenAICompatibleLLM, HuggingFaceLLM, OllamaLLM use only fetch.
- */
-/** Base class for all LLM backends. Subclass and implement generate(). */
-declare abstract class BaseLLM {
-    abstract generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Google Gemini via @google/generative-ai SDK. */
-declare class GeminiLLM extends BaseLLM {
-    readonly apiKey: string;
-    readonly modelName: string;
-    private _client;
-    constructor(apiKey: string, model?: string);
-    private getClient;
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** OpenAI via openai SDK. */
-declare class OpenAILLM extends BaseLLM {
-    readonly apiKey: string;
-    readonly modelName: string;
-    private _client;
-    constructor(apiKey: string, model?: string);
-    private getClient;
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Anthropic Claude via @anthropic-ai/sdk. */
-declare class ClaudeLLM extends BaseLLM {
-    readonly apiKey: string;
-    readonly modelName: string;
-    private _client;
-    constructor(apiKey: string, model?: string);
-    private getClient;
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Mistral AI via @mistralai/mistralai SDK. */
-declare class MistralLLM extends BaseLLM {
-    readonly apiKey: string;
-    readonly modelName: string;
-    private _client;
-    constructor(apiKey: string, model?: string);
-    private getClient;
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Cohere via cohere-ai SDK. */
-declare class CohereLLM extends BaseLLM {
-    readonly apiKey: string;
-    readonly modelName: string;
-    private _client;
-    constructor(apiKey: string, model?: string);
-    private getClient;
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/**
- * Universal backend for any OpenAI-compatible API endpoint.
- *
- * Works with: Groq, Together AI, Fireworks, vLLM, LM Studio,
- * OpenRouter, DeepSeek, Cerebras, SambaNova, Ollama (OpenAI mode),
- * and any other compatible service.
- */
-declare class OpenAICompatibleLLM extends BaseLLM {
-    baseUrl: string;
-    readonly model: string;
-    readonly apiKey: string | null;
-    readonly maxTokens: number;
-    readonly temperature: number;
-    readonly extraHeaders: Record<string, string>;
-    readonly timeout: number;
-    constructor(options: {
-        baseUrl: string;
-        model: string;
-        apiKey?: string | null;
-        maxTokens?: number;
-        temperature?: number;
-        extraHeaders?: Record<string, string>;
-        timeout?: number;
-    });
-    private buildHeaders;
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Groq — fast LLM inference via groq SDK. */
-declare class GroqLLM extends BaseLLM {
-    readonly apiKey: string;
-    readonly model: string;
-    private _client;
-    constructor(apiKey: string, model?: string);
-    private getClient;
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Together AI — open-source models. Zero SDK dependencies. */
-declare class TogetherLLM extends OpenAICompatibleLLM {
-    constructor(apiKey: string, model?: string, options?: {
-        maxTokens?: number;
-        temperature?: number;
-    });
-    toString(): string;
-}
-/** Fireworks AI — fast open-source inference. Zero SDK dependencies. */
-declare class FireworksLLM extends OpenAICompatibleLLM {
-    constructor(apiKey: string, model?: string, options?: {
-        maxTokens?: number;
-        temperature?: number;
-    });
-    toString(): string;
-}
-/** OpenRouter — access any model via one API. Zero SDK dependencies. */
-declare class OpenRouterLLM extends OpenAICompatibleLLM {
-    constructor(apiKey: string, model?: string, options?: {
-        maxTokens?: number;
-        temperature?: number;
-    });
-    toString(): string;
-}
-/** DeepSeek — powerful reasoning models. Zero SDK dependencies. */
-declare class DeepSeekLLM extends OpenAICompatibleLLM {
-    constructor(apiKey: string, model?: string, options?: {
-        maxTokens?: number;
-        temperature?: number;
-    });
-    toString(): string;
-}
-/** Cerebras — ultra-fast inference. Zero SDK dependencies. */
-declare class CerebrasLLM extends OpenAICompatibleLLM {
-    constructor(apiKey: string, model?: string, options?: {
-        maxTokens?: number;
-        temperature?: number;
-    });
-    toString(): string;
-}
-/** SambaNova — fast AI inference. Zero SDK dependencies. */
-declare class SambanovaLLM extends OpenAICompatibleLLM {
-    constructor(apiKey: string, model?: string, options?: {
-        maxTokens?: number;
-        temperature?: number;
-    });
-    toString(): string;
-}
-/** HuggingFace Inference API. Zero SDK dependencies. */
-declare class HuggingFaceLLM extends BaseLLM {
-    readonly apiKey: string;
-    readonly model: string;
-    readonly maxTokens: number;
-    constructor(apiKey: string, model?: string, maxTokens?: number);
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Ollama native backend using /api/generate endpoint. */
-declare class OllamaLLM extends BaseLLM {
-    readonly model: string;
-    baseUrl: string;
-    constructor(model?: string, baseUrl?: string);
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-/** Wrap any async or sync function as an LLM backend. */
-declare class FunctionLLM extends BaseLLM {
-    private readonly _fn;
-    constructor(fn: (prompt: string) => string | Promise<string>);
-    generate(prompt: string): Promise<string>;
-    toString(): string;
-}
-
-/** TreeDex: Tree-based document RAG framework. */
-
-/** Result of a TreeDex query. */
-declare class QueryResult {
-    readonly context: string;
-    readonly nodeIds: string[];
-    readonly pageRanges: [number, number][];
-    readonly reasoning: string;
-    readonly answer: string;
-    constructor(context: string, nodeIds: string[], pageRanges: [number, number][], reasoning: string, answer?: string);
-    /** Human-readable page ranges like 'pages 5-8, 12-15'. */
-    get pagesStr(): string;
-    toString(): string;
-}
-/** Tree-based document index for RAG retrieval. */
-declare class TreeDex {
-    readonly tree: TreeNode[];
-    readonly pages: Page[];
-    llm: BaseLLM | null;
-    private _nodeMap;
-    constructor(tree: TreeNode[], pages: Page[], llm?: BaseLLM | null);
-    /**
-     * Build a TreeDex index from a file.
-     *
-     * @param path - Path to document (PDF, TXT, HTML, DOCX)
-     * @param llm - LLM backend with .generate(prompt) method
-     * @param options - Optional configuration
-     */
-    static fromFile(path: string, llm: BaseLLM, options?: {
-        loader?: {
-            load(path: string): Promise<Page[]>;
-        };
-        maxTokens?: number;
-        overlap?: number;
-        verbose?: boolean;
-    }): Promise<TreeDex>;
-    /** Build a TreeDex index from pre-extracted pages. */
-    static fromPages(pages: Page[], llm: BaseLLM, options?: {
-        maxTokens?: number;
-        overlap?: number;
-        verbose?: boolean;
-    }): Promise<TreeDex>;
-    /** Create a TreeDex from an existing tree and pages. */
-    static fromTree(tree: TreeNode[], pages: Page[], llm?: BaseLLM | null): TreeDex;
-    /**
-     * Query the index and return relevant context.
-     *
-     * @param question - The user's question
-     * @param options - Optional LLM override or agentic mode
-     */
-    query(question: string, options?: BaseLLM | {
-        llm?: BaseLLM;
-        agentic?: boolean;
-    }): Promise<QueryResult>;
-    /** Save the index to a JSON file. */
-    save(path: string): Promise<string>;
-    /** Load a TreeDex index from a JSON file. */
-    static load(path: string, llm?: BaseLLM | null): Promise<TreeDex>;
-    /** Pretty-print the tree structure. */
-    showTree(): void;
-    /** Return index statistics. */
-    stats(): Stats;
-    /** Find sections that exceed size thresholds. */
-    findLargeSections(options?: {
-        maxPages?: number;
-        maxTokens?: number;
-    }): TreeNode[];
-}
-
-/**
- * Document loaders for multiple file formats.
- *
- * Each loader returns a list of objects: [{page_num, text, token_count}]
- * matching the format used by pdf-parser extractPages().
- */
-
-/** Split plain text into synthetic pages by character count. */
-declare function textToPages(text: string, charsPerPage?: number): Page[];
-/** Load PDF files using pdfjs-dist. */
-declare class PDFLoader {
-    load(path: string): Promise<Page[]>;
-}
-/** Load plain text or markdown files. */
-declare class TextLoader {
-    readonly charsPerPage: number;
-    constructor(charsPerPage?: number);
-    load(path: string): Promise<Page[]>;
-}
-/** Load HTML files, stripping tags to plain text. */
-declare class HTMLLoader {
-    readonly charsPerPage: number;
-    constructor(charsPerPage?: number);
-    load(path: string): Promise<Page[]>;
-    private stripHtml;
-}
-/** Load DOCX files using mammoth. */
-declare class DOCXLoader {
-    readonly charsPerPage: number;
-    constructor(charsPerPage?: number);
-    load(path: string): Promise<Page[]>;
-}
-/** Auto-detect file format and load pages. */
-declare function autoLoader(filePath: string): Promise<Page[]>;
-
-/** Tree construction utilities. */
-
-/**
- * Convert a flat list with `structure` fields into a hierarchical tree.
- *
- * Each item must have a `structure` field like "1", "1.1", "1.2.3".
- * Parent of "1.2.3" is "1.2", parent of "1.2" is "1", "1" is root.
- * Output nodes get a `nodes: []` field for children.
- */
-declare function listToTree(flatList: Array<{
-    structure: string;
-    title: string;
-    physical_index: number;
-    [key: string]: unknown;
-}>): TreeNode[];
-/**
- * Set start_index and end_index on each node.
- *
- * - start_index = node's physical_index
- * - end_index = next sibling's physical_index - 1, or parent's end,
- *   or total_pages - 1 for the last root node
- */
-declare function assignPageRanges(tree: TreeNode[], totalPages: number): TreeNode[];
-/** DFS traversal, assigns sequential IDs: '0001', '0002', etc. */
-declare function assignNodeIds(tree: TreeNode[]): TreeNode[];
-/** Return nodes that exceed page or token thresholds. */
-declare function findLargeNodes(tree: TreeNode[], options?: {
-    maxPages?: number;
-    maxTokens?: number;
-    pages?: Page[] | null;
-}): TreeNode[];
-/** Add `text` field to each node by concatenating page text for its range. */
-declare function embedTextInTree(tree: TreeNode[], pages: Page[]): TreeNode[];
-
-/** Tree manipulation and utility functions. */
-
-/** Flatten tree into {node_id: node_dict} for O(1) lookups. */
-declare function createNodeMapping(tree: TreeNode[]): Record<string, TreeNode>;
-/** Return a deep copy of the tree with all `text` fields removed. */
-declare function stripTextFromTree(tree: TreeNode[]): TreeNode[];
-/**
- * Gather and concatenate text from a list of node IDs.
- *
- * Format:
- *     [Section: Title]
- *     text
- *
- *     [Section: Title2]
- *     text2
- */
-declare function collectNodeTexts(nodeIds: string[], nodeMap: Record<string, TreeNode>): string;
-/** Recursively count total nodes in the tree. */
-declare function countNodes(tree: TreeNode[]): number;
-/** Return all nodes with empty `nodes` list. */
-declare function getLeafNodes(tree: TreeNode[]): TreeNode[];
-/** Flatten hierarchy back to a list in DFS order. */
-declare function treeToFlatList(tree: TreeNode[]): Array<Omit<TreeNode, "nodes">>;
-/**
- * Robust JSON extraction from LLM responses.
- *
- * Handles raw JSON, ```json code blocks, and minor formatting issues
- * like trailing commas.
- */
-declare function extractJson(text: string): unknown;
-/** Pretty-print tree structure for debugging. */
-declare function printTree(tree: TreeNode[], indent?: number): void;
-
-/** PDF extraction and page grouping. */
-
-/** Count tokens using cl100k_base-compatible encoding. */
-declare function countTokens(text: string): number;
-/**
- * Extract text from each page of a PDF.
- *
- * Returns a list of objects with page_num, text, and token_count.
- */
-declare function extractPages(pdfPath: string): Promise<Page[]>;
-/**
- * Combine pages[start:end+1] into a string with physical index tags.
- *
- * Each page is wrapped like:
- *     <physical_index_0>page text</physical_index_0>
- * where the number is the page's page_num.
- */
-declare function pagesToTaggedText(pages: Page[], start: number, end: number): string;
-/**
- * Split pages into token-budget groups, each returned as tagged text.
- *
- * Groups overlap by `overlap` pages for continuity.
- */
-declare function groupPages(pages: Page[], maxTokens?: number, overlap?: number): string[];
-
-/** Prompt templates for structure extraction and retrieval. */
-declare function structureExtractionPrompt(text: string): string;
-declare function structureContinuePrompt(previousStructure: string, text: string): string;
-declare function answerPrompt(context: string, query: string): string;
-declare function retrievalPrompt(treeStructure: string, query: string): string;
-
-export { BaseLLM, CerebrasLLM, ClaudeLLM, CohereLLM, DOCXLoader, DeepSeekLLM, FireworksLLM, FunctionLLM, GeminiLLM, GroqLLM, HTMLLoader, HuggingFaceLLM, type IndexData, MistralLLM, OllamaLLM, OpenAICompatibleLLM, OpenAILLM, OpenRouterLLM, PDFLoader, type Page, QueryResult, SambanovaLLM, type Stats, TextLoader, TogetherLLM, TreeDex, type TreeNode, answerPrompt, assignNodeIds, assignPageRanges, autoLoader, collectNodeTexts, countNodes, countTokens, createNodeMapping, embedTextInTree, extractJson, extractPages, findLargeNodes, getLeafNodes, groupPages, listToTree, pagesToTaggedText, printTree, retrievalPrompt, stripTextFromTree, structureContinuePrompt, structureExtractionPrompt, textToPages, treeToFlatList };