openkbs 0.0.65 → 0.0.66

package/templates/.claude/skills/openkbs/reference/commands.md

@@ -0,0 +1,370 @@
+# XML Commands Reference
+
+Commands are XML tags with JSON content that the LLM outputs. The backend parses these and executes corresponding functions.
+
+## Command Pattern
+
+```xml
+<commandName>
+{"param": "value"}
+</commandName>
+```
+
+Self-closing commands (no parameters):
+
+```xml
+<commandName/>
+```
+
+## How Commands Work
+
+```
+LLM outputs: "Let me search. <googleSearch>{"query": "..."}</googleSearch>"
+                                    ↓
+handler.js parses XML tags
+Matches against regex patterns in actions.js
+Executes the async function
+                                    ↓
+Result returned with _meta_actions:
+  - ["REQUEST_CHAT_MODEL"] → send back to LLM
+  - [] → display to user, stop
+```
+
+## Implementing Commands
+
+### In actions.js
+
+```javascript
+export const getActions = (meta, event) => [
+    // Standard command
+    [/<commandName>([\s\S]*?)<\/commandName>/s, async (match) => {
+        const data = JSON.parse(match[1].trim());
+        // Execute logic
+        return {
+            type: 'RESULT_TYPE',
+            data: result,
+            _meta_actions: ["REQUEST_CHAT_MODEL"]
+        };
+    }],
+
+    // Self-closing command
+    [/<commandName\s*\/>/s, async () => {
+        // Execute logic
+        return { type: 'RESULT', _meta_actions: [] };
+    }]
+];
+```
+
+### In instructions.txt
+
+```text
+<commandName>
+{
+  "param1": "description",
+  "param2": "description"
+}
+</commandName>
+Description: What this command does.
+```
+
+## Standard Commands
+
+### googleSearch
+
+Search the web.
+
+```xml
+<googleSearch>
+{"query": "search terms"}
+</googleSearch>
+```
+
+### webpageToText
+
+Extract text from a webpage.
+
+```xml
+<webpageToText>
+{"url": "https://example.com"}
+</webpageToText>
+```
+
+### createAIImage
+
+Generate an AI image.
+
+```xml
+<createAIImage>
+{
+  "prompt": "image description",
+  "aspect_ratio": "16:9"
+}
+</createAIImage>
+```
+
+Aspect ratios: `1:1`, `16:9`, `9:16`, `4:3`
+
+### setMemory
+
+Save data to memory.
+
+```xml
+<setMemory>
+{
+  "itemId": "memory_key_name",
+  "value": {"any": "data"},
+  "expirationInMinutes": 1440
+}
+</setMemory>
+```
+
+### deleteItem
+
+Delete a memory item.
+
+```xml
+<deleteItem>
+{"itemId": "memory_key_name"}
+</deleteItem>
+```
+
+### cleanupMemory
+
+Remove expired memory items.
+
+```xml
+<cleanupMemory/>
+```
+
+### scheduleTask
+
+Schedule a future task.
+
+```xml
+<scheduleTask>
+{
+  "message": "Reminder text",
+  "delay": "2h"
+}
+</scheduleTask>
+```
+
+Delay formats: `30m` (minutes), `2h` (hours), `1d` (days)
+Or specific time: `"time": "2024-12-25 10:00"`
+
+### getScheduledTasks
+
+List pending scheduled tasks.
+
+```xml
+<getScheduledTasks/>
+```
+
+### deleteScheduledTask
+
+Cancel a scheduled task.
+
+```xml
+<deleteScheduledTask>
+{"timestamp": 1704067200000}
+</deleteScheduledTask>
+```
+
+### sendTelegram
+
+Send a Telegram message (requires Telegram integration).
+
+```xml
+<sendTelegram>
+{"text": "Hello from agent!"}
+</sendTelegram>
+```
+
+### sendTelegramPhoto
+
+Send a photo to Telegram.
+
+```xml
+<sendTelegramPhoto>
+{"url": "https://example.com/image.png", "caption": "Photo caption"}
+</sendTelegramPhoto>
+```
+
+### createAIVideo
+
+Generate an AI video.
+
+```xml
+<createAIVideo>
+{
+  "prompt": "cinematic sunset timelapse",
+  "model": "sora-2",
+  "seconds": 8,
+  "size": "1280x720"
+}
+</createAIVideo>
+```
+
+Models: `sora-2`, `sora-2-pro`
+Seconds: `4`, `8`, `12`
+Sizes: `1280x720` (landscape), `720x1280` (portrait)
+
+### continueVideoPolling
+
+Check video generation status.
+
+```xml
+<continueVideoPolling>
+{"videoId": "video_123456"}
+</continueVideoPolling>
+```
+
+### deepResearch
+
+Start autonomous research (5-20 minutes).
+
+```xml
+<deepResearch>
+{
+  "query": "AI market trends 2025",
+  "previous_interaction_id": "optional_for_followup"
+}
+</deepResearch>
+```
+
+### continueDeepResearchPolling
+
+Check research status.
+
+```xml
+<continueDeepResearchPolling>
+{
+  "interactionId": "interaction_123",
+  "prepaidCredits": 50
+}
+</continueDeepResearchPolling>
+```
+
+### viewImage
+
+Load image into LLM vision context.
+
+```xml
+<viewImage>
+{"url": "https://example.com/image.jpg"}
+</viewImage>
+```
+
+### archiveItems
+
+Move items to VectorDB long-term storage.
+
+```xml
+<archiveItems>
+["memory_item1", "memory_item2"]
+</archiveItems>
+```
+
+### searchArchive
+
+Semantic search in VectorDB.
+
+```xml
+<searchArchive>
+{
+  "query": "find marketing strategies",
+  "topK": 10,
+  "minScore": 0
+}
+</searchArchive>
+```
+
+### publishWebPage
+
+Publish HTML as static page.
+
+```xml
+<publishWebPage>
+<!DOCTYPE html>
+<html>
+<head><title>My Page</title></head>
+<body>Content here</body>
+</html>
+</publishWebPage>
+```
+
+## MCP Commands
+
+MCP tools use a dynamic pattern:
+
+```xml
+<mcp_{server}_{toolName}>
+{"param": "value"}
+</mcp_{server}_{toolName}>
+```
+
+### Brave Search
+
+```xml
+<mcp_brave-search_brave_web_search>
+{"query": "search terms", "count": 10}
+</mcp_brave-search_brave_web_search>
+```
+
+### GitHub
+
+```xml
+<mcp_github_search_repositories>
+{"query": "language:typescript stars:>1000"}
+</mcp_github_search_repositories>
+```
+
+## Meta Actions
+
+Control what happens after command execution:
+
+```javascript
+// Send result to LLM for follow-up
+return { data: result, _meta_actions: ["REQUEST_CHAT_MODEL"] };
+
+// Display to user, stop conversation
+return { data: result, _meta_actions: [] };
+```
+
+Use `["REQUEST_CHAT_MODEL"]` when:
+- LLM needs to process the result
+- Multi-step workflows
+- Error handling
+
+Use `[]` when:
+- Final output (images, confirmations)
+- No further processing needed
+
+## Parallel Execution
+
+Multiple commands in a single message execute in parallel via `Promise.all`:
+
+```text
+<googleSearch>{"query": "topic 1"}</googleSearch>
+<googleSearch>{"query": "topic 2"}</googleSearch>
+```
+
+Both searches run simultaneously.
+
+## Error Handling
+
+Return errors in a consistent format:
+
+```javascript
+try {
+    // Execute command
+} catch (e) {
+    return {
+        type: "ERROR",
+        error: e.message,
+        _meta_actions: ["REQUEST_CHAT_MODEL"]
+    };
+}
+```
+
+The LLM receives the error and can inform the user or retry.

package/templates/.claude/skills/openkbs/reference/elastic-services.md

@@ -0,0 +1,327 @@
+# Elastic Services Reference
+
+OpenKBS provides managed cloud infrastructure that scales automatically.
+
+## Overview
+
+| Service | Purpose | CLI Command |
+|---------|---------|-------------|
+| Functions | Serverless Lambda (Node.js, Java, Python) | `openkbs fn` |
+| Postgres | Managed PostgreSQL (Neon) | `openkbs postgres` |
+| Storage | S3 file storage | `openkbs storage` |
+| Pulse | Real-time WebSocket pub/sub | `openkbs pulse` |
+
+## Configuration (openkbs.json)
+
+```json
+{
+  "elastic": {
+    "functions": {
+      "hello": {
+        "runtime": "nodejs22.x",
+        "memory": 512,
+        "timeout": 30
+      }
+    },
+    "postgres": true,
+    "storage": true,
+    "pulse": true
+  }
+}
+```
+
+## Deploy/Destroy
+
+```bash
+openkbs deploy          # Deploy all configured services
+openkbs destroy         # Remove all services
+openkbs stack           # Show current stack status
+```
+
+---
+
+## Functions (Lambda)
+
+Serverless functions with automatic scaling.
+
+### Create Function
+
+```bash
+mkdir -p functions/hello
+```
+
+Create `functions/hello/index.mjs`:
+
+```javascript
+export const handler = async (event) => {
+    const body = JSON.parse(event.body || '{}');
+    return {
+        statusCode: 200,
+        body: JSON.stringify({ message: 'Hello', input: body })
+    };
+};
+```
+
+### CLI Commands
+
+```bash
+openkbs fn list                           # List all functions
+openkbs fn push hello --region us-east-1  # Deploy function
+openkbs fn delete hello                   # Delete function
+openkbs fn logs hello                     # View logs
+openkbs fn env hello                      # View env vars
+openkbs fn env hello API_KEY=secret       # Set env var
+openkbs fn invoke hello '{"test": true}'  # Invoke function
+```
+
+### Supported Runtimes
+
+- `nodejs22.x`, `nodejs20.x`, `nodejs18.x`
+- `python3.12`, `python3.11`
+- `java21`, `java17`
+
+### Access from Agent
+
+```javascript
+// In actions.js
+const response = await fetch('https://fn.openkbs.com/YOUR_KB_ID/hello', {
+    method: 'POST',
+    body: JSON.stringify({ data: 'value' })
+});
+```
+
+---
+
+## Postgres (Neon)
+
+Managed PostgreSQL database.
+
+### CLI Commands
+
+```bash
+openkbs postgres shell              # Connect to psql
+openkbs postgres connection-string  # Get connection URL
+openkbs postgres status             # Show database info
+```
+
+### Access from Agent
+
+Connection string is available as `POSTGRES_URL` environment variable:
+
+```javascript
+// In onRequest.js or actions.js
+import pg from 'pg';
+const { Pool } = pg;
+
+const pool = new Pool({
+    connectionString: process.env.POSTGRES_URL,
+    ssl: { rejectUnauthorized: false }
+});
+
+const result = await pool.query('SELECT * FROM users WHERE id = $1', [userId]);
+```
+
+### Add Dependency
+
+In `src/Events/onRequest.json`:
+
+```json
+{
+  "dependencies": {
+    "pg": "^8.13.1"
+  }
+}
+```
+
+---
+
+## Storage (S3)
+
+File storage with presigned URLs.
+
+### CLI Commands
+
+```bash
+openkbs storage list              # List buckets
+openkbs storage list BUCKET_NAME  # List files in bucket
+openkbs storage upload FILE       # Upload file
+openkbs storage download FILE     # Download file
+openkbs storage delete FILE       # Delete file
+```
+
+### Access from Agent
+
+```javascript
+// Upload file
+const uploaded = await openkbs.uploadImage(
+    base64Content,
+    'image.png',
+    'image/png'
+);
+console.log(uploaded.url);  // Public URL
+
+// Get presigned URL for upload
+const presigned = await openkbs.kb({
+    action: 'getPresignedUploadUrl',
+    filename: 'document.pdf',
+    contentType: 'application/pdf'
+});
+// Returns: { uploadUrl, publicUrl }
+```
+
+---
+
+## Pulse (WebSocket)
+
+Real-time messaging and pub/sub.
+
+### CLI Commands
+
+```bash
+openkbs pulse status   # Show Pulse status
+openkbs pulse channels # List channels
+```
+
+### Access from Agent
+
+```javascript
+// Publish message
+await openkbs.pulse.publish('channel-name', {
+    type: 'notification',
+    data: { message: 'Hello subscribers!' }
+});
+
+// Subscribe (frontend)
+const ws = new WebSocket(`wss://pulse.openkbs.com/${kbId}/channel-name`);
+ws.onmessage = (event) => {
+    const data = JSON.parse(event.data);
+    console.log('Received:', data);
+};
+```
+
+### Use Cases
+
+- Real-time notifications
+- Live updates to frontend
+- Multi-user collaboration
+- Event streaming
+
+---
+
+## Full-Stack Example
+
+Complete Node.js application with all services:
+
+### openkbs.json
+
+```json
+{
+  "elastic": {
+    "functions": {
+      "api": { "runtime": "nodejs22.x", "memory": 512 }
+    },
+    "postgres": true,
+    "storage": true,
+    "pulse": true
+  }
+}
+```
+
+### functions/api/index.mjs
+
+```javascript
+import pg from 'pg';
+const { Pool } = pg;
+
+const pool = new Pool({
+    connectionString: process.env.POSTGRES_URL,
+    ssl: { rejectUnauthorized: false }
+});
+
+export const handler = async (event) => {
+    const { action, data } = JSON.parse(event.body || '{}');
+
+    switch (action) {
+        case 'list':
+            const result = await pool.query('SELECT * FROM items');
+            return { statusCode: 200, body: JSON.stringify(result.rows) };
+
+        case 'create':
+            await pool.query('INSERT INTO items (name) VALUES ($1)', [data.name]);
+            return { statusCode: 201, body: JSON.stringify({ success: true }) };
+
+        default:
+            return { statusCode: 400, body: JSON.stringify({ error: 'Unknown action' }) };
+    }
+};
+```
+
+### Deploy
+
+```bash
+openkbs deploy
+openkbs fn push api
+```
+
+---
+
+## Java API Example
+
+### functions/api/pom.xml
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>com.amazonaws</groupId>
+        <artifactId>aws-lambda-java-core</artifactId>
+        <version>1.2.3</version>
+    </dependency>
+    <dependency>
+        <groupId>org.postgresql</groupId>
+        <artifactId>postgresql</artifactId>
+        <version>42.7.4</version>
+    </dependency>
+</dependencies>
+```
+
+### Deploy Java Function
+
+```bash
+cd functions/api
+mvn package
+openkbs fn push api --runtime java21
+```
+
+---
+
+## Python API Example
+
+### functions/api/handler.py
+
+```python
+import json
+import psycopg2
+import os
+
+def handler(event, context):
+    conn = psycopg2.connect(os.environ['POSTGRES_URL'])
+    cur = conn.cursor()
+    cur.execute("SELECT * FROM items")
+    rows = cur.fetchall()
+    return {
+        'statusCode': 200,
+        'body': json.dumps(rows)
+    }
+```
+
+### requirements.txt
+
+```
+psycopg2-binary
+```
+
+### Deploy
+
+```bash
+openkbs fn push api --runtime python3.12
+```