capman 0.1.0 → 0.3.0

package/bin/capman.js

@@ -32,23 +32,31 @@ const log = {
 }
 
 function header() {
+  const pkg = require(path.join(__dirname, '..', 'package.json'))
   console.log()
-  console.log(`${c.bold}${c.teal}  capman${c.reset} ${c.gray}v0.1.0 — Capability Manifest Engine${c.reset}`)
+  console.log(`${c.bold}${c.teal}  capman${c.reset} ${c.gray}v${pkg.version} — Capability Manifest Engine${c.reset}`)
   console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}`)
   console.log()
 }
 
 function requireSrc() {
-  const distPath = path.join(__dirname, '..', 'dist', 'index.js')
+  const distPath = path.join(__dirname, '..', 'dist', 'cjs', 'index.js')
   if (fs.existsSync(distPath)) return require(distPath)
 
+  // dist not built — try to build automatically
+  log.info('dist/cjs not found — running build...')
   try {
-    require('ts-node/register')
-    return require(path.join(__dirname, '..', 'src', 'index.ts'))
+    require('child_process').execSync('npm run build', {
+      cwd: path.join(__dirname, '..'),
+      stdio: 'inherit'
+    })
+    if (fs.existsSync(distPath)) return require(distPath)
   } catch {
-    log.error('Cannot find dist/. Run: npx tsc')
-    process.exit(1)
+    // build failed
   }
+
+  log.error('Cannot find dist/cjs/. Run: pnpm run build')
+  process.exit(1)
 }
 
 function cmdHelp() {
@@ -60,6 +68,7 @@ function cmdHelp() {
   console.log(`    ${c.teal}generate${c.reset}  Generate manifest.json from config`)
   console.log(`    ${c.teal}validate${c.reset}  Validate an existing manifest.json`)
   console.log(`    ${c.teal}inspect${c.reset}   Print all capabilities in manifest`)
+  console.log(`    ${c.teal}demo${c.reset}      Run a live demo with sample queries`)
   console.log()
   console.log(`${c.bold}  Options:${c.reset}`)
   console.log(`    ${c.gray}--config    Path to config file  (default: capman.config.js)${c.reset}`)
@@ -176,11 +185,148 @@ function cmdInspect() {
   }
 }
 
+function cmdDemo() {
+  header()
+  const { generate, match, resolve } = requireSrc()
+
+  console.log(`${c.bold}  Live demo — see capman in action${c.reset}`)
+  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}\n`)
+
+  // Demo manifest — generic e-commerce app
+  const config = {
+    app: 'demo-store',
+    baseUrl: 'https://api.demo-store.com',
+    capabilities: [
+      {
+        id: 'check_product_availability',
+        name: 'Check product availability',
+        description: 'Check stock and pricing for a product by name or ID.',
+        examples: [
+          'Is the blue jacket in stock?',
+          'Check stock for blue jacket',
+          'Do you have size M available?',
+          'Product availability for jacket',
+          'Is jacket available?',
+        ],
+        params: [
+          { name: 'product', description: 'Product name or ID', required: true, source: 'user_query' }
+        ],
+        returns: ['stock', 'price', 'variants'],
+        resolver: { type: 'api', endpoints: [{ method: 'GET', path: '/products/{product}/availability' }] },
+        privacy: { level: 'public' },
+      },
+      {
+        id: 'get_order_status',
+        name: 'Get order status',
+        description: 'Retrieve the current status and tracking info for an order.',
+        examples: [
+          'Where is my order?',
+          'Track order 1234',
+          'What is the status of my recent purchase?',
+        ],
+        params: [
+          { name: 'order_id', description: 'Order ID', required: true, source: 'user_query' }
+        ],
+        returns: ['status', 'tracking', 'estimated_delivery'],
+        resolver: { type: 'api', endpoints: [{ method: 'GET', path: '/orders/{order_id}' }] },
+        privacy: { level: 'user_owned' },
+      },
+      {
+        id: 'navigate_to_screen',
+        name: 'Navigate to screen',
+        description: 'Route the user to a specific page in the store.',
+        examples: [
+          'Take me to cart',
+          'Open cart',
+          'Go to checkout',
+          'Navigate to account',
+          'Show homepage',
+        ],
+        params: [
+          { name: 'destination', description: 'Target screen', required: true, source: 'user_query' }
+        ],
+        returns: ['deep_link'],
+        resolver: { type: 'nav', destination: '/{destination}' },
+        privacy: { level: 'public' },
+      },
+    ],
+  }
+
+  const manifest = generate(config)
+
+  const queries = [
+    'Check availability for blue jacket',
+    'Track order 1234',
+    'Go to cart',
+    'Is the website down?',
+  ]
+
+  console.log(`${c.gray}  App: ${c.reset}${c.bold}${config.app}${c.reset}`)
+  console.log(`${c.gray}  Capabilities: ${c.reset}${manifest.capabilities.length}`)
+  console.log(`${c.gray}  Mode: keyword matcher (no LLM required)\n${c.reset}`)
+
+  let passed = 0
+  let outOfScope = 0
+
+  for (const query of queries) {
+    const start = Date.now()
+    const result = match(query, manifest)
+    const duration = Date.now() - start
+
+    if (result.capability) {
+      passed++
+      const resolverColor = result.capability.resolver.type === 'api' ? c.teal :
+                            result.capability.resolver.type === 'nav' ? c.teal : c.yellow
+
+      console.log(`  ${c.green}✓${c.reset}  ${c.bold}"${query}"${c.reset}`)
+      console.log(`     ${c.gray}→ matched:${c.reset}    ${resolverColor}${result.capability.id}${c.reset}`)
+      console.log(`     ${c.gray}→ intent:${c.reset}     ${result.intent}`)
+      console.log(`     ${c.gray}→ confidence:${c.reset} ${result.confidence}%`)
+
+      if (Object.keys(result.extractedParams).length > 0) {
+        const params = Object.entries(result.extractedParams)
+          .map(([k, v]) => `${k}=${v}`)
+          .join(', ')
+        console.log(`     ${c.gray}→ params:${c.reset}     ${params}`)
+      }
+
+      // Show what API call would be made
+      if (result.capability.resolver.type === 'api') {
+        const endpoint = result.capability.resolver.endpoints[0]
+        let path = endpoint.path
+        for (const [k, v] of Object.entries(result.extractedParams)) {
+          if (v) path = path.replace(`{${k}}`, v)
+        }
+        console.log(`     ${c.gray}→ api call:${c.reset}   ${endpoint.method} ${config.baseUrl}${path}`)
+      } else if (result.capability.resolver.type === 'nav') {
+        let dest = result.capability.resolver.destination
+        for (const [k, v] of Object.entries(result.extractedParams)) {
+          if (v) dest = dest.replace(`{${k}}`, v)
+        }
+        console.log(`     ${c.gray}→ nav target:${c.reset}  ${dest}`)
+      }
+
+      console.log(`     ${c.gray}→ time:${c.reset}       ${duration}ms\n`)
+    } else {
+      outOfScope++
+      console.log(`  ${c.yellow}○${c.reset}  ${c.bold}"${query}"${c.reset}`)
+      console.log(`     ${c.gray}→ out of scope — no capability handles this\n${c.reset}`)
+    }
+  }
+
+  console.log(`${c.gray}  ─────────────────────────────────────────${c.reset}`)
+  console.log(`  ${c.green}${passed} matched${c.reset}  ${c.gray}·${c.reset}  ${c.yellow}${outOfScope} out of scope${c.reset}  ${c.gray}·${c.reset}  ${manifest.capabilities.length} capabilities\n`)
+  console.log(`  ${c.gray}Try it on your own app:${c.reset}`)
+  console.log(`  ${c.teal}npx capman init${c.reset}  ${c.gray}→ create your manifest${c.reset}`)
+  console.log(`  ${c.teal}npx capman generate${c.reset}  ${c.gray}→ generate manifest.json${c.reset}\n`)
+}
+
 switch (command) {
   case 'init':     cmdInit();     break
   case 'generate': cmdGenerate(); break
   case 'validate': cmdValidate(); break
   case 'inspect':  cmdInspect();  break
+  case 'demo':     cmdDemo();     break
   case undefined:
   case '--help':
   case '-h':       cmdHelp();     break

package/dist/cjs/cache.d.ts

@@ -0,0 +1,42 @@
+import type { MatchResult } from './types';
+export interface CacheEntry {
+    query: string;
+    result: MatchResult;
+    cachedAt: string;
+    hits: number;
+}
+export interface CacheStore {
+    get(query: string): Promise<CacheEntry | null>;
+    set(query: string, result: MatchResult): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+export declare class MemoryCache implements CacheStore {
+    private store;
+    get(query: string): Promise<CacheEntry | null>;
+    set(query: string, result: MatchResult): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+export declare class FileCache implements CacheStore {
+    private filePath;
+    private store;
+    private loaded;
+    constructor(filePath?: string);
+    private load;
+    private save;
+    get(query: string): Promise<CacheEntry | null>;
+    set(query: string, result: MatchResult): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+export declare class ComboCache implements CacheStore {
+    private memory;
+    private file;
+    constructor(filePath?: string);
+    get(query: string): Promise<CacheEntry | null>;
+    set(query: string, result: MatchResult): Promise<void>;
+    clear(): Promise<void>;
+    size(): Promise<number>;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cjs/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../src/cache.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AAK1C,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAID,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAA;IAC9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;CACxB;AAUD,qBAAa,WAAY,YAAW,UAAU;IAC5C,OAAO,CAAC,KAAK,CAAgC;IAEvC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAW9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAWtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B;AAID,qBAAa,SAAU,YAAW,UAAU;IAC1C,OAAO,CAAC,QAAQ,CAAQ;IACxB,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,MAAM,CAAQ;gBAEV,QAAQ,SAAuB;IAI3C,OAAO,CAAC,IAAI;IAcZ,OAAO,CAAC,IAAI;IAWN,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAY9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAatD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAI9B;AAID,qBAAa,UAAW,YAAW,UAAU;IAC3C,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,IAAI,CAAW;gBAEX,QAAQ,SAAuB;IAKrC,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAgB9C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;CAG9B"}

package/dist/cjs/cache.js

@@ -0,0 +1,181 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComboCache = exports.FileCache = exports.MemoryCache = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logger_1 = require("./logger");
+// ─── Normalize query for cache key ────────────────────────────────────────────
+function normalizeQuery(query) {
+    return query.toLowerCase().trim().replace(/\s+/g, ' ');
+}
+// ─── Memory Cache ─────────────────────────────────────────────────────────────
+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_1.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_1.logger.debug(`Cache set (memory): "${query}"`);
+    }
+    async clear() {
+        this.store.clear();
+    }
+    async size() {
+        return this.store.size;
+    }
+}
+exports.MemoryCache = MemoryCache;
+// ─── File Cache ───────────────────────────────────────────────────────────────
+class FileCache {
+    constructor(filePath = '.capman/cache.json') {
+        this.store = new Map();
+        this.loaded = false;
+        this.filePath = path.resolve(process.cwd(), filePath);
+    }
+    load() {
+        if (this.loaded)
+            return;
+        try {
+            if (fs.existsSync(this.filePath)) {
+                const raw = JSON.parse(fs.readFileSync(this.filePath, 'utf-8'));
+                this.store = new Map(Object.entries(raw));
+                logger_1.logger.debug(`File cache loaded: ${this.store.size} entries`);
+            }
+        }
+        catch {
+            logger_1.logger.warn(`Failed to load file cache at ${this.filePath}`);
+        }
+        this.loaded = true;
+    }
+    save() {
+        try {
+            const dir = path.dirname(this.filePath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            const obj = Object.fromEntries(this.store);
+            fs.writeFileSync(this.filePath, JSON.stringify(obj, null, 2));
+        }
+        catch {
+            logger_1.logger.warn(`Failed to save file cache to ${this.filePath}`);
+        }
+    }
+    async get(query) {
+        this.load();
+        const key = normalizeQuery(query);
+        const entry = this.store.get(key);
+        if (entry) {
+            entry.hits++;
+            logger_1.logger.debug(`Cache hit (file): "${query}"`);
+            return entry;
+        }
+        return null;
+    }
+    async set(query, result) {
+        this.load();
+        const key = normalizeQuery(query);
+        this.store.set(key, {
+            query,
+            result,
+            cachedAt: new Date().toISOString(),
+            hits: 0,
+        });
+        this.save();
+        logger_1.logger.debug(`Cache set (file): "${query}"`);
+    }
+    async clear() {
+        this.store.clear();
+        this.save();
+    }
+    async size() {
+        this.load();
+        return this.store.size;
+    }
+}
+exports.FileCache = FileCache;
+// ─── Combo Cache (memory first, file fallback) ────────────────────────────────
+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);
+            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();
+    }
+}
+exports.ComboCache = ComboCache;
+//# sourceMappingURL=cache.js.map

package/dist/cjs/cache.js.map

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

package/dist/cjs/engine.d.ts

@@ -0,0 +1,82 @@
+import type { Manifest, MatchResult, ResolveResult } from './types';
+import type { LLMMatcherOptions } from './matcher';
+import type { ResolveOptions, AuthContext } from './resolver';
+import type { CacheStore } from './cache';
+import type { LearningStore } from './learning';
+import type { MatchMode } from './index';
+export interface EngineOptions {
+    /** The capability manifest to use */
+    manifest: Manifest;
+    /**
+     * Matching mode
+     * - 'cheap'    — keyword only, no LLM
+     * - 'balanced' — keyword first, LLM fallback (default)
+     * - 'accurate' — LLM first, keyword fallback
+     */
+    mode?: MatchMode;
+    /** LLM function for accurate/balanced matching */
+    llm?: LLMMatcherOptions['llm'];
+    /** Cache store — defaults to ComboCache (memory + file) */
+    cache?: CacheStore | false;
+    /** Learning store — defaults to FileLearningStore */
+    learning?: LearningStore | false;
+    /** Base URL for API resolvers */
+    baseUrl?: string;
+    /** Auth context for privacy-scoped capabilities */
+    auth?: AuthContext;
+    /** Custom headers for API calls */
+    headers?: Record<string, string>;
+    /** Confidence threshold for keyword matcher (default: 50) */
+    threshold?: number;
+}
+export interface EngineResult {
+    match: MatchResult;
+    resolution: ResolveResult;
+    /** How the match was resolved */
+    resolvedVia: 'cache' | 'keyword' | 'llm';
+    /** Total time in milliseconds */
+    durationMs: number;
+}
+export declare class CapmanEngine {
+    private manifest;
+    private mode;
+    private llm?;
+    private cache;
+    private learning;
+    private baseUrl?;
+    private auth?;
+    private headers?;
+    private threshold;
+    constructor(options: EngineOptions);
+    /**
+     * 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'
+     */
+    ask(query: string, overrides?: Partial<ResolveOptions>): Promise<EngineResult>;
+    /**
+     * Get stats from the learning store.
+     * Shows which capabilities are most used, LLM vs keyword ratio, cache hit rate.
+     */
+    getStats(): Promise<import("./learning").KeywordStats | null>;
+    /**
+     * Get the most frequently matched capabilities.
+     */
+    getTopCapabilities(limit?: number): Promise<{
+        id: string;
+        hits: number;
+    }[]>;
+    /**
+     * Clear the cache.
+     */
+    clearCache(): Promise<void>;
+    private resolveOptions;
+    private recordLearning;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/cjs/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACnE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,YAAY,CAAA;AAM9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAIxC,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,EAAE,QAAQ,CAAA;IAClB;;;;;OAKG;IACH,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,kDAAkD;IAClD,GAAG,CAAC,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAA;IAC9B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,UAAU,GAAG,KAAK,CAAA;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,EAAE,aAAa,GAAG,KAAK,CAAA;IAChC,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,mDAAmD;IACnD,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAID,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,WAAW,CAAA;IAClB,UAAU,EAAE,aAAa,CAAA;IACzB,iCAAiC;IACjC,WAAW,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,CAAA;IACxC,iCAAiC;IACjC,UAAU,EAAE,MAAM,CAAA;CACnB;AAID,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,GAAG,CAAC,CAA+B;IAC3C,OAAO,CAAC,KAAK,CAAuB;IACpC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,OAAO,CAAC,CAAS;IACzB,OAAO,CAAC,IAAI,CAAC,CAAiB;IAC9B,OAAO,CAAC,OAAO,CAAC,CAAyB;IACzC,OAAO,CAAC,SAAS,CAAQ;gBAEb,OAAO,EAAE,aAAa;IAsBlC;;;;;;;;;;OAUG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAkFxF;;;OAGG;IACG,QAAQ;IAKd;;OAEG;IACG,kBAAkB,CAAC,KAAK,SAAI;;;;IAKlC;;OAEG;IACG,UAAU;IAMhB,OAAO,CAAC,cAAc;YASR,cAAc;CAgB7B"}

package/dist/cjs/engine.js

@@ -0,0 +1,154 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CapmanEngine = void 0;
+const matcher_1 = require("./matcher");
+const resolver_1 = require("./resolver");
+const cache_1 = require("./cache");
+const learning_1 = require("./learning");
+const logger_1 = require("./logger");
+// ─── CapmanEngine ─────────────────────────────────────────────────────────────
+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 ComboCache, or disabled with false
+        this.cache = options.cache === false
+            ? null
+            : (options.cache ?? new cache_1.ComboCache());
+        // Learning — default FileLearningStore, or disabled with false
+        this.learning = options.learning === false
+            ? null
+            : (options.learning ?? new learning_1.FileLearningStore());
+        logger_1.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();
+        // ── Step 1: Check cache ──────────────────────────────────────────────────
+        if (this.cache) {
+            const cached = await this.cache.get(query);
+            if (cached) {
+                logger_1.logger.info(`Cache hit for: "${query}"`);
+                const resolution = await (0, resolver_1.resolve)(cached.result, cached.result.extractedParams, this.resolveOptions(overrides));
+                const result = {
+                    match: cached.result,
+                    resolution,
+                    resolvedVia: 'cache',
+                    durationMs: Date.now() - start,
+                };
+                await this.recordLearning(query, cached.result, 'cache');
+                return result;
+            }
+        }
+        // ── Step 2: Match ────────────────────────────────────────────────────────
+        let matchResult;
+        let resolvedVia = 'keyword';
+        switch (this.mode) {
+            case 'cheap': {
+                matchResult = (0, matcher_1.match)(query, this.manifest);
+                break;
+            }
+            case 'accurate': {
+                if (this.llm) {
+                    matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
+                    resolvedVia = 'llm';
+                }
+                else {
+                    logger_1.logger.warn('accurate mode requires llm — falling back to keyword');
+                    matchResult = (0, matcher_1.match)(query, this.manifest);
+                }
+                break;
+            }
+            case 'balanced':
+            default: {
+                const keywordResult = (0, matcher_1.match)(query, this.manifest);
+                if (keywordResult.confidence >= this.threshold || !this.llm) {
+                    matchResult = keywordResult;
+                }
+                else {
+                    logger_1.logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                    matchResult = await (0, matcher_1.matchWithLLM)(query, this.manifest, { llm: this.llm });
+                    resolvedVia = 'llm';
+                }
+                break;
+            }
+        }
+        // ── Step 3: Cache the match result ───────────────────────────────────────
+        if (this.cache && matchResult.capability) {
+            await this.cache.set(query, matchResult);
+        }
+        // ── Step 4: Resolve ──────────────────────────────────────────────────────
+        const resolution = await (0, resolver_1.resolve)(matchResult, matchResult.extractedParams, this.resolveOptions(overrides));
+        // ── Step 5: Record learning ──────────────────────────────────────────────
+        await this.recordLearning(query, matchResult, resolvedVia);
+        return {
+            match: matchResult,
+            resolution,
+            resolvedVia,
+            durationMs: Date.now() - start,
+        };
+    }
+    /**
+     * 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(),
+        });
+    }
+}
+exports.CapmanEngine = CapmanEngine;
+//# sourceMappingURL=engine.js.map