@tobilu/qmd 2.1.0 → 2.5.1

package/dist/collections.d.ts

@@ -60,6 +60,15 @@ export declare function setConfigSource(source?: {
  * Config file will be ~/.config/qmd/{indexName}.yml
  */
 export declare function setConfigIndexName(name: string): void;
+/**
+ * Find a project-local QMD config by walking upward from startDir.
+ * The local config lives at .qmd/index.yaml or .qmd/index.yml and,
+ * when used by the CLI, keeps both config and index DB writes inside
+ * the project instead of the global ~/.config / ~/.cache locations.
+ */
+export declare function findLocalConfigPath(startDir?: string): string | undefined;
+/** Return the local SQLite index path paired with a local .qmd/index.yaml file. */
+export declare function getLocalDbPath(configPath: string): string;
 /**
  * Load configuration from the configured source.
  * - Inline config: returns the in-memory object directly

package/dist/collections.js

@@ -5,8 +5,8 @@
  * Collections define which directories to index and their associated contexts.
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { join, dirname } from "path";
-import { homedir } from "os";
+import { join, dirname, resolve } from "path";
+import { qmdHomedir } from "./paths.js";
 import YAML from "yaml";
 // ============================================================================
 // Configuration paths
@@ -47,9 +47,7 @@ export function setConfigSource(source) {
 export function setConfigIndexName(name) {
     // Resolve relative paths to absolute paths and sanitize for use as filename
     if (name.includes('/')) {
-        const { resolve } = require('path');
-        const { cwd } = require('process');
-        const absolutePath = resolve(cwd(), name);
+        const absolutePath = resolve(process.cwd(), name);
         // Replace path separators with underscores to create a valid filename
         currentIndexName = absolutePath.replace(/\//g, '_').replace(/^_/, '');
     }
@@ -66,11 +64,37 @@ function getConfigDir() {
     if (process.env.XDG_CONFIG_HOME) {
         return join(process.env.XDG_CONFIG_HOME, "qmd");
     }
-    return join(homedir(), ".config", "qmd");
+    return join(qmdHomedir(), ".config", "qmd");
 }
 function getConfigFilePath() {
     return join(getConfigDir(), `${currentIndexName}.yml`);
 }
+/**
+ * Find a project-local QMD config by walking upward from startDir.
+ * The local config lives at .qmd/index.yaml or .qmd/index.yml and,
+ * when used by the CLI, keeps both config and index DB writes inside
+ * the project instead of the global ~/.config / ~/.cache locations.
+ */
+export function findLocalConfigPath(startDir = process.cwd()) {
+    let dir = resolve(startDir);
+    while (true) {
+        const qmdDir = join(dir, ".qmd");
+        const yamlPath = join(qmdDir, "index.yaml");
+        if (existsSync(yamlPath))
+            return yamlPath;
+        const ymlPath = join(qmdDir, "index.yml");
+        if (existsSync(ymlPath))
+            return ymlPath;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Return the local SQLite index path paired with a local .qmd/index.yaml file. */
+export function getLocalDbPath(configPath) {
+    return join(dirname(configPath), "index.sqlite");
+}
 /**
  * Ensure config directory exists
  */
@@ -101,7 +125,8 @@ export function loadConfig() {
     }
     try {
         const content = readFileSync(configPath, "utf-8");
-        const config = YAML.parse(content);
+        const parsed = YAML.parse(content);
+        const config = parsed ?? { collections: {} };
         // Ensure collections object exists
         if (!config.collections) {
             config.collections = {};

package/dist/db.d.ts

@@ -11,6 +11,8 @@
  * 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.
  */
@@ -22,15 +24,16 @@ export interface Database {
     exec(sql: string): void;
     prepare(sql: string): Statement;
     loadExtension(path: string): void;
+    transaction<T extends (...args: SQLiteValue[]) => unknown>(fn: T): T;
     close(): void;
 }
 export interface Statement {
-    run(...params: any[]): {
+    run(...params: SQLiteValue[]): {
         changes: number;
         lastInsertRowid: number | bigint;
     };
-    get(...params: any[]): any;
-    all(...params: any[]): any[];
+    get<T = unknown>(...params: SQLiteValue[]): T | undefined;
+    all<T = unknown>(...params: SQLiteValue[]): T[];
 }
 /**
  * Load the sqlite-vec extension into a database.

package/dist/db.js

@@ -10,7 +10,7 @@
  * Bun we call Database.setCustomSQLite() to swap in Homebrew's full-featured
  * SQLite build before creating any database instances.
  */
-export const isBun = typeof globalThis.Bun !== "undefined";
+export const isBun = "Bun" in globalThis;
 let _Database;
 let _sqliteVecLoad;
 if (isBun) {

package/dist/index.d.ts

@@ -62,6 +62,8 @@ export interface SearchOptions {
     collections?: string[];
     /** Max results (default: 10) */
     limit?: number;
+    /** Max candidates to rerank (default: 40) */
+    candidateLimit?: number;
     /** Minimum score threshold */
     minScore?: number;
     /** Include explain traces */
@@ -186,6 +188,8 @@ export interface QMDStore {
     embed(options?: {
         force?: boolean;
         model?: string;
+        /** Restrict embedding to documents in one collection. */
+        collection?: string;
         maxDocsPerBatch?: number;
         maxBatchBytes?: number;
         chunkStrategy?: ChunkStrategy;

package/dist/index.js

@@ -16,7 +16,7 @@
  *   const results = await store.search({ query: "how does auth work?" })
  *   await store.close()
  */
-import { createStore as createStoreInternal, hybridQuery, structuredSearch, extractSnippet, addLineNumbers, DEFAULT_EMBED_MODEL, DEFAULT_MULTI_GET_MAX_BYTES, reindexCollection, generateEmbeddings, listCollections as storeListCollections, syncConfigToDb, getStoreCollections, getStoreCollection, getStoreGlobalContext, getStoreContexts, upsertStoreCollection, deleteStoreCollection, renameStoreCollection, updateStoreContext, removeStoreContext, setStoreGlobalContext, vacuumDatabase, cleanupOrphanedContent, cleanupOrphanedVectors, deleteLLMCache, deleteInactiveDocuments, clearAllEmbeddings, } from "./store.js";
+import { createStore as createStoreInternal, hybridQuery, structuredSearch, extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES, reindexCollection, generateEmbeddings, listCollections as storeListCollections, syncConfigToDb, getStoreCollections, getStoreCollection, getStoreGlobalContext, getStoreContexts, upsertStoreCollection, deleteStoreCollection, renameStoreCollection, updateStoreContext, removeStoreContext, setStoreGlobalContext, vacuumDatabase, cleanupOrphanedContent, cleanupOrphanedVectors, deleteLLMCache, deleteInactiveDocuments, clearAllEmbeddings, } from "./store.js";
 import { LlamaCpp, } from "./llm.js";
 import { setConfigSource, loadConfig, addCollection as collectionsAddCollection, removeCollection as collectionsRemoveCollection, renameCollection as collectionsRenameCollection, addContext as collectionsAddContext, removeContext as collectionsRemoveContext, setGlobalContext as collectionsSetGlobalContext, } from "./collections.js";
 // Re-export utility functions and types used by frontends
@@ -109,6 +109,7 @@ export async function createStore(options) {
                     minScore: opts.minScore,
                     explain: opts.explain,
                     intent: opts.intent,
+                    candidateLimit: opts.candidateLimit,
                     skipRerank,
                     chunkStrategy: opts.chunkStrategy,
                 });
@@ -120,12 +121,13 @@ export async function createStore(options) {
                 minScore: opts.minScore,
                 explain: opts.explain,
                 intent: opts.intent,
+                candidateLimit: opts.candidateLimit,
                 skipRerank,
                 chunkStrategy: opts.chunkStrategy,
             });
         },
         searchLex: async (q, opts) => internal.searchFTS(q, opts?.limit, opts?.collection),
-        searchVector: async (q, opts) => internal.searchVec(q, DEFAULT_EMBED_MODEL, opts?.limit, opts?.collection),
+        searchVector: async (q, opts) => internal.searchVec(q, llm.embedModelName, opts?.limit, opts?.collection),
         expandQuery: async (q, opts) => internal.expandQuery(q, undefined, opts?.intent),
         get: async (pathOrDocid, opts) => internal.findDocument(pathOrDocid, opts),
         getDocumentBody: async (pathOrDocid, opts) => {
@@ -217,6 +219,7 @@ export async function createStore(options) {
             return generateEmbeddings(internal, {
                 force: embedOpts?.force,
                 model: embedOpts?.model,
+                collection: embedOpts?.collection,
                 maxDocsPerBatch: embedOpts?.maxDocsPerBatch,
                 maxBatchBytes: embedOpts?.maxBatchBytes,
                 chunkStrategy: embedOpts?.chunkStrategy,

package/dist/llm.d.ts

@@ -3,7 +3,27 @@
  *
  * Provides embeddings, text generation, and reranking using local GGUF models.
  */
-import { type Token as LlamaToken } from "node-llama-cpp";
+import type { Llama, Token as LlamaToken } from "node-llama-cpp";
+type NodeLlamaCppModule = {
+    getLlama: (options: Record<string, unknown>) => Promise<Llama>;
+    getLlamaGpuTypes?: (include?: "supported" | "allValid") => Promise<LlamaGpuMode[]>;
+    resolveModelFile: (model: string, cacheDir: string) => Promise<string>;
+    LlamaChatSession: new (options: {
+        contextSequence: unknown;
+    }) => {
+        prompt: (prompt: string, options?: Record<string, unknown>) => Promise<string>;
+    };
+    LlamaLogLevel: {
+        error: unknown;
+    };
+};
+export declare function setNodeLlamaCppModuleForTest(module: NodeLlamaCppModule | null): void;
+/**
+ * Some node-llama-cpp native build/probe paths write library noise to stdout.
+ * JSON APIs must reserve stdout for machine-readable payloads, so route that
+ * noise to stderr while native llama initialization is in progress.
+ */
+export declare function withNativeStdoutRedirectedToStderr<T>(fn: () => Promise<T>): Promise<T>;
 /**
  * Detect if a model URI uses the Qwen3-Embedding format.
  * Qwen3-Embedding uses a different prompting style than nomic/embeddinggemma.
@@ -140,6 +160,15 @@ export declare const LFM2_INSTRUCT_MODEL = "hf:LiquidAI/LFM2.5-1.2B-Instruct-GGU
 export declare const DEFAULT_EMBED_MODEL_URI = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
 export declare const DEFAULT_RERANK_MODEL_URI = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf";
 export declare const DEFAULT_GENERATE_MODEL_URI = "hf:tobil/qmd-query-expansion-1.7B-gguf/qmd-query-expansion-1.7B-q4_k_m.gguf";
+export type ModelResolutionConfig = {
+    embed?: string;
+    generate?: string;
+    rerank?: string;
+};
+export declare function resolveEmbedModel(config?: ModelResolutionConfig): string;
+export declare function resolveGenerateModel(config?: ModelResolutionConfig): string;
+export declare function resolveRerankModel(config?: ModelResolutionConfig): string;
+export declare function resolveModels(config?: ModelResolutionConfig): Required<ModelResolutionConfig>;
 export declare const DEFAULT_MODEL_CACHE_DIR: string;
 export type PullResult = {
     model: string;
@@ -147,6 +176,19 @@ export type PullResult = {
     sizeBytes: number;
     refreshed: boolean;
 };
+export type GgufFileInspection = {
+    exists: boolean;
+    valid: boolean;
+    kind: "missing" | "gguf" | "html" | "invalid";
+    sizeBytes?: number;
+    magic?: string;
+    details: string;
+};
+/**
+ * Inspect a potential GGUF model file without mutating it.
+ * Used by doctor for early diagnostics and by runtime validation before load.
+ */
+export declare function inspectGgufFile(filePath: string): GgufFileInspection;
 export declare function pullModels(models: string[], options?: {
     refresh?: boolean;
     cacheDir?: string;
@@ -211,6 +253,16 @@ export type LlamaCppConfig = {
      */
     disposeModelsOnInactivity?: boolean;
 };
+export type LlamaGpuMode = "auto" | "metal" | "vulkan" | "cuda" | false;
+type ParallelismOptions = {
+    gpu: string | false;
+    platform?: NodeJS.Platform;
+    computed: number;
+    envValue?: string;
+};
+export declare function resolveParallelismOverride(envValue?: string | undefined): number | undefined;
+export declare function resolveSafeParallelism(options: ParallelismOptions): number;
+export declare function resolveLlamaGpuMode(envValue?: string | undefined, forceCpuValue?: string | undefined): LlamaGpuMode;
 export declare class LlamaCpp implements LLM {
     private readonly _ciMode;
     private llama;
@@ -233,6 +285,8 @@ export declare class LlamaCpp implements LLM {
     private disposed;
     constructor(config?: LlamaCppConfig);
     get embedModelName(): string;
+    get generateModelName(): string;
+    get rerankModelName(): string;
     /**
      * Reset the inactivity timer. Called after each model operation.
      * When timer fires, models are unloaded to free memory (if no active sessions).
@@ -257,8 +311,12 @@ export declare class LlamaCpp implements LLM {
      * Initialize the llama instance (lazy)
      */
     private ensureLlama;
+    private isCpuOffloadForced;
+    private modelLoadOptions;
     /**
-     * Resolve a model URI to a local path, downloading if needed
+     * Resolve a model URI to a local path, downloading if needed.
+     * Validates the downloaded file is actually a GGUF model (not an HTML error page
+     * from a proxy or firewall).
      */
     private resolveModel;
     /**
@@ -328,6 +386,7 @@ export declare class LlamaCpp implements LLM {
      * detokenizes back to text if truncation is needed.
      * Returns the (possibly truncated) text and whether truncation occurred.
      */
+    private resolveEmbedTokenLimit;
     private truncateToContextSize;
     embed(text: string, options?: EmbedOptions): Promise<EmbeddingResult | null>;
     /**
@@ -349,7 +408,9 @@ export declare class LlamaCpp implements LLM {
      * Get device/GPU info for status display.
      * Initializes llama if not already done.
      */
-    getDeviceInfo(): Promise<{
+    getDeviceInfo(options?: {
+        allowBuild?: boolean;
+    }): Promise<{
         gpu: string | false;
         gpuOffloading: boolean;
         gpuDevices: string[];
@@ -406,3 +467,4 @@ export declare function setDefaultLlamaCpp(llm: LlamaCpp | null): void;
  * Call this before process exit to prevent NAPI crashes.
  */
 export declare function disposeDefaultLlamaCpp(): Promise<void>;
+export {};