@tobilu/qmd 1.1.1 → 1.1.5

package/dist/store.d.ts

@@ -202,11 +202,11 @@ export type Store = {
     toVirtualPath: (absolutePath: string) => string | null;
     searchFTS: (query: string, limit?: number, collectionName?: string) => SearchResult[];
     searchVec: (query: string, model: string, limit?: number, collectionName?: string, session?: ILLMSession, precomputedEmbedding?: number[]) => Promise<SearchResult[]>;
-    expandQuery: (query: string, model?: string) => Promise<ExpandedQuery[]>;
+    expandQuery: (query: string, model?: string, intent?: string) => Promise<ExpandedQuery[]>;
     rerank: (query: string, documents: {
         file: string;
         text: string;
-    }[], model?: string) => Promise<{
+    }[], model?: string, intent?: string) => Promise<{
         file: string;
         score: number;
     }[]>;
@@ -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
  */
@@ -575,15 +598,19 @@ export declare function clearAllEmbeddings(db: Database): void;
  * The hash_seq key is formatted as "hash_seq" for the vectors_vec table.
  */
 export declare function insertEmbedding(db: Database, hash: string, seq: number, pos: number, embedding: Float32Array, model: string, embeddedAt: string): void;
-export declare function expandQuery(query: string, model: string | undefined, db: Database): Promise<ExpandedQuery[]>;
+export declare function expandQuery(query: string, model: string | undefined, db: Database, intent?: string): Promise<ExpandedQuery[]>;
 export declare function rerank(query: string, documents: {
     file: string;
     text: string;
-}[], model: string | undefined, db: Database): Promise<{
+}[], model: string | undefined, db: Database, intent?: string): Promise<{
     file: string;
     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.
@@ -623,7 +650,17 @@ export type SnippetResult = {
     linesAfter: number;
     snippetLines: number;
 };
-export declare function extractSnippet(body: string, query: string, maxLen?: number, chunkPos?: number, chunkLen?: number): SnippetResult;
+/** Weight for intent terms relative to query terms (1.0) in snippet scoring */
+export declare const INTENT_WEIGHT_SNIPPET = 0.3;
+/** Weight for intent terms relative to query terms (1.0) in chunk selection */
+export declare const INTENT_WEIGHT_CHUNK = 0.5;
+/**
+ * Extract meaningful terms from an intent string, filtering stop words and punctuation.
+ * Uses Unicode-aware punctuation stripping so domain terms like "API" survive.
+ * Returns lowercase terms suitable for text matching.
+ */
+export declare function extractIntentTerms(intent: string): string[];
+export declare function extractSnippet(body: string, query: string, maxLen?: number, chunkPos?: number, chunkLen?: number, intent?: string): SnippetResult;
 /**
  * Add line numbers to text content.
  * Each line becomes: "{lineNum}: {content}"
@@ -654,6 +691,8 @@ export interface HybridQueryOptions {
     limit?: number;
     minScore?: number;
     candidateLimit?: number;
+    explain?: boolean;
+    intent?: string;
     hooks?: SearchHooks;
 }
 export interface HybridQueryResult {
@@ -666,7 +705,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.
  *
@@ -685,6 +730,7 @@ export interface VectorSearchOptions {
     collection?: string;
     limit?: number;
     minScore?: number;
+    intent?: string;
     hooks?: Pick<SearchHooks, 'onExpand'>;
 }
 export interface VectorSearchResult {
@@ -723,7 +769,8 @@ export interface StructuredSearchOptions {
     limit?: number;
     minScore?: number;
     candidateLimit?: number;
-    /** Future: domain intent hint for routing/boosting */
+    explain?: boolean;
+    /** Domain intent hint for disambiguation — steers reranking and chunk selection */
     intent?: string;
     hooks?: SearchHooks;
 }