agent-web-interface 4.3.0 → 4.4.0

package/dist/src/query/disambiguation.js

@@ -0,0 +1,123 @@
+/**
+ * Disambiguation
+ *
+ * Generate suggestions to narrow ambiguous query results.
+ * Analyzes matched nodes and suggests refinements.
+ */
+import { normalizeText } from '../lib/text-utils.js';
+import { normalizeLabelFilter } from './scoring.js';
+/**
+ * Generate disambiguation suggestions when query matches multiple elements.
+ * Suggests refinements that would narrow down the results.
+ */
+export function generateSuggestions(matches, request) {
+    const suggestions = [];
+    const nodes = matches.map((m) => m.node);
+    // Only generate suggestions if we have multiple matches
+    if (matches.length < 2)
+        return suggestions;
+    // 1. Suggest refining by kind if matches have different kinds
+    if (request.kind === undefined) {
+        const kindCounts = countByAttribute(nodes, (n) => n.kind);
+        if (kindCounts.size > 1) {
+            for (const [kind, count] of kindCounts) {
+                if (count < matches.length) {
+                    suggestions.push({
+                        type: 'refine_kind',
+                        message: `Add kind: "${kind}" to narrow to ${count} result(s)`,
+                        refinement: { kind },
+                        expected_matches: count,
+                    });
+                }
+            }
+        }
+    }
+    // 2. Suggest refining by region if matches span multiple regions
+    if (request.region === undefined) {
+        const regionCounts = countByAttribute(nodes, (n) => n.where.region);
+        if (regionCounts.size > 1) {
+            for (const [region, count] of regionCounts) {
+                if (count < matches.length && region !== 'unknown') {
+                    suggestions.push({
+                        type: 'refine_region',
+                        message: `Add region: "${region}" to narrow to ${count} result(s)`,
+                        refinement: { region },
+                        expected_matches: count,
+                    });
+                }
+            }
+        }
+    }
+    // 3. Suggest refining by group_id if matches have different groups
+    if (request.group_id === undefined) {
+        const groupCounts = countByAttribute(nodes, (n) => n.where.group_id);
+        groupCounts.delete(undefined); // Remove nodes without groups
+        if (groupCounts.size >= 1) {
+            for (const [groupId, count] of groupCounts) {
+                if (groupId !== undefined) {
+                    suggestions.push({
+                        type: 'refine_group',
+                        message: `Add group_id: "${groupId}" to narrow to ${count} result(s)`,
+                        refinement: { group_id: groupId },
+                        expected_matches: count,
+                    });
+                }
+            }
+        }
+    }
+    // 4. Suggest adding state filters
+    if (request.state === undefined) {
+        const enabledCount = nodes.filter((n) => n.state?.enabled).length;
+        if (enabledCount > 0 && enabledCount < matches.length) {
+            suggestions.push({
+                type: 'add_state',
+                message: `Add state: { enabled: true } to narrow to ${enabledCount} result(s)`,
+                refinement: { state: { enabled: true } },
+                expected_matches: enabledCount,
+            });
+        }
+        const visibleCount = nodes.filter((n) => n.state?.visible).length;
+        if (visibleCount > 0 && visibleCount < matches.length) {
+            suggestions.push({
+                type: 'add_state',
+                message: `Add state: { visible: true } to narrow to ${visibleCount} result(s)`,
+                refinement: { state: { visible: true } },
+                expected_matches: visibleCount,
+            });
+        }
+    }
+    // 5. Suggest refining label to exact match if using contains/fuzzy
+    if (request.label !== undefined) {
+        const { mode, text } = normalizeLabelFilter(request.label);
+        if (mode !== 'exact') {
+            const normalizedText = normalizeText(text.toLowerCase());
+            const exactCount = nodes.filter((n) => normalizeText(n.label.toLowerCase()) === normalizedText).length;
+            if (exactCount > 0 && exactCount < matches.length) {
+                suggestions.push({
+                    type: 'refine_label',
+                    message: `Use exact label match to narrow to ${exactCount} result(s)`,
+                    refinement: { label: { text, mode: 'exact' } },
+                    expected_matches: exactCount,
+                });
+            }
+        }
+    }
+    // Sort by expected_matches (prefer suggestions that narrow most effectively)
+    // and limit to top 5
+    return suggestions
+        .filter((s) => s.expected_matches > 0 && s.expected_matches < matches.length)
+        .sort((a, b) => a.expected_matches - b.expected_matches)
+        .slice(0, 5);
+}
+/**
+ * Count nodes by a given attribute.
+ */
+export function countByAttribute(nodes, getter) {
+    const counts = new Map();
+    for (const node of nodes) {
+        const value = getter(node);
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    return counts;
+}
+//# sourceMappingURL=disambiguation.js.map

package/dist/src/query/disambiguation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"disambiguation.js","sourceRoot":"","sources":["../../../src/query/disambiguation.ts"],"names":[],"mappings":"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"}

package/dist/src/query/fuzzy-match.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Fuzzy Match
+ *
+ * Fuzzy label matching for query engine.
+ * Uses token-based matching with configurable thresholds.
+ */
+import type { ReadableNode } from '../snapshot/snapshot.types.js';
+import type { FuzzyMatchOptions } from './types/query.types.js';
+/**
+ * Filter nodes by fuzzy label matching.
+ * Returns matched nodes and a map of node_id -> match score for relevance calculation.
+ */
+export declare function filterByLabelFuzzy(nodes: ReadableNode[], text: string, caseSensitive: boolean, options?: FuzzyMatchOptions): {
+    nodes: ReadableNode[];
+    scores: Map<string, number>;
+};
+//# sourceMappingURL=fuzzy-match.d.ts.map

package/dist/src/query/fuzzy-match.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzzy-match.d.ts","sourceRoot":"","sources":["../../../src/query/fuzzy-match.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAGhE;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,EAAE,EACrB,IAAI,EAAE,MAAM,EACZ,aAAa,EAAE,OAAO,EACtB,OAAO,GAAE,iBAAsB,GAC9B;IAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CA0BxD"}

package/dist/src/query/fuzzy-match.js

@@ -0,0 +1,34 @@
+/**
+ * Fuzzy Match
+ *
+ * Fuzzy label matching for query engine.
+ * Uses token-based matching with configurable thresholds.
+ */
+import { normalizeText, tokenizeForMatching, fuzzyTokensMatch } from '../lib/text-utils.js';
+/**
+ * Filter nodes by fuzzy label matching.
+ * Returns matched nodes and a map of node_id -> match score for relevance calculation.
+ */
+export function filterByLabelFuzzy(nodes, text, caseSensitive, options = {}) {
+    const scores = new Map();
+    const normalizedQuery = normalizeText(caseSensitive ? text : text.toLowerCase());
+    const queryTokens = tokenizeForMatching(normalizedQuery, 10, 2);
+    if (queryTokens.length === 0) {
+        return { nodes: [], scores };
+    }
+    const matched = nodes.filter((n) => {
+        const normalizedLabel = normalizeText(caseSensitive ? n.label : n.label.toLowerCase());
+        const labelTokens = tokenizeForMatching(normalizedLabel, 10, 2);
+        const result = fuzzyTokensMatch(labelTokens, queryTokens, {
+            minTokenOverlap: options.minTokenOverlap ?? 0.5,
+            prefixMatch: options.prefixMatch ?? true,
+            minSimilarity: options.minSimilarity ?? 0.8,
+        });
+        if (result.isMatch) {
+            scores.set(n.node_id, result.score);
+        }
+        return result.isMatch;
+    });
+    return { nodes: matched, scores };
+}
+//# sourceMappingURL=fuzzy-match.js.map

package/dist/src/query/fuzzy-match.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fuzzy-match.js","sourceRoot":"","sources":["../../../src/query/fuzzy-match.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAE5F;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAqB,EACrB,IAAY,EACZ,aAAsB,EACtB,UAA6B,EAAE;IAE/B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,MAAM,eAAe,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;IACjF,MAAM,WAAW,GAAG,mBAAmB,CAAC,eAAe,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;IAEhE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC;IAC/B,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;QACjC,MAAM,eAAe,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;QACvF,MAAM,WAAW,GAAG,mBAAmB,CAAC,eAAe,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC;QAEhE,MAAM,MAAM,GAAG,gBAAgB,CAAC,WAAW,EAAE,WAAW,EAAE;YACxD,eAAe,EAAE,OAAO,CAAC,eAAe,IAAI,GAAG;YAC/C,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;YACxC,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,GAAG;SAC5C,CAAC,CAAC;QAEH,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,MAAM,CAAC,OAAO,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AACpC,CAAC"}

package/dist/src/query/index.d.ts

@@ -6,4 +6,7 @@
 export * from './types/query.types.js';
 export { QueryEngine } from './query-engine.js';
 export type { QueryEngineOptions } from './query-engine.js';
+export { scoreMatch, calculateMaxPossibleScore, normalizeLabelFilter, SCORING_WEIGHTS, } from './scoring.js';
+export { generateSuggestions, countByAttribute } from './disambiguation.js';
+export { filterByLabelFuzzy } from './fuzzy-match.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/src/query/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,wBAAwB,CAAC;AAGvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,cAAc,wBAAwB,CAAC;AAGvC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAG5D,OAAO,EACL,UAAU,EACV,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAG5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/query/index.js

@@ -7,4 +7,10 @@
 export * from './types/query.types.js';
 // Query Engine
 export { QueryEngine } from './query-engine.js';
+// Scoring
+export { scoreMatch, calculateMaxPossibleScore, normalizeLabelFilter, SCORING_WEIGHTS, } from './scoring.js';
+// Disambiguation
+export { generateSuggestions, countByAttribute } from './disambiguation.js';
+// Fuzzy matching
+export { filterByLabelFuzzy } from './fuzzy-match.js';
 //# sourceMappingURL=index.js.map

package/dist/src/query/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,QAAQ;AACR,cAAc,wBAAwB,CAAC;AAEvC,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/query/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,QAAQ;AACR,cAAc,wBAAwB,CAAC;AAEvC,eAAe;AACf,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,UAAU;AACV,OAAO,EACL,UAAU,EACV,yBAAyB,EACzB,oBAAoB,EACpB,eAAe,GAChB,MAAM,cAAc,CAAC;AAEtB,iBAAiB;AACjB,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5E,iBAAiB;AACjB,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/query/query-engine.d.ts

@@ -72,40 +72,5 @@ export declare class QueryEngine {
      * Check if a node matches all state constraints
      */
     private matchState;
-    /**
-     * Normalize a label filter to its constituent parts
-     */
-    private normalizeLabelFilter;
-    /**
-     * Filter nodes by fuzzy label matching.
-     * Returns matched nodes and a map of node_id -> match score for relevance calculation.
-     */
-    private filterByLabelFuzzy;
-    /**
-     * Calculate relevance score and match reasons for a node.
-     *
-     * @param node - The node to score
-     * @param request - The original query request
-     * @param labelMatchScore - Pre-computed label match score (for fuzzy matching)
-     * @returns Relevance score (0-1) and list of reasons
-     */
-    private scoreMatch;
-    /**
-     * Calculate the maximum possible score given the request filters.
-     */
-    private calculateMaxPossibleScore;
-    /**
-     * Truncate a label for display in reasons.
-     */
-    private truncateLabel;
-    /**
-     * Generate disambiguation suggestions when query matches multiple elements.
-     * Suggests refinements that would narrow down the results.
-     */
-    private generateSuggestions;
-    /**
-     * Count nodes by a given attribute.
-     */
-    private countByAttribute;
 }
 //# sourceMappingURL=query-engine.d.ts.map

package/dist/src/query/query-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query-engine.d.ts","sourceRoot":"","sources":["../../../src/query/query-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGb,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EAQrB,MAAM,wBAAwB,CAAC;AAGhC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;CAOvB;AAoBD;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;OAEG;gBACS,QAAQ,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB;IAMpE;;OAEG;IACH,IAAI,CAAC,OAAO,GAAE,mBAAwB,GAAG,oBAAoB;IAwF7D;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIjD;;OAEG;IACH,eAAe,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAO9D;;OAEG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IAS3C;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,UAAU;IAsBlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;OAEG;IACH,OAAO,CAAC,UAAU;IAgClB;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAqC1B;;;;;;;OAOG;IACH,OAAO,CAAC,UAAU;IAqGlB;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAqBjC;;OAEG;IACH,OAAO,CAAC,aAAa;IASrB;;;OAGG;IACH,OAAO,CAAC,mBAAmB;IAgH3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAWzB"}
+{"version":3,"file":"query-engine.d.ts","sourceRoot":"","sources":["../../../src/query/query-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,YAAY,EAGb,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,mBAAmB,EACnB,oBAAoB,EAMrB,MAAM,wBAAwB,CAAC;AAMhC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;CAOvB;AAED;;GAEG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IAEtC;;OAEG;gBACS,QAAQ,EAAE,YAAY,EAAE,OAAO,GAAE,kBAAuB;IAMpE;;OAEG;IACH,IAAI,CAAC,OAAO,GAAE,mBAAwB,GAAG,oBAAoB;IAwF7D;;OAEG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAIjD;;OAEG;IACH,eAAe,IAAI;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAO9D;;OAEG;IACH,WAAW,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE;IAS3C;;OAEG;IACH,OAAO,CAAC,YAAY;IAKpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAUrB;;OAEG;IACH,OAAO,CAAC,UAAU;IAsBlB;;OAEG;IACH,OAAO,CAAC,cAAc;IAQtB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;OAEG;IACH,OAAO,CAAC,UAAU;CA+BnB"}

package/dist/src/query/query-engine.js

@@ -9,24 +9,10 @@
  * - Relevance scoring
  * - Disambiguation suggestions
  */
-import { normalizeText, tokenizeForMatching, fuzzyTokensMatch } from '../lib/text-utils.js';
-/**
- * Scoring weights for relevance calculation.
- * Values represent the maximum contribution each signal can add to the score.
- */
-const SCORING_WEIGHTS = {
-    labelMatch: {
-        exact: 0.4,
-        contains: 0.3,
-        fuzzy: 0.25, // Base, multiplied by fuzzy match quality
-    },
-    kindMatch: 0.15,
-    regionMatch: 0.12,
-    stateMatch: 0.03, // Per matching state property (max ~0.27 for 9 props)
-    groupMatch: 0.08,
-    headingMatch: 0.08,
-    visibility: 0.02,
-};
+import { normalizeText } from '../lib/text-utils.js';
+import { scoreMatch, normalizeLabelFilter } from './scoring.js';
+import { generateSuggestions } from './disambiguation.js';
+import { filterByLabelFuzzy } from './fuzzy-match.js';
 /**
  * Query engine for BaseSnapshot data
  */
@@ -57,9 +43,9 @@ export class QueryEngine {
         }
         // Filter by label (with fuzzy support)
         if (request.label !== undefined) {
-            const { mode, text, caseSensitive, fuzzyOptions } = this.normalizeLabelFilter(request.label);
+            const { mode, text, caseSensitive, fuzzyOptions } = normalizeLabelFilter(request.label);
             if (mode === 'fuzzy') {
-                const result = this.filterByLabelFuzzy(candidates, text, caseSensitive, fuzzyOptions);
+                const result = filterByLabelFuzzy(candidates, text, caseSensitive, fuzzyOptions);
                 candidates = result.nodes;
                 labelScores = result.scores;
             }
@@ -85,7 +71,7 @@ export class QueryEngine {
         }
         // Score all candidates
         const scoredMatches = candidates.map((node) => {
-            const { relevance, reasons } = this.scoreMatch(node, request, labelScores?.get(node.node_id));
+            const { relevance, reasons } = scoreMatch(node, request, labelScores?.get(node.node_id));
             return { node, relevance, match_reasons: reasons };
         });
         // Apply min_score filter
@@ -104,7 +90,7 @@ export class QueryEngine {
         // Generate suggestions if requested and results are ambiguous
         let suggestions;
         if (request.include_suggestions && totalMatched > 1) {
-            suggestions = this.generateSuggestions(limitedMatches, request);
+            suggestions = generateSuggestions(limitedMatches, request);
             if (suggestions.length === 0)
                 suggestions = undefined;
         }
@@ -154,7 +140,7 @@ export class QueryEngine {
      * Filter nodes by label text
      */
     filterByLabel(nodes, filter) {
-        const { text, mode, caseSensitive } = this.normalizeLabelFilter(filter);
+        const { text, mode, caseSensitive } = normalizeLabelFilter(filter);
         if (!text) {
             return nodes;
         }
@@ -219,291 +205,5 @@ export class QueryEngine {
         }
         return true;
     }
-    /**
-     * Normalize a label filter to its constituent parts
-     */
-    normalizeLabelFilter(filter) {
-        if (typeof filter === 'string') {
-            return { text: filter, mode: 'contains', caseSensitive: false };
-        }
-        return {
-            text: filter.text,
-            mode: filter.mode ?? 'contains',
-            caseSensitive: filter.caseSensitive ?? false,
-            fuzzyOptions: filter.fuzzyOptions,
-        };
-    }
-    // ===========================================================================
-    // Fuzzy Matching
-    // ===========================================================================
-    /**
-     * Filter nodes by fuzzy label matching.
-     * Returns matched nodes and a map of node_id -> match score for relevance calculation.
-     */
-    filterByLabelFuzzy(nodes, text, caseSensitive, options = {}) {
-        const scores = new Map();
-        const normalizedQuery = normalizeText(caseSensitive ? text : text.toLowerCase());
-        const queryTokens = tokenizeForMatching(normalizedQuery, 10, 2);
-        if (queryTokens.length === 0) {
-            return { nodes: [], scores };
-        }
-        const matched = nodes.filter((n) => {
-            const normalizedLabel = normalizeText(caseSensitive ? n.label : n.label.toLowerCase());
-            const labelTokens = tokenizeForMatching(normalizedLabel, 10, 2);
-            const result = fuzzyTokensMatch(labelTokens, queryTokens, {
-                minTokenOverlap: options.minTokenOverlap ?? 0.5,
-                prefixMatch: options.prefixMatch ?? true,
-                minSimilarity: options.minSimilarity ?? 0.8,
-            });
-            if (result.isMatch) {
-                scores.set(n.node_id, result.score);
-            }
-            return result.isMatch;
-        });
-        return { nodes: matched, scores };
-    }
-    // ===========================================================================
-    // Relevance Scoring
-    // ===========================================================================
-    /**
-     * Calculate relevance score and match reasons for a node.
-     *
-     * @param node - The node to score
-     * @param request - The original query request
-     * @param labelMatchScore - Pre-computed label match score (for fuzzy matching)
-     * @returns Relevance score (0-1) and list of reasons
-     */
-    scoreMatch(node, request, labelMatchScore) {
-        let relevance = 0;
-        const reasons = [];
-        // Label scoring
-        if (request.label !== undefined) {
-            const { mode } = this.normalizeLabelFilter(request.label);
-            let labelContribution;
-            if (mode === 'fuzzy' && labelMatchScore !== undefined) {
-                // Fuzzy: base weight * match quality
-                labelContribution = SCORING_WEIGHTS.labelMatch.fuzzy * labelMatchScore;
-            }
-            else if (mode === 'exact') {
-                labelContribution = SCORING_WEIGHTS.labelMatch.exact;
-            }
-            else {
-                labelContribution = SCORING_WEIGHTS.labelMatch.contains;
-            }
-            relevance += labelContribution;
-            reasons.push({
-                type: 'label',
-                description: `Label "${this.truncateLabel(node.label)}" matches query`,
-                score_contribution: labelContribution,
-            });
-        }
-        // Kind scoring
-        if (request.kind !== undefined) {
-            relevance += SCORING_WEIGHTS.kindMatch;
-            reasons.push({
-                type: 'kind',
-                description: `Kind "${node.kind}" matches filter`,
-                score_contribution: SCORING_WEIGHTS.kindMatch,
-            });
-        }
-        // Region scoring
-        if (request.region !== undefined) {
-            relevance += SCORING_WEIGHTS.regionMatch;
-            reasons.push({
-                type: 'region',
-                description: `Region "${node.where.region}" matches filter`,
-                score_contribution: SCORING_WEIGHTS.regionMatch,
-            });
-        }
-        // State scoring (per matched property)
-        if (request.state !== undefined && node.state) {
-            const matchedStates = Object.keys(request.state).filter((k) => request.state[k] !== undefined &&
-                request.state[k] === node.state[k]);
-            const stateContribution = matchedStates.length * SCORING_WEIGHTS.stateMatch;
-            if (stateContribution > 0) {
-                relevance += stateContribution;
-                reasons.push({
-                    type: 'state',
-                    description: `States match: ${matchedStates.join(', ')}`,
-                    score_contribution: stateContribution,
-                });
-            }
-        }
-        // Group scoring
-        if (request.group_id !== undefined) {
-            relevance += SCORING_WEIGHTS.groupMatch;
-            reasons.push({
-                type: 'group',
-                description: `Group "${node.where.group_id}" matches`,
-                score_contribution: SCORING_WEIGHTS.groupMatch,
-            });
-        }
-        // Heading context scoring
-        if (request.heading_context !== undefined) {
-            relevance += SCORING_WEIGHTS.headingMatch;
-            reasons.push({
-                type: 'heading',
-                description: `Heading context "${node.where.heading_context}" matches`,
-                score_contribution: SCORING_WEIGHTS.headingMatch,
-            });
-        }
-        // Visibility bonus (always applied if node is visible)
-        if (node.state?.visible) {
-            relevance += SCORING_WEIGHTS.visibility;
-        }
-        // Normalize to 0-1 range based on what was actually queried
-        // This gives higher scores when fewer filters are used but all match
-        const maxPossible = this.calculateMaxPossibleScore(request);
-        const normalizedRelevance = maxPossible > 0 ? Math.min(1, relevance / maxPossible) : 0;
-        return { relevance: normalizedRelevance, reasons };
-    }
-    /**
-     * Calculate the maximum possible score given the request filters.
-     */
-    calculateMaxPossibleScore(request) {
-        let max = SCORING_WEIGHTS.visibility; // Always possible
-        if (request.label !== undefined) {
-            const { mode } = this.normalizeLabelFilter(request.label);
-            max += SCORING_WEIGHTS.labelMatch[mode];
-        }
-        if (request.kind !== undefined)
-            max += SCORING_WEIGHTS.kindMatch;
-        if (request.region !== undefined)
-            max += SCORING_WEIGHTS.regionMatch;
-        if (request.state !== undefined) {
-            const stateCount = Object.keys(request.state).filter((k) => request.state[k] !== undefined).length;
-            max += stateCount * SCORING_WEIGHTS.stateMatch;
-        }
-        if (request.group_id !== undefined)
-            max += SCORING_WEIGHTS.groupMatch;
-        if (request.heading_context !== undefined)
-            max += SCORING_WEIGHTS.headingMatch;
-        return max;
-    }
-    /**
-     * Truncate a label for display in reasons.
-     */
-    truncateLabel(label, maxLength = 30) {
-        if (label.length <= maxLength)
-            return label;
-        return label.slice(0, maxLength - 1) + '…';
-    }
-    // ===========================================================================
-    // Disambiguation Suggestions
-    // ===========================================================================
-    /**
-     * Generate disambiguation suggestions when query matches multiple elements.
-     * Suggests refinements that would narrow down the results.
-     */
-    generateSuggestions(matches, request) {
-        const suggestions = [];
-        const nodes = matches.map((m) => m.node);
-        // Only generate suggestions if we have multiple matches
-        if (matches.length < 2)
-            return suggestions;
-        // 1. Suggest refining by kind if matches have different kinds
-        if (request.kind === undefined) {
-            const kindCounts = this.countByAttribute(nodes, (n) => n.kind);
-            if (kindCounts.size > 1) {
-                for (const [kind, count] of kindCounts) {
-                    if (count < matches.length) {
-                        suggestions.push({
-                            type: 'refine_kind',
-                            message: `Add kind: "${kind}" to narrow to ${count} result(s)`,
-                            refinement: { kind },
-                            expected_matches: count,
-                        });
-                    }
-                }
-            }
-        }
-        // 2. Suggest refining by region if matches span multiple regions
-        if (request.region === undefined) {
-            const regionCounts = this.countByAttribute(nodes, (n) => n.where.region);
-            if (regionCounts.size > 1) {
-                for (const [region, count] of regionCounts) {
-                    if (count < matches.length && region !== 'unknown') {
-                        suggestions.push({
-                            type: 'refine_region',
-                            message: `Add region: "${region}" to narrow to ${count} result(s)`,
-                            refinement: { region },
-                            expected_matches: count,
-                        });
-                    }
-                }
-            }
-        }
-        // 3. Suggest refining by group_id if matches have different groups
-        if (request.group_id === undefined) {
-            const groupCounts = this.countByAttribute(nodes, (n) => n.where.group_id);
-            groupCounts.delete(undefined); // Remove nodes without groups
-            if (groupCounts.size >= 1) {
-                for (const [groupId, count] of groupCounts) {
-                    if (groupId !== undefined) {
-                        suggestions.push({
-                            type: 'refine_group',
-                            message: `Add group_id: "${groupId}" to narrow to ${count} result(s)`,
-                            refinement: { group_id: groupId },
-                            expected_matches: count,
-                        });
-                    }
-                }
-            }
-        }
-        // 4. Suggest adding state filters
-        if (request.state === undefined) {
-            const enabledCount = nodes.filter((n) => n.state?.enabled).length;
-            if (enabledCount > 0 && enabledCount < matches.length) {
-                suggestions.push({
-                    type: 'add_state',
-                    message: `Add state: { enabled: true } to narrow to ${enabledCount} result(s)`,
-                    refinement: { state: { enabled: true } },
-                    expected_matches: enabledCount,
-                });
-            }
-            const visibleCount = nodes.filter((n) => n.state?.visible).length;
-            if (visibleCount > 0 && visibleCount < matches.length) {
-                suggestions.push({
-                    type: 'add_state',
-                    message: `Add state: { visible: true } to narrow to ${visibleCount} result(s)`,
-                    refinement: { state: { visible: true } },
-                    expected_matches: visibleCount,
-                });
-            }
-        }
-        // 5. Suggest refining label to exact match if using contains/fuzzy
-        if (request.label !== undefined) {
-            const { mode, text } = this.normalizeLabelFilter(request.label);
-            if (mode !== 'exact') {
-                const normalizedText = normalizeText(text.toLowerCase());
-                const exactCount = nodes.filter((n) => normalizeText(n.label.toLowerCase()) === normalizedText).length;
-                if (exactCount > 0 && exactCount < matches.length) {
-                    suggestions.push({
-                        type: 'refine_label',
-                        message: `Use exact label match to narrow to ${exactCount} result(s)`,
-                        refinement: { label: { text, mode: 'exact' } },
-                        expected_matches: exactCount,
-                    });
-                }
-            }
-        }
-        // Sort by expected_matches (prefer suggestions that narrow most effectively)
-        // and limit to top 5
-        return suggestions
-            .filter((s) => s.expected_matches > 0 && s.expected_matches < matches.length)
-            .sort((a, b) => a.expected_matches - b.expected_matches)
-            .slice(0, 5);
-    }
-    /**
-     * Count nodes by a given attribute.
-     */
-    countByAttribute(nodes, getter) {
-        const counts = new Map();
-        for (const node of nodes) {
-            const value = getter(node);
-            counts.set(value, (counts.get(value) ?? 0) + 1);
-        }
-        return counts;
-    }
 }
 //# sourceMappingURL=query-engine.js.map