openkbs 0.0.53 → 0.0.55

package/README.md

@@ -1,6 +1,5 @@
 # OpenKBS · [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/open-kbs/openkbs-chat/blob/main/LICENSE) [![npm version](https://img.shields.io/badge/npm-v0.0.20-orange.svg)](https://www.npmjs.com/package/openkbs)
 
-
 OpenKBS is an extendable AI service designed to build,
 deploy and integrate AI agents and applications.
 
@@ -26,8 +25,11 @@ deploy and integrate AI agents and applications.
         - [SDK](#sdk)
         - [Managing Secrets](#managing-secrets)
         - [Application Settings](#application-settings)
+        - [Message Types and Content Formats](#message-types-and-content-formats)
+        - [Supported AI Models](#supported-ai-models)
         - [LLM Instructions](#llm-instructions)
         - [Execution Environment](#execution-environment)
+        - [MCP Integration](#mcp-integration)
     - [Frontend](#frontend)
         - [Frontend Module Loading](#frontend-module-loading)
         - [Built-in UI Libraries](#built-in-ui-libraries)
@@ -169,40 +171,7 @@ Enhance your UI with Material-UI components:
 
    ```bash
    openkbs push 
-   ```
-
-### AI-Powered Frontend Generation
-
-OpenKBS provides simple AI-powered code generation. Use the `openkbs modify` command followed by your requirement:
-
-```bash
-openkbs modify "Implementing UI to manage renderSettings"
-```
-
-If you need to revert changes:
-```bash
-git checkout -- .
-```
-
-## Extend Backend
-
-Extend backend functionality using `openkbs modify` followed by your requirements. Add file paths to scope AI changes to specific files:
-
-```bash
-openkbs modify "Implement getContent backend tool that returns text or JSON from a given URL" src/Events/actions.js app/instructions.txt
-openkbs push
-```
-
-This adds a new backend tool in `actions.js` that:
-- Fetches content from URLs
-- Handles JSON and HTML responses
-- Auto-registers in `instructions.txt` (enabling LLM to understand and use it)
-- Available to users and LLM through chat
-
-Example usage in chat:
-```
-/getContent("https://api.example.com/data")
-```
+   `````
 
 ## Mobile & Desktop App
 
@@ -231,11 +200,13 @@ src/
 │   ├── onRequest.js            // Handles incoming user messages
 │   ├── onResponse.js           // Handles outgoing LLM messages
 │   ├── onPublicAPIRequest.js   // Handles public API requests
-│   ├── onAddMessages.js         // Handles messages added to the chat (NEW)
+│   ├── onAddMessages.js        // Handles messages added to the chat
+│   ├── onCronjob.js            // Scheduled task handler (runs on cron schedule)
 │   ├── onRequest.json          // Dependencies for onRequest handler
-│   ├── onResponse.json          // Dependencies for onResponse handler
+│   ├── onResponse.json         // Dependencies for onResponse handler
 │   ├── onPublicAPIRequest.json // Dependencies for onPublicAPIRequest handler
-│   └── onAddMessages.json       // Dependencies for onAddMessages handler (NEW)
+│   ├── onAddMessages.json      // Dependencies for onAddMessages handler
+│   └── onCronjob.json          // Dependencies for onCronjob handler
 │── Frontend/
 │   ├── contentRender.js        // Custom rendering logic for chat messages
 │   └── contentRender.json      // Dependencies for the contentRender module
@@ -262,129 +233,274 @@ The core of the OpenKBS backend framework revolves around the `onRequest` and `o
 
 ```javascript
 // src/Events/actions.js
-export const getActions = (meta) => {
-    return [
-        // Define your regular expressions and corresponding actions here
-        [/\/?yourCommand\("(.*)"\)/, async (match, event) => {
-            // Access match groups, event payload, and openkbs object
-            // Execute custom logic, API calls, etc.
-            // Return an object with action results and meta information
-            return { result: 'Your command executed', ...meta };
-        }],
-        // ... more actions
-    ];
-};
+export const getActions = (meta) => [
+    // Commands use XML tags with JSON content
+    [/<myCommand>([\s\S]*?)<\/myCommand>/s, async (match) => {
+        const data = JSON.parse(match[1].trim());
+        // Execute custom logic, API calls, etc.
+        return { result: data.param, ...meta };
+    }]
+];
 
 // src/Events/onRequest.js
 import {getActions} from './actions.js';
 export const handler = async (event) => {
-    const actions = getActions({ _meta_actions: [] }); // Initialize meta actions if needed
-    for (let [regex, action] of actions) {
-        const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;
+    const actions = getActions({ _meta_actions: [] });
+    const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;
+    for (const [regex, action] of actions) {
         const match = lastMessage?.match(regex);
-        if (match) return await action(match, event); // Execute matching action
+        if (match) return await action(match, event);
     }
-    return { type: 'CONTINUE' }; // Continue to the next handler or LLM
+    return { type: 'CONTINUE' };
 };
 
-
 // src/Events/onResponse.js
 import {getActions} from './actions.js';
-
 export const handler = async (event) => {
-     // Example of conditional meta actions based on message count:
     const maxSelfInvokeMessagesCount = 30;
     const actions = getActions({
         _meta_actions: event?.payload?.messages?.length > maxSelfInvokeMessagesCount
-            ? ["REQUEST_CHAT_MODEL_EXCEEDED"]
-            : ["REQUEST_CHAT_MODEL"]
+            ? [] : ["REQUEST_CHAT_MODEL"]
     });
-
-    for (let [regex, action] of actions) {
-        const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;        
+    const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;
+    for (const [regex, action] of actions) {
         const match = lastMessage?.match(regex);
         if (match) return await action(match, event);
     }
-
-    return { type: 'CONTINUE' }
+    return { type: 'CONTINUE' };
 };
-
 ```
 
 The `onRequest` and `onResponse` handlers are the core of customizing your OpenKBS agent's behavior. They act as middleware, intercepting messages before they reach the LLM (`onRequest`) and after the LLM generates a response (`onResponse`). This enables you to implement custom logic, interact with external APIs, and control the flow of the conversation.
 
+#### Command Format
+
+Commands use XML tags with JSON content inside. This format is cleaner and more flexible than regex-based parsing:
+
+```xml
+<commandName>
+{
+  "param1": "value1",
+  "param2": "value2"
+}
+</commandName>
+```
+
+For commands without parameters, use self-closing tags:
+```xml
+<commandName/>
+```
+
 **Example:**
 
 ```javascript
 // src/Events/actions.js
+
+// Helper function for uploading generated images
+const uploadGeneratedImage = async (base64Data, meta) => {
+    const fileName = `image-${Date.now()}-${Math.random().toString(36).substring(7)}.png`;
+    const uploadResult = await openkbs.uploadImage(base64Data, fileName, 'image/png');
+    return {
+        type: 'CHAT_IMAGE',
+        data: { imageUrl: uploadResult.url },
+        ...meta
+    };
+};
+
 export const getActions = (meta) => [
-    
-    [/\/?textToImage\("(.*)"\)/, async (match) => {
-        const response = await openkbs.textToImage(match[1], { serviceId: 'stability.sd3Medium' });
-        const imageSrc = `data:${response.ContentType};base64,${response.base64Data}`;
-        return { type: 'SAVED_CHAT_IMAGE', imageSrc, ...meta };
+
+    // AI Image Generation (supports multiple models)
+    [/<createAIImage>([\s\S]*?)<\/createAIImage>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            const model = data.model || "gemini-2.5-flash-image";
+            const params = { model, n: 1 };
+
+            if (data.imageUrls?.length > 0) {
+                params.imageUrls = data.imageUrls;
+            }
+
+            if (model === 'gpt-image-1') {
+                const validSizes = ["1024x1024", "1536x1024", "1024x1536", "auto"];
+                params.size = validSizes.includes(data.size) ? data.size : "1024x1024";
+                params.quality = "high";
+            } else if (model === 'gemini-2.5-flash-image') {
+                const validAspectRatios = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9"];
+                params.aspect_ratio = validAspectRatios.includes(data.aspect_ratio) ? data.aspect_ratio : "1:1";
+            }
+
+            const image = await openkbs.generateImage(data.prompt, params);
+            return await uploadGeneratedImage(image[0].b64_json, meta);
+        } catch (error) {
+            return { error: error.message || 'Image creation failed', ...meta };
+        }
     }],
 
-    [/\/?googleSearch\("(.*)"\)/, async (match) => {
-        const q = match[1];
-        const searchParams = match[2] && JSON.parse(match[2]) || {};
-        const params = {
-            q,
-            ...searchParams,
-            key: '{{secrets.googlesearch_api_key}}',
-            cx: '{{secrets.googlesearch_engine_id}}'
-        };
-        const response = (await axios.get('https://www.googleapis.com/customsearch/v1', { params }))?.data?.items;
-        const data = response?.map(({ title, link, snippet, pagemap }) => ({
-            title,
-            link,
-            snippet,
-            image: pagemap?.metatags?.[0]?.["og:image"]
-        }));
-        return { data, ...meta };
+    // AI Video Generation (Sora 2)
+    [/<createAIVideo>([\s\S]*?)<\/createAIVideo>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            const params = {
+                video_model: data.model || "sora-2",
+                seconds: [4, 8, 12].includes(data.seconds) ? data.seconds : 8
+            };
+
+            if (data.input_reference_url) {
+                params.input_reference_url = data.input_reference_url;
+            } else {
+                const validSizes = ['720x1280', '1280x720'];
+                params.size = validSizes.includes(data.size) ? data.size : '1280x720';
+            }
+
+            const videoData = await openkbs.generateVideo(data.prompt, params);
+
+            if (videoData?.[0]?.status === 'pending') {
+                return {
+                    type: 'VIDEO_PENDING',
+                    data: { videoId: videoData[0].video_id, message: 'Video generation in progress...' },
+                    ...meta
+                };
+            }
+
+            if (videoData?.[0]?.video_url) {
+                return { type: 'CHAT_VIDEO', data: { videoUrl: videoData[0].video_url }, ...meta };
+            }
+            return { error: 'Video generation failed', ...meta };
+        } catch (error) {
+            return { error: error.message || 'Video creation failed', ...meta };
+        }
     }],
 
-    [/\/?webpageToText\("(.*)"\)/, async (match) => {
-        let response = await openkbs.webpageToText(match[1]);
-        if (response?.content?.length > 5000) {
-            response.content = response.content.substring(0, 5000);
+    // Continue video polling
+    [/<continueVideoPolling>([\s\S]*?)<\/continueVideoPolling>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            const videoData = await openkbs.checkVideoStatus(data.videoId);
+
+            if (videoData?.[0]?.status === 'completed' && videoData[0].video_url) {
+                return { type: 'CHAT_VIDEO', data: { videoUrl: videoData[0].video_url }, ...meta };
+            } else if (videoData?.[0]?.status === 'pending') {
+                return { type: 'VIDEO_PENDING', data: { videoId: data.videoId, message: 'Still generating...' }, ...meta };
+            }
+            return { error: 'Video generation failed', ...meta };
+        } catch (error) {
+            return { error: error.message, ...meta };
         }
-        return { data: response, ...meta };
     }],
 
-    [/\/?documentToText\("(.*)"\)/, async (match) => {
-        let response = await openkbs.documentToText(match[1]);
-        if (response?.text?.length > 5000) {
-            response.text = response.text.substring(0, 5000);
+    // Google Search
+    [/<googleSearch>([\s\S]*?)<\/googleSearch>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            const response = await openkbs.googleSearch(data.query);
+            const results = response?.map(({ title, link, snippet, pagemap }) => ({
+                title, link, snippet,
+                image: pagemap?.metatags?.[0]?.["og:image"]
+            }));
+            return { data: results, ...meta };
+        } catch (e) {
+            return { error: e.message, ...meta };
         }
-        return { data: response, ...meta };
     }],
 
-    [/\/?imageToText\("(.*)"\)/, async (match) => {
-        let response = await openkbs.imageToText(match[1]);
-        if (response?.detections?.[0]?.txt) {
-          response = { detections: response?.detections?.[0]?.txt };
+    // Web scraping
+    [/<webpageToText>([\s\S]*?)<\/webpageToText>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            let response = await openkbs.webpageToText(data.url);
+            if (response?.content?.length > 5000) {
+                response.content = response.content.substring(0, 5000);
+            }
+            return { data: response, ...meta };
+        } catch (e) {
+            return { error: e.message, ...meta };
         }
-        return { data: response, ...meta };
     }],
 
-    [/\/?textToSpeech\("(.*)"\s*,\s*"(.*)"\)/, async (match) => {
-        const response = await openkbs.textToSpeech(match[2], {
-          languageCode: match[1]
-        });
-        return { data: response, ...meta };
+    // Exchange rates with period support
+    [/<getExchangeRates>([\s\S]*?)<\/getExchangeRates>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            // period can be: 'latest', 'YYYY-MM-DD' (historical), or 'YYYY-MM-DD..YYYY-MM-DD' (time series)
+            let response = await openkbs.getExchangeRates({
+                base: data.base,
+                symbols: data.symbols,
+                period: data.period || 'latest'
+            });
+            return { data: response, ...meta };
+        } catch (e) {
+            return { error: e.message, ...meta };
+        }
+    }],
+
+    // Send email
+    [/<sendMail>([\s\S]*?)<\/sendMail>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            const response = await openkbs.sendMail(data.to, data.subject, data.body);
+            return { type: 'EMAIL_SENT', data: { email: data.to, subject: data.subject, response }, ...meta };
+        } catch (e) {
+            return { error: e.message, ...meta };
+        }
     }],
 
-    // example: checkVAT("BG123456789")
-    [/\/?checkVAT\("(.*)"\)/, async (match) => {
-        let response = await openkbs.checkVAT(match[1]);
-        return { data: response, ...meta };
+    // Schedule task
+    [/<scheduleTask>([\s\S]*?)<\/scheduleTask>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            let scheduledTime;
+
+            if (data.time) {
+                let isoTimeStr = data.time.replace(' ', 'T');
+                if (!isoTimeStr.includes('Z') && !isoTimeStr.includes('+')) isoTimeStr += 'Z';
+                scheduledTime = new Date(isoTimeStr).getTime();
+            } else if (data.delay) {
+                let delayMs = 0;
+                if (data.delay.endsWith('h')) delayMs = parseFloat(data.delay) * 3600000;
+                else if (data.delay.endsWith('d')) delayMs = parseFloat(data.delay) * 86400000;
+                else delayMs = parseFloat(data.delay) * 60000;
+                scheduledTime = Date.now() + delayMs;
+            } else {
+                scheduledTime = Date.now() + 3600000;
+            }
+
+            const response = await openkbs.kb({
+                action: 'createScheduledTask',
+                scheduledTime: Math.floor(scheduledTime / 60000) * 60000,
+                taskPayload: { message: `[SCHEDULED_TASK] ${data.message}`, createdAt: Date.now() },
+                description: data.message.substring(0, 50)
+            });
+
+            return { type: 'TASK_SCHEDULED', data: { scheduledTime: new Date(scheduledTime).toISOString(), taskId: response.taskId }, ...meta };
+        } catch (e) {
+            return { error: e.message, ...meta };
+        }
+    }],
+
+    // Get scheduled tasks
+    [/<getScheduledTasks\s*\/>/s, async () => {
+        try {
+            const response = await openkbs.kb({ action: 'getScheduledTasks' });
+            return { type: 'SCHEDULED_TASKS_LIST', data: response, ...meta };
+        } catch (e) {
+            return { error: e.message, ...meta };
+        }
     }],
 
-    // example: getExchangeRates("USD", "EUR,GBP")
-    [/\/?getExchangeRates\("(.*)"\s*,\s*"(.*)"\)/, async (match) => {
-        let response = await openkbs.getExchangeRates(match[1], match[2]);
-        return { data: response, ...meta };
+    // View image - adds image to LLM vision context
+    [/<viewImage>([\s\S]*?)<\/viewImage>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            return {
+                data: [
+                    { type: "text", text: `Viewing image: ${data.url}` },
+                    { type: "image_url", image_url: { url: data.url } }
+                ],
+                ...meta
+            };
+        } catch (e) {
+            return { error: e.message, ...meta };
+        }
     }],
 ];
 ```
@@ -394,15 +510,13 @@ export const getActions = (meta) => [
 // src/Events/onRequest.js
 import {getActions} from './actions.js';
 
-
 export const handler = async (event) => {
-    const actions = getActions({});
+    const actions = getActions({ _meta_actions: [] });
     for (let [regex, action] of actions) {
         const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;
         const match = lastMessage?.match(regex);
         if (match) return await action(match);
     }
-    
     return { type: 'CONTINUE' }
 };
 ```
@@ -412,14 +526,12 @@ export const handler = async (event) => {
 import {getActions} from './actions.js';
 
 export const handler = async (event) => {
-    const actions = getActions({_meta_actions: ["REQUEST_CHAT_MODEL"]});
-    
+    const actions = getActions({ _meta_actions: ["REQUEST_CHAT_MODEL"] });
     for (let [regex, action] of actions) {
         const lastMessage = event.payload.messages[event.payload.messages.length - 1].content;
         const match = lastMessage?.match(regex);
         if (match) return await action(match);
     }
-    
     return { type: 'CONTINUE' }
 };
 ```
@@ -563,7 +675,79 @@ export const handler = async (event) => {
 
 ```
 
-**Dependencies (onRequest.json, onResponse.json, etc.):**
+#### onCronjob Handler
+
+The `onCronjob` handler enables scheduled task execution for your agent. It runs automatically based on a cron schedule you define, without requiring user interaction.
+
+**How it works:**
+1. Create `src/Events/onCronjob.js` with your handler logic
+2. Define the schedule using `handler.CRON_SCHEDULE` at the end of the file
+3. Deploy with `openkbs push` - the cronjob is automatically registered
+
+**Cron Schedule Format:**
+Standard cron syntax: `minute hour day month weekday`
+
+- `* * * * *` - Every minute
+- `*/5 * * * *` - Every 5 minutes
+- `0 * * * *` - Every hour
+- `0 0 * * *` - Daily at midnight
+- `0 9 * * 1-5` - Weekdays at 9 AM
+
+**Example `onCronjob.js`:**
+
+```javascript
+// src/Events/onCronjob.js
+
+export const handler = async (event) => {
+    try {
+        // Fetch external data
+        const response = await fetch('https://api.example.com/status');
+        const data = await response.json();
+
+        // Process and store results
+        await openkbs.createItem({
+            itemType: 'status_check',
+            itemId: `status_${Date.now()}`,
+            body: { timestamp: new Date().toISOString(), ...data }
+        });
+
+        // Optionally trigger a chat for notifications
+        if (data.alertLevel > 5) {
+            await openkbs.chats({
+                chatTitle: `Alert: ${data.message}`,
+                message: JSON.stringify([
+                    { type: "text", text: `ALERT: ${data.message}\nLevel: ${data.alertLevel}` }
+                ])
+            });
+        }
+
+        return {
+            success: true,
+            processed: data,
+            timestamp: new Date().toISOString()
+        };
+    } catch (error) {
+        return {
+            success: false,
+            error: error.message,
+            timestamp: new Date().toISOString()
+        };
+    }
+};
+
+// IMPORTANT: Define the cron schedule at the end of the file
+handler.CRON_SCHEDULE = "*/5 * * * *"; // Runs every 5 minutes
+```
+
+**Key Points:**
+- The `CRON_SCHEDULE` must be defined as `handler.CRON_SCHEDULE = "pattern"` at the end of the file
+- The handler receives an empty `event` object (no user payload)
+- Use `openkbs.chats()` to create new chat sessions for notifications
+- All SDK methods (`openkbs.*`) are available
+- Return an object with results for logging purposes
+- To disable the cronjob, simply remove or rename the `onCronjob.js` file and redeploy
+
+**Dependencies (onRequest.json, onResponse.json, onCronjob.json, etc.):**
 
 These files specify the NPM package dependencies required for the respective event handlers. They follow the standard `package.json` format.
 
@@ -598,33 +782,84 @@ if (actionMatch) {
 ```
 
 
-#### SDK
+#### SDK (Backend `openkbs` object)
 
-The `openkbs` object provides a set of utility functions and services to interact with the OpenKBS platform and external APIs. It's available within the event handlers.  Here are some commonly used functions:
+The `openkbs` object is a global object available in all backend event handlers (`onRequest`, `onResponse`, `onAddMessages`, `onPublicAPIRequest`, `onCronjob`). It provides access to OpenKBS services, external APIs, and data storage.
 
-* **`openkbs.textToImage(prompt, params)`:** Generates an image from a text prompt using a specified or default image generation service. Returns an object containing the image content type and base64 encoded data.
+**Properties:**
+```javascript
+openkbs.kbId              // Current Knowledge Base ID
+openkbs.clientHeaders     // Client headers (e.g., openkbs.clientHeaders['x-forwarded-for'] for IP)
+openkbs.AESKey            // Encryption key for this KB
+openkbs.chatJWT           // JWT token for current chat session
+```
 
-* **`openkbs.speechToText(audioURL, params)`:** Transcribes audio from a URL to text.
+##### Image & Video Generation
+
+* **`openkbs.generateImage(prompt, params)`:** Generates images using AI models. Returns array with `b64_json` data.
+  - `params.model`: `"gemini-2.5-flash-image"` (default, supports image editing) or `"gpt-image-1"` (better for text in images)
+  - `params.imageUrls`: Array of reference image URLs (gemini only)
+  - `params.aspect_ratio`: For gemini: `"1:1"`, `"16:9"`, `"9:16"`, `"3:2"`, `"2:3"`, `"4:3"`, `"3:4"`, `"4:5"`, `"5:4"`, `"21:9"`
+  - `params.size`: For gpt-image-1: `"1024x1024"`, `"1536x1024"`, `"1024x1536"`, `"auto"`
+  - `params.n`: Number of images (default: 1)
+
+* **`openkbs.generateVideo(prompt, params)`:** Generates videos using Sora 2. Returns array with `video_url` or `status: 'pending'`.
+  - `params.video_model`: `"sora-2"` (default, fast) or `"sora-2-pro"` (higher quality)
+  - `params.seconds`: `4`, `8` (default), or `12`
+  - `params.size`: `"1280x720"` (landscape) or `"720x1280"` (portrait)
+  - `params.input_reference_url`: Optional reference image URL
+
+* **`openkbs.checkVideoStatus(videoId)`:** Check status of pending video generation.
+
+* **`openkbs.uploadImage(base64Data, fileName, mimeType)`:** Upload image to storage. Returns `{ url }`.
+
+##### Deep Research
+
+* **`openkbs.deepResearch(input, params)`:** Autonomous research agent powered by Google Gemini. Performs multi-step research: plans → searches web → reads sources → iterates → synthesizes report.
+  - `input`: Research query or topic (string)
+  - `params.previous_interaction_id`: Optional - for follow-up questions on completed research
+  - Returns `{ status, interaction_id, output, usage, prepaid_credits }`
+  - Status can be `'completed'`, `'in_progress'`, or `'failed'`
+  - **Important:** Takes 5-20 minutes (up to 60 min for complex topics)
+  - **Pricing:** Requires minimum upfront charge of 50 credits (~€0.50). Additional usage charged on completion.
+
+* **`openkbs.checkDeepResearchStatus(interactionId, prepaidCredits)`:** Check status of pending deep research.
+  - `interactionId`: From previous `deepResearch()` response
+  - `prepaidCredits`: From previous response (for correct billing)
+  - Returns same format as `deepResearch()`
+
+##### Search & Content Extraction
+
+* **`openkbs.googleSearch(query, params)`:** Performs Google search. Optional `params.searchType: 'image'` for image search.
+
+* **`openkbs.webpageToText(pageURL, params)`:** Extracts text content from a webpage.
 
-* **`openkbs.webpageToText(pageURL, params)`:** Extracts text content from a given webpage URL.
+* **`openkbs.documentToText(documentURL, params)`:** Extracts text from documents (PDF, DOC, etc.).
 
-* **`openkbs.googleSearch(q, params)`:** Performs a Google search using the provided query and parameters.
+* **`openkbs.imageToText(imageUrl, params)`:** OCR - extracts text from images.
 
-* **`openkbs.sendMail(email, subject, content)`:** Sends an email to the specified recipient
+##### Communication
 
-* **`openkbs.checkVAT(vatNumber)`:** Validates a VAT number against official databases
+* **`openkbs.sendMail(email, subject, content)`:** Sends an email to the specified recipient.
 
-* **`openkbs.getExchangeRates(base, symbols)`:** Retrieves current exchange rates
+* **`openkbs.textToSpeech(text, params)`:** Converts text to speech. Returns `response.audioContent`.
 
-* **`openkbs.documentToText(documentURL, params)`:** Extracts text from various document formats.
+* **`openkbs.speechToText(audioURL, params)`:** Transcribes audio from a URL to text.
+
+##### Data & Utilities
 
-* **`openkbs.imageToText(imageUrl, params)`:** Extracts text from an image.
+* **`openkbs.getExchangeRates({ base, symbols, period })`:** Retrieves exchange rates.
+  - `base`: Base currency (e.g., `"EUR"`)
+  - `symbols`: Target currencies (e.g., `"USD,GBP"`)
+  - `period`: `"latest"` (default), `"YYYY-MM-DD"` (historical), or `"YYYY-MM-DD..YYYY-MM-DD"` (time series)
+
+* **`openkbs.checkVAT(vatNumber)`:** Validates a VAT number against official databases.
 
 * **`openkbs.translate(text, to)`:** Translates text to the specified target language.
 
 * **`openkbs.detectLanguage(text, params)`:** Detects the language of the provided text.
 
-* **`openkbs.textToSpeech(text, params)`:** Converts text to speech. Returns `response.audioContent` which automatically plays in the chat interface.
+##### Encryption & Storage
 
 * **`openkbs.encrypt(plaintext)`:** Encrypts data using the provided AES key.
 
@@ -632,25 +867,162 @@ The `openkbs` object provides a set of utility functions and services to interac
 
 * **`openkbs.items(data)`:** Interacts with the Items API for creating, updating, and deleting items.
 
+* **`openkbs.createItem({ itemType, itemId, body })`:** Create a new item.
+
+* **`openkbs.updateItem({ itemType, itemId, body })`:** Update an existing item.
+
+* **`openkbs.deleteItem(itemId)`:** Delete an item by ID.
+
+* **`openkbs.getItem(itemId)`:** Get a single item by ID. Returns item with auto-decrypted body.
+
+* **`openkbs.fetchItems({ limit, itemType, beginsWith, from, to, field })`:** Fetch multiple items with filters.
+  - `limit`: Max items to return (default: 1000)
+  - `itemType`: Filter by item type
+  - `beginsWith`: Filter by itemId prefix
+  - `from`, `to`: Date range filters
+  - `field`: Field name for range query
+
 * **`openkbs.chats(data)`:** Interacts with the Chats API.
 
-* **`openkbs.kb(data)`:** Interacts with the Knowledge Base API.
+* **`openkbs.kb(data)`:** Interacts with the Knowledge Base API. Actions include:
+  - `createScheduledTask`: Schedule a future task
+  - `getScheduledTasks`: List all scheduled tasks
+  - `deleteScheduledTask`: Delete a scheduled task
+  - `createPresignedURL`: Get URL for file upload
 
-* **`openkbs.clientHeaders`:** Exposes client headers for accessing information like IP address, location, etc. (e.g., `openkbs.clientHeaders['x-forwarded-for']`).
+##### Scheduled Tasks API
 
-* **`openkbs.createEmbeddings(input, model)`:** Create embeddings from input text
+Scheduled tasks allow your agent to execute actions at specific times in the future. When a scheduled task fires, it creates a new chat session with the task message.
+
+**Create a scheduled task:**
+```javascript
+const response = await openkbs.kb({
+    action: 'createScheduledTask',
+    scheduledTime: Date.now() + 3600000,  // Unix timestamp in ms (1 hour from now)
+    taskPayload: {
+        message: '[SCHEDULED_TASK] Send weekly report',
+        source: 'marketing_agent',
+        customData: { reportType: 'weekly' }
+    },
+    description: 'Weekly report task'  // Short description for listing
+});
+// Returns: { taskId: 'task_123...' }
+```
+
+**List scheduled tasks:**
+```javascript
+const tasks = await openkbs.kb({ action: 'getScheduledTasks' });
+// Returns: { items: [{ timestamp, taskPayload, description, status }] }
+```
+
+**Delete a scheduled task:**
+```javascript
+await openkbs.kb({
+    action: 'deleteScheduledTask',
+    timestamp: 1704067200000  // The scheduledTime of the task to delete
+});
+```
+
+**How it works:**
+1. Task is stored with the specified `scheduledTime`
+2. At the scheduled time, system creates a new chat with `taskPayload.message` as the initial message
+3. Your agent's `onRequest`/`onResponse` handlers process the message normally
+4. Use `[SCHEDULED_TASK]` prefix in message to help your agent identify scheduled tasks
+
+* **`openkbs.createEmbeddings(input, model)`:** Create embeddings from input text.
+  - `model`: `"text-embedding-3-large"` (default) or other OpenAI embedding models
+  - Returns: `{ embeddings, totalTokens, dimension }`
+
+* **`openkbs.parseJSONFromText(text)`:** Utility to extract JSON object from text. Returns parsed object or null.
+
+* **`openkbs.textToImage(prompt, params)`:** (Legacy) Generates image using Stability AI. Use `generateImage` for newer models.
+  - `params.serviceId`: `"stability.sd35Large"` (default) or `"stability.sd3Medium"`
+  - Returns: `{ ContentType, base64Data }`
 
 **Example SDK Usage:**
 
 ```javascript
-// ... inside an action ...
-const image = await openkbs.textToImage('a cat sitting on a mat');
-// ... use image.base64Data and image.ContentType ...
+// Generate an image with Gemini
+const images = await openkbs.generateImage('a sunset over mountains', {
+    model: 'gemini-2.5-flash-image',
+    aspect_ratio: '16:9'
+});
+const base64 = images[0].b64_json;
 
+// Upload the generated image
+const result = await openkbs.uploadImage(base64, 'sunset.png', 'image/png');
+console.log(result.url);
 
-//Encrypt submitted user data
-const encryptedValue = await openkbs.encrypt(userData);
+// Generate a video with Sora 2
+const video = await openkbs.generateVideo('a cat playing with yarn', {
+    video_model: 'sora-2',
+    seconds: 8,
+    size: '1280x720'
+});
+
+// Check video status if pending
+if (video[0]?.status === 'pending') {
+    const status = await openkbs.checkVideoStatus(video[0].video_id);
+    if (status[0]?.video_url) {
+        console.log('Video ready:', status[0].video_url);
+    }
+}
+
+// Get exchange rates for a date range
+const rates = await openkbs.getExchangeRates({
+    base: 'EUR',
+    symbols: 'USD,GBP,JPY',
+    period: '2024-01-01..2024-01-31'
+});
+
+// Item CRUD operations
+await openkbs.createItem({
+    itemType: 'memory',
+    itemId: 'memory_user_settings',
+    body: { theme: 'dark', notifications: true }
+});
+
+const item = await openkbs.getItem('memory_user_settings');
+console.log(item.item.body); // { theme: 'dark', notifications: true }
+
+await openkbs.updateItem({
+    itemType: 'memory',
+    itemId: 'memory_user_settings',
+    body: { theme: 'light', notifications: false }
+});
 
+// Fetch multiple items
+const items = await openkbs.fetchItems({
+    itemType: 'memory',
+    beginsWith: 'memory_',
+    limit: 100
+});
+
+// Schedule a task
+await openkbs.kb({
+    action: 'createScheduledTask',
+    scheduledTime: Date.now() + 3600000, // 1 hour from now
+    taskPayload: { message: 'Reminder to check analytics' },
+    description: 'Analytics reminder'
+});
+
+// Create embeddings
+const { embeddings, totalTokens } = await openkbs.createEmbeddings(
+    'Text to embed',
+    'text-embedding-3-large'
+);
+
+// Access client info
+const clientIP = openkbs.clientHeaders['x-forwarded-for'];
+const userAgent = openkbs.clientHeaders['user-agent'];
+
+// Encrypt/decrypt data
+const encryptedValue = await openkbs.encrypt(JSON.stringify(userData));
+const decryptedValue = JSON.parse(await openkbs.decrypt(encryptedValue));
+
+// Parse JSON from LLM response
+const jsonData = openkbs.parseJSONFromText('Some text {"key": "value"} more text');
+// Returns: { key: "value" }
 ```
 
 #### Managing Secrets
@@ -686,36 +1058,220 @@ This file contains essential configuration settings for the AI agent.
 }
 ```
 
+#### Message Types and Content Formats
+
+OpenKBS supports multiple message content types for rich interactions with AI models. Messages can be sent as plain text or as structured content arrays.
+
+##### Plain Text Messages
+
+The simplest format - just a string:
+
+```javascript
+{
+  "role": "user",
+  "content": "Hello, how are you?"
+}
+```
+
+##### Structured Content Arrays
+
+For rich content (images, documents, videos), use a JSON array as the content:
+
+```javascript
+{
+  role: "user",
+  content: JSON.stringify([
+    { type: "text", text: "Analyze this:" },
+    { type: "image_url", image_url: { url: "https://example.com/image.jpg" } }
+  ])
+}
+```
+
+##### Supported Content Types
+
+**text** - Plain text content
+```javascript
+{ type: "text", text: "Your message here" }
+```
+
+**image_url** - Images (JPEG, PNG, GIF, WebP, SVG) and PDFs
+```javascript
+{ type: "image_url", image_url: { url: "https://example.com/photo.jpg" } }
+{ type: "image_url", image_url: { url: "https://example.com/document.pdf" } }
+```
+
+**file_url** - Video files (Gemini models only)
+```javascript
+{ type: "file_url", file_url: { url: "https://example.com/video.mp4", mimeType: "video/mp4" } }
+{ type: "file_url", file_url: { url: "https://youtube.com/watch?v=VIDEO_ID" } }
+```
+
+##### Content Type Examples
+
+**Analyze an image:**
+```javascript
+content: JSON.stringify([
+  { type: "text", text: "What's in this image?" },
+  { type: "image_url", image_url: { url: "https://example.com/photo.jpg" } }
+])
+```
+
+**Compare multiple images:**
+```javascript
+content: JSON.stringify([
+  { type: "text", text: "Compare these:" },
+  { type: "image_url", image_url: { url: "https://example.com/image1.jpg" } },
+  { type: "image_url", image_url: { url: "https://example.com/image2.jpg" } }
+])
+```
+
+**Analyze a video (Gemini only):**
+```javascript
+content: JSON.stringify([
+  { type: "text", text: "Describe this video:" },
+  { type: "file_url", file_url: { url: "https://example.com/video.mp4", mimeType: "video/mp4" } }
+])
+```
+
+#### Supported AI Models
+
+OpenKBS provides a unified API for multiple AI providers. Configure your model in `app/settings.json`:
+
+```json
+{
+  "model": "claude-sonnet-4-5-20250929"
+}
+```
+
+##### Model Capabilities
+**Anthropic Claude** (Vision, PDF)
+**OpenAI GPT** (Vision, PDF, Video)
+**Google Gemini** (Vision, PDF, Video)
+**Other Models** (Text only)
+
+##### Usage in Actions
+
+When building custom actions that return content to the LLM, use the same content type format:
+
+```javascript
+// In actions.js - returning an image for analysis
+[/<viewImage>([\s\S]*?)<\/viewImage>/s, async (match) => {
+    const data = JSON.parse(match[1].trim());
+    return {
+        data: [
+            { type: "text", text: `Viewing image: ${data.url}` },
+            { type: "image_url", image_url: { url: data.url } }
+        ],
+        _meta_actions: ["REQUEST_CHAT_MODEL"]
+    };
+}]
+
+// Returning a video for analysis (Gemini only)
+[/<viewVideo>([\s\S]*?)<\/viewVideo>/s, async (match) => {
+    const data = JSON.parse(match[1].trim());
+    return {
+        data: [
+            { type: "text", text: `Analyzing video: ${data.url}` },
+            { type: "file_url", file_url: { url: data.url, mimeType: "video/mp4" } }
+        ],
+        _meta_actions: ["REQUEST_CHAT_MODEL"]
+    };
+}]
+```
+
 #### LLM Instructions
 `app/instructions.txt`
 This file contains the instructions for the LLM, guiding its behavior and interaction with custom functionalities.
 Clear and specific instructions ensure the LLM effectively utilizes provided actions and commands.
 
+**Command Format:**
+Commands use XML tags with JSON content. The LLM outputs these as regular text, and the backend parses and executes them.
+
 **Example Instructions:**
 
 ```
 You are an AI assistant.
 
-You can execute the following commands:
+LIST OF AVAILABLE COMMANDS:
+To execute a command, output it as text and wait for system response.
 
-/googleSearch("query")
+<googleSearch>
+{
+  "query": "search query"
+}
+</googleSearch>
 Description: """
-Get results from Google Search API.
+Get results from the Google Search API.
 """
 $InputLabel = """Let me Search in Google!"""
-$InputValue = """Search in google for the latest news"""
+$InputValue = """Search for latest news"""
+
+<createAIImage>
+{
+  "model": "gemini-2.5-flash-image",
+  "aspect_ratio": "16:9",
+  "prompt": "image description"
+}
+</createAIImage>
+Description: """
+Generate AI images. Models: gemini-2.5-flash-image (supports image editing, aspect ratios), gpt-image-1 (better for text).
+"""
+
+<createAIVideo>
+{
+  "model": "sora-2",
+  "size": "1280x720",
+  "seconds": 8,
+  "prompt": "video description"
+}
+</createAIVideo>
+Description: """
+Generate AI videos with Sora 2. Duration: 4, 8, or 12 seconds.
+"""
 
-/someCommand("param")
+<getExchangeRates>
+{
+  "base": "EUR",
+  "symbols": "USD,GBP",
+  "period": "latest"
+}
+</getExchangeRates>
+Description: """
+Get exchange rates. Period: 'latest', 'YYYY-MM-DD' (historical), or 'YYYY-MM-DD..YYYY-MM-DD' (time series).
+"""
+
+<scheduleTask>
+{
+  "delay": "2h",
+  "message": "Task description"
+}
+</scheduleTask>
+Description: """
+Schedule a future task. Use delay (minutes, "2h", "1d") or specific time (UTC).
+"""
+
+<getScheduledTasks/>
+Description: """
+List all scheduled tasks.
+"""
+
+<viewImage>
+{
+  "url": "https://example.com/image.jpg"
+}
+</viewImage>
+Description: """
+Add an image to the vision context. Use when you have an image URL that needs to be analyzed.
+The image will be added to the conversation for visual analysis.
+"""
 
 $Comment = """
 Any instructions or comments placed here will be removed before sending to the LLM.
 These can span multiple lines and contain any characters, code, or formatting.
 """
-...
-
 ```
 
-Command definitions may include \$InputLabel and \$InputValue which are invisiable to the LLM:
+Command definitions may include \$InputLabel and \$InputValue which are invisible to the LLM:
 
 `$InputLabel` - Text displayed as a selectable option in the chat interface.
 
@@ -723,7 +1279,7 @@ Command definitions may include \$InputLabel and \$InputValue which are invisiab
 
 These features provide quick command access and pre-populate inputs, enhancing user interaction.
 
-`zipMessages` and  `unzipMessages` command instructions allow the LLM to manage the chat size by summarizing or restoring portions of the conversation, optimizing context retention and token usage.
+`zipMessages` and `unzipMessages` command instructions allow the LLM to manage the chat size by summarizing or restoring portions of the conversation, optimizing context retention and token usage.
 
 Instructions:
 ```
@@ -738,12 +1294,41 @@ Include message IDs with optional summaries to maintain context while using fewe
 ```
 /unzipMessages([{ "MSG_ID" : 1234567890123 }])
 Description: """
-Uncompresses the message associated with the provided `MSG_ID`, restoring its original content to the chat. 
+Uncompresses the message associated with the provided `MSG_ID`, restoring its original content to the chat.
 """
 ```
 
 **Important:** `MSG_ID` value must be a unique identifier present anywhere in the message content. The OpenKBS platform automatically handles the zipping and unzipping of messages based on these commands. No custom implementation is required.
 
+#### Instruction Variables
+
+OpenKBS provides dynamic variables that can be used in `app/instructions.txt` to inject runtime information:
+
+- `{{kbId}}` - Current Knowledge Base ID → `abc123xyz`
+- `{{openkbsDateNow}}` - Current UTC time (ISO format) → `2025-01-15T14:30:00.000Z`
+- `{{openkbsTimestamp}}` - Current Unix timestamp (ms) → `1736948200000`
+- `{{openkbsDate:locale:timezone}}` - Formatted date with locale and timezone → `15/01/2025, 16:30:00`
+- `{{openkbsDateTZ:timezone}}` - Formatted date with timezone (en-GB locale) → `15/01/2025, 16:30:00`
+
+**Example usage in instructions.txt:**
+
+```
+You are a helpful assistant.
+
+## Current Time Information
+- UTC Time: {{openkbsDateNow}}
+- Local Time (Bulgaria): {{openkbsDate:bg-BG:Europe/Sofia}}
+- US Eastern Time: {{openkbsDate:en-US:America/New_York}}
+- Unix Timestamp: {{openkbsTimestamp}}
+- Agent ID: {{kbId}}
+
+Use the current time to provide time-aware responses.
+```
+
+**Locale examples:** `en-US`, `en-GB`, `bg-BG`, `de-DE`, `fr-FR`, `ja-JP`
+
+**Timezone examples:** `UTC`, `Europe/Sofia`, `America/New_York`, `Asia/Tokyo`, `Europe/London`
+
 #### Execution Environment
 
 The OpenKBS backend provides a pre-configured execution environment for your event handlers, including a set of globally available objects and libraries. This eliminates the need to explicitly declare these as dependencies in your `onRequest.json` or `onResponse.json` files.  These predefined resources facilitate various operations:
@@ -768,6 +1353,53 @@ Here's a breakdown of the key objects and utilities available within the OpenKBS
 
 * **`JSON5`:**  A more permissive JSON parser that supports comments, trailing commas, single quotes, and other convenient features not found in standard JSON. Useful for parsing configuration files or user input.
 
+#### MCP Integration
+
+Connect your agent to external tools using [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
+
+**Configure in `app/settings.json`:**
+```json
+{
+  "options": {
+    "mcpServers": {
+      "brave-search": {},
+      "github": {},
+      "slack": {}
+    }
+  }
+}
+```
+
+**Add required secrets** (Settings → Secrets):
+- `brave-search`: `BRAVE_API_KEY`
+- `github`: `GITHUB_PERSONAL_ACCESS_TOKEN`
+- `slack`: `SLACK_BOT_TOKEN`, `SLACK_TEAM_ID`
+
+**How it works:**
+1. Tools auto-discovered and injected into system prompt
+2. LLM outputs: `<mcp_brave-search_brave_web_search>{"query": "..."}</mcp_brave-search_brave_web_search>`
+3. Handler in `actions.js`:
+
+```javascript
+[/<mcp_([a-z0-9-]+)_([a-z0-9_]+)>([\s\S]*?)<\/mcp_\1_\2>/s, async (match) => {
+    const [, server, tool, argsJson] = match;
+    const result = await openkbs.mcp.callTool(server, tool, JSON.parse(argsJson || '{}'));
+    return { data: result?.content || [], _meta_actions: ['REQUEST_CHAT_MODEL'] };
+}]
+```
+
+**Custom MCP Server:**
+```json
+{
+  "options": {
+    "mcpServerUrl": "https://your-mcp-server.com",
+    "mcpServers": { "your-server": {} }
+  }
+}
+```
+
+Full tutorial: [MCP Integration Tutorial](https://openkbs.com/tutorials/mcp-integration/)
+
 ### Frontend
 
 The OpenKBS frontend framework is built using React and provides a flexible and extensible platform for building custom chat interfaces. It allows developers to customize the appearance and behavior of the chat through a `contentRender` module, which can be dynamically loaded and used to extend the core platform.
@@ -781,70 +1413,233 @@ The frontend framework dynamically loads the `contentRender.js` module. This mod
 
 The `contentRender.js` file is the heart of frontend customization. It can export several key functions:
 
-- **`onRenderChatMessage(params)`:** This function is called every time a chat message is rendered. It receives an object with various parameters, including:
-    - `msgIndex`: The index of the message being rendered.
-    - `messages`: The entire array of chat messages.
-    - `setMessages`: A function to update the `messages` state.
-    - `iframeRef`: A reference to the iframe element.
-    - `KB`: The Knowledge Base object containing application settings.
-    - `chatContainerRef`: A reference to the chat container element.
-    - `RequestChatAPI`: A function to send a message to the chat API.
-    - `setSystemAlert`: A function to display system alerts.
-    - `setBlockingLoading`: A function to display a loading indicator.
-    - `blockingLoading`: A boolean indicating if the loading indicator is active.
-    - `sendButtonRef`: A reference to the send button element.
-    - `sendButtonRippleRef`: A reference to the send button ripple effect.
-    - `setInputValue`: A function to set the value of the input field.
-    - `renderSettings`: An object containing rendering settings.
-    - `axios`: The axios library for making HTTP requests.
-    - `itemsAPI`: Functions for manipulating KB items.
-    - `createEmbeddingItem`: Functions to create embeddings.
-    - `indexedDB`: IndexedDB wrapper to access data.
-    - `chatAPI`: API to access chat data.
-    - `generateMsgId`: Generates a unique message ID.
-    - `kbUserData`: Function to get KB user data.
-    - `executeNodejs`: Execute custom JavaScript code inside a VM.
-
-  This function should return a React component representing the rendered message. If not defined, the default rendering mechanism is used.
+- **`onRenderChatMessage(params)`:** This function is called every time a chat message is rendered. It receives an object with various parameters:
+
+  **Message Context:**
+  - `msgIndex` - Index of the message being rendered
+  - `messages` - Entire array of chat messages
+  - `setMessages` - Function to update the messages state
+  - `KB` - Knowledge Base object containing application settings
+  - `kbUserData` - Function returning KB user data (chatUsername, etc.)
+
+  **UI Controls:**
+  - `setSystemAlert` - Display system alerts: `setSystemAlert({ severity: 'success', message: 'Done!' })`
+  - `setBlockingLoading` - Show/hide loading indicator: `setBlockingLoading(true)`
+  - `blockingLoading` - Boolean indicating if loading indicator is active
+  - `setInputValue` - Set the chat input field value
+  - `blockAutoscroll` - Control auto-scrolling behavior
+
+  **API & Communication:**
+  - `RequestChatAPI` - Send message to chat API: `await RequestChatAPI([...messages, newMsg])`
+  - `axios` - Axios library for HTTP requests
+  - `chatAPI` - API to access chat data
+  - `itemsAPI` - Functions for manipulating KB items
+
+  **DOM References:**
+  - `iframeRef` - Reference to iframe element
+  - `chatContainerRef` - Reference to chat container element
+  - `sendButtonRef` - Reference to send button element
+  - `sendButtonRippleRef` - Reference to send button ripple effect
+  - `newChatButtonRef` - Reference to new chat button
+
+  **Utilities & Libraries:**
+  - `generateMsgId` - Generates unique message ID
+  - `markdownHandler` - Markdown rendering utilities
+  - `createEmbeddingItem` - Functions to create embeddings
+  - `executeNodejs` - Execute custom JavaScript code inside a VM
+  - `initDB` - Initialize IndexedDB
+  - `indexedDB` - IndexedDB wrapper for local data access
+  - `Files` - File management utilities (same as `openkbs.Files`)
+  - `uploadFileAPI` - Upload files to storage
+
+  **Rendering Libraries (pre-loaded):**
+  - `theme` - MUI theme object
+  - `ReactPrismjs` - Syntax highlighting component
+  - `CopyToClipboard` - Clipboard copy component
+  - `APIResponseComponent` - Standard API response renderer
+  - `CodeViewer` - Code display component
+  - `textDetectionsImageFiles` - OCR detection results
+
+  **Return Value:** Return a React component to render the message, or `null` to use default rendering. Return `JSON.stringify({ type: 'HIDDEN_MESSAGE' })` to hide a message completely.
+
+  **Example Usage:**
+  ```javascript
+  const onRenderChatMessage = async (params) => {
+      const { content, role } = params.messages[params.msgIndex];
+      const { msgIndex, messages, setSystemAlert, RequestChatAPI,
+              kbUserData, generateMsgId, markdownHandler } = params;
+
+      // Hide system messages
+      if (role === 'system') {
+          return JSON.stringify({ type: 'HIDDEN_MESSAGE' });
+      }
+
+      // Custom rendering for specific content
+      if (content.includes('<myCommand>')) {
+          return <MyCustomComponent content={content} />;
+      }
+
+      // Send a follow-up message
+      const sendFollowUp = async () => {
+          await RequestChatAPI([...messages, {
+              role: 'user',
+              content: 'Follow up message',
+              userId: kbUserData().chatUsername,
+              msgId: generateMsgId()
+          }]);
+      };
+
+      return null; // Use default rendering
+  };
+  ```
 
 - **`Header(props)`:** This React component is rendered at the top of the chat interface. It receives the same `params` object as `onRenderChatMessage`. It can be used to add custom UI elements or controls to the chat header. If not defined, the standard OpenKBS chat header is displayed.
 
 - **`onDeleteChatMessage(params)`:** This async function is triggered when a chat message is deleted. This function receives a `params` object similar to the `onRenderChatMessage` function but also includes `chatId`, `message` (the message being deleted), and can be used to perform cleanup actions related to custom rendered content. If not defined, a default delete message function is executed.
 
-**Example `contentRender.js`:**
+**Example `contentRender.js` with Command Rendering:**
 
 ```javascript
 import React from 'react';
+import { Box, Tooltip, Typography, Zoom } from '@mui/material';
+import SearchIcon from '@mui/icons-material/Search';
+import ImageIcon from '@mui/icons-material/Image';
+import VideoLibraryIcon from '@mui/icons-material/VideoLibrary';
+
+// Define command patterns to detect
+const COMMAND_PATTERNS = [
+    /<createAIImage>[\s\S]*?<\/createAIImage>/,
+    /<createAIVideo>[\s\S]*?<\/createAIVideo>/,
+    /<googleSearch>[\s\S]*?<\/googleSearch>/
+];
 
-const onRenderChatMessage = async (params) => {
-  const { content, role } = params.messages[params.msgIndex];
-  if (role === 'assistant' && content.startsWith('```json')) {
-    try {
-      const jsonData = JSON.parse(content.replace('```json', '').replace('```', ''));
-      return <pre>{JSON.stringify(jsonData, null, 2)}</pre>;
-    } catch (e) {
-      console.error('Error parsing JSON:', e);
-      return null;
+// Icon mapping for commands
+const commandIcons = {
+    createAIImage: ImageIcon,
+    createAIVideo: VideoLibraryIcon,
+    googleSearch: SearchIcon
+};
+
+// Parse commands from content
+const parseCommands = (content) => {
+    const commands = [];
+    const regex = /<(\w+)>([\s\S]*?)<\/\1>/g;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        try {
+            commands.push({
+                name: match[1],
+                data: JSON.parse(match[2].trim())
+            });
+        } catch (e) {}
     }
-  }
+    return commands;
 };
 
-const Header = ({ setRenderSettings }) => {
-  // Custom header content
-  return (
-          <div>
-            <h1>Custom Chat Header</h1>
-          </div>
-  );
+// Render command as icon with tooltip
+const CommandIcon = ({ command }) => {
+    const Icon = commandIcons[command.name] || SearchIcon;
+    return (
+        <Tooltip title={<pre>{JSON.stringify(command.data, null, 2)}</pre>} arrow>
+            <Box sx={{
+                display: 'inline-flex',
+                width: 32, height: 32,
+                borderRadius: '50%',
+                backgroundColor: 'rgba(76, 175, 80, 0.1)',
+                border: '2px solid rgba(76, 175, 80, 0.3)',
+                alignItems: 'center',
+                justifyContent: 'center',
+                mx: 0.5
+            }}>
+                <Icon sx={{ fontSize: 16, color: '#4CAF50' }} />
+            </Box>
+        </Tooltip>
+    );
 };
 
-const onDeleteChatMessage = async (params) => {
-  // Perform cleanup or other actions on chat message delete
-  const { chatId, message, itemsAPI, KB, setBlockingLoading } = params;
-  // Perform action before the message is deleted
+const onRenderChatMessage = async (params) => {
+    const { content, role } = params.messages[params.msgIndex];
+
+    // Check for commands in content
+    const hasCommand = COMMAND_PATTERNS.some(p => p.test(content));
+    if (hasCommand) {
+        const commands = parseCommands(content);
+        return (
+            <Box>
+                {commands.map((cmd, i) => <CommandIcon key={i} command={cmd} />)}
+            </Box>
+        );
+    }
+
+    return null; // Use default rendering
 };
 
-const exports = { onRenderChatMessage, Header, onDeleteChatMessage };
+const Header = ({ setRenderSettings, openkbs, setSystemAlert }) => {
+    const [panelOpen, setPanelOpen] = React.useState(false);
+
+    React.useEffect(() => {
+        setRenderSettings({
+            disableBalanceView: false,
+            disableEmojiButton: true,
+            backgroundOpacity: 0.02
+        });
+    }, [setRenderSettings]);
+
+    return (
+        <>
+            {/* Settings button */}
+            <Box
+                onClick={() => setPanelOpen(true)}
+                sx={{
+                    position: 'absolute',
+                    top: 90, left: 340,
+                    width: 40, height: 40,
+                    borderRadius: '50%',
+                    backgroundColor: 'white',
+                    border: '1px solid #e0e0e0',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    cursor: 'pointer',
+                    zIndex: 1200
+                }}
+            >
+                ⚙️
+            </Box>
+
+            {/* Simple settings panel */}
+            {panelOpen && (
+                <Box
+                    onClick={() => setPanelOpen(false)}
+                    sx={{
+                        position: 'fixed',
+                        inset: 0,
+                        backgroundColor: 'rgba(0,0,0,0.5)',
+                        zIndex: 1300,
+                        display: 'flex',
+                        alignItems: 'center',
+                        justifyContent: 'center'
+                    }}
+                >
+                    <Box
+                        onClick={e => e.stopPropagation()}
+                        sx={{
+                            width: 400,
+                            backgroundColor: 'white',
+                            borderRadius: 2,
+                            p: 3
+                        }}
+                    >
+                        <Typography variant="h6">Settings</Typography>
+                        <Typography>Your custom admin panel here</Typography>
+                    </Box>
+                </Box>
+            )}
+        </>
+    );
+};
+
+const exports = { onRenderChatMessage, Header };
 window.contentRender = exports;
 export default exports;
 ```
@@ -1043,6 +1838,499 @@ const onRenderChatMessage = async (params) => {
 };
 ```
 
+#### Header Component Props
+
+The `Header` component receives all available props from the OpenKBS chat interface. These props enable full control over chat behavior, UI state, and data access.
+
+**All Available Props:**
+
+- `messages` (Array) - Current chat messages array
+- `setMessages` (Function) - Update messages array (e.g., add welcome message)
+- `KB` (Object) - Current Knowledge Base data
+- `openkbs` (Object) - OpenKBS SDK object (see Frontend SDK section)
+- `setRenderSettings` (Function) - Configure UI rendering options
+- `setSystemAlert` (Function) - Show alert notifications
+- `setBlockingLoading` (Function) - Show/hide full-screen loading overlay
+- `RequestChatAPI` (Function) - Send messages to chat API
+- `chatAPI` (Object) - Chat API utilities
+- `itemsAPI` (Object) - Items API (low-level)
+- `Files` (Object) - Files API module
+- `indexedDB` (Object) - IndexedDB interface for local storage
+- `initDB` (Function) - Initialize IndexedDB
+- `kbUserData` (Function) - Get current user data
+- `navigateToChat` (Function) - Navigate to different chat
+- `setIsContextItemsOpen` (Function) - Toggle context items panel
+- `isContextItemsOpen` (Boolean) - Context items panel state
+- `chatContainerRef` (Ref) - Reference to chat container element
+- `renderSettings` (Object) - Current render settings
+- `blockingLoading` (Boolean) - Loading state
+- `blockAutoscroll` (Boolean) - Auto-scroll state
+- `axios` (Object) - Axios HTTP client
+
+**Common Usage Patterns:**
+
+*setRenderSettings* - Configure UI behavior:
+```javascript
+const Header = ({ setRenderSettings }) => {
+    useEffect(() => {
+        setRenderSettings({
+            disableBalanceView: false,
+            disableEmojiButton: true,
+            disableChatModelsSelect: true,
+            disableShareButton: true,
+            disableMultichat: true,
+            disableMobileLeftButton: true,
+            disableTextToSpeechButton: true,
+            disableInitialScroll: true,
+            backgroundOpacity: 0.02,
+            customStreamingLoader: true,
+            inputLabelsQuickSend: true,
+            setMessageWidth: (content) => content.includes('<html') ? '90%' : undefined
+        });
+    }, [setRenderSettings]);
+};
+```
+
+*setSystemAlert* - Show notifications:
+```javascript
+const Header = ({ setSystemAlert }) => {
+    const showSuccess = () => {
+        setSystemAlert({
+            msg: 'Operation completed successfully',
+            type: 'success',  // 'success', 'error', 'warning', 'info'
+            duration: 3000    // milliseconds
+        });
+    };
+
+    const showError = (error) => {
+        setSystemAlert({
+            msg: error.message,
+            type: 'error',
+            duration: 5000
+        });
+    };
+};
+```
+
+*setBlockingLoading* - Full-screen loading overlay:
+```javascript
+const Header = ({ setBlockingLoading, openkbs }) => {
+    const loadData = async () => {
+        setBlockingLoading(true);  // Show loading
+        // Or with custom text:
+        // setBlockingLoading({ text: 'Loading files...' });
+
+        try {
+            const files = await openkbs.Files.listFiles('files');
+            // Process files...
+        } finally {
+            setBlockingLoading(false);  // Hide loading
+        }
+    };
+};
+```
+
+*RequestChatAPI* - Send messages programmatically:
+```javascript
+const Header = ({ RequestChatAPI, messages, kbUserData, navigateToChat }) => {
+    const sendQuickMessage = (prompt) => {
+        navigateToChat(null);  // Start new chat
+        RequestChatAPI([{
+            role: 'user',
+            content: prompt,
+            userId: kbUserData().chatUsername,
+            msgId: `${Date.now()}-${Math.floor(100000 + Math.random() * 900000)}`
+        }]);
+    };
+
+    return (
+        <button onClick={() => sendQuickMessage('Help me create a marketing plan')}>
+            Quick Action
+        </button>
+    );
+};
+```
+
+*setMessages* - Initialize welcome message:
+```javascript
+const Header = ({ messages, setMessages, openkbs }) => {
+    useEffect(() => {
+        const initWelcome = async () => {
+            // Only for new chats
+            if (!messages || messages.length === 0) {
+                const profile = await openkbs.getItem('memory_profile');
+
+                if (!profile?.item) {
+                    setMessages([{
+                        msgId: `${Date.now()}-${Math.floor(100000 + Math.random() * 900000)}`,
+                        role: 'assistant',
+                        content: 'Welcome! Tell me about your business to get started.'
+                    }]);
+                }
+            }
+        };
+
+        initWelcome();
+    }, [messages, setMessages, openkbs]);
+};
+```
+
+*navigateToChat* - Chat navigation:
+```javascript
+const Header = ({ navigateToChat }) => {
+    // Navigate to specific chat
+    const goToChat = (chatId) => navigateToChat(chatId);
+
+    // Start new chat
+    const newChat = () => navigateToChat(null);
+};
+```
+
+**Complete Header Example:**
+
+```javascript
+import React, { useEffect, useState } from 'react';
+import { IconButton, Dialog, Box, Button } from '@mui/material';
+import SettingsIcon from '@mui/icons-material/Settings';
+
+const Header = ({
+    setRenderSettings,
+    openkbs,
+    setSystemAlert,
+    setBlockingLoading,
+    messages,
+    setMessages,
+    RequestChatAPI,
+    kbUserData,
+    navigateToChat
+}) => {
+    const [panelOpen, setPanelOpen] = useState(false);
+    const [files, setFiles] = useState([]);
+
+    // Configure UI on mount
+    useEffect(() => {
+        setRenderSettings({
+            disableEmojiButton: true,
+            disableChatModelsSelect: true,
+            backgroundOpacity: 0.02
+        });
+    }, [setRenderSettings]);
+
+    // Initialize welcome message for new chats
+    useEffect(() => {
+        if (!messages?.length && openkbs) {
+            setMessages([{
+                msgId: `${Date.now()}-000000`,
+                role: 'assistant',
+                content: 'Welcome! How can I help you today?'
+            }]);
+        }
+    }, [messages, setMessages, openkbs]);
+
+    // Load files when panel opens
+    const loadFiles = async () => {
+        setBlockingLoading(true);
+        try {
+            const result = await openkbs.Files.listFiles('files');
+            setFiles(result || []);
+        } catch (e) {
+            setSystemAlert({ msg: e.message, type: 'error', duration: 5000 });
+        } finally {
+            setBlockingLoading(false);
+        }
+    };
+
+    // Quick action handler
+    const quickAction = (prompt) => {
+        navigateToChat(null);
+        RequestChatAPI([{
+            role: 'user',
+            content: prompt,
+            userId: kbUserData().chatUsername,
+            msgId: `${Date.now()}-${Math.floor(Math.random() * 900000)}`
+        }]);
+    };
+
+    return (
+        <>
+            <IconButton
+                onClick={() => { setPanelOpen(true); loadFiles(); }}
+                sx={{ position: 'absolute', top: 90, left: 340, zIndex: 1200 }}
+            >
+                <SettingsIcon />
+            </IconButton>
+
+            <Button
+                onClick={() => quickAction('Create a marketing plan')}
+                sx={{ position: 'absolute', top: 90, left: 400, zIndex: 1200 }}
+            >
+                Quick Action
+            </Button>
+
+            <Dialog open={panelOpen} onClose={() => setPanelOpen(false)}>
+                <Box sx={{ p: 2 }}>
+                    <h3>Files ({files.length})</h3>
+                    {files.map((f, i) => <div key={i}>{f.name}</div>)}
+                </Box>
+            </Dialog>
+        </>
+    );
+};
+
+const exports = { Header };
+window.contentRender = exports;
+export default exports;
+```
+
+#### Frontend SDK (`openkbs` object)
+
+The `openkbs` object is passed to `Header` and `onRenderChatMessage` functions, providing access to item storage, file management, and KB sharing APIs.
+
+**Properties:**
+```javascript
+const Header = ({ openkbs }) => {
+    console.log(openkbs.kbId);      // Current KB ID
+    console.log(openkbs.KBData);    // Full KB configuration
+    console.log(openkbs.Files);     // Files API module
+    console.log(openkbs.itemsAPI);  // Items API module (low-level)
+    console.log(openkbs.KBAPI);     // KB API module
+};
+```
+
+##### Item CRUD Operations
+
+```javascript
+// Create an item
+await openkbs.createItem({
+    itemType: 'memory',
+    itemId: 'memory_user_preferences',
+    body: { theme: 'dark', language: 'en' }  // Auto-encrypted
+});
+
+// Update an item
+await openkbs.updateItem({
+    itemType: 'memory',
+    itemId: 'memory_user_preferences',
+    body: { theme: 'light', language: 'bg' }
+});
+
+// Get a single item (auto-decrypted)
+const result = await openkbs.getItem('memory_user_preferences');
+console.log(result.item.body);  // { theme: 'light', language: 'bg' }
+
+// Delete an item
+await openkbs.deleteItem('memory_user_preferences');
+
+// Fetch multiple items with filters
+const items = await openkbs.fetchItems({
+    itemType: 'memory',           // Filter by item type
+    limit: 100,                   // Max items to return
+    beginsWith: 'memory_',        // Filter by ID prefix
+    from: '2024-01-01',           // Range start (for date fields)
+    to: '2024-12-31',             // Range end
+    field: 'createdAt',           // Field for range query
+});
+
+// Items are returned with decrypted bodies
+items.items.forEach(({ item, meta }) => {
+    console.log(meta.itemId, item.body);
+});
+```
+
+##### Encryption Utilities
+
+```javascript
+// Encrypt sensitive data
+const encrypted = await openkbs.encrypt('sensitive data');
+
+// Decrypt data
+const decrypted = await openkbs.decrypt(encrypted);
+```
+
+##### Files API (`openkbs.Files`)
+
+```javascript
+// List files in a namespace
+const files = await openkbs.Files.listFiles('files');
+
+// Upload a file
+const file = new File(['content'], 'example.txt', { type: 'text/plain' });
+await openkbs.Files.uploadFileAPI(file, 'files', (progress) => {
+    console.log(`Upload progress: ${progress}%`);
+});
+
+// Create presigned URL for upload/download
+const url = await openkbs.Files.createPresignedURL(
+    'files',           // namespace
+    'putObject',       // 'putObject' or 'getObject'
+    'myfile.pdf',      // filename
+    'application/pdf'  // content type
+);
+
+// Delete a file
+await openkbs.Files.deleteRawKBFile('filename.txt', 'files');
+
+// Rename a file
+await openkbs.Files.renameFile(
+    'files/kbId/old-name.txt',  // old path
+    'new-name.txt',              // new name
+    'files'                      // namespace
+);
+
+// Secrets management
+const secrets = await openkbs.Files.listSecrets();
+await openkbs.Files.createSecretWithKBToken('API_KEY', 'secret-value');
+await openkbs.Files.deleteSecret('API_KEY');
+
+// File versions
+const versions = await openkbs.Files.listVersions('myfile.js', 'functions');
+await openkbs.Files.restoreVersion('version-id', 'myfile.js', 'functions');
+```
+
+##### KB API (`openkbs.KBAPI`)
+
+```javascript
+// Get KB configuration
+const kb = await openkbs.KBAPI.getKB();
+
+// Share KB with another user (by email)
+await openkbs.KBAPI.shareKBWith('user@example.com');
+
+// Get list of users KB is shared with
+const shares = await openkbs.KBAPI.getKBShares();
+// Returns: { sharedWith: ['user1@example.com', 'user2@example.com'] }
+
+// Remove share
+await openkbs.KBAPI.unshareKBWith('user@example.com');
+
+// API Keys management
+const keys = await openkbs.KBAPI.getAPIKeys();
+const newKey = await openkbs.KBAPI.createAPIKey('My API Key', { resources: '*' });
+await openkbs.KBAPI.deleteAPIKey('api-key-id');
+
+// Update KB variable
+await openkbs.KBAPI.updateVariable('customSetting', 'value');
+
+// Search items (semantic search if embeddings enabled)
+const results = await openkbs.KBAPI.searchItems('search query', openkbs.kbId, 100);
+```
+
+##### Complete Header Example with Admin Panel
+
+```javascript
+import React, { useState, useEffect } from 'react';
+import { Box, IconButton, Dialog, Tabs, Tab, List, ListItem,
+         ListItemText, TextField, Button, Typography } from '@mui/material';
+import SettingsIcon from '@mui/icons-material/Settings';
+
+const Header = ({ openkbs, setRenderSettings, setSystemAlert, setBlockingLoading }) => {
+    const [open, setOpen] = useState(false);
+    const [tab, setTab] = useState(0);
+    const [files, setFiles] = useState([]);
+    const [shares, setShares] = useState([]);
+    const [email, setEmail] = useState('');
+
+    useEffect(() => {
+        setRenderSettings({
+            disableEmojiButton: true,
+            backgroundOpacity: 0.02
+        });
+    }, []);
+
+    // Load files
+    const loadFiles = async () => {
+        setBlockingLoading(true);
+        try {
+            const result = await openkbs.Files.listFiles('files');
+            setFiles(result || []);
+        } finally {
+            setBlockingLoading(false);
+        }
+    };
+
+    // Load shares
+    const loadShares = async () => {
+        const result = await openkbs.KBAPI.getKBShares();
+        setShares(result?.sharedWith || []);
+    };
+
+    // Share with user
+    const shareWith = async () => {
+        try {
+            await openkbs.KBAPI.shareKBWith(email);
+            setSystemAlert({ msg: `Shared with ${email}`, type: 'success', duration: 3000 });
+            setEmail('');
+            loadShares();
+        } catch (e) {
+            setSystemAlert({ msg: e.message, type: 'error', duration: 5000 });
+        }
+    };
+
+    useEffect(() => {
+        if (open && tab === 0) loadFiles();
+        if (open && tab === 1) loadShares();
+    }, [open, tab]);
+
+    return (
+        <>
+            <IconButton
+                onClick={() => setOpen(true)}
+                sx={{ position: 'absolute', top: 80, right: 20, zIndex: 1200 }}
+            >
+                <SettingsIcon />
+            </IconButton>
+
+            <Dialog open={open} onClose={() => setOpen(false)} maxWidth="md" fullWidth>
+                <Box sx={{ p: 2 }}>
+                    <Typography variant="h6">Settings</Typography>
+                    <Tabs value={tab} onChange={(e, v) => setTab(v)}>
+                        <Tab label="Files" />
+                        <Tab label="Sharing" />
+                    </Tabs>
+
+                    {tab === 0 && (
+                        <List>
+                            {files.map((file, i) => (
+                                <ListItem key={i}>
+                                    <ListItemText primary={file.name} />
+                                </ListItem>
+                            ))}
+                        </List>
+                    )}
+
+                    {tab === 1 && (
+                        <Box>
+                            <Box sx={{ display: 'flex', gap: 1, my: 2 }}>
+                                <TextField
+                                    fullWidth
+                                    label="Email"
+                                    value={email}
+                                    onChange={(e) => setEmail(e.target.value)}
+                                />
+                                <Button variant="contained" onClick={shareWith}>
+                                    Share
+                                </Button>
+                            </Box>
+                            <List>
+                                {shares.map((s, i) => (
+                                    <ListItem key={i}>
+                                        <ListItemText primary={s} />
+                                    </ListItem>
+                                ))}
+                            </List>
+                        </Box>
+                    )}
+                </Box>
+            </Dialog>
+        </>
+    );
+};
+
+const exports = { Header };
+window.contentRender = exports;
+export default exports;
+```
+
 ## API
 
 OpenKBS provides APIs to interact programmatically with your application. These APIs allow you to perform actions like starting new chats, retrieving chat messages, and managing data within your application. Data exchanged with these APIs is encrypted and decrypted using AES-256 encryption.
@@ -1387,4 +2675,4 @@ We welcome contributions from the community! Please feel free to submit issues,
 
 ## Contact
 
-For more information, visit our [official website](https://openkbs.com) or join our community discussions on [GitHub](https://github.com/open-kbs/openkbs/discussions).
+For more information, visit our [official website](https://openkbs.com) or join our community discussions on [GitHub](https://github.com/open-kbs/openkbs/discussions).