capman 0.2.0 → 0.4.0

package/dist/esm/cache.js

@@ -0,0 +1,139 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from './logger';
+// ─── Normalize query for cache key ────────────────────────────────────────────
+function normalizeQuery(query) {
+    return query.toLowerCase().trim().replace(/\s+/g, ' ');
+}
+// ─── Memory Cache ─────────────────────────────────────────────────────────────
+export class MemoryCache {
+    constructor() {
+        this.store = new Map();
+    }
+    async get(query) {
+        const key = normalizeQuery(query);
+        const entry = this.store.get(key);
+        if (entry) {
+            entry.hits++;
+            logger.debug(`Cache hit (memory): "${query}"`);
+            return entry;
+        }
+        return null;
+    }
+    async set(query, result) {
+        const key = normalizeQuery(query);
+        this.store.set(key, {
+            query,
+            result,
+            cachedAt: new Date().toISOString(),
+            hits: 0,
+        });
+        logger.debug(`Cache set (memory): "${query}"`);
+    }
+    async clear() {
+        this.store.clear();
+    }
+    async size() {
+        return this.store.size;
+    }
+}
+// ─── File Cache ───────────────────────────────────────────────────────────────
+export class FileCache {
+    constructor(filePath = '.capman/cache.json') {
+        this.store = new Map();
+        this.loaded = false;
+        this.filePath = path.resolve(process.cwd(), filePath);
+        logger.info(`FileCache initialized — writing to: ${this.filePath}`);
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        try {
+            const raw = await fs.promises.readFile(this.filePath, 'utf-8');
+            this.store = new Map(Object.entries(JSON.parse(raw)));
+            logger.debug(`File cache loaded: ${this.store.size} entries`);
+        }
+        catch {
+            // File doesn't exist yet — start fresh
+        }
+        this.loaded = true;
+    }
+    async save() {
+        try {
+            const dir = path.dirname(this.filePath);
+            await fs.promises.mkdir(dir, { recursive: true });
+            await fs.promises.writeFile(this.filePath, JSON.stringify(Object.fromEntries(this.store), null, 2));
+        }
+        catch {
+            logger.warn(`Failed to save file cache to ${this.filePath}`);
+        }
+    }
+    async get(query) {
+        await this.load();
+        const key = normalizeQuery(query);
+        const entry = this.store.get(key);
+        if (entry) {
+            entry.hits++;
+            logger.debug(`Cache hit (file): "${query}"`);
+            return entry;
+        }
+        return null;
+    }
+    async set(query, result) {
+        await this.load();
+        const key = normalizeQuery(query);
+        this.store.set(key, {
+            query,
+            result,
+            cachedAt: new Date().toISOString(),
+            hits: 0,
+        });
+        await this.save();
+        logger.debug(`Cache set (file): "${query}"`);
+    }
+    async clear() {
+        this.store.clear();
+        await this.save();
+    }
+    async size() {
+        await this.load();
+        return this.store.size;
+    }
+}
+// ─── Combo Cache (memory first, file fallback) ────────────────────────────────
+export class ComboCache {
+    constructor(filePath = '.capman/cache.json') {
+        this.memory = new MemoryCache();
+        this.file = new FileCache(filePath);
+    }
+    async get(query) {
+        // Memory first — fastest
+        const memHit = await this.memory.get(query);
+        if (memHit)
+            return memHit;
+        // File fallback — persists across restarts
+        const fileHit = await this.file.get(query);
+        if (fileHit) {
+            // Promote to memory for next time
+            await this.memory.set(query, fileHit.result);
+            logger.debug(`Cache promoted to memory: "${query}"`);
+            return fileHit;
+        }
+        return null;
+    }
+    async set(query, result) {
+        await Promise.all([
+            this.memory.set(query, result),
+            this.file.set(query, result),
+        ]);
+    }
+    async clear() {
+        await Promise.all([
+            this.memory.clear(),
+            this.file.clear(),
+        ]);
+    }
+    async size() {
+        return this.file.size();
+    }
+}

package/dist/esm/engine.js

@@ -0,0 +1,228 @@
+import { match as _match, matchWithLLM as _matchWithLLM } from './matcher';
+import { resolve as _resolve } from './resolver';
+import { MemoryCache } from './cache';
+import { MemoryLearningStore } from './learning';
+import { logger } from './logger';
+// ─── CapmanEngine ─────────────────────────────────────────────────────────────
+export class CapmanEngine {
+    constructor(options) {
+        this.manifest = options.manifest;
+        this.mode = options.mode ?? 'balanced';
+        this.llm = options.llm;
+        this.baseUrl = options.baseUrl;
+        this.auth = options.auth;
+        this.headers = options.headers;
+        this.threshold = options.threshold ?? 50;
+        // Cache — default MemoryCache (no filesystem writes), or disabled with false
+        // Use FileCache or ComboCache explicitly for persistence across restarts
+        this.cache = options.cache === false
+            ? null
+            : (options.cache ?? new MemoryCache());
+        // Learning — default MemoryLearningStore (no filesystem writes), or disabled with false
+        // Use FileLearningStore explicitly for persistence across restarts
+        this.learning = options.learning === false
+            ? null
+            : (options.learning ?? new MemoryLearningStore());
+        logger.info(`CapmanEngine initialized — mode: ${this.mode}, cache: ${this.cache ? 'enabled' : 'disabled'}, learning: ${this.learning ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Ask the engine a natural language query.
+     * Automatically handles caching, matching, resolution, and learning.
+     *
+     * @example
+     * const engine = new CapmanEngine({ manifest, llm: myLLM })
+     * const result = await engine.ask("Check availability for blue jacket")
+     * console.log(result.match.capability?.id)  // check_product_availability
+     * console.log(result.resolution.apiCalls)   // [{ url: '...', method: 'GET' }]
+     * console.log(result.resolvedVia)           // 'keyword' | 'llm' | 'cache'
+     */
+    async ask(query, overrides = {}) {
+        const start = Date.now();
+        const steps = [];
+        let resolvedVia = 'keyword';
+        // ── Step 1: Check cache ──────────────────────────────────────────────────
+        const cacheStart = Date.now();
+        if (this.cache) {
+            const cached = await this.cache.get(query);
+            if (cached) {
+                steps.push({ type: 'cache_check', status: 'hit', durationMs: Date.now() - cacheStart, detail: 'Served from cache' });
+                logger.info(`Cache hit for: "${query}"`);
+                const resolution = await _resolve(cached.result, cached.result.extractedParams, this.resolveOptions(overrides));
+                const trace = {
+                    query,
+                    candidates: cached.result.candidates ?? [],
+                    reasoning: [`Served from cache (original: ${cached.result.reasoning})`],
+                    steps,
+                    resolvedVia: 'cache',
+                    totalMs: Date.now() - start,
+                };
+                const result = {
+                    match: cached.result,
+                    resolution,
+                    resolvedVia: 'cache',
+                    durationMs: Date.now() - start,
+                    trace,
+                };
+                await this.recordLearning(query, cached.result, 'cache');
+                return result;
+            }
+            steps.push({ type: 'cache_check', status: 'miss', durationMs: Date.now() - cacheStart });
+        }
+        else {
+            steps.push({ type: 'cache_check', status: 'skip', durationMs: 0, detail: 'Cache disabled' });
+        }
+        // ── Step 2: Match ────────────────────────────────────────────────────────
+        let matchResult;
+        switch (this.mode) {
+            case 'cheap': {
+                const t = Date.now();
+                matchResult = _match(query, this.manifest);
+                steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                break;
+            }
+            case 'accurate': {
+                if (this.llm) {
+                    const t = Date.now();
+                    matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                    resolvedVia = 'llm';
+                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                }
+                else {
+                    logger.warn('accurate mode requires llm — falling back to keyword');
+                    const t = Date.now();
+                    matchResult = _match(query, this.manifest);
+                    steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t, detail: 'llm not provided, used keyword' });
+                }
+                break;
+            }
+            case 'balanced':
+            default: {
+                const t1 = Date.now();
+                const keywordResult = _match(query, this.manifest);
+                steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t1, detail: `confidence: ${keywordResult.confidence}%` });
+                if (keywordResult.confidence >= this.threshold || !this.llm) {
+                    matchResult = keywordResult;
+                }
+                else {
+                    logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                    const t2 = Date.now();
+                    matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                    resolvedVia = 'llm';
+                    steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                }
+                break;
+            }
+        }
+        // ── Step 3: Privacy check ────────────────────────────────────────────────
+        if (matchResult.capability) {
+            const privacyLevel = matchResult.capability.privacy.level;
+            steps.push({
+                type: 'privacy_check',
+                status: 'pass',
+                durationMs: 0,
+                detail: `level: ${privacyLevel}`,
+            });
+        }
+        // ── Step 4: Cache the match result ───────────────────────────────────────
+        if (this.cache && matchResult.capability) {
+            await this.cache.set(query, matchResult);
+        }
+        // ── Step 5: Resolve ──────────────────────────────────────────────────────
+        const resolveStart = Date.now();
+        const resolution = await _resolve(matchResult, matchResult.extractedParams, this.resolveOptions(overrides));
+        steps.push({
+            type: 'resolve',
+            status: resolution.success ? 'pass' : 'fail',
+            durationMs: Date.now() - resolveStart,
+            detail: resolution.error ?? `via ${resolution.resolverType}`,
+        });
+        // ── Step 6: Build reasoning array ────────────────────────────────────────
+        const reasoning = [];
+        if (matchResult.candidates?.length) {
+            const winner = matchResult.candidates.find(c => c.matched);
+            const rejected = matchResult.candidates
+                .filter(c => !c.matched && c.score > 0)
+                .sort((a, b) => b.score - a.score)
+                .slice(0, 3);
+            if (winner) {
+                reasoning.push(`Matched "${winner.capabilityId}" with ${winner.score}% confidence`);
+            }
+            if (rejected.length) {
+                reasoning.push(`Rejected: ${rejected.map(r => `${r.capabilityId} (${r.score}%)`).join(', ')}`);
+            }
+            reasoning.push(`Resolved via: ${resolvedVia}`);
+            if (matchResult.extractedParams && Object.keys(matchResult.extractedParams).length) {
+                const params = Object.entries(matchResult.extractedParams)
+                    .map(([k, v]) => `${k}=${v}`)
+                    .join(', ');
+                reasoning.push(`Extracted params: ${params}`);
+            }
+        }
+        else {
+            reasoning.push(matchResult.reasoning);
+        }
+        // ── Step 7: Record learning ──────────────────────────────────────────────
+        await this.recordLearning(query, matchResult, resolvedVia);
+        const trace = {
+            query,
+            candidates: matchResult.candidates ?? [],
+            reasoning,
+            steps,
+            resolvedVia,
+            totalMs: Date.now() - start,
+        };
+        return {
+            match: matchResult,
+            resolution,
+            resolvedVia,
+            durationMs: Date.now() - start,
+            trace,
+        };
+    }
+    /**
+     * Get stats from the learning store.
+     * Shows which capabilities are most used, LLM vs keyword ratio, cache hit rate.
+     */
+    async getStats() {
+        if (!this.learning)
+            return null;
+        return this.learning.getStats();
+    }
+    /**
+     * Get the most frequently matched capabilities.
+     */
+    async getTopCapabilities(limit = 5) {
+        if (!this.learning)
+            return [];
+        return this.learning.getTopCapabilities(limit);
+    }
+    /**
+     * Clear the cache.
+     */
+    async clearCache() {
+        if (this.cache)
+            await this.cache.clear();
+    }
+    // ── Private helpers ────────────────────────────────────────────────────────
+    resolveOptions(overrides = {}) {
+        return {
+            baseUrl: this.baseUrl,
+            auth: this.auth,
+            headers: this.headers,
+            ...overrides,
+        };
+    }
+    async recordLearning(query, matchResult, resolvedVia) {
+        if (!this.learning)
+            return;
+        await this.learning.record({
+            query,
+            capabilityId: matchResult.capability?.id ?? null,
+            confidence: matchResult.confidence,
+            intent: matchResult.intent,
+            extractedParams: matchResult.extractedParams,
+            resolvedVia,
+            timestamp: new Date().toISOString(),
+        });
+    }
+}

package/dist/esm/generator.js

@@ -1,10 +1,11 @@
+import { VERSION } from './version';
 import * as fs from 'fs';
 import * as path from 'path';
 import { validateConfig, validateManifest } from './schema';
 import { logger } from './logger';
 export function generate(config) {
     return {
-        version: '0.2.0',
+        version: VERSION,
         app: config.app,
         generatedAt: new Date().toISOString(),
         capabilities: config.capabilities,

package/dist/esm/index.js

@@ -6,6 +6,12 @@ export { resolve } from './resolver';
 // ─── Convenience: ask() — match + resolve in one call ────────────────────────
 import { match as _match, matchWithLLM as _matchWithLLM } from './matcher';
 import { resolve as _resolve } from './resolver';
+// ─── Engine (recommended API) ─────────────────────────────────────────────────
+export { CapmanEngine } from './engine';
+// ─── Cache ────────────────────────────────────────────────────────────────────
+export { MemoryCache, FileCache, ComboCache } from './cache';
+// ─── Learning ─────────────────────────────────────────────────────────────────
+export { FileLearningStore, MemoryLearningStore } from './learning';
 /**
  * One-shot convenience: match + resolve in a single call.
  *

package/dist/esm/learning.js

@@ -0,0 +1,116 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from './logger';
+// ─── Shared computation helpers ───────────────────────────────────────────────
+function computeStats(entries) {
+    const index = {};
+    let totalQueries = 0;
+    let llmQueries = 0;
+    let cacheHits = 0;
+    let outOfScope = 0;
+    for (const entry of entries) {
+        totalQueries++;
+        if (entry.resolvedVia === 'llm')
+            llmQueries++;
+        if (entry.resolvedVia === 'cache')
+            cacheHits++;
+        if (!entry.capabilityId)
+            outOfScope++;
+        if (entry.capabilityId) {
+            const words = entry.query.toLowerCase()
+                .split(/\W+/)
+                .filter(w => w.length > 2);
+            for (const word of words) {
+                if (!index[word])
+                    index[word] = {};
+                index[word][entry.capabilityId] =
+                    (index[word][entry.capabilityId] ?? 0) + 1;
+            }
+        }
+    }
+    return { index, totalQueries, llmQueries, cacheHits, outOfScope };
+}
+function computeTopCapabilities(entries, limit) {
+    const counts = {};
+    for (const entry of entries) {
+        if (entry.capabilityId) {
+            counts[entry.capabilityId] = (counts[entry.capabilityId] ?? 0) + 1;
+        }
+    }
+    return Object.entries(counts)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, limit)
+        .map(([id, hits]) => ({ id, hits }));
+}
+// ─── File Learning Store ──────────────────────────────────────────────────────
+export class FileLearningStore {
+    constructor(filePath = '.capman/learning.json') {
+        this.entries = [];
+        this.loaded = false;
+        this.filePath = path.resolve(process.cwd(), filePath);
+        logger.info(`FileLearningStore initialized — writing to: ${this.filePath}`);
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        try {
+            const raw = await fs.promises.readFile(this.filePath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            this.entries = parsed.entries ?? [];
+            logger.debug(`Learning store loaded: ${this.entries.length} entries`);
+        }
+        catch {
+            // File doesn't exist yet — start fresh
+        }
+        this.loaded = true;
+    }
+    async save() {
+        try {
+            const dir = path.dirname(this.filePath);
+            await fs.promises.mkdir(dir, { recursive: true });
+            await fs.promises.writeFile(this.filePath, JSON.stringify({
+                entries: this.entries,
+                updatedAt: new Date().toISOString(),
+            }, null, 2));
+        }
+        catch {
+            logger.warn(`Failed to save learning store to ${this.filePath}`);
+        }
+    }
+    async record(entry) {
+        await this.load();
+        this.entries.push(entry);
+        await this.save();
+        logger.debug(`Learning recorded: "${entry.query}" → ${entry.capabilityId ?? 'OUT_OF_SCOPE'} via ${entry.resolvedVia}`);
+    }
+    async getStats() {
+        await this.load();
+        return computeStats(this.entries);
+    }
+    async getTopCapabilities(limit = 5) {
+        await this.load();
+        return computeTopCapabilities(this.entries, limit);
+    }
+    async clear() {
+        this.entries = [];
+        await this.save();
+    }
+}
+// ─── Memory Learning Store (for testing) ─────────────────────────────────────
+export class MemoryLearningStore {
+    constructor() {
+        this.entries = [];
+    }
+    async record(entry) {
+        this.entries.push(entry);
+    }
+    async getStats() {
+        return computeStats(this.entries);
+    }
+    async getTopCapabilities(limit = 5) {
+        return computeTopCapabilities(this.entries, limit);
+    }
+    async clear() {
+        this.entries = [];
+    }
+}

package/dist/esm/matcher.js

@@ -76,19 +76,41 @@ function extractParams(query, cap) {
         // e.g. "profile for johndoe" → johndoe
         //      "articles by jane"   → jane
         //      "tag javascript"     → javascript
+        // Use param name and description as hints for what to look for
+        const paramHints = [param.name, ...param.description.toLowerCase().split(/\s+/)]
+            .filter(w => w.length > 2);
+        // Try keyword-based extraction first
         const keywords = [
             `for `, `by `, `about `, `named `, `called `,
             `tag `, `user `, `author `, `slug `, `id `,
-            `to `, `from `, `with `,
+            `from `, `with `,
         ];
+        // For nav params — look for destination after navigation verbs
+        const navKeywords = [`to `, `open `, `show `];
+        const isNavParam = param.name === 'destination' ||
+            param.description.toLowerCase().includes('screen') ||
+            param.description.toLowerCase().includes('page');
+        const activeKeywords = isNavParam
+            ? [...navKeywords, ...keywords]
+            : keywords;
         let extracted = null;
-        for (const kw of keywords) {
+        for (const kw of activeKeywords) {
             const idx = q.indexOf(kw);
             if (idx !== -1) {
                 const after = query.slice(idx + kw.length).trim();
-                const token = after.split(/\s+/)[0];
-                if (token && token.length > 1) {
-                    extracted = token.replace(/[^a-zA-Z0-9-_@.]/g, '');
+                // Get remaining words, filter stopwords, take first meaningful one
+                const tokens = after.split(/\s+/)
+                    .map(t => t.replace(/[^a-zA-Z0-9-_@.]/g, ''))
+                    .filter(t => t.length > 1 && !STOPWORDS.has(t.toLowerCase()));
+                if (tokens.length > 0) {
+                    // For IDs and numbers — single token is correct
+                    const isIdParam = param.name === 'id' ||
+                        param.name.endsWith('_id') ||
+                        param.name.endsWith('Id') ||
+                        /^\s*\w+\s+id\b/i.test(param.description) ||
+                        /^id\b/i.test(param.description);
+                    // For names, products, destinations — grab multi-word phrase
+                    extracted = (isIdParam || isNavParam) ? tokens[0] : tokens.join('-').toLowerCase();
                     break;
                 }
             }
@@ -118,33 +140,44 @@ export function match(query, manifest) {
     logger.debug(`Manifest has ${manifest.capabilities.length} capabilities`);
     let best = null;
     let bestScore = 0;
+    const allScores = [];
     for (const cap of manifest.capabilities) {
         const score = scoreCapability(query, cap);
         logger.debug(`  scored "${cap.id}": ${score}%`);
+        allScores.push({ cap, score });
         if (score > bestScore) {
             bestScore = score;
             best = cap;
         }
     }
+    const candidates = allScores.map(({ cap, score }) => ({
+        capabilityId: cap.id,
+        score,
+        matched: cap.id === best?.id,
+    }));
     if (!best || bestScore < 50) {
         logger.info(`No match above threshold (best: ${bestScore}% for "${best?.id ?? 'none'}")`);
+        // Out of scope return:
         return {
             capability: null,
             confidence: bestScore,
             intent: 'out_of_scope',
             extractedParams: {},
             reasoning: `No capability matched with sufficient confidence (best score: ${bestScore})`,
+            candidates,
         };
     }
     const params = extractParams(query, best);
     logger.info(`Matched "${best.id}" at ${bestScore}% confidence`);
     logger.debug(`Extracted params: ${JSON.stringify(params)}`);
+    // Matched return:
     return {
         capability: best,
         confidence: bestScore,
         intent: resolverToIntent(best),
         extractedParams: params,
         reasoning: `Matched "${best.id}" via keyword scoring (score: ${bestScore})`,
+        candidates,
     };
 }
 export async function matchWithLLM(query, manifest, options) {