@tobilu/qmd 1.1.5 → 1.1.6

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [1.1.6] - 2026-03-09
+
+QMD can now be used as a library. `import { createStore } from '@tobilu/qmd'`
+gives you the full search and indexing API — hybrid query, BM25, structured
+search, collection/context management — without shelling out to the CLI.
+
+### Changes
+
+- **SDK / library mode**: `createStore({ dbPath, config })` returns a
+  `QMDStore` with `query()`, `search()`, `structuredSearch()`, `get()`,
+  `multiGet()`, and collection/context management methods. Supports inline
+  config (no files needed) or a YAML config path.
+- **Package exports**: `package.json` now declares `main`, `types`, and
+  `exports` so bundlers and TypeScript resolve `@tobilu/qmd` correctly.
+
 ## [1.1.5] - 2026-03-07
 
 Ambiguous queries like "performance" now produce dramatically better results

package/README.md

@@ -137,6 +137,81 @@ LLM models stay loaded in VRAM across requests. Embedding/reranking contexts are
 
 Point any MCP client at `http://localhost:8181/mcp` to connect.
 
+### SDK / Library Usage
+
+Use QMD as a library in your own Node.js or Bun applications:
+
+```sh
+npm install @tobilu/qmd
+```
+
+```typescript
+import { createStore } from '@tobilu/qmd'
+
+// Create a store with inline config (no config file needed)
+const store = createStore({
+  dbPath: './my-index.sqlite',
+  config: {
+    collections: {
+      docs: { path: '/path/to/docs', pattern: '**/*.md' },
+      notes: { path: '/path/to/notes', pattern: '**/*.md' },
+    },
+  },
+})
+
+// Or reference a YAML config file
+const store2 = createStore({
+  dbPath: './my-index.sqlite',
+  configPath: './qmd.yml',
+})
+```
+
+**Search & retrieval:**
+
+```typescript
+// Hybrid search: BM25 + vector + query expansion + LLM reranking (best quality)
+const results = await store.query("authentication flow", { limit: 5 })
+
+// Fast BM25 keyword search (no LLM, synchronous)
+const keywords = store.search("auth middleware", { limit: 10 })
+
+// Structured search with pre-expanded queries (for LLM callers)
+const structured = await store.structuredSearch([
+  { type: 'lex', query: 'authentication' },
+  { type: 'vec', query: 'how users log in' },
+], { limit: 5 })
+
+// Get a document by path or docid
+const doc = store.get("docs/readme.md")
+const byId = store.get("#abc123")
+
+// Get multiple documents by glob
+const { docs, errors } = store.multiGet("docs/**/*.md")
+```
+
+**Collection & context management:**
+
+```typescript
+// Add a collection
+store.addCollection("myapp", { path: "/src/myapp", pattern: "**/*.ts" })
+
+// Add context (improves search relevance)
+store.addContext("myapp", "/auth", "Authentication and session management")
+store.setGlobalContext("Internal engineering documentation")
+
+// List everything
+store.listCollections()
+store.listContexts()
+```
+
+**Lifecycle:**
+
+```typescript
+store.close()
+```
+
+The SDK requires explicit `dbPath` and config — no defaults are assumed. This makes it safe to embed in any application without side effects.
+
 ## Architecture
 
 ```

package/dist/collections.d.ts

@@ -34,18 +34,32 @@ export interface CollectionConfig {
 export interface NamedCollection extends Collection {
     name: string;
 }
+/**
+ * Set the config source for SDK mode.
+ * - File path: load/save from a specific YAML file
+ * - Inline config: use an in-memory CollectionConfig (saveConfig updates in place, no file I/O)
+ * - undefined: reset to default file-based config
+ */
+export declare function setConfigSource(source?: {
+    configPath?: string;
+    config?: CollectionConfig;
+}): void;
 /**
  * Set the current index name for config file lookup
  * Config file will be ~/.config/qmd/{indexName}.yml
  */
 export declare function setConfigIndexName(name: string): void;
 /**
- * Load configuration from ~/.config/qmd/index.yml
+ * Load configuration from the configured source.
+ * - Inline config: returns the in-memory object directly
+ * - File-based: reads from YAML file (default ~/.config/qmd/index.yml)
  * Returns empty config if file doesn't exist
  */
 export declare function loadConfig(): CollectionConfig;
 /**
- * Save configuration to ~/.config/qmd/index.yml
+ * Save configuration to the configured source.
+ * - Inline config: updates the in-memory object (no file I/O)
+ * - File-based: writes to YAML file (default ~/.config/qmd/index.yml)
  */
 export declare function saveConfig(config: CollectionConfig): void;
 /**

package/dist/collections.js

@@ -5,7 +5,7 @@
  * Collections define which directories to index and their associated contexts.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { join } from "path";
+import { join, dirname } from "path";
 import { homedir } from "os";
 import YAML from "yaml";
 // ============================================================================
@@ -13,6 +13,33 @@ import YAML from "yaml";
 // ============================================================================
 // Current index name (default: "index")
 let currentIndexName = "index";
+// SDK mode: optional in-memory config or custom config path
+let configSource = { type: 'file' };
+/**
+ * Set the config source for SDK mode.
+ * - File path: load/save from a specific YAML file
+ * - Inline config: use an in-memory CollectionConfig (saveConfig updates in place, no file I/O)
+ * - undefined: reset to default file-based config
+ */
+export function setConfigSource(source) {
+    if (!source) {
+        configSource = { type: 'file' };
+        return;
+    }
+    if (source.config) {
+        // Ensure collections object exists
+        if (!source.config.collections) {
+            source.config.collections = {};
+        }
+        configSource = { type: 'inline', config: source.config };
+    }
+    else if (source.configPath) {
+        configSource = { type: 'file', path: source.configPath };
+    }
+    else {
+        configSource = { type: 'file' };
+    }
+}
 /**
  * Set the current index name for config file lookup
  * Config file will be ~/.config/qmd/{indexName}.yml
@@ -57,11 +84,18 @@ function ensureConfigDir() {
 // Core functions
 // ============================================================================
 /**
- * Load configuration from ~/.config/qmd/index.yml
+ * Load configuration from the configured source.
+ * - Inline config: returns the in-memory object directly
+ * - File-based: reads from YAML file (default ~/.config/qmd/index.yml)
  * Returns empty config if file doesn't exist
  */
 export function loadConfig() {
-    const configPath = getConfigFilePath();
+    // SDK inline config mode
+    if (configSource.type === 'inline') {
+        return configSource.config;
+    }
+    // File-based config (SDK custom path or default)
+    const configPath = configSource.path || getConfigFilePath();
     if (!existsSync(configPath)) {
         return { collections: {} };
     }
@@ -79,11 +113,21 @@ export function loadConfig() {
     }
 }
 /**
- * Save configuration to ~/.config/qmd/index.yml
+ * Save configuration to the configured source.
+ * - Inline config: updates the in-memory object (no file I/O)
+ * - File-based: writes to YAML file (default ~/.config/qmd/index.yml)
  */
 export function saveConfig(config) {
-    ensureConfigDir();
-    const configPath = getConfigFilePath();
+    // SDK inline config mode: update in place, no file I/O
+    if (configSource.type === 'inline') {
+        configSource.config = config;
+        return;
+    }
+    const configPath = configSource.path || getConfigFilePath();
+    const configDir = dirname(configPath);
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
     try {
         const yaml = YAML.stringify(config, {
             indent: 2,
@@ -318,13 +362,18 @@ export function findContextForPath(collectionName, filePath) {
  * Get the config file path (useful for error messages)
  */
 export function getConfigPath() {
-    return getConfigFilePath();
+    if (configSource.type === 'inline')
+        return '<inline>';
+    return configSource.path || getConfigFilePath();
 }
 /**
  * Check if config file exists
  */
 export function configExists() {
-    return existsSync(getConfigFilePath());
+    if (configSource.type === 'inline')
+        return true;
+    const path = configSource.path || getConfigFilePath();
+    return existsSync(path);
 }
 /**
  * Validate a collection name

package/dist/index.d.ts

@@ -0,0 +1,129 @@
+/**
+ * QMD SDK - Library mode for programmatic access to QMD search and indexing.
+ *
+ * Usage:
+ *   import { createStore } from '@tobilu/qmd'
+ *
+ *   const store = createStore({
+ *     dbPath: './my-index.sqlite',
+ *     config: {
+ *       collections: {
+ *         docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *       }
+ *     }
+ *   })
+ *
+ *   const results = await store.query("how does auth work?")
+ *   store.close()
+ */
+import { type Store as InternalStore, type DocumentResult, type DocumentNotFound, type SearchResult, type HybridQueryResult, type HybridQueryOptions, type HybridQueryExplain, type StructuredSubSearch, type StructuredSearchOptions, type MultiGetResult, type IndexStatus, type IndexHealthInfo, type ExpandedQuery, type SearchHooks } from "./store.js";
+import { type Collection, type CollectionConfig, type NamedCollection, type ContextMap } from "./collections.js";
+export type { DocumentResult, DocumentNotFound, SearchResult, HybridQueryResult, HybridQueryOptions, HybridQueryExplain, StructuredSubSearch, StructuredSearchOptions, MultiGetResult, IndexStatus, IndexHealthInfo, ExpandedQuery, SearchHooks, Collection, CollectionConfig, NamedCollection, ContextMap, };
+/**
+ * Options for creating a QMD store.
+ * You must provide `dbPath` and either `configPath` (YAML file) or `config` (inline).
+ */
+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.
+ */
+export interface QMDStore {
+    /** The underlying internal store (for advanced use) */
+    readonly internal: InternalStore;
+    /** Path to the SQLite database */
+    readonly dbPath: string;
+    /** Hybrid search: BM25 + vector + query expansion + LLM reranking */
+    query(query: string, options?: HybridQueryOptions): Promise<HybridQueryResult[]>;
+    /** BM25 full-text keyword search (fast, no LLM) */
+    search(query: string, options?: {
+        limit?: number;
+        collection?: string;
+    }): SearchResult[];
+    /** Structured search with pre-expanded queries (for LLM callers) */
+    structuredSearch(searches: StructuredSubSearch[], options?: StructuredSearchOptions): Promise<HybridQueryResult[]>;
+    /** Get a single document by path or docid */
+    get(pathOrDocid: string, options?: {
+        includeBody?: boolean;
+    }): DocumentResult | DocumentNotFound;
+    /** Get multiple documents by glob pattern or comma-separated list */
+    multiGet(pattern: string, options?: {
+        includeBody?: boolean;
+        maxBytes?: number;
+    }): {
+        docs: MultiGetResult[];
+        errors: string[];
+    };
+    /** Add or update a collection */
+    addCollection(name: string, opts: {
+        path: string;
+        pattern?: string;
+        ignore?: string[];
+    }): void;
+    /** Remove a collection */
+    removeCollection(name: string): boolean;
+    /** Rename a collection */
+    renameCollection(oldName: string, newName: string): boolean;
+    /** List all collections with document stats */
+    listCollections(): {
+        name: string;
+        pwd: string;
+        glob_pattern: string;
+        doc_count: number;
+        active_count: number;
+        last_modified: string | null;
+    }[];
+    /** Add context for a path within a collection */
+    addContext(collectionName: string, pathPrefix: string, contextText: string): boolean;
+    /** Remove context from a collection path */
+    removeContext(collectionName: string, pathPrefix: string): boolean;
+    /** Set global context (applies to all collections) */
+    setGlobalContext(context: string | undefined): void;
+    /** Get global context */
+    getGlobalContext(): string | undefined;
+    /** List all contexts across all collections */
+    listContexts(): Array<{
+        collection: string;
+        path: string;
+        context: string;
+    }>;
+    /** Get index status (document counts, collections, embedding state) */
+    getStatus(): IndexStatus;
+    /** Get index health info (stale embeddings, etc.) */
+    getIndexHealth(): IndexHealthInfo;
+    /** Close the database connection */
+    close(): void;
+}
+/**
+ * Create a QMD store for programmatic access to search and indexing.
+ *
+ * @example
+ * ```typescript
+ * // With a YAML config file
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   configPath: './qmd.yml',
+ * })
+ *
+ * // With inline config (no files needed besides the DB)
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   config: {
+ *     collections: {
+ *       docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *     }
+ *   }
+ * })
+ *
+ * const results = await store.query("authentication flow")
+ * store.close()
+ * ```
+ */
+export declare function createStore(options: StoreOptions): QMDStore;

package/dist/index.js

@@ -0,0 +1,95 @@
+/**
+ * QMD SDK - Library mode for programmatic access to QMD search and indexing.
+ *
+ * Usage:
+ *   import { createStore } from '@tobilu/qmd'
+ *
+ *   const store = createStore({
+ *     dbPath: './my-index.sqlite',
+ *     config: {
+ *       collections: {
+ *         docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *       }
+ *     }
+ *   })
+ *
+ *   const results = await store.query("how does auth work?")
+ *   store.close()
+ */
+import { createStore as createStoreInternal, hybridQuery, structuredSearch, listCollections as storeListCollections, } from "./store.js";
+import { setConfigSource, loadConfig, addCollection as collectionsAddCollection, removeCollection as collectionsRemoveCollection, renameCollection as collectionsRenameCollection, listCollections as collectionsListCollections, addContext as collectionsAddContext, removeContext as collectionsRemoveContext, setGlobalContext as collectionsSetGlobalContext, getGlobalContext as collectionsGetGlobalContext, listAllContexts as collectionsListAllContexts, } from "./collections.js";
+/**
+ * Create a QMD store for programmatic access to search and indexing.
+ *
+ * @example
+ * ```typescript
+ * // With a YAML config file
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   configPath: './qmd.yml',
+ * })
+ *
+ * // With inline config (no files needed besides the DB)
+ * const store = createStore({
+ *   dbPath: './index.sqlite',
+ *   config: {
+ *     collections: {
+ *       docs: { path: '/path/to/docs', pattern: '**\/*.md' }
+ *     }
+ *   }
+ * })
+ *
+ * const results = await store.query("authentication flow")
+ * store.close()
+ * ```
+ */
+export function createStore(options) {
+    if (!options.dbPath) {
+        throw new Error("dbPath is required");
+    }
+    if (!options.configPath && !options.config) {
+        throw new Error("Either configPath or config is required");
+    }
+    if (options.configPath && options.config) {
+        throw new Error("Provide either configPath or config, not both");
+    }
+    // Inject config source into collections module
+    setConfigSource({
+        configPath: options.configPath,
+        config: options.config,
+    });
+    // Create the internal store
+    const internal = createStoreInternal(options.dbPath);
+    const store = {
+        internal,
+        dbPath: internal.dbPath,
+        // Search & Retrieval
+        query: (q, opts) => hybridQuery(internal, q, opts),
+        search: (q, opts) => internal.searchFTS(q, opts?.limit, opts?.collection),
+        structuredSearch: (searches, opts) => structuredSearch(internal, searches, opts),
+        get: (pathOrDocid, opts) => internal.findDocument(pathOrDocid, opts),
+        multiGet: (pattern, opts) => internal.findDocuments(pattern, opts),
+        // Collection Management
+        addCollection: (name, opts) => {
+            collectionsAddCollection(name, opts.path, opts.pattern);
+        },
+        removeCollection: (name) => collectionsRemoveCollection(name),
+        renameCollection: (oldName, newName) => collectionsRenameCollection(oldName, newName),
+        listCollections: () => storeListCollections(internal.db),
+        // Context Management
+        addContext: (collectionName, pathPrefix, contextText) => collectionsAddContext(collectionName, pathPrefix, contextText),
+        removeContext: (collectionName, pathPrefix) => collectionsRemoveContext(collectionName, pathPrefix),
+        setGlobalContext: (context) => collectionsSetGlobalContext(context),
+        getGlobalContext: () => collectionsGetGlobalContext(),
+        listContexts: () => collectionsListAllContexts(),
+        // Index Health
+        getStatus: () => internal.getStatus(),
+        getIndexHealth: () => internal.getIndexHealth(),
+        // Lifecycle
+        close: () => {
+            internal.close();
+            setConfigSource(undefined); // Reset config source
+        },
+    };
+    return store;
+}

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "@tobilu/qmd",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "bin": {
     "qmd": "dist/qmd.js"
   },