opc-agent 0.3.0 → 0.5.0

package/dist/templates/financial-advisor.d.ts

@@ -0,0 +1,15 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+import type { OADDocument } from '../schema/oad';
+export declare class BudgetAnalysisSkill extends BaseSkill {
+    name: string;
+    description: string;
+    execute(_context: AgentContext, message: Message): Promise<SkillResult>;
+}
+export declare class FinancialPlanningSkill extends BaseSkill {
+    name: string;
+    description: string;
+    execute(_context: AgentContext, message: Message): Promise<SkillResult>;
+}
+export declare function createFinancialAdvisorConfig(): OADDocument;
+//# sourceMappingURL=financial-advisor.d.ts.map

package/dist/templates/financial-advisor.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FinancialPlanningSkill = exports.BudgetAnalysisSkill = void 0;
+exports.createFinancialAdvisorConfig = createFinancialAdvisorConfig;
+const base_1 = require("../skills/base");
+class BudgetAnalysisSkill extends base_1.BaseSkill {
+    name = 'budget-analysis';
+    description = 'Analyze budgets and expenses';
+    async execute(_context, message) {
+        const lower = message.content.toLowerCase();
+        if (lower.includes('budget') || lower.includes('expense') || lower.includes('cost')) {
+            return this.match('I can help analyze your budget. Please share your income and expense categories, and I\'ll provide insights on spending patterns and savings opportunities.', 0.8);
+        }
+        if (lower.includes('save') || lower.includes('saving')) {
+            return this.match('Common savings strategies: 50/30/20 rule (needs/wants/savings), automate transfers, review subscriptions, negotiate bills, and track daily spending.', 0.75);
+        }
+        return this.noMatch();
+    }
+}
+exports.BudgetAnalysisSkill = BudgetAnalysisSkill;
+class FinancialPlanningSkill extends base_1.BaseSkill {
+    name = 'financial-planning';
+    description = 'Help with financial planning and advice';
+    async execute(_context, message) {
+        const lower = message.content.toLowerCase();
+        if (lower.includes('invest') || lower.includes('portfolio')) {
+            return this.match('For investment planning, consider: risk tolerance, time horizon, diversification, asset allocation, and regular rebalancing. This is general guidance — consult a certified financial advisor for personalized advice.', 0.8);
+        }
+        if (lower.includes('retire') || lower.includes('pension')) {
+            return this.match('Retirement planning essentials: estimate target savings (25x annual expenses), maximize employer matching, consider tax-advantaged accounts, and start early for compound growth.', 0.8);
+        }
+        return this.noMatch();
+    }
+}
+exports.FinancialPlanningSkill = FinancialPlanningSkill;
+function createFinancialAdvisorConfig() {
+    return {
+        apiVersion: 'opc/v1',
+        kind: 'Agent',
+        metadata: {
+            name: 'financial-advisor',
+            version: '1.0.0',
+            description: 'AI Financial Advisor - budget analysis, expense tracking, financial planning',
+            author: 'OPC',
+            license: 'Apache-2.0',
+        },
+        spec: {
+            model: 'deepseek-chat',
+            systemPrompt: 'You are a financial advisor AI. Help users with budget analysis, expense tracking, and financial planning. Always recommend consulting a certified financial advisor for binding decisions.',
+            skills: [
+                { name: 'budget-analysis', description: 'Analyze budgets and expenses' },
+                { name: 'financial-planning', description: 'Financial planning advice' },
+            ],
+            channels: [{ type: 'web', port: 3000 }],
+            memory: { shortTerm: true, longTerm: false },
+            streaming: false,
+        },
+    };
+}
+//# sourceMappingURL=financial-advisor.js.map

package/dist/templates/legal-assistant.d.ts

@@ -0,0 +1,15 @@
+import { BaseSkill } from '../skills/base';
+import type { AgentContext, Message, SkillResult } from '../core/types';
+import type { OADDocument } from '../schema/oad';
+export declare class ContractReviewSkill extends BaseSkill {
+    name: string;
+    description: string;
+    execute(_context: AgentContext, message: Message): Promise<SkillResult>;
+}
+export declare class ComplianceCheckSkill extends BaseSkill {
+    name: string;
+    description: string;
+    execute(_context: AgentContext, message: Message): Promise<SkillResult>;
+}
+export declare function createLegalAssistantConfig(): OADDocument;
+//# sourceMappingURL=legal-assistant.d.ts.map

package/dist/templates/legal-assistant.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ComplianceCheckSkill = exports.ContractReviewSkill = void 0;
+exports.createLegalAssistantConfig = createLegalAssistantConfig;
+const base_1 = require("../skills/base");
+const LEGAL_TERMS = {
+    'force majeure': 'A clause that frees parties from obligations due to extraordinary events.',
+    'indemnification': 'One party agrees to compensate the other for certain damages or losses.',
+    'limitation of liability': 'A cap on the amount one party can claim from the other.',
+    'non-compete': 'Restricts a party from competing within a specified scope and timeframe.',
+    'confidentiality': 'Obligations to keep certain information private.',
+    'termination': 'Conditions under which the agreement may be ended.',
+};
+class ContractReviewSkill extends base_1.BaseSkill {
+    name = 'contract-review';
+    description = 'Review contracts and identify key clauses';
+    async execute(_context, message) {
+        const lower = message.content.toLowerCase();
+        for (const [term, explanation] of Object.entries(LEGAL_TERMS)) {
+            if (lower.includes(term)) {
+                return this.match(`📋 **${term.toUpperCase()}**: ${explanation}`, 0.85);
+            }
+        }
+        if (lower.includes('review') || lower.includes('contract')) {
+            return this.match('I can review contracts for key clauses like force majeure, indemnification, limitation of liability, non-compete, confidentiality, and termination provisions.', 0.7);
+        }
+        return this.noMatch();
+    }
+}
+exports.ContractReviewSkill = ContractReviewSkill;
+class ComplianceCheckSkill extends base_1.BaseSkill {
+    name = 'compliance-check';
+    description = 'Check compliance with regulations';
+    async execute(_context, message) {
+        const lower = message.content.toLowerCase();
+        if (lower.includes('gdpr') || lower.includes('privacy')) {
+            return this.match('GDPR compliance requires: data minimization, consent mechanisms, right to erasure, data protection officer, and breach notification within 72 hours.', 0.9);
+        }
+        if (lower.includes('compliance') || lower.includes('regulation')) {
+            return this.match('I can check compliance with GDPR, CCPA, SOX, HIPAA, and other major regulations. Please specify the regulation and context.', 0.7);
+        }
+        return this.noMatch();
+    }
+}
+exports.ComplianceCheckSkill = ComplianceCheckSkill;
+function createLegalAssistantConfig() {
+    return {
+        apiVersion: 'opc/v1',
+        kind: 'Agent',
+        metadata: {
+            name: 'legal-assistant',
+            version: '1.0.0',
+            description: 'AI Legal Assistant - contract review, compliance checking, legal research',
+            author: 'OPC',
+            license: 'Apache-2.0',
+        },
+        spec: {
+            model: 'deepseek-chat',
+            systemPrompt: 'You are a legal assistant AI. Help users review contracts, check compliance, and research legal topics. Always recommend consulting a qualified attorney for binding decisions.',
+            skills: [
+                { name: 'contract-review', description: 'Review contracts and identify key clauses' },
+                { name: 'compliance-check', description: 'Check regulatory compliance' },
+            ],
+            channels: [{ type: 'web', port: 3000 }],
+            memory: { shortTerm: true, longTerm: false },
+            streaming: false,
+        },
+    };
+}
+//# sourceMappingURL=legal-assistant.js.map

package/examples/customer-service-demo/README.md

@@ -0,0 +1,90 @@
+# ShopBot — Customer Service Demo
+
+A complete e-commerce customer service agent built with OPC Agent, deployable to OpenClaw.
+
+## What's Inside
+
+- `oad.yaml` — Full agent definition with product FAQ, order tracking, complaint handling
+- Rich system prompt with personality, escalation rules, and response templates
+- Telegram + Web channel configuration
+
+## Quick Start
+
+### 1. Install OPC Agent
+
+```bash
+npm install -g opc-agent
+```
+
+### 2. Validate the Agent
+
+```bash
+cd examples/customer-service-demo
+opc info
+opc build
+```
+
+### 3. Deploy to OpenClaw
+
+**Option A: Generate workspace files**
+```bash
+opc deploy --target openclaw --output ./shopbot-workspace
+```
+
+This creates a complete OpenClaw agent workspace with:
+- `IDENTITY.md` — Agent identity
+- `SOUL.md` — System prompt and model config
+- `AGENTS.md` — Skills, memory, and trust config
+- `USER.md` — User preferences template
+- `MEMORY.md` — Persistent memory template
+
+**Option B: Deploy and auto-register**
+```bash
+opc deploy --target openclaw --install
+```
+
+This generates the workspace AND registers the agent in `~/.openclaw/openclaw.json`.
+
+### 4. Restart OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+### 5. Test in Telegram
+
+Send a message to your OpenClaw Telegram bot. ShopBot will respond!
+
+Try these:
+- "What headphones do you sell?"
+- "Track my order TS-123456"
+- "I want to return my laptop stand"
+- "This is unacceptable, I want to speak to a manager"
+
+## Architecture
+
+```
+OPC Agent (Development)          OpenClaw (Runtime)
+┌─────────────────────┐         ┌──────────────────────┐
+│  oad.yaml           │         │  IDENTITY.md         │
+│  (agent definition) │──deploy─│  SOUL.md             │
+│                     │         │  AGENTS.md           │
+│  opc build/test     │         │  USER.md             │
+│  opc deploy         │         │  MEMORY.md           │
+└─────────────────────┘         │                      │
+                                │  ← Telegram/Web →    │
+                                └──────────────────────┘
+```
+
+OPC Agent is the **development framework**. OpenClaw is the **runtime**.
+
+## Customization
+
+Edit `oad.yaml` to:
+- Change the product catalog
+- Adjust escalation rules
+- Add new skills
+- Switch LLM provider/model
+- Modify the system prompt personality
+
+Then re-deploy: `opc deploy --target openclaw --install`

package/examples/customer-service-demo/oad.yaml

@@ -0,0 +1,107 @@
+apiVersion: opc/v1
+kind: Agent
+metadata:
+  name: ShopBot
+  version: "1.0.0"
+  description: "E-commerce customer service agent for TechStyle — handles product FAQs, order tracking, returns, and complaint escalation"
+  author: "TechStyle Inc."
+  license: Apache-2.0
+  marketplace:
+    category: customer-service
+    pricing: free
+    tags: [ecommerce, support, faq, orders]
+
+spec:
+  provider:
+    default: deepseek
+    allowed: [openai, deepseek, qwen]
+  model: deepseek-chat
+
+  systemPrompt: |
+    You are ShopBot, the friendly and professional customer service agent for TechStyle, 
+    an online electronics and lifestyle store.
+
+    ## Personality
+    - Warm, helpful, and patient
+    - Professional but not robotic — use a conversational tone
+    - Proactive: anticipate follow-up questions
+    - Empathetic: acknowledge customer frustration before solving problems
+
+    ## Core Capabilities
+    1. **Product FAQ**: Answer questions about products, specs, pricing, availability
+    2. **Order Tracking**: Look up order status by order ID (format: TS-XXXXXX)
+    3. **Returns & Refunds**: Guide customers through return process (30-day policy)
+    4. **Complaint Handling**: De-escalate issues, offer solutions, escalate when needed
+
+    ## Escalation Rules
+    - Escalate to human agent if:
+      - Customer asks 3+ times about the same unresolved issue
+      - Customer explicitly requests a human
+      - Issue involves billing disputes over $100
+      - Customer uses abusive language (remain calm, offer to transfer)
+    - Say: "Let me connect you with a specialist who can help further."
+
+    ## Response Guidelines
+    - Keep responses under 200 words unless detailed explanation is needed
+    - Always confirm understanding: "Just to make sure I understand..."
+    - End with a follow-up: "Is there anything else I can help with?"
+    - For order lookups, ask for order ID if not provided
+    - Never make up order status — if you can't find it, say so
+
+    ## Product Catalog (Quick Reference)
+    - TechStyle Pro Headphones — $149, wireless, ANC, 30hr battery
+    - TechStyle Slim Laptop Stand — $59, aluminum, adjustable
+    - TechStyle Power Bank 20K — $39, 20000mAh, USB-C PD
+    - TechStyle Smart Watch S3 — $199, health tracking, 5-day battery
+    - TechStyle Webcam 4K — $89, autofocus, built-in mic
+
+    ## Return Policy
+    - 30-day return window from delivery date
+    - Item must be in original packaging
+    - Free return shipping for defective items
+    - Refund processed within 5-7 business days
+    - Gift cards and sale items are final sale
+
+  skills:
+    - name: product-faq
+      description: "Answer product questions from the catalog knowledge base"
+      config:
+        source: catalog
+        fallback: "I don't have that info right now. Let me check with the team."
+
+    - name: order-lookup
+      description: "Look up order status by order ID"
+      config:
+        idPattern: "TS-\\d{6}"
+        notFoundMessage: "I couldn't find that order. Double-check the ID (format: TS-XXXXXX)."
+
+    - name: complaint-handler
+      description: "Handle complaints with empathy and escalation logic"
+      config:
+        maxAttempts: 3
+        escalationMessage: "Let me connect you with a specialist who can help further."
+
+  channels:
+    - type: telegram
+      config:
+        welcomeMessage: "Hi! 👋 I'm ShopBot from TechStyle. How can I help you today?"
+    - type: web
+      port: 3000
+
+  memory:
+    shortTerm: true
+    longTerm: false
+
+  dtv:
+    trust:
+      level: verified
+    value:
+      metrics:
+        - response_time
+        - resolution_rate
+        - customer_satisfaction
+
+  streaming:
+    enabled: true
+
+  locale: en

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "opc-agent",
-  "version": "0.3.0",
-  "description": "Open Agent Framework — Build, test, and run AI Agents for business workstations",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "opc": "dist/cli.js"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run",
-    "dev": "tsc --watch",
-    "lint": "tsc --noEmit"
-  },
-  "keywords": [
-    "agent",
-    "ai",
-    "llm",
-    "framework",
-    "typescript",
-    "agent-framework"
-  ],
-  "author": "Deepleaper",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Deepleaper/opc-agent.git"
-  },
-  "dependencies": {
-    "agentkits": "^0.1.0",
-    "commander": "^12.0.0",
-    "express": "^4.21.0",
-    "js-yaml": "^4.1.0",
-    "ws": "^8.20.0",
-    "zod": "^3.23.0"
-  },
-  "devDependencies": {
-    "@types/express": "^4.17.21",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node": "^20.11.0",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.5.0",
-    "vitest": "^2.0.0"
-  }
-}
+{
+  "name": "opc-agent",
+  "version": "0.5.0",
+  "description": "Open Agent Framework — Build, test, and run AI Agents for business workstations",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "opc": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "dev": "tsc --watch",
+    "lint": "tsc --noEmit"
+  },
+  "keywords": [
+    "agent",
+    "ai",
+    "llm",
+    "framework",
+    "typescript",
+    "agent-framework"
+  ],
+  "author": "Deepleaper",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Deepleaper/opc-agent.git"
+  },
+  "dependencies": {
+    "agentkits": "^0.1.0",
+    "commander": "^12.0.0",
+    "express": "^4.21.0",
+    "js-yaml": "^4.1.0",
+    "ws": "^8.20.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}

package/src/channels/voice.ts

@@ -0,0 +1,106 @@
+import { BaseChannel } from './index';
+import type { Message } from '../core/types';
+import { Logger } from '../core/logger';
+
+// ── Voice Channel Types ─────────────────────────────────────
+
+export interface STTProvider {
+  name: string;
+  transcribe(audio: Buffer, options?: STTOptions): Promise<string>;
+}
+
+export interface TTSProvider {
+  name: string;
+  synthesize(text: string, options?: TTSOptions): Promise<Buffer>;
+}
+
+export interface STTOptions {
+  language?: string;
+  model?: string;
+}
+
+export interface TTSOptions {
+  voice?: string;
+  speed?: number;
+  language?: string;
+}
+
+export interface VoiceChannelConfig {
+  sttProvider?: STTProvider;
+  ttsProvider?: TTSProvider;
+  sampleRate?: number;
+  language?: string;
+}
+
+// ── Voice Channel ───────────────────────────────────────────
+
+export class VoiceChannel extends BaseChannel {
+  type = 'voice';
+  private config: VoiceChannelConfig;
+  private logger = new Logger('voice-channel');
+  private running = false;
+
+  constructor(config?: VoiceChannelConfig) {
+    super();
+    this.config = config ?? {};
+  }
+
+  async start(): Promise<void> {
+    this.running = true;
+    this.logger.info('Voice channel started', {
+      stt: this.config.sttProvider?.name ?? 'none',
+      tts: this.config.ttsProvider?.name ?? 'none',
+    });
+  }
+
+  async stop(): Promise<void> {
+    this.running = false;
+    this.logger.info('Voice channel stopped');
+  }
+
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /** Process audio input: STT → Agent → TTS */
+  async processAudio(audio: Buffer): Promise<{ text: string; response: string; audioResponse?: Buffer }> {
+    if (!this.handler) throw new Error('No message handler set');
+
+    // STT
+    let text: string;
+    if (this.config.sttProvider) {
+      text = await this.config.sttProvider.transcribe(audio, { language: this.config.language });
+    } else {
+      text = audio.toString('utf-8'); // Fallback: treat as text
+    }
+
+    this.logger.debug('STT result', { text });
+
+    // Create message and send to agent
+    const message: Message = {
+      id: `voice_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+      role: 'user',
+      content: text,
+      timestamp: Date.now(),
+      metadata: { channel: 'voice' },
+    };
+
+    const response = await this.handler(message);
+
+    // TTS
+    let audioResponse: Buffer | undefined;
+    if (this.config.ttsProvider) {
+      audioResponse = await this.config.ttsProvider.synthesize(response.content, { language: this.config.language });
+    }
+
+    return { text, response: response.content, audioResponse };
+  }
+
+  setSTTProvider(provider: STTProvider): void {
+    this.config.sttProvider = provider;
+  }
+
+  setTTSProvider(provider: TTSProvider): void {
+    this.config.ttsProvider = provider;
+  }
+}