capman 0.2.0 → 0.4.0

package/bin/capman.js

@@ -32,8 +32,9 @@ 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()
 }
@@ -42,13 +43,20 @@ function requireSrc() {
   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/cjs/. Run: pnpm run build')
-    process.exit(1)
+    // build failed
   }
+
+  log.error('Cannot find dist/cjs/. Run: pnpm run build')
+  process.exit(1)
 }
 
 function cmdHelp() {
@@ -60,11 +68,14 @@ 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(`    ${c.teal}run${c.reset}       Run a query against your manifest`)
   console.log()
   console.log(`${c.bold}  Options:${c.reset}`)
   console.log(`    ${c.gray}--config    Path to config file  (default: capman.config.js)${c.reset}`)
   console.log(`    ${c.gray}--out       Output path          (default: manifest.json)${c.reset}`)
   console.log(`    ${c.gray}--manifest  Manifest to read     (default: manifest.json)${c.reset}`)
+  console.log(`    ${c.gray}Options: --debug (show all candidates)${c.reset}`)
   console.log()
 }
 
@@ -176,11 +187,216 @@ 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`)
+}
+
+function cmdRun() {
+  header()
+  const query = args[1]
+  const debug = flags.includes('--debug')
+  const manifestPath = getFlag('--manifest') ?? 'manifest.json'
+
+  if (!query) {
+    log.error('Please provide a query. Example: node bin/capman.js run "show me articles"')
+    process.exit(1)
+  }
+
+  const { readManifest, match } = requireSrc()
+
+  let manifest
+  try {
+    manifest = readManifest(manifestPath)
+  } catch (e) {
+    log.error(e.message)
+    process.exit(1)
+  }
+
+  log.info(`Query: "${query}"`)
+  log.blank()
+
+  const result = match(query, manifest)
+
+  if (result.capability) {
+    console.log(`  ${c.green}✓${c.reset}  Matched: ${c.bold}${result.capability.id}${c.reset}`)
+    console.log(`     Intent:     ${result.intent}`)
+    console.log(`     Confidence: ${result.confidence}%`)
+    console.log(`     Resolver:   ${result.capability.resolver.type}`)
+
+    if (Object.keys(result.extractedParams).length > 0) {
+      const params = Object.entries(result.extractedParams)
+        .map(([k, v]) => `${k}=${v}`)
+        .join(', ')
+      console.log(`     Params:     ${params}`)
+    }
+
+    if (debug && result.candidates?.length) {
+      log.blank()
+      console.log(`  ${c.gray}── All candidates:${c.reset}`)
+      result.candidates
+        .sort((a, b) => b.score - a.score)
+        .forEach(c2 => {
+          const marker = c2.matched ? c.green + '✓' : c.gray + '○'
+          console.log(`     ${marker}${c.reset}  ${c2.capabilityId}: ${c2.score}%`)
+        })
+    }
+  } else {
+    console.log(`  ${c.yellow}○${c.reset}  OUT_OF_SCOPE — no capability matched`)
+    console.log(`     ${c.gray}${result.reasoning}${c.reset}`)
+
+    if (debug && result.candidates?.length) {
+      log.blank()
+      console.log(`  ${c.gray}── All candidates:${c.reset}`)
+      result.candidates
+        .sort((a, b) => b.score - a.score)
+        .slice(0, 5)
+        .forEach(c2 => {
+          console.log(`     ${c.gray}○  ${c2.capabilityId}: ${c2.score}%${c.reset}`)
+        })
+    }
+  }
+  console.log()
+}
+
 switch (command) {
   case 'init':     cmdInit();     break
   case 'generate': cmdGenerate(); break
   case 'validate': cmdValidate(); break
   case 'inspect':  cmdInspect();  break
+  case 'demo':     cmdDemo();     break
+  case 'run':      cmdRun();      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;YAK7B,IAAI;YAYJ,IAAI;IAaZ,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;IAiB9C,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,179 @@
+"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);
+        logger_1.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_1.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_1.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_1.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_1.logger.debug(`Cache set (file): "${query}"`);
+    }
+    async clear() {
+        this.store.clear();
+        await this.save();
+    }
+    async size() {
+        await 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);
+            logger_1.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();
+    }
+}
+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, ExecutionTrace } 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;
+    resolvedVia: 'cache' | 'keyword' | 'llm';
+    durationMs: number;
+    /** Full execution trace — always present */
+    trace: ExecutionTrace;
+}
+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,cAAc,EAAa,MAAM,SAAS,CAAA;AAC9F,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,WAAW,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,CAAA;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,KAAK,EAAE,cAAc,CAAA;CACtB;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;IAwBlC;;;;;;;;;;OAUG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAkKxF;;;OAGG;IACG,QAAQ;IAKd;;OAEG;IACG,kBAAkB,CAAC,KAAK,SAAI;;;;IAKlC;;OAEG;IACG,UAAU;IAMhB,OAAO,CAAC,cAAc;YASR,cAAc;CAgB7B"}