capman 0.4.2 → 0.4.4

package/dist/esm/engine.d.ts

@@ -0,0 +1,138 @@
+import type { Manifest, MatchResult, ResolveResult, ExecutionTrace, ExplainResult } 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 MemoryCache. Use FileCache or ComboCache for persistence. */
+    cache?: CacheStore | false;
+    /** Learning store — defaults to MemoryLearningStore. Use FileLearningStore for persistence. */
+    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;
+    /**
+     * Maximum LLM calls per minute in balanced/accurate mode.
+     * After limit is hit, falls back to keyword result.
+     * @default 60
+     */
+    maxLLMCallsPerMinute?: number;
+    /**
+     * Minimum milliseconds between consecutive LLM calls.
+     * Useful for free-tier models with burst limits.
+     * @default 0
+     */
+    llmCooldownMs?: number;
+    /**
+     * Maximum consecutive LLM failures before circuit breaker opens.
+     * When open, LLM calls are skipped for llmCircuitBreakerResetMs.
+     * @default 3
+     */
+    llmCircuitBreakerThreshold?: number;
+    /**
+     * Milliseconds to wait before retrying LLM after circuit breaker opens.
+     * @default 60000
+     */
+    llmCircuitBreakerResetMs?: 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;
+    private maxLLMCallsPerMinute;
+    private llmCooldownMs;
+    private llmCircuitBreakerThreshold;
+    private llmCircuitBreakerResetMs;
+    private llmCallsThisMinute;
+    private llmWindowStart;
+    private llmLastCallAt;
+    private llmConsecutiveFails;
+    private llmCircuitOpenAt;
+    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>;
+    /**
+     * Explain what would happen for a query — without executing it.
+     * Shows matched capability, all candidate scores with reasoning,
+     * and what action would be taken.
+     *
+     * @example
+     * const explanation = await engine.explain('track order 1234')
+     * console.log(explanation.matched.reasoning)
+     * console.log(explanation.wouldExecute.action)
+     * console.log(explanation.candidates)
+     */
+    explain(query: string): Promise<ExplainResult>;
+    /**
+     * Checks all rate limiting and circuit breaker conditions.
+     * Returns null if LLM call is allowed, or a skip reason string if it should be skipped.
+     */
+    private checkLLMAllowed;
+    /**
+     * Records a successful LLM call — updates rate limit counters.
+     */
+    private recordLLMSuccess;
+    /**
+     * Records a failed LLM call — may open the circuit breaker.
+     */
+    private recordLLMFailure;
+    private resolveOptions;
+    private recordLearning;
+}

package/dist/esm/engine.js

@@ -6,6 +6,12 @@ import { MemoryCache, normalizeQuery } from './cache';
 // ─── CapmanEngine ─────────────────────────────────────────────────────────────
 export class CapmanEngine {
     constructor(options) {
+        // ── LLM rate limiting state ────────────────────────────────────────────────
+        this.llmCallsThisMinute = 0;
+        this.llmWindowStart = Date.now();
+        this.llmLastCallAt = 0;
+        this.llmConsecutiveFails = 0;
+        this.llmCircuitOpenAt = 0;
         this.manifest = options.manifest;
         this.mode = options.mode ?? 'balanced';
         this.llm = options.llm;
@@ -13,6 +19,10 @@ export class CapmanEngine {
         this.auth = options.auth;
         this.headers = options.headers;
         this.threshold = options.threshold ?? 50;
+        this.maxLLMCallsPerMinute = options.maxLLMCallsPerMinute ?? 60;
+        this.llmCooldownMs = options.llmCooldownMs ?? 0;
+        this.llmCircuitBreakerThreshold = options.llmCircuitBreakerThreshold ?? 3;
+        this.llmCircuitBreakerResetMs = options.llmCircuitBreakerResetMs ?? 60000;
         // Cache — default MemoryCache (no filesystem writes), or disabled with false
         // Use FileCache or ComboCache explicitly for persistence across restarts
         this.cache = options.cache === false
@@ -51,7 +61,7 @@ export class CapmanEngine {
                 const resolution = await _resolve(cached.result, cached.result.extractedParams, this.resolveOptions(overrides));
                 const trace = {
                     query,
-                    candidates: cached.result.candidates ?? [],
+                    candidates: cached.result.candidates,
                     reasoning: [`Served from cache (original: ${cached.result.reasoning})`],
                     steps,
                     resolvedVia: 'cache',
@@ -83,10 +93,30 @@ export class CapmanEngine {
             }
             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}%` });
+                    const skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger.warn(`LLM skipped — ${skipReason} — 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 skipped: ${skipReason}` });
+                    }
+                    else {
+                        const t = Date.now();
+                        try {
+                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            this.recordLLMFailure();
+                            logger.warn(`LLM call failed — falling back to keyword: ${err}`);
+                            const t2 = Date.now();
+                            matchResult = _match(query, this.manifest);
+                            steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t, detail: String(err) });
+                            steps.push({ type: 'keyword_match', status: 'pass', durationMs: Date.now() - t2, detail: 'fallback after llm failure' });
+                        }
+                    }
                 }
                 else {
                     logger.warn('accurate mode requires llm — falling back to keyword');
@@ -105,11 +135,28 @@ export class CapmanEngine {
                     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}%` });
+                    const skipReason = this.checkLLMAllowed();
+                    if (skipReason) {
+                        logger.warn(`LLM skipped — ${skipReason}`);
+                        steps.push({ type: 'llm_match', status: 'skip', durationMs: 0, detail: skipReason });
+                        matchResult = keywordResult;
+                    }
+                    else {
+                        logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                        const t2 = Date.now();
+                        try {
+                            matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                            this.recordLLMSuccess();
+                            resolvedVia = 'llm';
+                            steps.push({ type: 'llm_match', status: 'pass', durationMs: Date.now() - t2, detail: `confidence: ${matchResult.confidence}%` });
+                        }
+                        catch (err) {
+                            this.recordLLMFailure();
+                            logger.warn(`LLM call failed — falling back to keyword: ${err}`);
+                            steps.push({ type: 'llm_match', status: 'fail', durationMs: Date.now() - t2, detail: String(err) });
+                            matchResult = keywordResult;
+                        }
+                    }
                 }
                 break;
             }
@@ -140,7 +187,7 @@ export class CapmanEngine {
         });
         // ── Step 6: Build reasoning array ────────────────────────────────────────
         const reasoning = [];
-        if (matchResult.candidates?.length) {
+        if (matchResult.candidates.length) {
             const winner = matchResult.candidates.find(c => c.matched);
             const rejected = matchResult.candidates
                 .filter(c => !c.matched && c.score > 0)
@@ -167,7 +214,7 @@ export class CapmanEngine {
         await this.recordLearning(query, matchResult, resolvedVia);
         const trace = {
             query,
-            candidates: matchResult.candidates ?? [],
+            candidates: matchResult.candidates,
             reasoning,
             steps,
             resolvedVia,
@@ -205,6 +252,259 @@ export class CapmanEngine {
         if (this.cache)
             await this.cache.clear();
     }
+    /**
+     * Explain what would happen for a query — without executing it.
+     * Shows matched capability, all candidate scores with reasoning,
+     * and what action would be taken.
+     *
+     * @example
+     * const explanation = await engine.explain('track order 1234')
+     * console.log(explanation.matched.reasoning)
+     * console.log(explanation.wouldExecute.action)
+     * console.log(explanation.candidates)
+     */
+    async explain(query) {
+        const start = Date.now();
+        // ── Match — mirrors ask() logic including rate limiting ───────────────────
+        let matchResult;
+        let resolvedVia = 'keyword';
+        if (this.mode === 'accurate') {
+            if (this.llm) {
+                const skipReason = this.checkLLMAllowed();
+                if (skipReason) {
+                    logger.warn(`explain(): LLM skipped — ${skipReason} — falling back to keyword`);
+                    matchResult = _match(query, this.manifest);
+                }
+                else {
+                    try {
+                        matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                        this.recordLLMSuccess();
+                        resolvedVia = 'llm';
+                    }
+                    catch (err) {
+                        this.recordLLMFailure();
+                        logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
+                        matchResult = _match(query, this.manifest);
+                    }
+                }
+            }
+            else {
+                matchResult = _match(query, this.manifest);
+            }
+        }
+        else if (this.mode === 'balanced' && this.llm) {
+            // Keyword first — escalate to LLM if low confidence (same as ask())
+            const keywordResult = _match(query, this.manifest);
+            if (keywordResult.confidence >= this.threshold) {
+                matchResult = keywordResult;
+            }
+            else {
+                const skipReason = this.checkLLMAllowed();
+                if (skipReason) {
+                    logger.warn(`explain(): LLM skipped — ${skipReason}`);
+                    matchResult = keywordResult;
+                }
+                else {
+                    try {
+                        matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                        this.recordLLMSuccess();
+                        resolvedVia = 'llm';
+                    }
+                    catch (err) {
+                        this.recordLLMFailure();
+                        logger.warn(`explain(): LLM call failed — falling back to keyword: ${err}`);
+                        matchResult = keywordResult;
+                    }
+                }
+            }
+        }
+        else {
+            // cheap mode or no llm — keyword only
+            matchResult = _match(query, this.manifest);
+        }
+        // ── Build candidate explanations ─────────────────────────────────────────
+        const candidates = matchResult.candidates
+            .sort((a, b) => b.score - a.score)
+            .map(c => {
+            const cap = this.manifest.capabilities.find(mc => mc.id === c.capabilityId);
+            let explanation = '';
+            if (c.score === 0) {
+                explanation = 'No keyword overlap with examples or description';
+            }
+            else if (c.score >= 90) {
+                explanation = `Strong match (${c.score}%) — query closely matches examples`;
+            }
+            else if (c.score >= 50) {
+                const qWords = query.toLowerCase().split(/\W+/).filter(Boolean);
+                const matchedWords = (cap?.examples ?? [])
+                    .flatMap(e => e.toLowerCase().split(/\s+/))
+                    .filter(w => qWords.includes(w) && w.length > 2);
+                const unique = [...new Set(matchedWords)].slice(0, 3);
+                explanation = unique.length
+                    ? `Matched keywords: ${unique.join(', ')} (${c.score}%)`
+                    : `Partial match (${c.score}%) — some keyword overlap`;
+            }
+            else {
+                explanation = `Weak match (${c.score}%) — below 50% confidence threshold, rejected`;
+            }
+            return { capabilityId: c.capabilityId, score: c.score, matched: c.matched, explanation };
+        });
+        // ── Build reasoning array ────────────────────────────────────────────────
+        const reasoning = [];
+        const winner = candidates.find(c => c.matched);
+        const rejected = candidates.filter(c => !c.matched && c.score > 0).slice(0, 3);
+        if (winner) {
+            reasoning.push(`Matched "${winner.capabilityId}" with ${winner.score}% confidence`);
+        }
+        else {
+            reasoning.push('No capability matched above the 50% confidence threshold');
+        }
+        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)
+                .filter(([, v]) => v !== null)
+                .map(([k, v]) => `${k}=${v}`)
+                .join(', ');
+            if (params)
+                reasoning.push(`Would extract params: ${params}`);
+        }
+        // ── Build wouldExecute ───────────────────────────────────────────────────
+        const cap = matchResult.capability;
+        let action = null;
+        let blocked = null;
+        let privacy = null;
+        let resolverType = null;
+        if (cap) {
+            privacy = cap.privacy.level;
+            resolverType = cap.resolver.type;
+            // Check if privacy would block — mirrors checkPrivacy() in resolver.ts
+            if (cap.privacy.level === 'user_owned') {
+                if (!this.auth?.isAuthenticated) {
+                    blocked = `Capability "${cap.id}" requires authentication (privacy: user_owned)`;
+                }
+            }
+            else if (cap.privacy.level === 'admin') {
+                if (!this.auth?.isAuthenticated) {
+                    blocked = `Capability "${cap.id}" requires authentication (privacy: admin)`;
+                }
+                else if (this.auth.role !== 'admin') {
+                    blocked = `Capability "${cap.id}" requires admin role (current role: ${this.auth.role ?? 'none'})`;
+                }
+            }
+            if (!blocked) {
+                // Build action string
+                const params = matchResult.extractedParams;
+                if (cap.resolver.type === 'api') {
+                    const endpoint = cap.resolver.endpoints[0];
+                    let path = endpoint.path;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            path = path.replace(`{${k}}`, v);
+                    }
+                    const base = this.baseUrl ?? '';
+                    action = `${endpoint.method} ${base}${path}`;
+                }
+                else if (cap.resolver.type === 'nav') {
+                    let dest = cap.resolver.destination;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            dest = dest.replace(`{${k}}`, v);
+                    }
+                    action = `navigate → ${dest}`;
+                }
+                else if (cap.resolver.type === 'hybrid') {
+                    const hybrid = cap.resolver;
+                    const endpoint = hybrid.api.endpoints[0];
+                    let path = endpoint.path;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            path = path.replace(`{${k}}`, v);
+                    }
+                    let dest = hybrid.nav.destination;
+                    for (const [k, v] of Object.entries(params)) {
+                        if (v)
+                            dest = dest.replace(`{${k}}`, v);
+                    }
+                    const base = this.baseUrl ?? '';
+                    action = `${endpoint.method} ${base}${path} + navigate → ${dest}`;
+                }
+            }
+        }
+        return {
+            query,
+            matched: {
+                capability: matchResult.capability,
+                confidence: matchResult.confidence,
+                intent: matchResult.intent,
+                reasoning,
+            },
+            candidates,
+            wouldExecute: { resolverType, action, privacy, blocked },
+            resolvedVia,
+            durationMs: Date.now() - start,
+        };
+    }
+    /**
+     * Checks all rate limiting and circuit breaker conditions.
+     * Returns null if LLM call is allowed, or a skip reason string if it should be skipped.
+     */
+    checkLLMAllowed() {
+        const now = Date.now();
+        // ── Circuit breaker ──────────────────────────────────────────────────────
+        if (this.llmCircuitOpenAt > 0) {
+            const elapsed = now - this.llmCircuitOpenAt;
+            if (elapsed < this.llmCircuitBreakerResetMs) {
+                const remainingSec = Math.ceil((this.llmCircuitBreakerResetMs - elapsed) / 1000);
+                return `circuit breaker open — ${remainingSec}s remaining`;
+            }
+            // Reset circuit breaker — try again
+            logger.info('LLM circuit breaker reset — trying again');
+            this.llmCircuitOpenAt = 0;
+            this.llmConsecutiveFails = 0;
+        }
+        // ── Cooldown between calls ───────────────────────────────────────────────
+        if (this.llmCooldownMs > 0 && this.llmLastCallAt > 0) {
+            const elapsed = now - this.llmLastCallAt;
+            if (elapsed < this.llmCooldownMs) {
+                const remainingMs = this.llmCooldownMs - elapsed;
+                return `cooldown active — ${remainingMs}ms remaining`;
+            }
+        }
+        // ── Per-minute rate limit ────────────────────────────────────────────────
+        const windowElapsed = now - this.llmWindowStart;
+        if (windowElapsed >= 60000) {
+            this.llmCallsThisMinute = 0;
+            this.llmWindowStart = now;
+        }
+        if (this.llmCallsThisMinute >= this.maxLLMCallsPerMinute) {
+            // Recalculate elapsed after possible window reset above
+            const resetIn = Math.ceil((60000 - (now - this.llmWindowStart)) / 1000);
+            return `rate limit reached (${this.maxLLMCallsPerMinute}/min) — resets in ${Math.max(0, resetIn)}s`;
+        }
+        // Reserve the slot atomically before the call happens
+        this.llmCallsThisMinute++;
+        this.llmLastCallAt = Date.now();
+        return null;
+    }
+    /**
+     * Records a successful LLM call — updates rate limit counters.
+     */
+    recordLLMSuccess() {
+        this.llmConsecutiveFails = 0;
+    }
+    /**
+     * Records a failed LLM call — may open the circuit breaker.
+     */
+    recordLLMFailure() {
+        this.llmConsecutiveFails++;
+        if (this.llmConsecutiveFails >= this.llmCircuitBreakerThreshold) {
+            this.llmCircuitOpenAt = Date.now();
+            logger.warn(`LLM circuit breaker opened after ${this.llmConsecutiveFails} consecutive failures — pausing for ${this.llmCircuitBreakerResetMs / 1000}s`);
+        }
+    }
     // ── Private helpers ────────────────────────────────────────────────────────
     resolveOptions(overrides = {}) {
         return {

package/dist/esm/generator.d.ts

@@ -0,0 +1,7 @@
+import type { CapmanConfig, Manifest, ValidationResult } from './types';
+export declare function generate(config: CapmanConfig): Manifest;
+export declare function loadConfig(configPath?: string): CapmanConfig;
+export declare function writeManifest(manifest: Manifest, outputPath?: string): string;
+export declare function readManifest(manifestPath?: string): Manifest;
+export declare function validate(manifest: Manifest): ValidationResult;
+export declare function generateStarterConfig(): string;

package/dist/esm/generator.js

@@ -28,6 +28,10 @@ export function loadConfig(configPath) {
         if (fs.existsSync(resolved)) {
             let raw;
             // Catch syntax errors in config file
+            // Note: require() only works with CJS config files (.js, .json)
+            // ESM config files (.mjs or "type": "module") are not supported.
+            // Use a CJS config file or convert with: module.exports = { ... }
+            // Full ESM config support is planned for v0.5.
             try {
                 const mod = require(resolved);
                 raw = mod.default ?? mod;

package/dist/esm/index.d.ts

@@ -0,0 +1,47 @@
+export { setLogLevel } from './logger';
+export type { LogLevel } from './logger';
+export type { Capability, CapabilityParam, CapmanConfig, Manifest, MatchResult, ExecutionTrace, TraceStep, MatchCandidate, ResolveResult, ApiCallResult, ValidationResult, Resolver, ApiResolver, NavResolver, HybridResolver, PrivacyScope, ResolverType, HttpMethod, ExplainResult, ExplainCandidate, } from './types';
+export { generate, loadConfig, writeManifest, readManifest, validate, generateStarterConfig, } from './generator';
+export { match, matchWithLLM, } from './matcher';
+export type { LLMMatcherOptions } from './matcher';
+export { resolve } from './resolver';
+export type { ResolveOptions, AuthContext } from './resolver';
+export { CapmanEngine } from './engine';
+export type { EngineOptions, EngineResult } from './engine';
+export { MemoryCache, FileCache, ComboCache, buildCacheKey, normalizeQuery } from './cache';
+export type { CacheStore, CacheEntry } from './cache';
+export { FileLearningStore, MemoryLearningStore } from './learning';
+export type { LearningStore, LearningEntry, KeywordStats } from './learning';
+export { parseOpenAPI } from './parser';
+export type { ParseResult } from './parser';
+import type { Manifest, MatchResult, ResolveResult } from './types';
+import type { LLMMatcherOptions } from './matcher';
+import type { ResolveOptions } from './resolver';
+export type MatchMode = 'cheap' | 'balanced' | 'accurate';
+export interface AskOptions extends ResolveOptions {
+    llm?: LLMMatcherOptions['llm'];
+    /**
+     * Controls how intent matching is performed.
+     * - 'cheap'    — keyword only, no LLM calls
+     * - 'balanced' — keyword first, LLM fallback if confidence < 50% (default)
+     * - 'accurate' — LLM first, keyword fallback
+     * @default 'balanced'
+     */
+    mode?: MatchMode;
+}
+export interface AskResult {
+    match: MatchResult;
+    resolution: ResolveResult;
+}
+/**
+ * One-shot convenience: match + resolve in a single call.
+ * Delegates to CapmanEngine internally.
+ *
+ * @deprecated For full features including trace and caching, use CapmanEngine directly.
+ *
+ * @example
+ * const result = await ask("show me the dashboard", manifest, {
+ *   baseUrl: 'https://api.your-app.com',
+ * })
+ */
+export declare function ask(query: string, manifest: Manifest, options?: AskOptions): Promise<AskResult>;

package/dist/esm/learning.d.ts

@@ -0,0 +1,55 @@
+export interface LearningEntry {
+    query: string;
+    capabilityId: string | null;
+    confidence: number;
+    intent: string;
+    extractedParams: Record<string, string | null>;
+    resolvedVia: 'keyword' | 'llm' | 'cache';
+    timestamp: string;
+}
+export interface KeywordStats {
+    /** keyword → Map of capabilityId → hit count */
+    index: Record<string, Record<string, number>>;
+    /** Total queries processed */
+    totalQueries: number;
+    /** Queries that went to LLM */
+    llmQueries: number;
+    /** Queries served from cache */
+    cacheHits: number;
+    /** Out of scope queries */
+    outOfScope: number;
+}
+export interface LearningStore {
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}
+export declare class FileLearningStore implements LearningStore {
+    private filePath;
+    private entries;
+    private loaded;
+    constructor(filePath?: string);
+    private load;
+    private save;
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}
+export declare class MemoryLearningStore implements LearningStore {
+    private entries;
+    record(entry: LearningEntry): Promise<void>;
+    getStats(): Promise<KeywordStats>;
+    getTopCapabilities(limit?: number): Promise<Array<{
+        id: string;
+        hits: number;
+    }>>;
+    clear(): Promise<void>;
+}

package/dist/esm/learning.js

@@ -57,8 +57,13 @@ export class FileLearningStore {
         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`);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && Array.isArray(parsed.entries)) {
+                this.entries = parsed.entries;
+                logger.debug(`Learning store loaded: ${this.entries.length} entries`);
+            }
+            else {
+                logger.warn(`Learning store at ${this.filePath} contained unexpected format — starting fresh`);
+            }
         }
         catch {
             // File doesn't exist yet — start fresh