@tobilu/qmd 1.0.7 → 1.1.2

package/dist/store.d.ts

@@ -280,15 +280,6 @@ export type DocumentResult = {
  * Extract short docid from a full hash (first 6 characters).
  */
 export declare function getDocid(hash: string): string;
-/**
- * Handelize a filename to be more token-friendly.
- * - Convert triple underscore `___` to `/` (folder separator)
- * - Convert to lowercase
- * - Replace sequences of non-word chars (except /) with single dash
- * - Remove leading/trailing dashes from path segments
- * - Preserve folder structure (a/b/c/d.md stays structured)
- * - Preserve file extension
- */
 export declare function handelize(path: string): string;
 /**
  * Search result extends DocumentResult with score and source info
@@ -308,6 +299,38 @@ export type RankedResult = {
     body: string;
     score: number;
 };
+export type RRFContributionTrace = {
+    listIndex: number;
+    source: "fts" | "vec";
+    queryType: "original" | "lex" | "vec" | "hyde";
+    query: string;
+    rank: number;
+    weight: number;
+    backendScore: number;
+    rrfContribution: number;
+};
+export type RRFScoreTrace = {
+    contributions: RRFContributionTrace[];
+    baseScore: number;
+    topRank: number;
+    topRankBonus: number;
+    totalScore: number;
+};
+export type HybridQueryExplain = {
+    ftsScores: number[];
+    vectorScores: number[];
+    rrf: {
+        rank: number;
+        positionScore: number;
+        weight: number;
+        baseScore: number;
+        topRankBonus: number;
+        totalScore: number;
+        contributions: RRFContributionTrace[];
+    };
+    rerankScore: number;
+    blendedScore: number;
+};
 /**
  * Error result when document is not found
  */
@@ -548,6 +571,12 @@ export declare function getCollectionsWithoutContext(db: Database): {
  * Useful for suggesting where context might be needed.
  */
 export declare function getTopLevelPathsWithoutContext(db: Database, collectionName: string): string[];
+/**
+ * Validate that a vec/hyde query doesn't use lex-only syntax.
+ * Returns error message if invalid, null if valid.
+ */
+export declare function validateSemanticQuery(query: string): string | null;
+export declare function validateLexQuery(query: string): string | null;
 export declare function searchFTS(db: Database, query: string, limit?: number, collectionName?: string): SearchResult[];
 export declare function searchVec(db: Database, query: string, model: string, limit?: number, collectionName?: string, session?: ILLMSession, precomputedEmbedding?: number[]): Promise<SearchResult[]>;
 /**
@@ -578,6 +607,10 @@ export declare function rerank(query: string, documents: {
     score: number;
 }[]>;
 export declare function reciprocalRankFusion(resultLists: RankedResult[][], weights?: number[], k?: number): RankedResult[];
+/**
+ * Build per-document RRF contribution traces for explain/debug output.
+ */
+export declare function buildRrfTrace(resultLists: RankedResult[][], weights?: number[], listMeta?: RankedListMeta[], k?: number): Map<string, RRFScoreTrace>;
 /**
  * Find a document by filename/path, docid (#hash), or with fuzzy matching.
  * Returns document metadata without body by default.
@@ -630,18 +663,25 @@ export declare function addLineNumbers(text: string, startLine?: number): string
 export interface SearchHooks {
     /** BM25 probe found strong signal — expansion will be skipped */
     onStrongSignal?: (topScore: number) => void;
-    /** Query expansion complete. Empty array = strong signal skip (no expansion). */
-    onExpand?: (original: string, expanded: ExpandedQuery[]) => void;
+    /** Query expansion starting */
+    onExpandStart?: () => void;
+    /** Query expansion complete. Empty array = strong signal skip. elapsedMs = time taken. */
+    onExpand?: (original: string, expanded: ExpandedQuery[], elapsedMs: number) => void;
+    /** Embedding starting (vec/hyde queries) */
+    onEmbedStart?: (count: number) => void;
+    /** Embedding complete */
+    onEmbedDone?: (elapsedMs: number) => void;
     /** Reranking is about to start */
     onRerankStart?: (chunkCount: number) => void;
     /** Reranking finished */
-    onRerankDone?: () => void;
+    onRerankDone?: (elapsedMs: number) => void;
 }
 export interface HybridQueryOptions {
     collection?: string;
     limit?: number;
     minScore?: number;
     candidateLimit?: number;
+    explain?: boolean;
     hooks?: SearchHooks;
 }
 export interface HybridQueryResult {
@@ -654,7 +694,13 @@ export interface HybridQueryResult {
     score: number;
     context: string | null;
     docid: string;
+    explain?: HybridQueryExplain;
 }
+export type RankedListMeta = {
+    source: "fts" | "vec";
+    queryType: "original" | "lex" | "vec" | "hyde";
+    query: string;
+};
 /**
  * Hybrid search: BM25 + vector + query expansion + RRF + chunked reranking.
  *
@@ -694,3 +740,44 @@ export interface VectorSearchResult {
  * 4. Sort by score descending, filter by minScore, slice to limit
  */
 export declare function vectorSearchQuery(store: Store, query: string, options?: VectorSearchOptions): Promise<VectorSearchResult[]>;
+/**
+ * A single sub-search in a structured search request.
+ * Matches the format used in QMD training data.
+ */
+export interface StructuredSubSearch {
+    /** Search type: 'lex' for BM25, 'vec' for semantic, 'hyde' for hypothetical */
+    type: 'lex' | 'vec' | 'hyde';
+    /** The search query text */
+    query: string;
+    /** Optional line number for error reporting (CLI parser) */
+    line?: number;
+}
+export interface StructuredSearchOptions {
+    collections?: string[];
+    limit?: number;
+    minScore?: number;
+    candidateLimit?: number;
+    explain?: boolean;
+    /** Future: domain intent hint for routing/boosting */
+    intent?: string;
+    hooks?: SearchHooks;
+}
+/**
+ * Structured search: execute pre-expanded queries without LLM query expansion.
+ *
+ * Designed for LLM callers (MCP/HTTP) that generate their own query expansions.
+ * Skips the internal expandQuery() step — goes directly to:
+ *
+ * Pipeline:
+ * 1. Route searches: lex→FTS, vec/hyde→vector (batch embed)
+ * 2. RRF fusion across all result lists
+ * 3. Chunk documents + keyword-best-chunk selection
+ * 4. Rerank on chunks
+ * 5. Position-aware score blending
+ * 6. Dedup, filter, slice
+ *
+ * This is the recommended endpoint for capable LLMs — they can generate
+ * better query variations than our small local model, especially for
+ * domain-specific or nuanced queries.
+ */
+export declare function structuredSearch(store: Store, searches: StructuredSubSearch[], options?: StructuredSearchOptions): Promise<HybridQueryResult[]>;