capman 0.4.0 → 0.4.2

package/README.md

@@ -1,178 +1,273 @@
-# Capman — Capability Manifest Engine
+# capman
 
-Let AI agents interact with your app **without navigating the UI**.
+**Capability Manifest Engine** — let AI agents interact with your app reliably and explainably.
 
-Instead of an AI blindly clicking through screens to find information,
-capman lets your app declare what it can do — and the AI uses that map
-to get answers directly.
+Instead of an AI blindly clicking through screens, capman gives it a structured map of what your app can do — and shows you exactly why it made every decision.
+
+```bash
+npm install capman
+```
 
 ---
 
 ## The Problem
 
-When an AI agent needs to answer "are there available seats for Friday?",
-today it navigates your entire app like a tourist with no map:
+When an AI agent answers *"are there seats available Friday?"*, today it navigates your app like a tourist with no map:
 
 ```
-AI clicks → Home → Explore → Events → Category → Detail → Availability
+AI clicks → Home → Explore → Events → Category → Availability
 ```
 
-That's slow, wasteful, and exposes parts of your app the AI shouldn't see.
+Slow. Wasteful. Touches screens it shouldn't.
 
 ## The Solution
 
-Your app publishes a **capability manifest** — a machine-readable list of
-everything it can do, what API to call, and what data scope is allowed.
-
-The AI reads the manifest and goes directly to the answer.
+Your app publishes a **capability manifest** — a machine-readable list of everything it can do, what API to call, and what data is allowed. The AI reads the manifest and goes directly to the answer.
 
 ```
-User query → match capability → resolve via API or nav → done
+User query → match capability → resolve via API or nav → structured result
 ```
 
 ---
 
-## Install
+## Quick Start
+
+**1. Generate your manifest — three ways:**
 
 ```bash
-npm install capman
+# From an OpenAPI/Swagger spec (fastest, no API key needed)
+npx capman generate --from openapi.json
+npx capman generate --from https://api.your-app.com/openapi.json
+
+# AI-assisted — describe your app in plain English
+npx capman generate --ai
+
+# Manual — edit capman.config.js yourself
+npx capman init
 ```
 
----
+**2. Use the engine in your AI agent**
 
-## Quick Start
+```typescript
+import { CapmanEngine, readManifest } from 'capman'
+
+const manifest = readManifest()
 
-**1. Create a config file**
+const engine = new CapmanEngine({
+  manifest,
+  baseUrl: 'https://api.your-app.com',
+})
+
+const result = await engine.ask('Check availability for blue jacket')
+
+console.log(result.match.capability?.id)    // 'check_product_availability'
+console.log(result.resolution.apiCalls)     // [{ method: 'GET', url: '...' }]
+console.log(result.resolvedVia)             // 'keyword' | 'llm' | 'cache'
+console.log(result.trace.reasoning)         // ['Matched "check_product_availability" with 100% confidence', ...]
+```
+
+**3. See it live**
 
 ```bash
-npx capman init
+npx capman demo
 ```
 
-This creates a `capman.config.js` in your project. Edit it to define
-your app's capabilities.
+---
+
+## Manifest Generation
+
+capman gives you three ways to create your manifest — pick based on what you have:
+
+### From OpenAPI / Swagger spec
 
-**2. Generate the manifest**
+If your backend has an OpenAPI spec (most do), capman reads it and generates a complete manifest automatically. No LLM needed, no API key, works offline.
 
 ```bash
-npx capman generate
+npx capman generate --from openapi.json
+npx capman generate --from https://api.your-app.com/openapi.json
 ```
 
-This reads your config and outputs a `manifest.json`.
+What it does automatically:
+- Converts every endpoint into a capability with correct ID, name, and description
+- Extracts path params, query params, and request body fields
+- Infers privacy scope from security schemes — bearer token → `user_owned`, admin tags → `admin`, no auth → `public`
+- Generates natural language examples from the operation summary
+- Writes a ready `capman.config.js` for you to review and adjust
 
-**3. Use the SDK in your AI agent**
+```
+✓ Parsed 19 capabilities from spec
+✓ Config written to capman.config.js
+✓ Manifest written to manifest.json
+```
 
-```typescript
-import { match, resolve, readManifest } from 'capman'
+### AI-assisted generation
 
-const manifest = readManifest()
+No OpenAPI spec? Describe your app in plain English and capman uses an LLM to generate a full manifest.
 
-// Match a user query to a capability
-const matchResult = match("show me my account details", manifest)
+```bash
+npx capman generate --ai
+```
 
-// Resolve it
-const result = await resolve(matchResult, {}, {
-  baseUrl: 'https://api.your-app.com'
-})
+```
+Describe your app and its main capabilities:
+> A SaaS CRM. Users can create contacts, log calls, view pipeline
+  stages. Admins can manage teams and billing.
+
+Using anthropic to generate manifest...
+✓ 6 capabilities generated
+```
+
+Requires one of: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` in your environment.
+
+### Manual
+
+For full control, start from a starter config and define capabilities yourself:
 
-console.log(result.apiCalls)  // [{ method: 'GET', url: '...' }]
-console.log(result.navTarget) // '/dashboard/profile'
+```bash
+npx capman init
 ```
 
 ---
 
-## CLI Commands
+## Execution Trace
 
-| Command | What it does |
-|---|---|
-| `capman init` | Create a starter `capman.config.js` |
-| `capman generate` | Generate `manifest.json` from config |
-| `capman validate` | Validate your manifest for errors |
-| `capman inspect` | Print all capabilities in the manifest |
+Every `engine.ask()` call returns a full execution trace — so you always know why the AI did what it did.
+
+```typescript
+const result = await engine.ask('Check availability for blue jacket')
+
+console.log(result.trace)
+// {
+//   query: 'Check availability for blue jacket',
+//   candidates: [
+//     { capabilityId: 'check_product_availability', score: 100, matched: true },
+//     { capabilityId: 'get_order_status', score: 12, matched: false },
+//     { capabilityId: 'navigate_to_screen', score: 0, matched: false },
+//   ],
+//   reasoning: [
+//     'Matched "check_product_availability" with 100% confidence',
+//     'Rejected: get_order_status (12%)',
+//     'Resolved via: keyword',
+//     'Extracted params: product=blue-jacket',
+//   ],
+//   steps: [
+//     { type: 'cache_check',    status: 'miss', durationMs: 0 },
+//     { type: 'keyword_match',  status: 'pass', durationMs: 1, detail: 'confidence: 100%' },
+//     { type: 'privacy_check',  status: 'pass', durationMs: 0, detail: 'level: public' },
+//     { type: 'resolve',        status: 'pass', durationMs: 2, detail: 'via api' },
+//   ],
+//   resolvedVia: 'keyword',
+//   totalMs: 4,
+// }
+```
+
+Debug any query from the CLI:
+
+```bash
+npx capman run "check availability for blue jacket" --debug
+```
 
 ---
 
-## SDK Reference
+## Matching Modes
 
-### `match(query, manifest)`
-Matches a user query to the best capability using keyword scoring.
-Returns a `MatchResult` with the capability, confidence score, and intent.
+Control the cost/accuracy tradeoff with three matching modes:
+
+```typescript
+// cheap — keyword only, no LLM, free
+const engine = new CapmanEngine({ manifest, mode: 'cheap' })
+
+// balanced — keyword first, LLM fallback if confidence < 50% (default)
+const engine = new CapmanEngine({ manifest, mode: 'balanced', llm: myLLM })
+
+// accurate — LLM first, keyword fallback
+const engine = new CapmanEngine({ manifest, mode: 'accurate', llm: myLLM })
+```
 
-### `matchWithLLM(query, manifest, { llm })`
-Same as `match()` but uses an LLM for higher accuracy on ambiguous queries.
-Pass in any LLM function — works with Anthropic, OpenAI, or any local model.
+Pass any LLM function — works with Anthropic, OpenAI, or any model:
 
 ```typescript
-const result = await matchWithLLM("find me something", manifest, {
+import Anthropic from '@anthropic-ai/sdk'
+const anthropic = new Anthropic()
+
+const engine = new CapmanEngine({
+  manifest,
+  mode: 'balanced',
   llm: async (prompt) => {
     const res = await anthropic.messages.create({
       model: 'claude-sonnet-4-20250514',
       max_tokens: 500,
-      messages: [{ role: 'user', content: prompt }]
+      messages: [{ role: 'user', content: prompt }],
     })
     return res.content[0].text
-  }
+  },
 })
 ```
 
-### `resolve(matchResult, params, options)`
-Executes a matched capability via API call, navigation, or both.
+---
 
-### `ask(query, manifest, options)`
-Convenience function — match + resolve in one call.
+## Caching + Learning
 
 ```typescript
-const { match, resolution } = await ask("go to settings", manifest)
+import { CapmanEngine, FileCache, FileLearningStore } from 'capman'
+
+const engine = new CapmanEngine({
+  manifest,
+  cache:    new FileCache('.capman/cache.json'),
+  learning: new FileLearningStore('.capman/learning.json'),
+})
+
+const stats = await engine.getStats()
+// { totalQueries: 142, llmQueries: 18, cacheHits: 67, outOfScope: 3 }
+
+const top = await engine.getTopCapabilities(3)
+// [{ id: 'check_product_availability', hits: 58 }, ...]
 ```
 
 ---
 
-## Capability Config
-
-Each capability in your `capman.config.js` looks like this:
-
-```javascript
-{
-  id: 'get_resource',
-  name: 'Get a resource',
-  description: 'Fetch a resource by ID or name.',  // used for matching
-  examples: [                                        // improves accuracy
-    'Show me resource details',
-    'Find resource by ID',
-  ],
-  params: [
-    {
-      name: 'resource_id',
-      description: 'The resource ID',
-      required: true,
-      source: 'user_query',  // or 'session', 'context', 'static'
-    }
-  ],
-  returns: ['resource', 'metadata'],
-  resolver: {
-    type: 'api',             // 'api', 'nav', or 'hybrid'
-    endpoints: [
-      { method: 'GET', path: '/resources/{resource_id}' }
-    ],
+## Privacy + Auth
+
+Privacy scope is enforced **per capability**, before resolution happens:
+
+```typescript
+const engine = new CapmanEngine({
+  manifest,
+  baseUrl: 'https://api.your-app.com',
+  auth: {
+    isAuthenticated: true,
+    role: 'user',
+    userId: 'user-123',  // auto-injected into session params
   },
-  privacy: {
-    level: 'public',         // 'public', 'user_owned', or 'admin'
-    note: 'No auth required'
-  }
-}
+})
 ```
 
 ---
 
-## Privacy Scopes
+## Resolver Hardening
 
-| Level | Meaning |
-|---|---|
-| `public` | No auth required |
-| `user_owned` | Requires auth, scoped to current user only |
-| `admin` | Restricted to admin roles |
+```typescript
+const result = await engine.ask('show my orders', {
+  retries:   2,
+  timeoutMs: 3000,
+})
+```
+
+---
 
-Privacy scope is declared **per capability** — the AI is scoped to only
-what each capability allows, before resolution happens.
+## CLI Commands
+
+| Command | What it does |
+|---|---|
+| `capman init` | Create a starter `capman.config.js` |
+| `capman generate` | Generate manifest from `capman.config.js` |
+| `capman generate --from <path\|url>` | Generate from OpenAPI/Swagger spec |
+| `capman generate --ai` | Generate manifest using AI |
+| `capman validate` | Validate your manifest for errors |
+| `capman inspect` | Print all capabilities in the manifest |
+| `capman run "query"` | Run a query against your manifest |
+| `capman run "query" --debug` | Run with full candidate scoring |
+| `capman demo` | Live demo with a sample app |
 
 ---
 
@@ -186,23 +281,44 @@ what each capability allows, before resolution happens.
 
 ---
 
+## Privacy Scopes
+
+| Level | Meaning |
+|---|---|
+| `public` | No auth required |
+| `user_owned` | Requires auth, scoped to current user only |
+| `admin` | Restricted to admin roles |
+
+---
+
+## Param Sources
+
+| Source | Meaning |
+|---|---|
+| `user_query` | Extracted from the user's query |
+| `session` | Injected from `auth.userId` automatically |
+| `context` | Provided by the caller |
+| `static` | Fixed value, never changes |
+
+---
+
 ## Honest Limits
 
 **Works well:**
 - Structured data retrieval via APIs
-- Navigating to known app screens
-- Multi-endpoint aggregation
-- Privacy scoping per capability
-- Auto-updating on deploy
+- Auto-generating manifests from OpenAPI specs
+- Privacy enforcement per capability
+- Full execution tracing and debugging
+- Caching repeated queries
 
 **Current limits:**
 - Real-time infra status (is the server down?)
 - UI-only state with no API backing
-- Cross-app orchestration
-- Very ambiguous queries without LLM matcher
+- Very ambiguous queries — use `mode: 'accurate'` with an LLM
+- Multi-instance deployments need Redis adapter (planned for v0.5)
 
 ---
 
 ## License
 
-MIT
+MIT — [github.com/Hobbydefiningdoctory/capman]