capman 0.2.0 → 0.3.0

package/dist/cjs/schema.d.ts

@@ -146,6 +146,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         }>;
     }, "strip", z.ZodTypeAny, {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -155,7 +156,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -188,6 +188,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         examples?: string[] | undefined;
     }, {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -197,7 +198,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -230,6 +230,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         examples?: string[] | undefined;
     }>, "many">, {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -239,7 +240,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -272,6 +272,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         examples?: string[] | undefined;
     }[], {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -281,7 +282,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -317,6 +317,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
     app: string;
     capabilities: {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -326,7 +327,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -363,6 +363,7 @@ export declare const CapmanConfigSchema: z.ZodObject<{
     app: string;
     capabilities: {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -372,7 +373,6 @@ export declare const CapmanConfigSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -554,6 +554,7 @@ export declare const ManifestSchema: z.ZodObject<{
         }>;
     }, "strip", z.ZodTypeAny, {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -563,7 +564,6 @@ export declare const ManifestSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -596,6 +596,7 @@ export declare const ManifestSchema: z.ZodObject<{
         examples?: string[] | undefined;
     }, {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -605,7 +606,6 @@ export declare const ManifestSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -642,6 +642,7 @@ export declare const ManifestSchema: z.ZodObject<{
     app: string;
     capabilities: {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -651,7 +652,6 @@ export declare const ManifestSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {
@@ -689,6 +689,7 @@ export declare const ManifestSchema: z.ZodObject<{
     app: string;
     capabilities: {
         name: string;
+        id: string;
         params: {
             name: string;
             required: boolean;
@@ -698,7 +699,6 @@ export declare const ManifestSchema: z.ZodObject<{
         }[];
         description: string;
         returns: string[];
-        id: string;
         resolver: {
             type: "api";
             endpoints: {

package/dist/cjs/types.d.ts

@@ -58,15 +58,22 @@ export interface MatchResult {
     extractedParams: Record<string, string | null>;
     reasoning: string;
 }
+export interface ApiCallResult {
+    method: string;
+    url: string;
+    params: Record<string, unknown>;
+    /** HTTP status code — only present when actually executed (not dry run) */
+    status?: number;
+    /** Parsed JSON response body — only present when actually executed */
+    data?: unknown;
+}
 export interface ResolveResult {
     success: boolean;
     resolverType: ResolverType | null;
-    apiCalls?: Array<{
-        method: string;
-        url: string;
-        params: Record<string, unknown>;
-    }>;
+    apiCalls?: ApiCallResult[];
     navTarget?: string;
+    /** Execution time in milliseconds */
+    durationMs?: number;
     error?: string;
 }
 export interface ValidationResult {

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

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

package/dist/cjs/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.3.0";
+//# sourceMappingURL=version.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,OAAO,UAAU,CAAA"}

package/dist/cjs/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+// Auto-generated by scripts/version.js — do not edit manually
+exports.VERSION = '0.3.0';
+//# sourceMappingURL=version.js.map

package/dist/cjs/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":";;;AAAA,8DAA8D;AACjD,QAAA,OAAO,GAAG,OAAO,CAAA"}

package/dist/esm/cache.js

@@ -0,0 +1,141 @@
+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);
+    }
+    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.debug(`File cache loaded: ${this.store.size} entries`);
+            }
+        }
+        catch {
+            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.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.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.debug(`Cache set (file): "${query}"`);
+    }
+    async clear() {
+        this.store.clear();
+        this.save();
+    }
+    async size() {
+        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);
+            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,149 @@
+import { match as _match, matchWithLLM as _matchWithLLM } from './matcher';
+import { resolve as _resolve } from './resolver';
+import { ComboCache } from './cache';
+import { FileLearningStore } 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 ComboCache, or disabled with false
+        this.cache = options.cache === false
+            ? null
+            : (options.cache ?? new ComboCache());
+        // Learning — default FileLearningStore, or disabled with false
+        this.learning = options.learning === false
+            ? null
+            : (options.learning ?? new FileLearningStore());
+        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.info(`Cache hit for: "${query}"`);
+                const resolution = await _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 = _match(query, this.manifest);
+                break;
+            }
+            case 'accurate': {
+                if (this.llm) {
+                    matchResult = await _matchWithLLM(query, this.manifest, { llm: this.llm });
+                    resolvedVia = 'llm';
+                }
+                else {
+                    logger.warn('accurate mode requires llm — falling back to keyword');
+                    matchResult = _match(query, this.manifest);
+                }
+                break;
+            }
+            case 'balanced':
+            default: {
+                const keywordResult = _match(query, this.manifest);
+                if (keywordResult.confidence >= this.threshold || !this.llm) {
+                    matchResult = keywordResult;
+                }
+                else {
+                    logger.info(`Low confidence (${keywordResult.confidence}%) — escalating to LLM`);
+                    matchResult = await _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 _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(),
+        });
+    }
+}

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,145 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from './logger';
+// ─── File Learning Store ──────────────────────────────────────────────────────
+export class FileLearningStore {
+    constructor(filePath = '.capman/learning.json') {
+        this.entries = [];
+        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.entries = raw.entries ?? [];
+                logger.debug(`Learning store loaded: ${this.entries.length} entries`);
+            }
+        }
+        catch {
+            logger.warn(`Failed to load learning store at ${this.filePath}`);
+        }
+        this.loaded = true;
+    }
+    save() {
+        try {
+            const dir = path.dirname(this.filePath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.writeFileSync(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) {
+        this.load();
+        this.entries.push(entry);
+        this.save();
+        logger.debug(`Learning recorded: "${entry.query}" → ${entry.capabilityId ?? 'OUT_OF_SCOPE'} via ${entry.resolvedVia}`);
+    }
+    async getStats() {
+        this.load();
+        const index = {};
+        let totalQueries = 0;
+        let llmQueries = 0;
+        let cacheHits = 0;
+        let outOfScope = 0;
+        for (const entry of this.entries) {
+            totalQueries++;
+            if (entry.resolvedVia === 'llm')
+                llmQueries++;
+            if (entry.resolvedVia === 'cache')
+                cacheHits++;
+            if (!entry.capabilityId)
+                outOfScope++;
+            if (entry.capabilityId) {
+                // Index each word of the query against the matched capability
+                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 };
+    }
+    async getTopCapabilities(limit = 5) {
+        this.load();
+        const counts = {};
+        for (const entry of this.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 }));
+    }
+    async clear() {
+        this.entries = [];
+        this.save();
+    }
+}
+// ─── Memory Learning Store (for testing) ─────────────────────────────────────
+export class MemoryLearningStore {
+    constructor() {
+        this.entries = [];
+    }
+    async record(entry) {
+        this.entries.push(entry);
+    }
+    async getStats() {
+        const index = {};
+        let totalQueries = 0;
+        let llmQueries = 0;
+        let cacheHits = 0;
+        let outOfScope = 0;
+        for (const entry of this.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 };
+    }
+    async getTopCapabilities(limit = 5) {
+        const counts = {};
+        for (const entry of this.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 }));
+    }
+    async clear() {
+        this.entries = [];
+    }
+}