opc-agent 1.3.2 → 1.4.0

package/docs/api/sdk.md

@@ -1,80 +1,80 @@
-# SDK Reference
-
-## Core Classes
-
-### AgentRuntime
-
-```typescript
-import { AgentRuntime } from 'opc-agent';
-
-const runtime = new AgentRuntime();
-await runtime.loadConfig('oad.yaml');
-const agent = await runtime.initialize();
-await runtime.start();
-```
-
-### AnalyticsEngine
-
-```typescript
-import { AnalyticsEngine } from 'opc-agent';
-
-const engine = new AnalyticsEngine('.');
-engine.trackMessage('user-1', 250, 100, 50);
-engine.trackToolUse('search', true, 120);
-const stats = engine.getStats();
-```
-
-### RateLimiter
-
-```typescript
-import { RateLimiter } from 'opc-agent';
-
-const limiter = new RateLimiter({
-  userLimit: { maxRequests: 60, windowMs: 60000 },
-  providerLimit: { maxRequests: 100, windowMs: 60000 },
-});
-
-await limiter.acquire('user-1', 'openai');
-```
-
-### LLMCache
-
-```typescript
-import { LLMCache } from 'opc-agent';
-
-const cache = new LLMCache({ ttlMs: 3600000 });
-const key = LLMCache.makeKey(messages, systemPrompt);
-const cached = cache.get(key);
-if (!cached) {
-  const response = await callLLM(messages);
-  cache.set(key, response);
-}
-```
-
-### Testing
-
-```typescript
-import { runTests, formatReport } from 'opc-agent';
-
-const report = await runTests('oad.yaml');
-console.log(formatReport(report));
-```
-
-## Templates
-
-13 built-in templates:
-
-| Template | Description |
-|----------|-------------|
-| `customer-service` | FAQ + human handoff |
-| `sales-assistant` | Product Q&A + lead capture |
-| `knowledge-base` | RAG with DeepBrain |
-| `code-reviewer` | Bug detection + style checks |
-| `hr-recruiter` | Resume screening + interviews |
-| `project-manager` | Task tracking + meeting notes |
-| `content-writer` | Blog + social media + SEO |
-| `legal-assistant` | Contract review + compliance |
-| `financial-advisor` | Budget + expense tracking |
-| `executive-assistant` | Calendar + email + meetings |
-| `data-analyst` | Data querying + visualization |
-| `teacher` | Lesson plans + quizzes |
+# SDK Reference
+
+## Core Classes
+
+### AgentRuntime
+
+```typescript
+import { AgentRuntime } from 'opc-agent';
+
+const runtime = new AgentRuntime();
+await runtime.loadConfig('oad.yaml');
+const agent = await runtime.initialize();
+await runtime.start();
+```
+
+### AnalyticsEngine
+
+```typescript
+import { AnalyticsEngine } from 'opc-agent';
+
+const engine = new AnalyticsEngine('.');
+engine.trackMessage('user-1', 250, 100, 50);
+engine.trackToolUse('search', true, 120);
+const stats = engine.getStats();
+```
+
+### RateLimiter
+
+```typescript
+import { RateLimiter } from 'opc-agent';
+
+const limiter = new RateLimiter({
+  userLimit: { maxRequests: 60, windowMs: 60000 },
+  providerLimit: { maxRequests: 100, windowMs: 60000 },
+});
+
+await limiter.acquire('user-1', 'openai');
+```
+
+### LLMCache
+
+```typescript
+import { LLMCache } from 'opc-agent';
+
+const cache = new LLMCache({ ttlMs: 3600000 });
+const key = LLMCache.makeKey(messages, systemPrompt);
+const cached = cache.get(key);
+if (!cached) {
+  const response = await callLLM(messages);
+  cache.set(key, response);
+}
+```
+
+### Testing
+
+```typescript
+import { runTests, formatReport } from 'opc-agent';
+
+const report = await runTests('oad.yaml');
+console.log(formatReport(report));
+```
+
+## Templates
+
+13 built-in templates:
+
+| Template | Description |
+|----------|-------------|
+| `customer-service` | FAQ + human handoff |
+| `sales-assistant` | Product Q&A + lead capture |
+| `knowledge-base` | RAG with DeepBrain |
+| `code-reviewer` | Bug detection + style checks |
+| `hr-recruiter` | Resume screening + interviews |
+| `project-manager` | Task tracking + meeting notes |
+| `content-writer` | Blog + social media + SEO |
+| `legal-assistant` | Contract review + compliance |
+| `financial-advisor` | Budget + expense tracking |
+| `executive-assistant` | Calendar + email + meetings |
+| `data-analyst` | Data querying + visualization |
+| `teacher` | Lesson plans + quizzes |

package/docs/guide/concepts.md

@@ -1,51 +1,51 @@
-# Core Concepts
-
-## Agent
-
-An Agent is an autonomous AI entity with a defined lifecycle:
-
-```
-init → ready → running → stopped
-```
-
-Each agent has a name, system prompt, skills, channels, and memory.
-
-## Skill
-
-Skills are modular capabilities an agent can use. Each skill:
-- Has a `name` and `description`
-- Receives the conversation context and current message
-- Returns whether it handled the message and with what confidence
-
-Built-in skills include FAQ lookup and human handoff.
-
-## Channel
-
-Channels are the interfaces through which users interact with agents:
-- **Web** — HTTP API with `/chat` endpoint and SSE streaming
-- More channels (WebSocket, CLI, Slack) coming soon
-
-## Memory
-
-Agents have two types of memory:
-- **Short-term** — Conversation history within a session
-- **Long-term** — Persistent knowledge across sessions (coming soon)
-
-## DTV (Data / Trust / Value)
-
-The DTV framework governs agent operations:
-
-### Data
-Read-only access to business data. Agents can read configurations but cannot modify source systems.
-
-### Trust
-Progressive trust levels control agent capabilities:
-- **sandbox** — No network, limited capabilities
-- **verified** — Identity confirmed, basic capabilities
-- **certified** — Security audited, full capabilities
-- **listed** — Published in OPC marketplace
-
-### Value
-Metrics tracking for agent performance and ROI:
-- Response time, satisfaction scores, resolution rates
-- Automated reporting and dashboards
+# Core Concepts
+
+## Agent
+
+An Agent is an autonomous AI entity with a defined lifecycle:
+
+```
+init → ready → running → stopped
+```
+
+Each agent has a name, system prompt, skills, channels, and memory.
+
+## Skill
+
+Skills are modular capabilities an agent can use. Each skill:
+- Has a `name` and `description`
+- Receives the conversation context and current message
+- Returns whether it handled the message and with what confidence
+
+Built-in skills include FAQ lookup and human handoff.
+
+## Channel
+
+Channels are the interfaces through which users interact with agents:
+- **Web** — HTTP API with `/chat` endpoint and SSE streaming
+- More channels (WebSocket, CLI, Slack) coming soon
+
+## Memory
+
+Agents have two types of memory:
+- **Short-term** — Conversation history within a session
+- **Long-term** — Persistent knowledge across sessions (coming soon)
+
+## DTV (Data / Trust / Value)
+
+The DTV framework governs agent operations:
+
+### Data
+Read-only access to business data. Agents can read configurations but cannot modify source systems.
+
+### Trust
+Progressive trust levels control agent capabilities:
+- **sandbox** — No network, limited capabilities
+- **verified** — Identity confirmed, basic capabilities
+- **certified** — Security audited, full capabilities
+- **listed** — Published in OPC marketplace
+
+### Value
+Metrics tracking for agent performance and ROI:
+- Response time, satisfaction scores, resolution rates
+- Automated reporting and dashboards

package/docs/guide/configuration.md

@@ -1,79 +1,79 @@
-# Configuration
-
-## OAD File Structure
-
-The `oad.yaml` file is the heart of your agent configuration:
-
-```yaml
-apiVersion: opc/v1
-kind: Agent
-metadata:
-  name: my-agent
-  version: 1.0.0
-  description: My AI agent
-spec:
-  provider:
-    default: openai
-    allowed: [openai, deepseek, qwen]
-  model: gpt-4o-mini
-  systemPrompt: "You are a helpful assistant."
-  skills: []
-  channels:
-    - type: web
-      port: 3000
-  memory:
-    shortTerm: true
-    longTerm: false
-  testing:
-    cases:
-      - name: greeting-test
-        input: "Hello"
-        expect:
-          contains: ["hello", "help"]
-          maxLatencyMs: 5000
-  rateLimits:
-    perUser:
-      maxRequests: 60
-      windowMs: 60000
-    perProvider:
-      maxRequests: 100
-      windowMs: 60000
-  cache:
-    enabled: true
-    ttlMs: 3600000
-```
-
-## Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `OPC_LLM_API_KEY` | LLM API key | — |
-| `OPC_LLM_BASE_URL` | LLM API base URL | `https://api.openai.com/v1` |
-| `OPC_LLM_MODEL` | Model name | `gpt-4o-mini` |
-
-## Rate Limiting
-
-Configure per-user and per-provider rate limits in `oad.yaml`:
-
-```yaml
-spec:
-  rateLimits:
-    perUser:
-      maxRequests: 60
-      windowMs: 60000
-    perProvider:
-      maxRequests: 100
-      windowMs: 60000
-```
-
-## Caching
-
-Enable LLM response caching to reduce API costs:
-
-```yaml
-spec:
-  cache:
-    enabled: true
-    ttlMs: 3600000  # 1 hour
-    maxEntries: 1000
-```
+# Configuration
+
+## OAD File Structure
+
+The `oad.yaml` file is the heart of your agent configuration:
+
+```yaml
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: my-agent
+  version: 1.0.0
+  description: My AI agent
+spec:
+  provider:
+    default: openai
+    allowed: [openai, deepseek, qwen]
+  model: gpt-4o-mini
+  systemPrompt: "You are a helpful assistant."
+  skills: []
+  channels:
+    - type: web
+      port: 3000
+  memory:
+    shortTerm: true
+    longTerm: false
+  testing:
+    cases:
+      - name: greeting-test
+        input: "Hello"
+        expect:
+          contains: ["hello", "help"]
+          maxLatencyMs: 5000
+  rateLimits:
+    perUser:
+      maxRequests: 60
+      windowMs: 60000
+    perProvider:
+      maxRequests: 100
+      windowMs: 60000
+  cache:
+    enabled: true
+    ttlMs: 3600000
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OPC_LLM_API_KEY` | LLM API key | — |
+| `OPC_LLM_BASE_URL` | LLM API base URL | `https://api.openai.com/v1` |
+| `OPC_LLM_MODEL` | Model name | `gpt-4o-mini` |
+
+## Rate Limiting
+
+Configure per-user and per-provider rate limits in `oad.yaml`:
+
+```yaml
+spec:
+  rateLimits:
+    perUser:
+      maxRequests: 60
+      windowMs: 60000
+    perProvider:
+      maxRequests: 100
+      windowMs: 60000
+```
+
+## Caching
+
+Enable LLM response caching to reduce API costs:
+
+```yaml
+spec:
+  cache:
+    enabled: true
+    ttlMs: 3600000  # 1 hour
+    maxEntries: 1000
+```

package/docs/guide/deployment.md

@@ -1,42 +1,42 @@
-# Deployment
-
-## Docker
-
-Every `opc init` project includes a `Dockerfile` and `docker-compose.yml`:
-
-```bash
-docker compose up -d
-```
-
-## Deploy to OpenClaw
-
-```bash
-opc deploy --target openclaw
-opc deploy --target openclaw --install  # Also register in config
-```
-
-## Deploy to Hermes
-
-```bash
-opc deploy --target hermes
-opc deploy --target hermes --output ./my-hermes-deploy
-```
-
-## Environment Variables
-
-Set your API keys in `.env`:
-
-```bash
-OPC_LLM_API_KEY=sk-xxx
-OPC_LLM_BASE_URL=https://api.openai.com/v1
-OPC_LLM_MODEL=gpt-4o-mini
-```
-
-## Production Checklist
-
-- [ ] Set proper API keys in `.env`
-- [ ] Configure rate limits in `oad.yaml`
-- [ ] Enable caching for cost reduction
-- [ ] Set up analytics monitoring
-- [ ] Run `opc test` before deployment
-- [ ] Review trust/DTV settings
+# Deployment
+
+## Docker
+
+Every `opc init` project includes a `Dockerfile` and `docker-compose.yml`:
+
+```bash
+docker compose up -d
+```
+
+## Deploy to OpenClaw
+
+```bash
+opc deploy --target openclaw
+opc deploy --target openclaw --install  # Also register in config
+```
+
+## Deploy to Hermes
+
+```bash
+opc deploy --target hermes
+opc deploy --target hermes --output ./my-hermes-deploy
+```
+
+## Environment Variables
+
+Set your API keys in `.env`:
+
+```bash
+OPC_LLM_API_KEY=sk-xxx
+OPC_LLM_BASE_URL=https://api.openai.com/v1
+OPC_LLM_MODEL=gpt-4o-mini
+```
+
+## Production Checklist
+
+- [ ] Set proper API keys in `.env`
+- [ ] Configure rate limits in `oad.yaml`
+- [ ] Enable caching for cost reduction
+- [ ] Set up analytics monitoring
+- [ ] Run `opc test` before deployment
+- [ ] Review trust/DTV settings

package/docs/guide/getting-started.md

@@ -1,44 +1,44 @@
-# Getting Started
-
-## Installation
-
-```bash
-npm install -g opc-agent
-```
-
-## Create Your First Agent
-
-```bash
-# Initialize a new project
-opc init my-agent --template customer-service
-
-# Enter the project
-cd my-agent
-
-# Validate the OAD definition
-opc build
-
-# Run in sandbox mode
-opc test
-
-# Start the agent
-opc run
-```
-
-## Test the Agent
-
-```bash
-curl -X POST http://localhost:3000/chat \
-  -H "Content-Type: application/json" \
-  -d '{"message": "What are your business hours?"}'
-```
-
-## Project Structure
-
-```
-my-agent/
-├── oad.yaml       # Agent definition (OAD Schema v1)
-└── README.md
-```
-
-The `oad.yaml` file defines everything about your agent: its identity, skills, channels, and configuration.
+# Getting Started
+
+## Installation
+
+```bash
+npm install -g opc-agent
+```
+
+## Create Your First Agent
+
+```bash
+# Initialize a new project
+opc init my-agent --template customer-service
+
+# Enter the project
+cd my-agent
+
+# Validate the OAD definition
+opc build
+
+# Run in sandbox mode
+opc test
+
+# Start the agent
+opc run
+```
+
+## Test the Agent
+
+```bash
+curl -X POST http://localhost:3000/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message": "What are your business hours?"}'
+```
+
+## Project Structure
+
+```
+my-agent/
+├── oad.yaml       # Agent definition (OAD Schema v1)
+└── README.md
+```
+
+The `oad.yaml` file defines everything about your agent: its identity, skills, channels, and configuration.

package/docs/guide/templates.md

@@ -1,28 +1,28 @@
-# Templates
-
-Templates are pre-built agent configurations for common use cases.
-
-## Customer Service
-
-A complete customer service agent with:
-- FAQ lookup skill
-- Human handoff when confidence is low
-- Web channel for HTTP integration
-
-```bash
-opc init my-service --template customer-service
-```
-
-## Creating Custom Templates
-
-Templates are OAD YAML files with optional skill implementations. To create your own:
-
-1. Define `oad.yaml` with your agent specification
-2. Implement custom skills extending `BaseSkill`
-3. Package as a directory with `oad.yaml` + `README.md`
-
-More templates coming soon:
-- Sales Assistant
-- Internal IT Help Desk
-- Data Analysis Agent
-- Content Moderation Agent
+# Templates
+
+Templates are pre-built agent configurations for common use cases.
+
+## Customer Service
+
+A complete customer service agent with:
+- FAQ lookup skill
+- Human handoff when confidence is low
+- Web channel for HTTP integration
+
+```bash
+opc init my-service --template customer-service
+```
+
+## Creating Custom Templates
+
+Templates are OAD YAML files with optional skill implementations. To create your own:
+
+1. Define `oad.yaml` with your agent specification
+2. Implement custom skills extending `BaseSkill`
+3. Package as a directory with `oad.yaml` + `README.md`
+
+More templates coming soon:
+- Sales Assistant
+- Internal IT Help Desk
+- Data Analysis Agent
+- Content Moderation Agent