mind-palace-graph 0.3.0

package/dist/api.d.ts

@@ -0,0 +1,682 @@
+/**
+ * Programmatic API for mpg.
+ *
+ * This is the surface an LLM harness should embed against instead of
+ * shelling out to the CLI. It exposes the same operations the CLI
+ * does, but as async functions returning structured data.
+ *
+ * The CLI is a thin wrapper over this module. Conversely, this module
+ * is what powers `mpg search`, `mpg stash`, etc. for in-process use.
+ */
+import { type Stash } from "./mind-palace.js";
+import type { Node } from "./types.js";
+export type Effort = "scan" | "quick" | "normal" | "deep" | "auto";
+export type Strategy = "fill" | "deep";
+export type SortMode = "default" | "recent" | "oldest";
+export type WindowCurve = "flat" | "linear" | "log";
+export interface SearchOptions {
+    /** Regex pattern. Required for search. */
+    pattern: string;
+    /** Paths to search (files, dirs, globs, @file, @-). */
+    in?: string[];
+    /** Search the stdout of a command. */
+    cmd?: string;
+    /** Read content from stdin. */
+    stdin?: boolean;
+    /** Fetch and search a URL. */
+    url?: string;
+    /** Tokens of context before each match. Default: 500. */
+    before?: number;
+    /** Tokens of context after each match. Default: 500. */
+    after?: number;
+    /** Cap on the number of nodes returned. Default: 30. */
+    maxNodes?: number;
+    /** Total token budget across all nodes. */
+    maxTokens?: number;
+    /** How to use --max-tokens. Default: "fill". */
+    strategy?: Strategy;
+    /** Effort preset. Default: "normal". */
+    effort?: Effort;
+    /** rg options. */
+    rg?: {
+        caseInsensitive?: boolean;
+        word?: boolean;
+        fixedStrings?: boolean;
+        multiline?: boolean;
+        hidden?: boolean;
+        noIgnore?: boolean;
+        include?: string[];
+        exclude?: string[];
+        type?: string;
+    };
+    /** Use a stashed file list as the search target. */
+    from?: string;
+    /** Compose multiple stashes' file lists as the search target. */
+    compose?: string[];
+    /** Palace file path. Defaults to project-scoped. */
+    palacePath?: string;
+    /** Pagination: 1-indexed page number. */
+    page?: number;
+    /** Pagination: items per page (default 10). */
+    pageSize?: number;
+    /** Disable pagination; return everything. */
+    all?: boolean;
+    /**
+     * Disable the wide-record auto-tune. By default, when the sources
+     * being searched have a median line length over ~500 chars (typical
+     * of JSONL event streams), mpg drops `before`/`after` to 0 so each
+     * node is just the matched line. Set this to `true` to keep the
+     * effort-preset windowing regardless of corpus shape.
+     */
+    noAutoTune?: boolean;
+    /**
+     * Order returned nodes by source file modification time.
+     *   "default" (or undefined): rg's natural traversal order.
+     *   "recent": newest-edited files first. Surfaces what changed
+     *             recently — useful when scan is used as a memory index.
+     *   "oldest": oldest files first.
+     * Non-file sources (cmd / url / stdin) sort to the end in `recent`
+     * and to the beginning in `oldest`.
+     */
+    sort?: SortMode;
+    /**
+     * Token-window decay curve applied across returned nodes.
+     *   "flat" (or undefined): every node gets the full `before`/`after`
+     *     window. The classic behavior.
+     *   "linear": window decays linearly from full at rank 0 down to a
+     *     small floor (~10% of full) at the last rank. Combined with
+     *     `sort: "recent"`, this gives recent nodes rich context and
+     *     older nodes a tight disambiguating window.
+     *   "log": window decays as `full / log2(rank + 2)`. Gentler than
+     *     linear — useful when you want meaningful context several
+     *     ranks deep, not just on the first hit.
+     * In all modes the per-node window is bounded between 0 and the
+     * configured `before`/`after`.
+     */
+    windowCurve?: WindowCurve;
+    /** Sub-line clip mode (N chars on each side of the matched span). */
+    clipChars?: number;
+    /** Typo-tolerant search via regex transform (skipped if pattern is regex-y). */
+    fuzzy?: boolean;
+}
+/** Public, harness-friendly node shape. Same as internal Node. */
+export interface SearchNode extends Node {
+}
+/** Public, harness-friendly result shape. */
+export interface SearchResult {
+    pattern: string;
+    effort: Effort;
+    strategy: Strategy;
+    /**
+     * Machine-readable status so LLMs can branch without parsing text.
+     *   - "ok":          matches returned cleanly.
+     *   - "no_matches":  zero matches, all sources searched successfully.
+     *   - "truncated":   matches exceeded budget; partial result.
+     *   - "partial":     at least one source errored but others returned
+     *                    matches. Check `errors[]` for per-source failures.
+     *   - "error":       all sources errored; no usable matches.
+     */
+    status: "ok" | "no_matches" | "truncated" | "partial" | "error";
+    total_nodes: number;
+    total_tokens: number;
+    /** Token count of the actual nodes returned (after pagination). */
+    page_tokens: number;
+    sources_count: number;
+    truncated: boolean;
+    nodes: SearchNode[];
+    /** Per-source errors. Empty array when all sources searched cleanly. */
+    errors: Array<{
+        source: string;
+        message: string;
+    }>;
+    duration_ms: number;
+    before_tokens: number;
+    after_tokens: number;
+    max_nodes: number;
+    max_tokens?: number;
+    /** True when the wide-record auto-tune shrank before/after to 0. */
+    auto_tune_applied?: boolean;
+    /** Optional pagination metadata; absent when pagination is off. */
+    pagination?: {
+        page: number;
+        page_size: number;
+        total_items: number;
+        total_pages: number;
+        has_next: boolean;
+        has_prev: boolean;
+    };
+}
+export interface StashOptions {
+    /** Stash name. */
+    name: string;
+    /** Free-form note. */
+    note?: string;
+    /** Tags for filtering. */
+    tags?: string[];
+    /** Overwrite an existing stash. Default: merge. */
+    replace?: boolean;
+    /** Palace file path. Defaults to project-scoped. */
+    palacePath?: string;
+    /**
+     * Auto-expire this stash after the given duration (e.g. "1h", "7d").
+     * Pruned automatically by `mpg --mp-prune-expired`. Default: no expiry.
+     */
+    ttl?: string;
+    /**
+     * Locations-only stash: drop context_before/match_text/context_after
+     * to keep just (source, line, span). Useful when you only need the
+     * stash for `--mp-from` re-search and don't want to persist body text.
+     */
+    locations?: boolean;
+}
+export interface StashResult {
+    action: "created" | "merged" | "replaced";
+    stash: Stash;
+    palace_path: string;
+}
+/**
+ * Threshold above which auto-tune treats the corpus as "wide-record"
+ * (JSONL events, log lines with embedded JSON, etc) and drops
+ * before/after padding. Chosen so that typical source code (lines
+ * usually under 200 chars) stays in the line-based regime, while
+ * single-line serialized events trip the switch.
+ */
+export declare const WIDE_RECORD_MEDIAN_THRESHOLD = 500;
+/**
+ * Estimate median line length across the first chunk of up to 3 files.
+ * Used by the wide-record auto-tune.
+ *
+ * Bounded I/O: we read at most 64KB per file and at most 256KB total,
+ * regardless of file size. A file whose head contains any NUL byte is
+ * treated as binary and skipped — otherwise a stray .png in a dir spec
+ * would feed garbage into the median.
+ */
+export declare function sampleMedianLineLength(files: string[]): number;
+/**
+ * Run a search and return structured result.
+ *
+ * @example
+ *   const r = await search({ pattern: "TODO", in: ["src/"], effort: "quick" });
+ *   console.log(r.total_nodes, r.nodes[0].match_text);
+ */
+export declare function search(opts: SearchOptions): Promise<SearchResult>;
+/**
+ * Stash a search result in the mind palace.
+ *
+ * The `result` can be a SearchResult, or just an array of Nodes.
+ * Returns the action taken (created/merged/replaced) and the full stash.
+ */
+export declare function stash(result: SearchResult | SearchNode[], opts: StashOptions): Promise<StashResult>;
+export declare function listStashes(palacePath?: string, tagFilter?: string[]): Stash[];
+export declare function getStash(name: string, palacePath?: string): Stash | null;
+export declare function dropStash(name: string, palacePath?: string): boolean;
+/** Resolve a stash (or composition of stashes) to its source paths. */
+export declare function stashToSources(names: string | string[], palacePath?: string): string[];
+/** Claude-compatible tool definitions. Drop into Claude's API. */
+export declare const claudeTools: readonly [{
+    readonly type: "function";
+    readonly function: {
+        readonly name: "mpg_search";
+        readonly description: string;
+        readonly parameters: {
+            type: "object";
+            properties: {
+                pattern: {
+                    type: string;
+                    description: string;
+                };
+                in: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                cmd: {
+                    type: string;
+                    description: string;
+                };
+                url: {
+                    type: string;
+                    description: string;
+                };
+                before: {
+                    type: string;
+                    description: string;
+                };
+                after: {
+                    type: string;
+                    description: string;
+                };
+                max_nodes: {
+                    type: string;
+                    description: string;
+                };
+                max_tokens: {
+                    type: string;
+                    description: string;
+                };
+                effort: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                strategy: {
+                    type: string;
+                    enum: string[];
+                    description: string;
+                };
+                from: {
+                    type: string;
+                    description: string;
+                };
+                compose: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                page: {
+                    type: string;
+                    description: string;
+                };
+                page_size: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "mpg_stash";
+        readonly description: string;
+        readonly parameters: {
+            type: "object";
+            properties: {
+                name: {
+                    type: string;
+                    description: string;
+                };
+                note: {
+                    type: string;
+                    description: string;
+                };
+                tags: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                pattern: {
+                    type: string;
+                    description: string;
+                };
+                in: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                effort: {
+                    type: string;
+                    enum: string[];
+                };
+                replace: {
+                    type: string;
+                    description: string;
+                };
+                palace_path: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "mpg_list_stashes";
+        readonly description: string;
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly tag_filter: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                    };
+                    readonly description: "Only show stashes with all of these tags.";
+                };
+                readonly page: {
+                    readonly type: "number";
+                    readonly description: "1-indexed page number.";
+                };
+                readonly page_size: {
+                    readonly type: "number";
+                    readonly description: "Stashes per page. Default 20.";
+                };
+                readonly palace_path: {
+                    readonly type: "string";
+                    readonly description: "Override mind-palace file.";
+                };
+            };
+            readonly required: string[];
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "mpg_get_stash";
+        readonly description: string;
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Name of the stash to retrieve.";
+                };
+                readonly with_nodes: {
+                    readonly type: "boolean";
+                    readonly description: string;
+                };
+                readonly page: {
+                    readonly type: "number";
+                    readonly description: "1-indexed page number (only when with_nodes:true).";
+                };
+                readonly page_size: {
+                    readonly type: "number";
+                    readonly description: "Nodes per page. Default 10 (only when with_nodes:true).";
+                };
+                readonly palace_path: {
+                    readonly type: "string";
+                    readonly description: "Override mind-palace file.";
+                };
+            };
+            readonly required: readonly ["name"];
+        };
+    };
+}, {
+    readonly type: "function";
+    readonly function: {
+        readonly name: "mpg_drop_stash";
+        readonly description: string;
+        readonly parameters: {
+            readonly type: "object";
+            readonly properties: {
+                readonly name: {
+                    readonly type: "string";
+                    readonly description: "Name of the stash to drop.";
+                };
+                readonly palace_path: {
+                    readonly type: "string";
+                    readonly description: "Override mind-palace file.";
+                };
+            };
+            readonly required: readonly ["name"];
+        };
+    };
+}];
+/** Gemini-compatible tool definitions (function_declarations array). */
+export declare const geminiTools: {
+    name: "mpg_search" | "mpg_stash" | "mpg_list_stashes" | "mpg_get_stash" | "mpg_drop_stash";
+    description: string;
+    parameters: {
+        type: "object";
+        properties: {
+            pattern: {
+                type: string;
+                description: string;
+            };
+            in: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            cmd: {
+                type: string;
+                description: string;
+            };
+            url: {
+                type: string;
+                description: string;
+            };
+            before: {
+                type: string;
+                description: string;
+            };
+            after: {
+                type: string;
+                description: string;
+            };
+            max_nodes: {
+                type: string;
+                description: string;
+            };
+            max_tokens: {
+                type: string;
+                description: string;
+            };
+            effort: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            strategy: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            from: {
+                type: string;
+                description: string;
+            };
+            compose: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            page: {
+                type: string;
+                description: string;
+            };
+            page_size: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    } | {
+        type: "object";
+        properties: {
+            name: {
+                type: string;
+                description: string;
+            };
+            note: {
+                type: string;
+                description: string;
+            };
+            tags: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            pattern: {
+                type: string;
+                description: string;
+            };
+            in: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            effort: {
+                type: string;
+                enum: string[];
+            };
+            replace: {
+                type: string;
+                description: string;
+            };
+            palace_path: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    } | {
+        readonly type: "object";
+        readonly properties: {
+            readonly tag_filter: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Only show stashes with all of these tags.";
+            };
+            readonly page: {
+                readonly type: "number";
+                readonly description: "1-indexed page number.";
+            };
+            readonly page_size: {
+                readonly type: "number";
+                readonly description: "Stashes per page. Default 20.";
+            };
+            readonly palace_path: {
+                readonly type: "string";
+                readonly description: "Override mind-palace file.";
+            };
+        };
+        readonly required: string[];
+    } | {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly description: "Name of the stash to retrieve.";
+            };
+            readonly with_nodes: {
+                readonly type: "boolean";
+                readonly description: string;
+            };
+            readonly page: {
+                readonly type: "number";
+                readonly description: "1-indexed page number (only when with_nodes:true).";
+            };
+            readonly page_size: {
+                readonly type: "number";
+                readonly description: "Nodes per page. Default 10 (only when with_nodes:true).";
+            };
+            readonly palace_path: {
+                readonly type: "string";
+                readonly description: "Override mind-palace file.";
+            };
+        };
+        readonly required: readonly ["name"];
+    } | {
+        readonly type: "object";
+        readonly properties: {
+            readonly name: {
+                readonly type: "string";
+                readonly description: "Name of the stash to drop.";
+            };
+            readonly palace_path: {
+                readonly type: "string";
+                readonly description: "Override mind-palace file.";
+            };
+        };
+        readonly required: readonly ["name"];
+    };
+}[];
+/** Legacy: single-tool definition for OpenAI-compatible APIs. */
+export declare const toolDefinition: {
+    readonly name: "mpg";
+    readonly description: string;
+    readonly parameters: {
+        readonly type: "object";
+        readonly properties: {
+            readonly action: {
+                readonly type: "string";
+                readonly enum: readonly ["search", "stash", "list", "get", "drop"];
+                readonly description: "Which operation to perform.";
+            };
+            readonly pattern: {
+                readonly type: "string";
+                readonly description: "Regex pattern (search).";
+            };
+            readonly in: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Paths to search.";
+            };
+            readonly name: {
+                readonly type: "string";
+                readonly description: "Stash name (stash/get/drop).";
+            };
+            readonly note: {
+                readonly type: "string";
+                readonly description: "Stash note (stash).";
+            };
+            readonly tags: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Tags (stash/filter).";
+            };
+            readonly before: {
+                readonly type: "number";
+            };
+            readonly after: {
+                readonly type: "number";
+            };
+            readonly max_nodes: {
+                readonly type: "number";
+            };
+            readonly max_tokens: {
+                readonly type: "number";
+            };
+            readonly effort: {
+                readonly type: "string";
+                readonly enum: readonly ["quick", "normal", "deep", "auto"];
+            };
+            readonly from: {
+                readonly type: "string";
+                readonly description: "Stash name as search target.";
+            };
+            readonly compose: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: "Stash names as union target.";
+            };
+            readonly page: {
+                readonly type: "number";
+                readonly description: "1-indexed page number.";
+            };
+            readonly page_size: {
+                readonly type: "number";
+                readonly description: "Items per page.";
+            };
+        };
+        readonly required: readonly ["action"];
+    };
+};