capman 0.6.1 → 0.6.2

package/dist/esm/matcher.js

@@ -237,6 +237,20 @@ export function extractBigrams(tokens) {
     }
     return bigrams;
 }
+/**
+ * Reciprocal Rank Fusion — fuses multiple ranked lists into a single score map.
+ * k=60 is the standard literature default.
+ */
+export function rrf(rankings, k = 60) {
+    const scores = new Map();
+    for (const ranking of rankings) {
+        const sorted = [...ranking].sort((a, b) => b.score - a.score);
+        sorted.forEach((item, rank) => {
+            scores.set(item.id, (scores.get(item.id) ?? 0) + 1 / (k + rank + 1));
+        });
+    }
+    return scores;
+}
 /**
  * Returns a sub-manifest containing only capabilities that match ALL provided tags.
  * Capabilities without tags are excluded when tags filter is active.
@@ -528,16 +542,57 @@ export function match(query, manifest, options = {}) {
     const b = options.bm25B ?? 0.75;
     // Calibrate ceiling — max self-score for normalization
     const ceiling = options.bm25Ceiling ?? calibrateCeiling(manifest.capabilities, bm25Index, k1, b);
-    const allScores = [];
+    // Build per-source ranked lists for RRF fusion
+    const keywordRanking = [];
+    const fuzzyRanking = [];
+    const embeddingRanking = [];
+    const keywordScoreMap = new Map();
     for (const cap of manifest.capabilities) {
         const rawBM25 = scoreCapability(qWordSet, cap, bm25Index, k1, b);
         const bm25Score = Math.min(100, Math.round((rawBM25 / ceiling) * 100));
         const bonusPoints = bigramBonus(qBigrams, bm25Index.bigrams[cap.id] ?? new Set());
         const keywordScore = Math.min(100, bm25Score + bonusPoints);
         const fuzzyScore = fuzzyScoreMap.get(cap.id) ?? 0;
-        const via = fuzzyScore > keywordScore ? 'fuzzy' : 'keyword';
-        const score = Math.min(100, Math.round(Math.max(keywordScore, fuzzyScore)));
-        logger.debug(`  scored "${cap.id}": ${score}% (keyword: ${keywordScore}%, fuzzy: ${Math.round(fuzzyScore)}%)`);
+        const embScore = options.embeddingScores?.get(cap.id) ?? 0;
+        if (keywordScore > 0)
+            keywordRanking.push({ id: cap.id, score: keywordScore });
+        keywordScoreMap.set(cap.id, keywordScore);
+        if (fuzzyScore > 0)
+            fuzzyRanking.push({ id: cap.id, score: fuzzyScore });
+        if (embScore > 0)
+            embeddingRanking.push({ id: cap.id, score: embScore });
+    }
+    // RRF fusion. Anchor to theoretical max — a rank-1 entry in all lists scores
+    // rankings.length/(k+1). Using observed max instead inflates zero-overlap queries
+    // (all capabilities rank equally) to 100%, breaking out-of-scope rejection.
+    const rrfK = 60;
+    const rankings = [
+        keywordRanking,
+        ...(fuzzyRanking.length > 0 ? [fuzzyRanking] : []),
+        ...(embeddingRanking.length > 0 ? [embeddingRanking] : []),
+    ];
+    const rrfScores = rrf(rankings, rrfK);
+    const theoreticalMax = rankings.length / (rrfK + 1);
+    // Pre-compute rank maps — rank 0 = best. Used for accurate via attribution.
+    const rankIn = (list, id) => {
+        const idx = list.findIndex(e => e.id === id);
+        return idx === -1 ? Infinity : idx;
+    };
+    const allScores = [];
+    for (const cap of manifest.capabilities) {
+        const rrfScore = rrfScores.get(cap.id) ?? 0;
+        const score = Math.min(100, Math.round((rrfScore / theoreticalMax) * 100));
+        const keywordScore = keywordScoreMap.get(cap.id) ?? 0;
+        const fuzzyScore = fuzzyScoreMap.get(cap.id) ?? 0;
+        const embScore = options.embeddingScores?.get(cap.id) ?? 0;
+        // via = whichever signal ranked this capability highest (lowest rank index).
+        // Uses rank position rather than raw score — RRF is rank-based, not score-based.
+        const kRank = rankIn(keywordRanking, cap.id);
+        const fRank = rankIn(fuzzyRanking, cap.id);
+        const eRank = rankIn(embeddingRanking, cap.id);
+        const via = eRank < fRank && eRank < kRank ? 'embedding' :
+            fRank < kRank ? 'fuzzy' : 'keyword';
+        logger.debug(`  scored "${cap.id}": ${score}% (keyword: ${keywordScore}%, fuzzy: ${Math.round(fuzzyScore)}%, emb: ${Math.round(embScore)}%, rrf: ${rrfScore.toFixed(4)})`);
         allScores.push({ cap, score, via });
         if (score > bestScore) {
             bestScore = score;
@@ -567,7 +622,8 @@ export function match(query, manifest, options = {}) {
     logger.debug(`Extracted params: ${JSON.stringify(Object.fromEntries(Object.entries(params).map(([k, v]) => [k, v != null ? '[REDACTED]' : 'null'])))}`);
     // Use the via tag tracked during scoring — avoids redundant scoreCapability call.
     const bestEntry = allScores.find(s => s.cap.id === best.id);
-    const winner = bestEntry?.via === 'fuzzy' ? 'fuzzy match' : 'keyword scoring';
+    const winner = bestEntry?.via === 'embedding' ? 'embedding match' :
+        bestEntry?.via === 'fuzzy' ? 'fuzzy match' : 'keyword scoring';
     // Matched return:
     return {
         capability: best,
@@ -589,17 +645,17 @@ export function match(query, manifest, options = {}) {
  * wrapper that maps the prompt to a proper system message, keeping user query
  * data in the user turn only.
  */
-export async function matchWithLLM(query, manifest, options) {
+export async function matchWithLLM(query, topCandidates, options) {
     // Truncate description and examples — prevents context window overflow and
     // reduces prompt injection surface from third-party OpenAPI spec content.
     const MAX_DESC_LEN = 200;
     const MAX_EXAMPLE_LEN = 100;
-    const manifestSummary = manifest.capabilities.map(c => `- ${c.id} (${c.resolver.type}): ${sanitizeForPrompt(c.description, MAX_DESC_LEN)}${c.examples?.length
+    const manifestSummary = topCandidates.map(c => `- ${c.id} (${c.resolver.type}): ${sanitizeForPrompt(c.description, MAX_DESC_LEN)}${c.examples?.length
         ? `\n  examples: ${c.examples.slice(0, 2).map(e => sanitizeForPrompt(e, MAX_EXAMPLE_LEN)).join(', ')}`
         : ''}`).join('\n');
     // Sanitize app name — strip newlines and control characters that could
     // break the prompt structure or inject additional instructions.
-    const safeApp = sanitizeForPrompt(manifest.app, 100);
+    const safeApp = sanitizeForPrompt(options.app ?? 'the application', 100);
     const prompt = `You are an intent matcher for an AI agent system.
 
   App: ${safeApp}
@@ -641,7 +697,7 @@ ${JSON.stringify({ user_query: query })}
     const isOOS = parsed.matched_capability === 'OUT_OF_SCOPE';
     const capability = isOOS
         ? null
-        : manifest.capabilities.find(c => c.id === parsed.matched_capability) ?? null;
+        : topCandidates.find(c => c.id === parsed.matched_capability) ?? null;
     // If LLM returned an unknown capability ID, treat as out of scope
     const effectivelyOOS = isOOS || capability === null;
     if (!isOOS && capability === null) {
@@ -657,7 +713,7 @@ ${JSON.stringify({ user_query: query })}
     const llmConfidence = effectivelyOOS
         ? 0
         : Math.min(100, Math.max(0, Math.round(parsed.confidence)));
-    const allCandidates = manifest.capabilities.map(c => ({
+    const allCandidates = topCandidates.map(c => ({
         capabilityId: c.id,
         score: c.id === capability?.id ? llmConfidence : 0,
         matched: c.id === capability?.id,

package/dist/esm/schema.js

@@ -114,7 +114,7 @@ export const CapmanConfigSchema = z.object({
         .refine(caps => new Set(caps.map(c => c.id)).size === caps.length, 'capability ids must be unique'),
 }).refine(cfg => {
     const needsBaseUrl = cfg.capabilities.some(c => c.resolver.type === 'api' || c.resolver.type === 'hybrid');
-    return !needsBaseUrl || !!cfg.baseUrl;
+    return !needsBaseUrl || !!cfg.baseUrl || (cfg.servers?.length ?? 0) > 0;
 }, { message: 'baseUrl is required when any capability uses an api or hybrid resolver' });
 // ─── Manifest Schema ──────────────────────────────────────────────────────────
 export const ManifestSchema = z.object({

package/dist/esm/types.d.ts

@@ -81,6 +81,15 @@ export interface LifecycleInfo {
     /** Human-readable note for consumers */
     note?: string;
 }
+/**
+ * Optional embedding provider for semantic similarity matching.
+ * Zero mandatory dependency — only used when passed to EngineOptions.
+ * Implement with any model: OpenAI, local ONNX, Transformers.js, etc.
+ */
+export interface EmbeddingProvider {
+    /** Encode a batch of texts into fixed-length float vectors. */
+    encode(texts: string[]): Promise<number[][]>;
+}
 export interface MatchHint {
     /**
      * Advisory preferred matching mode for this capability.

package/dist/esm/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.6.0";
+export declare const VERSION = "0.6.1";

package/dist/esm/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/version.js — do not edit manually
-export const VERSION = '0.6.0';
+export const VERSION = '0.6.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "capman",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Capability Manifest Engine — let AI agents interact with your app without navigating the UI",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",