ko-qmd 2.8.3-ko.2

package/dist/db.d.ts

@@ -0,0 +1,63 @@
+/**
+ * db.ts - Cross-runtime SQLite compatibility layer
+ *
+ * Provides a unified Database export that works under both Bun (bun:sqlite)
+ * and Node.js (better-sqlite3). The APIs are nearly identical — the main
+ * difference is the import path.
+ *
+ * On macOS, Apple's system SQLite is compiled with SQLITE_OMIT_LOAD_EXTENSION,
+ * which prevents loading native extensions like sqlite-vec. When running under
+ * Bun we call Database.setCustomSQLite() to swap in Homebrew's full-featured
+ * SQLite build before creating any database instances.
+ */
+export declare const isBun: boolean;
+export type SQLiteValue = string | number | bigint | Buffer | Uint8Array | Float32Array | null;
+export type SQLiteParams = readonly SQLiteValue[];
+/**
+ * Open a SQLite database. Works with both bun:sqlite and better-sqlite3.
+ *
+ * `bun:sqlite` and `better-sqlite3` both default `busy_timeout` to 0, so
+ * concurrent writers throw `SQLITE_BUSY` instead of waiting. WAL improves
+ * read-while-write concurrency but does not serialise writers. Setting the
+ * timeout at connection open makes parallel processes (e.g. an `update` or
+ * `query` racing a long `embed`, or a first-open schema migration racing any
+ * routine command) queue at batch boundaries instead of failing on contact.
+ *
+ * WAL is enabled here too (with a bounded retry) so connection-level pragmas
+ * live in one place and the cold-database journal migration survives concurrent
+ * opens.
+ *
+ * Default 120_000 ms outlasts the worst-case batch commit on a multi-GB
+ * index. Override with `QMD_SQLITE_BUSY_TIMEOUT` (value in milliseconds; `0`
+ * restores the upstream fail-fast behaviour). See
+ * https://bun.sh/docs/api/sqlite#busy-timeout.
+ */
+export declare function openDatabase(path: string): Database;
+/**
+ * Common subset of the Database interface used throughout QMD.
+ */
+export interface Database {
+    exec(sql: string): void;
+    prepare(sql: string): Statement;
+    loadExtension(path: string): void;
+    transaction<T extends (...args: SQLiteValue[]) => unknown>(fn: T): T & {
+        immediate: T;
+    };
+    close(): void;
+}
+export interface Statement {
+    run(...params: SQLiteValue[]): {
+        changes: number;
+        lastInsertRowid: number | bigint;
+    };
+    get<T = unknown>(...params: SQLiteValue[]): T | undefined;
+    all<T = unknown>(...params: SQLiteValue[]): T[];
+    iterate<T = unknown>(...params: SQLiteValue[]): IterableIterator<T>;
+}
+/**
+ * Load the sqlite-vec extension into a database.
+ *
+ * Throws with platform-specific fix instructions when the extension is
+ * unavailable.
+ */
+export declare function loadSqliteVec(db: Database): void;

package/dist/db.js

@@ -0,0 +1,130 @@
+/**
+ * db.ts - Cross-runtime SQLite compatibility layer
+ *
+ * Provides a unified Database export that works under both Bun (bun:sqlite)
+ * and Node.js (better-sqlite3). The APIs are nearly identical — the main
+ * difference is the import path.
+ *
+ * On macOS, Apple's system SQLite is compiled with SQLITE_OMIT_LOAD_EXTENSION,
+ * which prevents loading native extensions like sqlite-vec. When running under
+ * Bun we call Database.setCustomSQLite() to swap in Homebrew's full-featured
+ * SQLite build before creating any database instances.
+ */
+export const isBun = "Bun" in globalThis;
+let _Database;
+let _sqliteVecLoad;
+if (isBun) {
+    // Dynamic string prevents tsc from resolving bun:sqlite on Node.js builds
+    const bunSqlite = "bun:" + "sqlite";
+    const BunDatabase = (await import(/* @vite-ignore */ bunSqlite)).Database;
+    // See: https://bun.com/docs/runtime/sqlite#setcustomsqlite
+    if (process.platform === "darwin") {
+        const homebrewPaths = [
+            "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib", // Apple Silicon
+            "/usr/local/opt/sqlite/lib/libsqlite3.dylib", // Intel
+        ];
+        for (const p of homebrewPaths) {
+            try {
+                BunDatabase.setCustomSQLite(p);
+                break;
+            }
+            catch { }
+        }
+    }
+    _Database = BunDatabase;
+    // setCustomSQLite may have silently failed — test that extensions actually work.
+    try {
+        const { getLoadablePath } = await import("sqlite-vec");
+        const vecPath = getLoadablePath();
+        const testDb = new BunDatabase(":memory:");
+        testDb.loadExtension(vecPath);
+        testDb.close();
+        _sqliteVecLoad = (db) => db.loadExtension(vecPath);
+    }
+    catch {
+        // Vector search won't work, but BM25 and other operations are unaffected.
+        _sqliteVecLoad = null;
+    }
+}
+else {
+    _Database = (await import("better-sqlite3")).default;
+    const sqliteVec = await import("sqlite-vec");
+    _sqliteVecLoad = (db) => sqliteVec.load(db);
+}
+function isBusyError(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const code = err.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_BUSY_SNAPSHOT")
+        return true;
+    const message = err.message;
+    return typeof message === "string" && /database is locked|database is busy|SQLITE_BUSY/i.test(message);
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Switch a connection to WAL, retrying on `SQLITE_BUSY` within the busy-timeout
+ * budget. Unlike ordinary writes, migrating the journal needs a brief exclusive
+ * lock and does NOT invoke the busy handler, so concurrent first-time opens of a
+ * cold database throw "database is locked" even with `busy_timeout` set. Once the
+ * database is already WAL the pragma is a cheap no-op that does not contend.
+ */
+function enableWal(db, budgetMs) {
+    const deadline = Date.now() + Math.max(budgetMs, 0);
+    for (let attempt = 0;; attempt++) {
+        try {
+            db.exec("PRAGMA journal_mode = WAL");
+            return;
+        }
+        catch (err) {
+            if (!isBusyError(err) || Date.now() >= deadline)
+                throw err;
+            sleepSync(Math.min(5 + attempt, 25));
+        }
+    }
+}
+/**
+ * Open a SQLite database. Works with both bun:sqlite and better-sqlite3.
+ *
+ * `bun:sqlite` and `better-sqlite3` both default `busy_timeout` to 0, so
+ * concurrent writers throw `SQLITE_BUSY` instead of waiting. WAL improves
+ * read-while-write concurrency but does not serialise writers. Setting the
+ * timeout at connection open makes parallel processes (e.g. an `update` or
+ * `query` racing a long `embed`, or a first-open schema migration racing any
+ * routine command) queue at batch boundaries instead of failing on contact.
+ *
+ * WAL is enabled here too (with a bounded retry) so connection-level pragmas
+ * live in one place and the cold-database journal migration survives concurrent
+ * opens.
+ *
+ * Default 120_000 ms outlasts the worst-case batch commit on a multi-GB
+ * index. Override with `QMD_SQLITE_BUSY_TIMEOUT` (value in milliseconds; `0`
+ * restores the upstream fail-fast behaviour). See
+ * https://bun.sh/docs/api/sqlite#busy-timeout.
+ */
+export function openDatabase(path) {
+    const db = new _Database(path);
+    const raw = process.env.QMD_SQLITE_BUSY_TIMEOUT;
+    const parsed = raw !== undefined && raw !== "" ? Number(raw) : Number.NaN;
+    const busyTimeoutMs = Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 120_000;
+    db.exec(`PRAGMA busy_timeout = ${busyTimeoutMs}`);
+    enableWal(db, busyTimeoutMs);
+    return db;
+}
+/**
+ * Load the sqlite-vec extension into a database.
+ *
+ * Throws with platform-specific fix instructions when the extension is
+ * unavailable.
+ */
+export function loadSqliteVec(db) {
+    if (!_sqliteVecLoad) {
+        const hint = isBun && process.platform === "darwin"
+            ? "On macOS with Bun, install Homebrew SQLite: brew install sqlite\n" +
+                "Or install qmd with npm instead: npm install -g ko-qmd"
+            : "Ensure the sqlite-vec native module is installed correctly.";
+        throw new Error(`sqlite-vec extension is unavailable. ${hint}`);
+    }
+    _sqliteVecLoad(db);
+}

package/dist/hangul.d.ts

@@ -0,0 +1,54 @@
+/**
+ * hangul.ts - Korean (Hangul) handling for FTS5 indexing and queries.
+ *
+ * ko-qmd patch stack: all Hangul-specific logic lives here so store.ts keeps
+ * at most two call sites. Han and kana text never reaches these functions.
+ */
+/**
+ * Syllable bigrams of every Hangul run in `text`, space-joined in run order
+ * (`검색을 개선` → `검색 색을 개선`). Appended after the character-spaced field
+ * text at index time: the character tokens keep their original adjacency, so
+ * existing phrase queries match exactly as before, and bigram phrases from
+ * one run stay contiguous.
+ */
+export declare function hangulBigramTail(text: string): string;
+/**
+ * Strip one trailing particle (or 기) from a pure-Hangul word when the stem
+ * keeps at least two syllables (`검색을` → `검색`, `책을` stays). Returns null
+ * when nothing is stripped.
+ */
+export declare function stripHangulParticle(word: string): string | null;
+/**
+ * Strip one trailing verbal/nominalizing ending (`토큰화하는` → `토큰화`,
+ * `검색하기` → `검색`). Returns null when nothing is stripped. Endings are tried
+ * before particles so `하기` wins over the bare `기` that would leave `검색하`.
+ */
+export declare function stripHangulEnding(word: string): string | null;
+/**
+ * Stems worth querying for one Hangul word, longest first and without the word
+ * itself: an ending (`토큰화하는` → `토큰화`), then particles, twice, so a chain
+ * like `청킹에서의` reaches `청킹`. Two rounds cover the chains Korean actually
+ * stacks in queries (`에서 + 의`, `으로 + 는`) without unwinding real syllables.
+ */
+export declare function hangulStems(word: string): string[];
+/**
+ * FTS5 expression for a plain (unquoted) Hangul query term: for the word and
+ * each of its stems, a bigram phrase (from hangulBigramTail) OR the character
+ * phrase (`검색` → `("검색" OR "검 색")`). The character phrase keeps spacing
+ * variants matching (`간격반복` over `간격 반복`), which bigrams cannot span; the
+ * bigram phrase adds its BM25 weight. Returns null for single syllables and
+ * non-Hangul or mixed-script terms, so the caller keeps its default character
+ * phrase.
+ */
+export declare function hangulTermQuery(term: string): string | null;
+/**
+ * FTS5 expression for a term that glues Hangul to Latin or digits
+ * (`SKILL.md계약의핵심`, `hook이유일한hardboundary다`, `auto-dream의발화조건`).
+ * The index already splits scripts — hangulBigramTail only sees Hangul runs and the
+ * porter tokenizer splits the rest — so the query has to split too, or the glued term
+ * is searched as one phrase that appears nowhere. Each Hangul run goes through
+ * hangulTermQuery, each Latin/digit run becomes a prefix term, and the runs are ANDed.
+ * Separators (`.`, `-`, `/`, `+`) are dropped with the rest of the non-alphanumerics.
+ * Returns null when the term is not mixed script, so callers keep their own handling.
+ */
+export declare function hangulMixedQuery(term: string): string | null;

package/dist/hangul.js

@@ -0,0 +1,140 @@
+/**
+ * hangul.ts - Korean (Hangul) handling for FTS5 indexing and queries.
+ *
+ * ko-qmd patch stack: all Hangul-specific logic lives here so store.ts keeps
+ * at most two call sites. Han and kana text never reaches these functions.
+ */
+const HANGUL_WORD_PATTERN = /^\p{Script=Hangul}+$/u;
+const HANGUL_RUN_PATTERN = /\p{Script=Hangul}+/gu;
+// Particles (design §4) plus the nominalizing ending 기 (`나누기` → `나누`).
+// Longest first, so 에서 wins over 에 and 으로 over 로.
+const SUFFIXES = [
+    "에게", "에서", "으로", "까지", "부터", "처럼",
+    "은", "는", "이", "가", "을", "를", "에", "로", "의", "도", "와", "과", "기",
+];
+// Verbal and nominalizing endings on 하다/되다 stems (`토큰화하는` → `토큰화`).
+// Longest first, and always tried before SUFFIXES so `하기` wins over bare `기`.
+const ENDINGS = [
+    "하려는", "되려는", "하면서", "되면서",
+    "하는", "하기", "한다", "했다", "하며", "하고", "하여", "해서", "하지", "하다",
+    "되는", "되기", "된다", "됐다", "되며", "되고", "되어", "돼서", "되다",
+    "한", "된",
+];
+const MIN_STEM_SYLLABLES = 2;
+function syllableBigrams(word) {
+    const syllables = Array.from(word);
+    return syllables.slice(1).map((s, i) => syllables[i] + s);
+}
+/**
+ * Syllable bigrams of every Hangul run in `text`, space-joined in run order
+ * (`검색을 개선` → `검색 색을 개선`). Appended after the character-spaced field
+ * text at index time: the character tokens keep their original adjacency, so
+ * existing phrase queries match exactly as before, and bigram phrases from
+ * one run stay contiguous.
+ */
+export function hangulBigramTail(text) {
+    const runs = text.match(HANGUL_RUN_PATTERN) ?? [];
+    return runs.flatMap(syllableBigrams).join(" ");
+}
+/**
+ * Strip one trailing particle (or 기) from a pure-Hangul word when the stem
+ * keeps at least two syllables (`검색을` → `검색`, `책을` stays). Returns null
+ * when nothing is stripped.
+ */
+export function stripHangulParticle(word) {
+    return stripOnce(word, SUFFIXES);
+}
+/**
+ * Strip one trailing verbal/nominalizing ending (`토큰화하는` → `토큰화`,
+ * `검색하기` → `검색`). Returns null when nothing is stripped. Endings are tried
+ * before particles so `하기` wins over the bare `기` that would leave `검색하`.
+ */
+export function stripHangulEnding(word) {
+    return stripOnce(word, ENDINGS);
+}
+function stripOnce(word, suffixes) {
+    if (!HANGUL_WORD_PATTERN.test(word))
+        return null;
+    const syllables = Array.from(word);
+    for (const suffix of suffixes) {
+        const stemLength = syllables.length - Array.from(suffix).length;
+        if (stemLength < MIN_STEM_SYLLABLES)
+            continue;
+        if (word.endsWith(suffix))
+            return syllables.slice(0, stemLength).join("");
+    }
+    return null;
+}
+/**
+ * Stems worth querying for one Hangul word, longest first and without the word
+ * itself: an ending (`토큰화하는` → `토큰화`), then particles, twice, so a chain
+ * like `청킹에서의` reaches `청킹`. Two rounds cover the chains Korean actually
+ * stacks in queries (`에서 + 의`, `으로 + 는`) without unwinding real syllables.
+ */
+export function hangulStems(word) {
+    const stems = [];
+    let current = word;
+    for (let round = 0; round < 2; round++) {
+        const next = stripHangulEnding(current) ?? stripHangulParticle(current);
+        if (next === null || next === current)
+            break;
+        stems.push(next);
+        current = next;
+    }
+    return [...stems, ...stems.flatMap(contractions)];
+}
+/**
+ * 하 ↔ 해 siblings of a stem (`더하` → `더해`). 하다 verbs contract in running
+ * text (`더하여` is written `더해`), so a stem stripped back to 하 would never
+ * meet the contracted spelling the document actually uses. One syllable swap,
+ * no new stripping.
+ */
+function contractions(stem) {
+    if (stem.endsWith("하"))
+        return [`${stem.slice(0, -1)}해`];
+    if (stem.endsWith("해"))
+        return [`${stem.slice(0, -1)}하`];
+    return [];
+}
+/**
+ * FTS5 expression for a plain (unquoted) Hangul query term: for the word and
+ * each of its stems, a bigram phrase (from hangulBigramTail) OR the character
+ * phrase (`검색` → `("검색" OR "검 색")`). The character phrase keeps spacing
+ * variants matching (`간격반복` over `간격 반복`), which bigrams cannot span; the
+ * bigram phrase adds its BM25 weight. Returns null for single syllables and
+ * non-Hangul or mixed-script terms, so the caller keeps its default character
+ * phrase.
+ */
+export function hangulTermQuery(term) {
+    if (!HANGUL_WORD_PATTERN.test(term) || Array.from(term).length < 2)
+        return null;
+    const phrases = (s) => [`"${syllableBigrams(s).join(" ")}"`, `"${Array.from(s).join(" ")}"`];
+    const stems = hangulStems(term);
+    return `(${[...stems.flatMap(phrases), ...phrases(term)].join(" OR ")})`;
+}
+/**
+ * FTS5 expression for a term that glues Hangul to Latin or digits
+ * (`SKILL.md계약의핵심`, `hook이유일한hardboundary다`, `auto-dream의발화조건`).
+ * The index already splits scripts — hangulBigramTail only sees Hangul runs and the
+ * porter tokenizer splits the rest — so the query has to split too, or the glued term
+ * is searched as one phrase that appears nowhere. Each Hangul run goes through
+ * hangulTermQuery, each Latin/digit run becomes a prefix term, and the runs are ANDed.
+ * Separators (`.`, `-`, `/`, `+`) are dropped with the rest of the non-alphanumerics.
+ * Returns null when the term is not mixed script, so callers keep their own handling.
+ */
+export function hangulMixedQuery(term) {
+    // Set subtraction (v flag) keeps a non-Hangul run from swallowing the Hangul next to it —
+    // plain alternation matches `[\p{L}\p{N}]+` across the boundary once it starts on Latin.
+    const runs = term.match(/\p{Script=Hangul}+|[[\p{L}\p{N}]--[\p{Script=Hangul}]]+/gv) ?? [];
+    const hangulRuns = runs.filter((r) => HANGUL_WORD_PATTERN.test(r));
+    if (hangulRuns.length === 0 || hangulRuns.length === runs.length)
+        return null;
+    const parts = runs.flatMap((run) => {
+        if (HANGUL_WORD_PATTERN.test(run)) {
+            return [hangulTermQuery(run) ?? `"${Array.from(run).join(" ")}"`];
+        }
+        const latin = run.replace(/[^\p{L}\p{N}'_]/gu, "").toLowerCase();
+        return latin ? [`"${latin}"*`] : [];
+    });
+    return parts.length > 0 ? `(${parts.join(" AND ")})` : null;
+}

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+/**
+ * QMD SDK - Library mode for programmatic access to QMD search and indexing.
+ *
+ * Usage:
+ *   import { createStore } from '@tobilu/qmd'
+ *
+ *   const store = await createStore({
+ *     dbPath: './my-index.sqlite',
+ *     config: {
+ *       collections: {
+ *         docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *       }
+ *     }
+ *   })
+ *
+ *   const results = await store.search({ query: "how does auth work?" })
+ *   await store.close()
+ */
+import { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES, type Store as InternalStore, type DocumentResult, type DocumentNotFound, type DocumentExcludedByIgnore, type DocumentLookupError, type SearchResult, type HybridQueryResult, type HybridQueryOptions, type HybridQueryExplain, type ExpandedQuery, type StructuredSearchOptions, type MultiGetResult, type IndexStatus, type IndexHealthInfo, type SearchHooks, type ReindexProgress, type ReindexResult, type EmbedProgress, type EmbedResult, type ChunkStrategy } from "./store.js";
+import { type Collection, type CollectionConfig, type NamedCollection, type ContextMap } from "./collections.js";
+export type { DocumentResult, DocumentNotFound, DocumentExcludedByIgnore, DocumentLookupError, SearchResult, HybridQueryResult, HybridQueryOptions, HybridQueryExplain, ExpandedQuery, StructuredSearchOptions, MultiGetResult, IndexStatus, IndexHealthInfo, SearchHooks, ReindexProgress, ReindexResult, EmbedProgress, EmbedResult, Collection, CollectionConfig, NamedCollection, ContextMap, };
+export type { InternalStore };
+export { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES };
+export type { ChunkStrategy } from "./store.js";
+export { getDefaultDbPath } from "./store.js";
+export { Maintenance } from "./maintenance.js";
+/**
+ * Progress info emitted during update() for each file processed.
+ */
+export type UpdateProgress = {
+    collection: string;
+    file: string;
+    current: number;
+    total: number;
+};
+/**
+ * Aggregated result from update() across all collections.
+ */
+export type UpdateResult = {
+    collections: number;
+    indexed: number;
+    updated: number;
+    unchanged: number;
+    removed: number;
+    skipped: number;
+    needsEmbedding: number;
+};
+/**
+ * Options for the unified search() method.
+ */
+export interface SearchOptions {
+    /** Simple query string — will be auto-expanded via LLM */
+    query?: string;
+    /** Pre-expanded queries (from expandQuery) — skips auto-expansion */
+    queries?: ExpandedQuery[];
+    /** Domain intent hint — steers reranking and snippet/chunk selection */
+    intent?: string;
+    /** Rerank results using LLM (default: true) */
+    rerank?: boolean;
+    /** Filter to a specific collection */
+    collection?: string;
+    /** Filter to specific collections */
+    collections?: string[];
+    /** Max results (default: 10) */
+    limit?: number;
+    /** Max candidates to rerank (default: 40) */
+    candidateLimit?: number;
+    /** Minimum score threshold */
+    minScore?: number;
+    /** Include explain traces */
+    explain?: boolean;
+    /** Chunk strategy: "auto" (default, uses AST for code files) or "regex" (legacy) */
+    chunkStrategy?: ChunkStrategy;
+}
+/**
+ * Options for searchLex() — BM25 keyword search.
+ */
+export interface LexSearchOptions {
+    limit?: number;
+    collection?: string | string[];
+}
+/**
+ * Options for searchVector() — vector similarity search.
+ */
+export interface VectorSearchOptions {
+    limit?: number;
+    collection?: string | string[];
+}
+/**
+ * Options for expandQuery() — manual query expansion.
+ */
+export interface ExpandQueryOptions {
+    /**
+     * @deprecated Ignored. Intent no longer feeds the expansion model — caller
+     * intent is meta-language the model reproduced verbatim as sub-queries.
+     * Pass intent via SearchOptions instead, where it shapes reranking and
+     * snippet selection.
+     */
+    intent?: string;
+}
+/**
+ * Options for creating a QMD store.
+ *
+ * Provide `dbPath` and optionally `configPath` (YAML file) or `config` (inline).
+ * If neither configPath nor config is provided, the store reads from existing
+ * DB state (useful for reopening a previously-configured store).
+ */
+export interface StoreOptions {
+    /** Path to the SQLite database file */
+    dbPath: string;
+    /** Path to a YAML config file (mutually exclusive with `config`) */
+    configPath?: string;
+    /** Inline collection config (mutually exclusive with `configPath`) */
+    config?: CollectionConfig;
+}
+/**
+ * The QMD SDK store — provides search, retrieval, collection management,
+ * context management, and indexing operations.
+ *
+ * All methods are async. The store manages its own LlamaCpp instance
+ * (lazy-loaded, auto-unloaded after inactivity) — no global singletons.
+ */
+export interface QMDStore {
+    /** The underlying internal store (for advanced use) */
+    readonly internal: InternalStore;
+    /** Path to the SQLite database */
+    readonly dbPath: string;
+    /** Full search: query expansion + multi-signal retrieval + LLM reranking */
+    search(options: SearchOptions): Promise<HybridQueryResult[]>;
+    /** BM25 keyword search (fast, no LLM) */
+    searchLex(query: string, options?: LexSearchOptions): Promise<SearchResult[]>;
+    /** Vector similarity search (embedding model, no reranking) */
+    searchVector(query: string, options?: VectorSearchOptions): Promise<SearchResult[]>;
+    /** Expand a query into typed sub-searches (lex/vec/hyde) for manual control */
+    expandQuery(query: string, options?: ExpandQueryOptions): Promise<ExpandedQuery[]>;
+    /** Get a single document by path or docid */
+    get(pathOrDocid: string, options?: {
+        includeBody?: boolean;
+    }): Promise<DocumentResult | DocumentLookupError>;
+    /** Get the body content of a document, optionally sliced by line range */
+    getDocumentBody(pathOrDocid: string, opts?: {
+        fromLine?: number;
+        maxLines?: number;
+    }): Promise<string | null>;
+    /** Get multiple documents by glob pattern or comma-separated list */
+    multiGet(pattern: string, options?: {
+        includeBody?: boolean;
+        maxBytes?: number;
+    }): Promise<{
+        docs: MultiGetResult[];
+        errors: string[];
+    }>;
+    /** Add or update a collection */
+    addCollection(name: string, opts: {
+        path: string;
+        pattern?: string;
+        ignore?: string[];
+    }): Promise<void>;
+    /** Remove a collection */
+    removeCollection(name: string): Promise<boolean>;
+    /** Rename a collection */
+    renameCollection(oldName: string, newName: string): Promise<boolean>;
+    /** List all collections with document stats */
+    listCollections(): Promise<{
+        name: string;
+        pwd: string;
+        glob_pattern: string;
+        doc_count: number;
+        active_count: number;
+        last_modified: string | null;
+        includeByDefault: boolean;
+    }[]>;
+    /** Get names of collections included by default in queries */
+    getDefaultCollectionNames(): Promise<string[]>;
+    /** Add context for a path within a collection */
+    addContext(collectionName: string, pathPrefix: string, contextText: string): Promise<boolean>;
+    /** Remove context from a collection path */
+    removeContext(collectionName: string, pathPrefix: string): Promise<boolean>;
+    /** Set global context (applies to all collections) */
+    setGlobalContext(context: string | undefined): Promise<void>;
+    /** Get global context */
+    getGlobalContext(): Promise<string | undefined>;
+    /** List all contexts across all collections */
+    listContexts(): Promise<Array<{
+        collection: string;
+        path: string;
+        context: string;
+    }>>;
+    /** Re-index collections by scanning the filesystem */
+    update(options?: {
+        collections?: string[];
+        onProgress?: (info: UpdateProgress) => void;
+    }): Promise<UpdateResult>;
+    /** Generate vector embeddings for documents that need them */
+    embed(options?: {
+        force?: boolean;
+        model?: string;
+        /** Restrict embedding to documents in one collection. */
+        collection?: string;
+        maxDocsPerBatch?: number;
+        maxBatchBytes?: number;
+        chunkStrategy?: ChunkStrategy;
+        onProgress?: (info: EmbedProgress) => void;
+    }): Promise<EmbedResult>;
+    /** Get index status (document counts, collections, embedding state) */
+    getStatus(): Promise<IndexStatus>;
+    /** Get index health info (stale embeddings, etc.) */
+    getIndexHealth(): Promise<IndexHealthInfo>;
+    /** Close the store and release all resources (LLM models, DB connection) */
+    close(): Promise<void>;
+}
+/**
+ * Create a QMD store for programmatic access to search and indexing.
+ *
+ * @example
+ * ```typescript
+ * // With a YAML config file
+ * const store = await createStore({
+ *   dbPath: './index.sqlite',
+ *   configPath: './qmd.yml',
+ * })
+ *
+ * // With inline config (no files needed besides the DB)
+ * const store = await createStore({
+ *   dbPath: './index.sqlite',
+ *   config: {
+ *     collections: {
+ *       docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *     }
+ *   }
+ * })
+ *
+ * const results = await store.search({ query: "authentication flow" })
+ * await store.close()
+ * ```
+ */
+export declare function createStore(options: StoreOptions): Promise<QMDStore>;