ko-qmd 2.8.3-ko.10

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+/**
+ * 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 { DocumentFilter } from "./filters.js";
+import type { DocumentMetadata, MetadataScalar, MetadataScalarArray, MetadataValue } from "./metadata.js";
+import { parseMetadataFilter, MetadataFilterError, type MetadataFilter, type MetadataFilterGroup, type MetadataFilterNegation, type MetadataCondition } from "./metadata-filter.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 { DocumentMetadata, MetadataScalar, MetadataScalarArray, MetadataValue, MetadataFilter, MetadataFilterGroup, MetadataFilterNegation, MetadataCondition, };
+export { parseMetadataFilter, MetadataFilterError };
+export type { InternalStore };
+export type { StoreRerankOptions } from "./store.js";
+export { extractSnippet, addLineNumbers, DEFAULT_MULTI_GET_MAX_BYTES };
+export type { ChunkStrategy } from "./store.js";
+export type { DocumentFilter } from "./filters.js";
+export { buildDocumentFilter, describeFilter, parseTimeSpec } from "./filters.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 — auto-expanded via LLM, unless it contains Hangul */
+    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[];
+    /** Metadata filter — every returned result satisfies it */
+    filter?: MetadataFilter;
+    /** Max results (default: 10) */
+    limit?: number;
+    /** Max candidates to rerank (default: 40) */
+    candidateLimit?: number;
+    /** Per-request rerank doc token cap; overrides QMD_RERANK_MAX_DOC_TOKENS */
+    rerankMaxDocTokens?: 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;
+    /**
+     * Narrow the corpus before anything is ranked: path globs against
+     * `collection/path`, and a `modified_at` range. Build one with
+     * `buildDocumentFilter` so `--since 7d` and a bad span both behave.
+     * ANDed with `filter`.
+     */
+    scope?: DocumentFilter;
+    /** Past this many ms, answer in RRF order instead of waiting for the reranker (unset or 0 = wait) */
+    rerankDeadlineMs?: number;
+    /** Past this many ms, search the original query only instead of waiting for expansion (unset or 0 = wait) */
+    expandDeadlineMs?: number;
+    /** Progress callbacks for expansion, embedding and reranking */
+    hooks?: SearchHooks;
+}
+/**
+ * Options for searchLex() — BM25 keyword search.
+ */
+export interface LexSearchOptions {
+    limit?: number;
+    collection?: string | string[];
+    /** Metadata filter — every returned result satisfies it */
+    filter?: MetadataFilter;
+    /** Narrow the corpus by path glob and `modified_at` before ranking (see `buildDocumentFilter`) */
+    scope?: DocumentFilter;
+}
+/**
+ * Options for searchVector() — vector similarity search.
+ */
+export interface VectorSearchOptions {
+    limit?: number;
+    collection?: string | string[];
+    /** Metadata filter — every returned result satisfies it */
+    filter?: MetadataFilter;
+    /** Narrow the corpus by path glob and `modified_at` before ranking (see `buildDocumentFilter`) */
+    scope?: DocumentFilter;
+}
+/**
+ * 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>;

package/dist/index.js

@@ -0,0 +1 @@
+var M=Object.defineProperty;var t=(i,r)=>M(i,"name",{value:r,configurable:!0});import{createStore as P,hybridQuery as w,structuredSearch as v,extractSnippet as L,addLineNumbers as B,DEFAULT_MULTI_GET_MAX_BYTES as E,reindexCollection as T,generateEmbeddings as q,listCollections as D,syncConfigToDb as b,getStoreCollections as G,getStoreGlobalContext as F,getStoreContexts as I,upsertStoreCollection as R,deleteStoreCollection as U,renameStoreCollection as A,updateStoreContext as _,removeStoreContext as H,setStoreGlobalContext as Q}from"./store.js";import{LlamaCpp as V}from"./llm.js";import{parseMetadataFilter as g,MetadataFilterError as Y}from"./metadata-filter.js";import{setConfigSource as h,loadConfig as j,addCollection as X,removeCollection as $,renameCollection as z,addContext as J,removeContext as K,setGlobalContext as N}from"./collections.js";import{buildDocumentFilter as ie,describeFilter as ce,parseTimeSpec as ae}from"./filters.js";import{getDefaultDbPath as de}from"./store.js";import{Maintenance as fe}from"./maintenance.js";async function te(i){if(!i.dbPath)throw new Error("dbPath is required");if(i.configPath&&i.config)throw new Error("Provide either configPath or config, not both");const r=P(i.dbPath),c=r.db,d=!!i.configPath;let s;i.configPath?(h({configPath:i.configPath}),s=j(),b(c,s)):i.config&&(h({config:i.config}),s=i.config,b(c,s));const m=new V({embedModel:s?.models?.embed,generateModel:s?.models?.generate,rerankModel:s?.models?.rerank,inactivityTimeoutMs:300*1e3,disposeModelsOnInactivity:!0});return r.llm=m,{internal:r,dbPath:r.dbPath,search:t(async e=>{if(!e.query&&!e.queries)throw new Error("search() requires either 'query' or 'queries'");const n=[...e.collection?[e.collection]:[],...e.collections??[]],o=e.rerank===!1,f=e.filter===void 0?void 0:g(e.filter);return e.queries?v(r,e.queries,{collections:n.length>0?n:void 0,filter:f,limit:e.limit,minScore:e.minScore,explain:e.explain,intent:e.intent,candidateLimit:e.candidateLimit,rerankMaxDocTokens:e.rerankMaxDocTokens,skipRerank:o,chunkStrategy:e.chunkStrategy,scope:e.scope,rerankDeadlineMs:e.rerankDeadlineMs,hooks:e.hooks}):w(r,e.query,{collection:n.length>0?n:void 0,filter:f,limit:e.limit,minScore:e.minScore,explain:e.explain,intent:e.intent,candidateLimit:e.candidateLimit,rerankMaxDocTokens:e.rerankMaxDocTokens,skipRerank:o,chunkStrategy:e.chunkStrategy,scope:e.scope,rerankDeadlineMs:e.rerankDeadlineMs,expandDeadlineMs:e.expandDeadlineMs,hooks:e.hooks})},"search"),searchLex:t(async(e,n)=>{const o=n?.filter===void 0?void 0:g(n.filter);return r.searchFTS(e,n?.limit,n?.collection,o,n?.scope)},"searchLex"),searchVector:t(async(e,n)=>{const o=n?.filter===void 0?void 0:g(n.filter);return r.searchVec(e,m.embedModelName,n?.limit,n?.collection,void 0,void 0,o,n?.scope)},"searchVector"),expandQuery:t(async e=>r.expandQuery(e),"expandQuery"),get:t(async(e,n)=>r.findDocument(e,n),"get"),getDocumentBody:t(async(e,n)=>{const o=r.findDocument(e,{includeBody:!1});return"error"in o?null:r.getDocumentBody(o,n?.fromLine,n?.maxLines)},"getDocumentBody"),multiGet:t(async(e,n)=>r.findDocuments(e,n),"multiGet"),addCollection:t(async(e,n)=>{R(c,e,{path:n.path,pattern:n.pattern,ignore:n.ignore}),(d||i.config)&&X(e,n.path,n.pattern,{ignore:n.ignore})},"addCollection"),removeCollection:t(async e=>{const n=U(c,e);return(d||i.config)&&$(e),n},"removeCollection"),renameCollection:t(async(e,n)=>{const o=A(c,e,n);return(d||i.config)&&z(e,n),o},"renameCollection"),listCollections:t(async()=>D(c),"listCollections"),getDefaultCollectionNames:t(async()=>D(c).filter(n=>n.includeByDefault).map(n=>n.name),"getDefaultCollectionNames"),addContext:t(async(e,n,o)=>{const f=_(c,e,n,o);return(d||i.config)&&J(e,n,o),f},"addContext"),removeContext:t(async(e,n)=>{const o=H(c,e,n);return(d||i.config)&&K(e,n),o},"removeContext"),setGlobalContext:t(async e=>{Q(c,e),(d||i.config)&&N(e)},"setGlobalContext"),getGlobalContext:t(async()=>F(c),"getGlobalContext"),listContexts:t(async()=>I(c),"listContexts"),update:t(async e=>{const n=G(c),o=e?.collections;if(o){const a=new Set(n.map(u=>u.name)),l=o.filter(u=>!a.has(u));if(l.length>0)throw new Error(`Unknown collection(s): ${l.join(", ")}`)}const f=o?n.filter(a=>o.includes(a.name)):n;r.clearCache();let y=0,x=0,C=0,k=0,S=0;for(const a of f){const l=await T(r,a.path,a.pattern||"**/*.md",a.name,{ignorePatterns:a.ignore,onProgress:e?.onProgress?u=>e.onProgress({collection:a.name,...u}):void 0});y+=l.indexed,x+=l.updated,C+=l.unchanged,k+=l.removed,S+=l.skipped}return{collections:f.length,indexed:y,updated:x,unchanged:C,removed:k,skipped:S,needsEmbedding:r.getHashesNeedingEmbedding()}},"update"),embed:t(async e=>q(r,{force:e?.force,model:e?.model,collection:e?.collection,maxDocsPerBatch:e?.maxDocsPerBatch,maxBatchBytes:e?.maxBatchBytes,chunkStrategy:e?.chunkStrategy,onProgress:e?.onProgress}),"embed"),getStatus:t(async()=>r.getStatus(),"getStatus"),getIndexHealth:t(async()=>r.getIndexHealth(),"getIndexHealth"),close:t(async()=>{await m.dispose(),r.close(),(d||i.config)&&h(void 0)},"close")}}t(te,"createStore");export{E as DEFAULT_MULTI_GET_MAX_BYTES,fe as Maintenance,Y as MetadataFilterError,B as addLineNumbers,ie as buildDocumentFilter,te as createStore,ce as describeFilter,L as extractSnippet,de as getDefaultDbPath,g as parseMetadataFilter,ae as parseTimeSpec};