openkbs 0.0.53 → 0.0.55

package/templates/CLAUDE.md

@@ -1,284 +1,655 @@
 # Claude Code Instructions
 
+> **Full Documentation**: For comprehensive SDK reference, API details, and advanced examples, fetch the official documentation:
+> `https://raw.githubusercontent.com/open-kbs/openkbs/refs/heads/main/README.md`
+> Or visit: https://github.com/open-kbs/openkbs
+
 # MANDATORY FIRST STEPS
-**CRITICAL**: Before taking ANY action, implementing ANY feature, planing the implementation or answering ANY question about this project, you must perform the following steps:
+
+**CRITICAL**: Before taking ANY action, you must:
 
 **FIRST**: Update the knowledge base:
 ```bash
 openkbs update
 ```
 
-**SECOND**: Read every single file in the examples folder using the Read tool:
-- First discover all files in the `.openkbs/knowledge/examples/` directory and ALL subdirectories.
-- Then, use the Read tool to examine the content of EACH file individually (skip only icon.png files, src/Frontend/Presentational/* and src/Events/Helpers/*).
-- You must read ALL files directly
+**SECOND**: Read the https://github.com/open-kbs/tutorials and all files in `.openkbs/knowledge/examples/` directory and subdirectories using the Read tool (skip icon.png, src/Frontend/Presentational/*, src/Events/Helpers/*).
+``
+**THIRD**: Read existing agent code in `./app/` and `./src/` folders.
 
-**THIRD**: Read existing agent code using the Read tool:
-- First discover all files in the `./app/`, `./src/`, and `./scripts/` folders.
-- Then, use the Read tool to examine each file individually
+# Critical Rules
+- Never skip reading examples
+- Never guess framework methods, settings or variables — always reference the examples
+- In src/Events and src/Frontend always use Imports (not Require)
+- Valid values for `_meta_actions` key are `[]` or `["REQUEST_CHAT_MODEL"]`
+- Add npm dependencies only if necessary
+- Before using third-party services in handlers, ask the user for permission
 
-# OpenKBS Agent Development Guidelines
+---
 
-## **Critical** Rules (**IMPORTANT**)
-- Never skip reading examples
-- Study the complete working examples to understand OpenKBS patterns
-- Never guess framework methods, settings or variables — always reference the examples.
+# OpenKBS Framework Overview
 
-## FIRST DECISION: Execution Context Analysis
+## What is OpenKBS?
 
-** BEFORE writing ANY code, you MUST answer these questions IN ORDER:**
+OpenKBS is a framework for building **AI agents** - intelligent assistants that can:
+- Converse with users via LLM (Claude, GPT, etc.)
+- Execute commands (generate images, send emails, search web, etc.)
+- Store and retrieve data (memory system)
+- Run scheduled tasks (cronjobs)
+- Provide custom UI (React-based frontend)
 
-1. **Where will this code execute?** (Cloud or Local)
-2. **What resources does it need to access?** (List each: databases, APIs, files, etc.)
-3. **Where does each resource exist?** (Public internet, local network, specific machine)
-4. **Can the execution environment reach each resource?** (Network path exists?)
+## How It Works - The Request/Response Cycle
 
-**You MUST show your reasoning for these 4 questions before any code implementation.**
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           USER SENDS MESSAGE                                 │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  1. onRequest Handler (optional)                                            │
+│     - Pre-process user message                                              │
+│     - Inject context (memory items, user data)                              │
+│     - Validate or transform input                                           │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  2. LLM Processing                                                          │
+│     - System instructions from app/instructions.txt                         │
+│     - Conversation history                                                  │
+│     - LLM generates response (may include <command> tags)                   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                                    ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  3. onResponse Handler                                                      │
+│     - Parse LLM response for commands: <commandName>{...}</commandName>     │
+│     - Execute matching actions from actions.js                              │
+│     - Return result with _meta_actions:                                     │
+│       • [] = stop, show result to user                                      │
+│       • ["REQUEST_CHAT_MODEL"] = send result back to LLM for continuation   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                    │
+                    ┌───────────────┴───────────────┐
+                    │                               │
+                    ▼                               ▼
+        ┌───────────────────┐           ┌───────────────────┐
+        │ _meta_actions: [] │           │ REQUEST_CHAT_MODEL│
+        │ Show to user      │           │ Loop back to LLM  │
+        └───────────────────┘           └───────────────────┘
+```
 
-## Development Guidelines
-- To add npm dependency to backend handlers, add it to onRequest.json and onResponse.json
-- In src/Events and src/Frontend always use Imports (not Require)
-- To add npm dependency to the frontend, add it to contentRender.json
-- Valid values for the _meta_actions key are [] or ["REQUEST_CHAT_MODEL"]
-- Add and use npm dependencies only if necessary, some of those shown in the examples are purely demonstrative
-- If developing new agent, generate it's own ./scripts/run_job.js
-- Before using third-party services in onRequest and onResponse handlers, ask the user for permission
-- provide README.md
-
-## Architecture Overview: Execution Environments Define Everything
-
-OpenKBS provides **three distinct execution environments**, each with different capabilities and constraints:
-
-### Execution Environment Reality Check
-
-**Cloud Environment (`./src/Events/`):**
-- Runs in serverless compute service for running code (stateless, ephemeral)
-- No localhost, no local filesystem, no persistent state
-- Can ONLY reach internet-accessible resources
-- Each execution is isolated and temporary
-
-**Browser Environment (`./src/Frontend/`):**
-- Runs in user's browser when visiting https://[kbId].apps.openkbs.com
-- React-based UI customization
-- Subject to browser security constraints
-
-**Local Environment (`./scripts/`) - Optional but Powerful:**
-- Runs on YOUR machine with YOUR network context
-- Can access YOUR localhost, files, and local services
-- Enables advanced patterns: multi-agent orchestration, local resource integration
-- Not required for simple agents, but unlocks complex workflows
-
-### The Fundamental Rule
-**Before writing ANY code, ask: Where does this run and what can it reach?**
-
-### Backend
-The OpenKBS backend framework is for developing AI agents with custom tools, using Node.js.
-It integrates with openkbs chat service via `onRequest` and `onResponse` handlers for custom actions and service integration.
-
-#### Backend Handlers (Cloud Environment)
-The OpenKBS framework's core uses `onRequest` and `onResponse` handlers as middleware for message tool call parsing and execution.
-These handlers run in the cloud environment.
-- **`onResponse` Handler:** Activated after the LLM generates a message, enabling command extraction, and action execution.
-- **`onRequest` Handler:** Triggered on user message to allow the user to execute action
-
-#### NPM Dependencies for onRequest.js or onResponse.js Backend Handlers (Cloud → Public resources)
-1. If a file imports an NPM dependency and is then imported by onRequest.js or onResponse.js, this dependency must be defined in the handler's corresponding json file
-   Example: If actions.js imports mysql2 and onResponse.js imports actions.js, then mysql2 must be in onResponse.json:
-   {
-   "dependencies": {
-   "mysql2": "latest"
-   }
-   }
-
-Similarly, we need to create onRequest.json for onRequest.js as each handler have separate Node.js build with separate dependencies
-
-#### Managing Secrets for Backend Handlers
-Secrets securely store credentials that allow Backend Handlers to access external services like databases, APIs, etc.
-Example:
-`const key = "{{secrets.KEY}}"`
-
-**Workflow**:
-1. Write code using {{secrets.SECRET_NAME}} placeholders
-2. Deploy agent with `openkbs push` (generates kbId in settings.json)
-3. Prompt developer to define secrets: `Please set your credentials at: https://[kbId].apps.openkbs.com/?add_secrets=SECRET_NAME1,SECRET_NAME2`
-
-**Example**: For MySQL connection requiring {{secrets.DB_HOST}}, {{secrets.DB_USER}}, {{secrets.DB_PASS}}:
-`Please define your database credentials: https://[kbId].apps.openkbs.com/?add_secrets=DB_HOST,DB_USER,DB_PASS`
-
-**Important**
-Secrets syntax above is only applicable for all src/Events/* files, and NOT for User-Run Scripts
-
-#### User-Run Scripts (Local Environment)
-User-run scripts are located in the `./scripts/` folder and communicate with cloud agents via API calls.
-They execute locally, receiving the final result of the agent's flow as an API response.
-This setup allows seamless interaction with local services, such as a MySQL database, directly on the user's machine.
-To handle secrets in user-defined scripts, define them in a `.env` file and load them using the `dotenv` package.
-
-**Key Components:**
-- `scripts/run_job.js` - Main job runner for calling the cloud agent
-- `scripts/utils/agent_client.js` - Shared utility using `OpenKBSAgentClient` class
-- Custom workflow scripts for multi-agent orchestration
-
-**Architecture:**
-- Scripts use `OpenKBSAgentClient` to communicate with deployed cloud agents
-- **Path Resolution**: Automatically finds `app/settings.json` and `.openkbs/secrets.json` by walking up directories
-- **Usage**: `const client = new OpenKBSAgentClient(); await client.runJob(message);`
-- **Multi-agent support**: Each agent (base or related) finds its own settings and secrets in its directory structure
-
-#### NPM Dependencies for User-Run Scripts (Local → Public + Private resources)
-Add needed NPM dependencies to `package.json`
-Example: Script connecting to local MySQL:
-```json
+## Project Structure
+
+```
+my-agent/
+├── app/
+│   ├── settings.json        # Agent config (model, title, tools)
+│   ├── instructions.txt     # System prompt for LLM
+│   └── icon.png             # Agent icon
+├── src/
+│   ├── Events/              # Backend handlers (serverless)
+│   │   ├── onRequest.js     # Pre-process user messages
+│   │   ├── onResponse.js    # Execute commands from LLM
+│   │   ├── actions.js       # Command implementations
+│   │   ├── onCronjob.js     # Scheduled tasks
+│   │   └── *.json           # NPM dependencies per handler
+│   └── Frontend/            # Browser-side React code
+│       ├── contentRender.js # Custom UI (Header, message rendering)
+│       └── contentRender.json # Frontend NPM dependencies
+└── README.md
+```
+
+## Two Execution Environments
+
+### 1. Backend (Cloud) - `src/Events/`
+- Runs in **serverless Lambda** (Node.js)
+- Stateless, ephemeral execution
+- Has `openkbs` SDK object with full capabilities
+- Can access external APIs, databases, send emails
+- Triggered by: user messages, LLM responses, cronjobs, API calls
+
+### 2. Frontend (Browser) - `src/Frontend/`
+- Runs in **user's browser** (React)
+- Customizes chat UI (header, message rendering)
+- Has `openkbs` object with item CRUD, Files API, Sharing API
+- Cannot access secrets or server-side resources
+
+## Event Handlers
+
+| Handler | Trigger | Purpose |
+|---------|---------|---------|
+| `onRequest` | User sends message | Pre-process, inject context, validate |
+| `onResponse` | LLM generates response | Parse commands, execute actions |
+| `onCronjob` | Cron schedule | Automated tasks, cleanup, reports |
+| `onAddMessages` | API adds messages | Process external integrations |
+| `onPublicAPIRequest` | Public API call | Webhooks, external triggers |
+
+## The Command Pattern
+
+LLM outputs commands as XML tags. Backend parses and executes them:
+
+```
+User: "Generate an image of a sunset"
+        ↓
+LLM: "I'll create that for you. <createAIImage>{"prompt": "sunset"}</createAIImage>"
+        ↓
+onResponse: Matches pattern, calls openkbs.generateImage()
+        ↓
+Returns: { type: 'CHAT_IMAGE', data: { imageUrl: '...' }, _meta_actions: [] }
+        ↓
+Frontend: Renders image to user
+```
+
+## Memory System
+
+Persistent key-value storage with automatic encryption:
+
+```javascript
+// Backend
+await openkbs.createItem({ itemType: 'memory', itemId: 'memory_user_prefs', body: { theme: 'dark' } });
+const item = await openkbs.getItem('memory_user_prefs');
+
+// Frontend (same API)
+await openkbs.createItem({ itemType: 'memory', itemId: 'memory_key', body: { data: 'value' } });
+```
+
+Items are auto-encrypted and scoped to the KB. Use prefixes for organization:
+- `memory_` - User/agent memory
+- `agent_` - Agent configuration
+- `cache_` - Temporary cached data
+
+## Frontend Framework
+
+The frontend is an **extendable React application** that runs in the user's browser. You customize it through `contentRender.js` which exports specific functions:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                         CHAT APPLICATION (React)                            │
+├─────────────────────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Header Component (optional)                                         │   │
+│  │  - Custom UI above chat (settings panels, navigation, branding)      │   │
+│  │  - Receives: openkbs, setRenderSettings, setSystemAlert, etc.        │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Chat Messages Area                                                  │   │
+│  │  ┌─────────────────────────────────────────────────────────────┐    │   │
+│  │  │  Each message passes through onRenderChatMessage()          │    │   │
+│  │  │  - Return React component → custom rendering                │    │   │
+│  │  │  - Return null → default markdown rendering                 │    │   │
+│  │  │  - Return HIDDEN_MESSAGE → hide message completely          │    │   │
+│  │  └─────────────────────────────────────────────────────────────┘    │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │  Input Area (built-in, customizable via setRenderSettings)          │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+**Key Extension Points:**
+
+| Export | Purpose |
+|--------|---------|
+| `Header` | Custom header component (settings panels, branding, navigation) |
+| `onRenderChatMessage` | Custom message rendering (widgets, images, hidden messages) |
+
+**What You Can Do:**
+
+1. **Custom Command Widgets** - Render `<createAIImage>` as icon instead of raw XML
+2. **Settings Panels** - Add tabbed panels for Memory, Files, Sharing management
+3. **Hide System Messages** - Filter out technical responses from UI
+4. **Custom Interactions** - Buttons that send follow-up messages via `RequestChatAPI`
+5. **Branding** - Custom logos, colors via `setRenderSettings`
+
+**Built-in Libraries** (no need to install):
+- `react` - React 18
+- `@mui/material` - Material UI components
+- `@mui/icons-material` - Material icons
+- `@emotion/react` - CSS-in-JS styling
+
+**Frontend SDK (`openkbs` object):**
+- Item CRUD - same API as backend
+- `openkbs.Files` - Upload, list, delete files
+- `openkbs.KBAPI` - Share KB with users
+- `openkbs.kbId`, `openkbs.isMobile` - Context info
+
+---
+
+# Architecture Details
+
+OpenKBS provides **two execution environments**:
+
+## Cloud Environment (`./src/Events/`)
+Runs in serverless compute (stateless, ephemeral). Can only reach internet-accessible resources.
+
+### Backend Handlers
+- **`onRequest`**: Triggered on user message, allows pre-processing
+- **`onResponse`**: Activated after LLM response, enables command extraction and action execution
+- **`onCronjob`**: Scheduled task execution (define schedule with `handler.CRON_SCHEDULE`)
+- **`onAddMessages`**: Intercept messages added via API
+- **`onPublicAPIRequest`**: Handle public API requests (no auth required)
+
+### Command Format
+Commands use XML tags with JSON content. The LLM outputs these as regular text:
+```xml
+<commandName>
 {
-   "dependencies": {
-      "mysql2": "latest",
-      "dotenv": "latest"
-   }
+  "param1": "value1",
+  "param2": "value2"
 }
+</commandName>
 ```
-Run `npm install` before executing scripts.
 
-### Frontend Overview
-The OpenKBS frontend framework, built with React and MUI, offers a flexible platform for custom chat interfaces. Developers can customize chat appearance and behavior via the `contentRender` module.
+Self-closing tags for commands without parameters:
+```xml
+<commandName/>
+```
 
-#### contentRender
-The `contentRender.js` file is central to frontend customization, exporting key functions for interface adjustments.
-- **`onRenderChatMessage(params)`:** function called every time a chat message is rendered.
+### Action Pattern
+```javascript
+// src/Events/actions.js
+export const getActions = (meta, event) => [
+    // Basic command with JSON parsing
+    [/<commandName>([\s\S]*?)<\/commandName>/s, async (match) => {
+        const data = JSON.parse(match[1].trim());
+        return { type: 'RESULT', data: result, ...meta, _meta_actions: ['REQUEST_CHAT_MODEL'] };
+    }],
+
+    // View image - adds to LLM vision context
+    [/<viewImage>([\s\S]*?)<\/viewImage>/s, async (match) => {
+        const data = JSON.parse(match[1].trim());
+        return {
+            data: [
+                { type: "text", text: `Viewing: ${data.url}` },
+                { type: "image_url", image_url: { url: data.url } }
+            ],
+            ...meta, _meta_actions: ['REQUEST_CHAT_MODEL']
+        };
+    }],
+
+    // Memory operations
+    [/<setMemory>([\s\S]*?)<\/setMemory>/s, async (match) => {
+        const data = JSON.parse(match[1].trim());
+        await openkbs.updateItem({
+            itemType: 'memory',
+            itemId: data.itemId.startsWith('memory_') ? data.itemId : `memory_${data.itemId}`,
+            body: { value: data.value, updatedAt: new Date().toISOString() }
+        });
+        return { type: 'MEMORY_UPDATED', itemId: data.itemId, ...meta, _meta_actions: ['REQUEST_CHAT_MODEL'] };
+    }],
+
+    // Delete item
+    [/<deleteItem>([\s\S]*?)<\/deleteItem>/s, async (match) => {
+        const data = JSON.parse(match[1].trim());
+        await openkbs.deleteItem(data.itemId);
+        return { type: 'ITEM_DELETED', itemId: data.itemId, ...meta, _meta_actions: ['REQUEST_CHAT_MODEL'] };
+    }],
+];
+```
 
-#### OpenKBS commands
-`openkbs create my-agent` - creates a directory structure for a new agent
-`openkbs push` - after completing changes to your agent, use this command to deploy it to the OpenKBS cloud.
-`node scripts/run_job.js init` - execute right after `openkbs push` to configure the API Key before running the job for the specific agent.
+### onCronjob Handler
+```javascript
+// src/Events/onCronjob.js
+export const handler = async (event) => {
+    // Create a new chat with notification
+    await openkbs.chats({
+        chatTitle: 'Scheduled Report',
+        message: JSON.stringify([{ type: "text", text: "Daily report" }])
+    });
+    return { success: true };
+};
+
+// IMPORTANT: Define schedule at end of file
+handler.CRON_SCHEDULE = "0 * * * *"; // Every hour
+```
 
-### Creating Related Agents
-To create related agents that work alongside the main agent:
+Cron patterns: `* * * * *` (every min), `*/5 * * * *` (5 min), `0 * * * *` (hourly), `0 0 * * *` (daily)
+
+## Backend SDK (openkbs object)
+
+### Image & Video Generation
+```javascript
+// Generate image with Gemini (supports editing with reference images)
+const images = await openkbs.generateImage(prompt, {
+    model: 'gemini-2.5-flash-image', // or 'gpt-image-1' (better for text)
+    aspect_ratio: '16:9',            // gemini: 1:1, 16:9, 9:16, 4:3, 3:4
+    imageUrls: ['reference.jpg'],    // gemini only - for editing
+    size: '1024x1024'                // gpt-image-1: 1024x1024, 1536x1024, 1024x1536
+});
+const uploaded = await openkbs.uploadImage(images[0].b64_json, 'output.png', 'image/png');
+console.log(uploaded.url);
+
+// Generate video with Sora 2
+const video = await openkbs.generateVideo(prompt, {
+    video_model: 'sora-2',           // or 'sora-2-pro' (higher quality)
+    seconds: 8,                      // 4, 8, or 12
+    size: '1280x720',                // or '720x1280' (portrait)
+    input_reference_url: 'img.jpg'   // optional reference image
+});
+// Check status if pending
+if (video[0]?.status === 'pending') {
+    const status = await openkbs.checkVideoStatus(video[0].video_id);
+}
+```
 
-1. **Create in related-agents/ folder**: `cd related-agents && openkbs create agent-name`
-2. **Each related agent gets**: Own `app/settings.json`, `src/` folder, and `.openkbs/secrets.json`
-3. **Script usage**: Related agents use their own `agent_client.js` located in their subdirectory, ensuring they access their own settings and secrets file.
-4. **Multi-agent workflows**: Scripts can orchestrate multiple agents by creating separate client instances
+### Item Storage (Memory System)
+```javascript
+// Create/Update item (upsert pattern)
+async function upsertItem(itemType, itemId, body) {
+    try {
+        await openkbs.updateItem({ itemType, itemId, body });
+    } catch (e) {
+        await openkbs.createItem({ itemType, itemId, body });
+    }
+}
 
-Related agents are independent but can share the base agent's script utilities.
+// Memory with expiration
+await upsertItem('memory', 'memory_user_preferences', {
+    value: { theme: 'dark', language: 'en' },
+    updatedAt: new Date().toISOString(),
+    exp: new Date(Date.now() + 60 * 60 * 1000).toISOString() // 1 hour
+});
+
+// Get single item (body is auto-decrypted)
+const item = await openkbs.getItem('memory_user_preferences');
+console.log(item.item.body.value);
+
+// Fetch multiple items with filters
+const items = await openkbs.fetchItems({
+    itemType: 'memory',
+    beginsWith: 'memory_',
+    limit: 100
+});
+
+// Delete item
+await openkbs.deleteItem('memory_user_preferences');
+
+// Cleanup expired items
+const now = new Date();
+for (const item of items.items) {
+    if (item.item?.body?.exp && new Date(item.item.body.exp) < now) {
+        await openkbs.deleteItem(item.meta.itemId);
+    }
+}
+```
 
-## OpenKBS Agent Architecture: From Single Agent to Complex Orchestration
+### Search & Content
+```javascript
+// Google Search
+const results = await openkbs.googleSearch('AI trends 2025');
+const images = await openkbs.googleSearch('sunset', { searchType: 'image' });
 
-### Core Architecture Philosophy
+// Extract text from webpage
+const text = await openkbs.webpageToText('https://example.com');
 
-OpenKBS enables everything from simple single-agent automation to sophisticated multi-agent systems through a **dual-environment architecture** that seamlessly combines **cloud-based autonomous agents** with **local orchestration scripts**.
+// OCR - extract text from image
+const ocr = await openkbs.imageToText('https://example.com/document.jpg');
+console.log(ocr.results);
 
-### Understanding Where Code Runs
+// Extract text from PDF/DOC
+const docText = await openkbs.documentToText('https://example.com/file.pdf');
+```
 
-**The fundamental principle**: Cloud agents operate in cloud infrastructure, local scripts run on your machine. This separation enables powerful patterns:
+### Communication
+```javascript
+// Send email (HTML supported)
+await openkbs.sendMail('user@example.com', 'Subject', '<h1>Hello</h1><p>Content</p>');
 
-**Cloud agents (serverless functions)** can access:
-- Internet-reachable services only
-- Public APIs and databases
-- Any service with a public endpoint
+// Text to speech
+const audio = await openkbs.textToSpeech('Hello world');
+console.log(audio.audioContent); // base64
 
-**Local scripts (on your machine)** can access:
-- Local resources (localhost, 127.0.0.1, local files)
-- Cloud agents via API calls
-- Both local and internet resources
+// Speech to text
+const transcript = await openkbs.speechToText('https://example.com/audio.mp3');
 
-**Architecture emerges from execution context**: When resources exist only locally, the architecture naturally becomes: Local Script → Cloud Agent (processing) → JSON → Local Script → Local Resource
+// Translation
+const { translation } = await openkbs.translate('Hello world', 'bg');
 
-### Advanced Pattern: Tool Composition (When Needed)
+// Language detection
+const { language } = await openkbs.detectLanguage('Здравей свят');
+```
 
-Since cloud agent tools are code, you can create composite tools when facing repetitive multi-step operations.
-This is useful when an agent would otherwise need many interaction cycles for a single logical operation.
+### Chat Operations
+```javascript
+// Create new chat (for notifications, scheduled tasks)
+await openkbs.chats({
+    chatTitle: 'Alert: Fire Detected',
+    message: JSON.stringify([{ type: "text", text: "Fire detected at location X" }])
+});
+
+// Update chat title and icon
+await openkbs.chats({
+    action: "updateChat",
+    title: await openkbs.encrypt('New Title'),
+    chatIcon: '🔥',
+    chatId: event.payload.chatId
+});
+```
 
-**Use sparingly**: Only create composite tools when they significantly reduce agent interactions or when domain logic requires atomic operations.
+### Scheduled Tasks
+```javascript
+// Create scheduled task (fires at specific time, creates new chat)
+await openkbs.kb({
+    action: 'createScheduledTask',
+    scheduledTime: Date.now() + 3600000, // 1 hour from now (ms)
+    taskPayload: {
+        message: '[SCHEDULED_TASK] Send weekly report',
+        customData: { reportType: 'weekly' }
+    },
+    description: 'Weekly report'
+});
+
+// List scheduled tasks
+const tasks = await openkbs.kb({ action: 'getScheduledTasks' });
+
+// Delete scheduled task
+await openkbs.kb({ action: 'deleteScheduledTask', timestamp: 1704067200000 });
+```
 
-### The Powerful Two-Environment System
+### File Upload with Presigned URL
+```javascript
+// Download file and upload to KB storage
+const fileResponse = await axios.get(sourceUrl, { responseType: 'arraybuffer' });
 
-#### 1. Cloud Environment (Autonomous Agent Execution)
-**Location**: `./src/Events/` - Deployed via `openkbs push`  
-**Purpose**: Autonomous agent execution with intelligent decision-making
+const presigned = await openkbs.kb({
+    action: 'createPresignedURL',
+    namespace: 'files',
+    fileName: 'uploaded.jpg',
+    fileType: 'image/jpeg',
+    presignedOperation: 'putObject'
+});
 
-**Capabilities**:
-- Autonomous multi-step workflows with decision branching
-- Integration with ANY internet-accessible service (public or private)
-- Secure credential management via {{secrets.KEY}} system
-- Sequential tool call execution based on intermediate results
-- Complex data extraction and structured JSON responses
-- Access to cloud databases, public APIs, web services with proper credentials
+await axios.put(presigned, fileResponse.data, {
+    headers: { 'Content-Type': 'image/jpeg', 'Content-Length': fileResponse.data.length }
+});
 
-**Agent Execution Flow**:
-```
-User Message → Agent Processes → Tool Call 1 → Analyze Result → Decision → Tool Call 2 → ... → Final JSON Response
+const publicUrl = `https://your-domain.file.vpc1.us/files/${openkbs.kbId}/uploaded.jpg`;
 ```
 
-**Key Insight**: Cloud agents can securely connect to APIs, and any service that have public IPs/URLs
+### Utilities
+```javascript
+// Exchange rates (latest, historical, time series)
+const rates = await openkbs.getExchangeRates({ base: 'EUR', symbols: 'USD,GBP' });
+const historical = await openkbs.getExchangeRates({ base: 'EUR', symbols: 'USD', period: '2024-01-15' });
+const series = await openkbs.getExchangeRates({ base: 'EUR', symbols: 'USD', period: '2024-01-01..2024-01-31' });
 
-#### 2. Local Environment (Orchestration & Local Services)
-**Location**: `./scripts/` - Execute locally with `node`  
-**Purpose**: Agent orchestration and local infrastructure integration
+// VAT validation
+const vat = await openkbs.checkVAT('BG123456789');
 
-**Capabilities**:
-- Orchestrate multiple cloud agents in complex workflows
-- Direct access to local services (localhost databases, file systems)
-- Dynamic workflow creation based on agent responses
-- Parallel and sequential agent coordination
-- Local credential management via .env files
-- Bridge between cloud intelligence and local infrastructure
+// Parse JSON from text (handles LLM output with extra text)
+const data = openkbs.parseJSONFromText('Some text {"key": "value"} more text');
 
-### Why This Architecture Matters
+// Encryption (uses KB's AES key)
+const encrypted = await openkbs.encrypt(JSON.stringify(sensitiveData));
+const decrypted = JSON.parse(await openkbs.decrypt(encrypted));
 
-#### Key Architectural Insights
-- **Cloud agents** = Autonomous intelligence with internet access
-- **Local scripts** = Infrastructure control and orchestration
-- Scripts call agents via API, agents return JSON, scripts handle the rest
+// Create embeddings
+const { embeddings, totalTokens } = await openkbs.createEmbeddings('Text to embed', 'text-embedding-3-large');
+```
+
+### Properties
+```javascript
+openkbs.kbId              // Current Knowledge Base ID
+openkbs.clientHeaders     // Request headers (IP, user-agent, etc.)
+openkbs.AESKey            // Encryption key
+openkbs.chatJWT           // Current chat JWT token
+```
+
+### NPM Dependencies
+Add to handler's JSON file (e.g., `onResponse.json`):
+```json
+{
+  "dependencies": { "mysql2": "latest", "decimal.js": "^10.4.3" }
+}
+```
 
-### Orchestration Patterns
+### Secrets Management
+Use `{{secrets.KEY}}` placeholders (replaced at runtime):
+```javascript
+const apiKey = "{{secrets.EXTERNAL_API_KEY}}";
+const telegramToken = "{{secrets.TELEGRAM_BOT_TOKEN}}";
+```
 
-Whether using a single agent or multiple agents, common patterns include:
+## Browser Environment (`./src/Frontend/`)
+Runs in user's browser at `https://[kbId].apps.openkbs.com`. React-based UI customization.
+
+### contentRender.js
+
+**`onRenderChatMessage(params)`** - Custom message rendering. Key params:
+- `msgIndex`, `messages`, `setMessages` - message context
+- `setSystemAlert({ severity, message })` - show alerts (severity: 'success', 'error', 'warning', 'info')
+- `setBlockingLoading(bool)` - loading overlay
+- `RequestChatAPI(messages)` - send chat messages
+- `kbUserData()`, `generateMsgId()` - user info and ID generation
+- `markdownHandler`, `theme` - rendering utilities
+
+Return: React component, `null` for default, `JSON.stringify({ type: 'HIDDEN_MESSAGE' })` to hide.
+
+**`Header(props)`** - Custom header component. Same props plus `openkbs` object.
+
+```javascript
+import React, { useState, useEffect } from 'react';
+import { Box, Button, CircularProgress } from '@mui/material';
+
+const onRenderChatMessage = async (params) => {
+    const { content, role } = params.messages[params.msgIndex];
+    const { msgIndex, messages, setSystemAlert, RequestChatAPI, kbUserData, generateMsgId } = params;
+
+    // Hide system messages
+    if (role === 'system') return JSON.stringify({ type: 'HIDDEN_MESSAGE' });
+
+    // Custom rendering for commands
+    if (content.includes('<myCommand>')) {
+        return <MyComponent content={content} />;
+    }
+
+    // Send follow-up message example
+    const sendFollowUp = async () => {
+        await RequestChatAPI([...messages, {
+            role: 'user',
+            content: 'Follow up',
+            userId: kbUserData().chatUsername,
+            msgId: generateMsgId()
+        }]);
+    };
+
+    return null; // Use default rendering
+};
+
+const Header = ({ setRenderSettings, openkbs, setSystemAlert, setBlockingLoading }) => {
+    const [loading, setLoading] = useState(false);
+
+    useEffect(() => {
+        setRenderSettings({
+            disableEmojiButton: true,
+            disableBalanceView: false,
+            backgroundOpacity: 0.02
+        });
+    }, [setRenderSettings]);
+
+    return <Box>Custom Header</Box>;
+};
+
+const exports = { onRenderChatMessage, Header };
+window.contentRender = exports;
+export default exports;
+```
 
-1. **Single Agent**: Script → Agent → Process Result → Store/Act
-2. **Hierarchical**: Script → Discovery Agent → N Results → Spawn N Detail Agents → Aggregate
-3. **Pipeline**: Script → Agent A → Agent B (uses A's output) → Agent C → Final Result
-4. **Event-Driven**: Database Change → Script Detects → Triggers Appropriate Agent(s)
-5. **Parallel**: Script → [Agent A, Agent B, Agent C] simultaneously → Combine Results
-6. **Database Integration**: Script reads local DB → Sends data to Agent → Agent processes → Returns JSON → Script stores in local DB
+### Frontend openkbs Object
+
+```javascript
+// Item CRUD (auto-encrypted)
+await openkbs.createItem({ itemType: 'memory', itemId: 'memory_key', body: { value: 'data' } });
+await openkbs.updateItem({ itemType: 'memory', itemId: 'memory_key', body: { value: 'updated' } });
+const item = await openkbs.getItem('memory_key');
+console.log(item.item.body.value);
+
+// Fetch with filters
+const items = await openkbs.fetchItems({
+    itemType: 'memory',
+    beginsWith: 'memory_',
+    limit: 100
+});
+items.items.forEach(({ item, meta }) => {
+    console.log(meta.itemId, item.body);
+});
+
+await openkbs.deleteItem('memory_key');
+```
 
+### Files API
+```javascript
+// List files in namespace
+const files = await openkbs.Files.listFiles('files');
+// Returns: [{ Key: 'files/kbId/filename.jpg', Size: 12345, LastModified: '...' }]
 
-### Understanding the Architecture
+// Upload file with progress
+const onProgress = (percent) => console.log(`${percent}% uploaded`);
+await openkbs.Files.uploadFileAPI(fileObject, 'files', onProgress);
 
-#### Cloud Agents (The Intelligence Layer)
-**This is where ALL agentic flow happens:**
-- Agents execute autonomously in the cloud
-- Users can login to the chat UI at `https://[kbId].apps.openkbs.com` to monitor execution
-- Each message and tool call is visible in the chat interface
-- Agents make decisions, call tools, and process data autonomously
-- The agent IS the intelligence - it thinks, decides, and acts
+// Delete file
+await openkbs.Files.deleteRawKBFile('filename.jpg', 'files');
 
-#### Local Scripts (The Orchestration Layer)
-**Scripts are API clients that:**
-- Call cloud agents via API
-- Receive the final JSON result after agent completes its autonomous flow
-- Handle local infrastructure (databases, files)
-- Orchestrate multiple agent calls
-- Process and route results between agents
+// Rename file
+await openkbs.Files.renameFile('old-path/file.jpg', 'new-path/file.jpg', 'files');
 
+// File URL pattern
+const fileUrl = `https://your-domain.file.vpc1.us/files/${openkbs.kbId}/filename.jpg`;
+```
 
-### Security & Best Practices
+### Sharing API
+```javascript
+// Share KB with another user
+await openkbs.KBAPI.shareKBWith('user@example.com');
 
-#### Cloud Security
-- Use {{secrets.KEY}} for all sensitive credentials
-- Secrets are encrypted and never exposed in code
-- Each agent can have its own set of secrets
-- Supports database passwords, API keys, OAuth tokens
+// Get current shares
+const shares = await openkbs.KBAPI.getKBShares();
+// Returns: { sharedWith: ['email1@example.com', 'email2@example.com'] }
 
-#### Local Security
-- Use .env files for local credentials
-- Keep local scripts in private repositories
-- Implement proper error handling and logging
-- Use database transactions for consistency
+// Remove share
+await openkbs.KBAPI.unshareKBWith('user@example.com');
+```
 
-### Summary
+### Other Frontend Properties
+```javascript
+openkbs.kbId           // Current KB ID
+openkbs.isMobile       // Boolean - is mobile device
+openkbs.KBData         // KB metadata (title, description, etc.)
+```
 
-OpenKBS enables building sophisticated AI systems where:
-- Cloud agents provide autonomous intelligence
-- Local scripts orchestrate workflows and handle infrastructure
-- You maintain full control while agents think and act independently
+### NPM Dependencies
+Add to `contentRender.json`. Built-in (fixed): react, @mui/material, @mui/icons-material, @emotion/react.
 
+# OpenKBS Commands
+- `openkbs create my-agent` - Create new agent
+- `openkbs push` - Deploy to cloud
+- `openkbs update` - Update knowledge base
 
+# Development Guidelines
+- Backend deps → `onRequest.json`, `onResponse.json`, `onCronjob.json`
+- Frontend deps → `contentRender.json`
+- Provide README.md for the agent