openkbs 0.0.65 → 0.0.67

package/templates/.claude/skills/openkbs/reference/frontend-sdk.md

@@ -0,0 +1,299 @@
+# Frontend SDK Reference
+
+OpenKBS frontend is a React 18 application. Customize through `src/Frontend/contentRender.js`.
+
+## Built-in Libraries (No Install Needed)
+
+These libraries are provided by OpenKBS and marked with `(fixed)` in `contentRender.json`:
+
+- React 18 (`react`, `react-dom`)
+- Material-UI (`@mui/material`, `@mui/icons-material`)
+- Emotion (`@emotion/react`, `@emotion/styled`)
+
+## contentRender.js Exports
+
+| Export | Purpose |
+|--------|---------|
+| `onRenderChatMessage` | Custom message rendering |
+| `Header` | Custom header component |
+
+## onRenderChatMessage
+
+Receives each message and returns custom rendering:
+
+```javascript
+const onRenderChatMessage = async (params) => {
+    const { content, role } = params.messages[params.msgIndex];
+    const { msgIndex, messages, markdownHandler } = params;
+
+    // Return null for default markdown rendering
+    // Return React component for custom rendering
+    // Return JSON.stringify({ type: 'HIDDEN_MESSAGE' }) to hide
+
+    return null;
+};
+```
+
+### Parameters
+
+- `params.messages` - All messages in conversation
+- `params.msgIndex` - Current message index
+- `params.markdownHandler` - Function to render markdown
+- `params.setSystemAlert({ severity, message })` - Show alerts (success, error, warning, info)
+- `params.setBlockingLoading(bool)` - Show loading overlay
+- `params.RequestChatAPI(messages)` - Send messages to LLM
+- `params.kbUserData()` - Get user info
+- `params.generateMsgId()` - Generate unique message ID
+- `params.theme` - Current MUI theme
+
+### Return Values
+
+```javascript
+// Default rendering
+return null;
+
+// Custom component
+return <div>Custom content</div>;
+
+// Hide message
+return JSON.stringify({ type: 'HIDDEN_MESSAGE' });
+```
+
+## Header Component
+
+Customize the chat header:
+
+```javascript
+const Header = ({ setRenderSettings }) => {
+    useEffect(() => {
+        setRenderSettings({
+            disableShareButton: true,
+            disableBalanceView: true
+        });
+    }, [setRenderSettings]);
+
+    return <div>Custom Header</div>;
+};
+```
+
+## Command Rendering Pattern
+
+Define commands with icons:
+
+```javascript
+// commands.js
+import SearchIcon from '@mui/icons-material/Search';
+import ImageIcon from '@mui/icons-material/Image';
+
+export const COMMANDS = {
+    googleSearch: { icon: SearchIcon },
+    createAIImage: { icon: ImageIcon },
+    cleanupMemory: { icon: ClearIcon, selfClosing: true }
+};
+
+// Generate regex patterns
+export const COMMAND_PATTERNS = Object.entries(COMMANDS).map(([name, config]) => {
+    if (config.selfClosing) {
+        return new RegExp(`<${name}\\s*\\/>`);
+    }
+    return new RegExp(`<${name}>[\\s\\S]*?<\\/${name}>`);
+});
+```
+
+## Command Circle Component
+
+Render commands as interactive icons:
+
+```javascript
+const CommandCircle = ({ command, response }) => {
+    const IconComponent = COMMANDS[command.name]?.icon || BoltIcon;
+    const isSuccess = response && !response.error;
+
+    return (
+        <Tooltip title={getTooltipContent()}>
+            <Box sx={{
+                width: 36, height: 36,
+                borderRadius: '50%',
+                backgroundColor: isSuccess ? 'rgba(76, 175, 80, 0.08)' : 'rgba(0, 0, 0, 0.04)',
+                border: '2px solid',
+                borderColor: isSuccess ? 'rgba(76, 175, 80, 0.3)' : 'rgba(0, 0, 0, 0.12)',
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center'
+            }}>
+                <IconComponent sx={{ fontSize: 18 }} />
+            </Box>
+        </Tooltip>
+    );
+};
+```
+
+## Image Display with Download
+
+```javascript
+const ImageWithDownload = ({ imageUrl }) => {
+    const [isLoading, setIsLoading] = useState(true);
+
+    const handleDownload = async () => {
+        const link = document.createElement('a');
+        link.download = 'image.png';
+
+        const response = await fetch(imageUrl);
+        const blob = await response.blob();
+        link.href = URL.createObjectURL(blob);
+        link.click();
+    };
+
+    return (
+        <div>
+            <img
+                src={imageUrl}
+                onLoad={() => setIsLoading(false)}
+                style={{ maxWidth: '100%', borderRadius: 8 }}
+            />
+            {!isLoading && (
+                <button onClick={handleDownload}>
+                    <DownloadIcon /> Download
+                </button>
+            )}
+        </div>
+    );
+};
+```
+
+## Parsing JSON Results
+
+```javascript
+const onRenderChatMessage = async (params) => {
+    const { content } = params.messages[params.msgIndex];
+
+    let JSONData;
+    try { JSONData = JSON.parse(content); } catch (e) {}
+
+    // Handle CHAT_IMAGE result
+    if (JSONData?.type === 'CHAT_IMAGE' && JSONData?.data?.imageUrl) {
+        return <ImageWithDownload imageUrl={JSONData.data.imageUrl} />;
+    }
+
+    // Hide CONTINUE messages
+    if (JSONData?.type === 'CONTINUE') {
+        return JSON.stringify({ type: 'HIDDEN_MESSAGE' });
+    }
+
+    return null;
+};
+```
+
+## contentRender.json
+
+Declare dependencies:
+
+```json
+{
+  "dependencies": {
+    "react": "^18.2.0 (fixed)",
+    "react-dom": "^18.2.0 (fixed)",
+    "@mui/material": "^5.16.1 (fixed)",
+    "@mui/icons-material": "^5.16.1 (fixed)",
+    "@emotion/react": "^11.10.6 (fixed)",
+    "@emotion/styled": "^11.10.6 (fixed)"
+  }
+}
+```
+
+The `(fixed)` suffix indicates built-in libraries that don't need bundling.
+
+## Frontend openkbs Object
+
+The `openkbs` object is available globally in frontend code.
+
+### Item CRUD
+
+```javascript
+// Create item
+await openkbs.createItem({
+    itemType: 'memory',
+    itemId: 'memory_key',
+    body: { value: 'data' }
+});
+
+// Update item
+await openkbs.updateItem({
+    itemType: 'memory',
+    itemId: 'memory_key',
+    body: { value: 'updated' }
+});
+
+// Get single item
+const item = await openkbs.getItem('memory_key');
+console.log(item.item.body.value);
+
+// Fetch multiple items
+const items = await openkbs.fetchItems({
+    itemType: 'memory',
+    beginsWith: 'memory_',
+    limit: 100
+});
+
+// Delete item
+await openkbs.deleteItem('memory_key');
+```
+
+### Files API
+
+```javascript
+// List files
+const files = await openkbs.Files.listFiles('files');
+// Returns: [{ Key, Size, LastModified }, ...]
+
+// Upload with progress
+const onProgress = (percent) => console.log(`${percent}%`);
+await openkbs.Files.uploadFileAPI(fileObject, 'files', onProgress);
+
+// Delete file
+await openkbs.Files.deleteRawKBFile('filename.jpg', 'files');
+
+// Rename file
+await openkbs.Files.renameFile('old.jpg', 'new.jpg', 'files');
+```
+
+### Sharing API
+
+```javascript
+// Share KB
+await openkbs.KBAPI.shareKBWith('user@example.com');
+
+// Get shares
+const shares = await openkbs.KBAPI.getKBShares();
+// Returns: { sharedWith: ['email1', 'email2'] }
+
+// Remove share
+await openkbs.KBAPI.unshareKBWith('user@example.com');
+```
+
+### Properties
+
+```javascript
+openkbs.kbId       // Current KB ID
+openkbs.isMobile   // Boolean - is mobile device
+openkbs.KBData     // KB metadata
+```
+
+## Debug Mode
+
+Add `?debug=1` to URL to see raw messages:
+
+```
+https://YOUR_KB_ID.apps.openkbs.com?debug=1
+```
+
+## Mobile Detection
+
+```javascript
+const isMobile = window.innerWidth < 960;
+// Or use: openkbs.isMobile
+```
+
+## Complete Example
+
+See [examples/ai-marketing-agent/src/Frontend/](../examples/ai-marketing-agent/src/Frontend/) for a full implementation.

package/templates/platform/README.md

@@ -0,0 +1,70 @@
+# {{APP_NAME}} Platform
+
+OpenKBS full-stack platform with AI agents, serverless functions, and static site.
+
+## Structure
+
+```
+{{APP_NAME}}/
+├── agents/                 # AI agents
+│   └── assistant/          # Sample assistant agent
+│       ├── app/
+│       │   ├── settings.json
+│       │   └── instructions.txt
+│       └── src/
+│           ├── Events/
+│           └── Frontend/
+├── functions/              # Serverless Lambda functions
+│   └── api/
+│       └── index.mjs       # Sample API endpoint
+├── site/                   # Static site for whitelabel
+│   └── index.html
+├── openkbs.json            # Elastic services configuration
+└── README.md
+```
+
+## Deploy
+
+```bash
+# Deploy elastic services (postgres, storage, pulse)
+openkbs deploy
+
+# Deploy the API function
+openkbs fn push api
+
+# Deploy static site
+openkbs site push
+
+# Deploy an agent
+cd agents/assistant
+openkbs push
+```
+
+## Elastic Services
+
+Enabled in `openkbs.json`:
+
+- **Postgres**: `openkbs postgres shell` to connect
+- **Storage**: `openkbs storage ls` to list files
+- **Pulse**: `openkbs pulse status` for WebSocket info
+- **Functions**: `openkbs fn list` to see deployed functions
+
+## Development
+
+```bash
+# Check stack status
+openkbs stack status
+
+# View function logs
+openkbs fn logs api
+
+# Invoke function locally
+openkbs fn invoke api '{"action": "hello"}'
+```
+
+## URLs
+
+After deployment:
+- Site: `https://YOUR_DOMAIN/`
+- API: `https://fn.openkbs.com/YOUR_KB_ID/api`
+- Agent: `https://YOUR_KB_ID.apps.openkbs.com`

package/templates/platform/agents/assistant/app/instructions.txt

@@ -0,0 +1,25 @@
+You are an AI assistant for {{APP_NAME}}.
+
+## Available Commands
+
+<googleSearch>
+{"query": "search terms"}
+</googleSearch>
+Search the web for information.
+
+<setMemory>
+{"itemId": "memory_key", "value": "data to remember"}
+</setMemory>
+Save data to memory. The itemId must start with "memory_".
+
+<deleteItem>
+{"itemId": "memory_key"}
+</deleteItem>
+Delete a memory item.
+
+## Guidelines
+
+1. Be helpful and concise
+2. Use commands when needed to assist the user
+3. Remember important information using setMemory
+4. Search the web when you need current information

package/templates/platform/agents/assistant/app/settings.json

@@ -0,0 +1,17 @@
+{
+  "kbTitle": "{{APP_NAME}} Assistant",
+  "kbDescription": "AI assistant for {{APP_NAME}} platform",
+  "model": "anthropic/claude-sonnet-4-20250514",
+  "maxTokens": 16000,
+  "itemTypes": {
+    "memory": {
+      "attributes": [
+        { "attrName": "itemId", "attrType": "itemId", "encrypted": false },
+        { "attrName": "body", "attrType": "body", "encrypted": true }
+      ]
+    }
+  },
+  "options": {
+    "priorityItems": [{ "prefix": "memory_", "limit": 50 }]
+  }
+}

package/templates/platform/agents/assistant/src/Events/actions.js

@@ -0,0 +1,81 @@
+/**
+ * Command actions for {{APP_NAME}} Assistant
+ */
+
+export const getActions = (meta, event) => [
+    // Google Search
+    [/<googleSearch>([\s\S]*?)<\/googleSearch>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+            const results = await openkbs.googleSearch(data.query);
+
+            const formatted = results?.slice(0, 5).map(({ title, link, snippet }) => ({
+                title, link, snippet
+            }));
+
+            return {
+                type: 'SEARCH_RESULTS',
+                data: formatted,
+                ...meta,
+                _meta_actions: ["REQUEST_CHAT_MODEL"]
+            };
+        } catch (e) {
+            return { error: e.message, ...meta, _meta_actions: ["REQUEST_CHAT_MODEL"] };
+        }
+    }],
+
+    // Set Memory
+    [/<setMemory>([\s\S]*?)<\/setMemory>/s, async (match) => {
+        try {
+            const data = JSON.parse(match[1].trim());
+
+            if (!data.itemId?.startsWith('memory_')) {
+                return {
+                    type: "MEMORY_ERROR",
+                    error: "itemId must start with 'memory_'",
+                    _meta_actions: ["REQUEST_CHAT_MODEL"]
+                };
+            }
+
+            try {
+                await openkbs.updateItem({
+                    itemType: 'memory',
+                    itemId: data.itemId,
+                    body: { value: data.value, updatedAt: new Date().toISOString() }
+                });
+            } catch (e) {
+                await openkbs.createItem({
+                    itemType: 'memory',
+                    itemId: data.itemId,
+                    body: { value: data.value, updatedAt: new Date().toISOString() }
+                });
+            }
+
+            return {
+                type: "MEMORY_SAVED",
+                itemId: data.itemId,
+                ...meta,
+                _meta_actions: ["REQUEST_CHAT_MODEL"]
+            };
+        } catch (e) {
+            return { error: e.message, ...meta, _meta_actions: ["REQUEST_CHAT_MODEL"] };
+        }
+    }],
+
+    // Delete Item
+    [/<deleteItem>([\s\S]*?)<\/deleteItem>/s, async (match) => {
+        try {
+            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"]
+            };
+        } catch (e) {
+            return { error: e.message, ...meta, _meta_actions: ["REQUEST_CHAT_MODEL"] };
+        }
+    }]
+];

package/templates/platform/agents/assistant/src/Events/onResponse.js

@@ -0,0 +1,41 @@
+import { getActions } from './actions.js';
+
+export const handler = async (event) => {
+    const response = event?.payload?.response?.content ?? event?.payload?.response;
+    if (!response) return { type: 'EMPTY_RESPONSE' };
+
+    const meta = {
+        role: 'tool',
+        name: 'command_executor',
+        msgId: `msg_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`
+    };
+
+    const actions = getActions(meta, event);
+    const results = [];
+
+    for (const [pattern, handler] of actions) {
+        const matches = response.matchAll(new RegExp(pattern.source, pattern.flags + 'g'));
+        for (const match of matches) {
+            results.push(handler(match));
+        }
+    }
+
+    if (results.length === 0) {
+        return { type: 'NO_COMMANDS', _meta_actions: [] };
+    }
+
+    const resolved = await Promise.all(results);
+
+    if (resolved.length === 1) {
+        return resolved[0];
+    }
+
+    return {
+        type: 'MULTI_COMMAND_RESULT',
+        results: resolved,
+        ...meta,
+        _meta_actions: resolved.some(r => r._meta_actions?.includes("REQUEST_CHAT_MODEL"))
+            ? ["REQUEST_CHAT_MODEL"]
+            : []
+    };
+};

package/templates/platform/agents/assistant/src/Events/onResponse.json

@@ -0,0 +1,3 @@
+{
+  "dependencies": {}
+}

package/templates/platform/agents/assistant/src/Frontend/contentRender.js

@@ -0,0 +1,26 @@
+import React from 'react';
+
+const onRenderChatMessage = async (params) => {
+    const { content, role } = params.messages[params.msgIndex];
+
+    // Hide tool messages
+    if (role === 'tool') {
+        return JSON.stringify({ type: 'HIDDEN_MESSAGE' });
+    }
+
+    return null; // Default rendering
+};
+
+const Header = ({ setRenderSettings }) => {
+    React.useEffect(() => {
+        setRenderSettings({
+            disableBalanceView: true
+        });
+    }, [setRenderSettings]);
+
+    return null;
+};
+
+const exports = { onRenderChatMessage, Header };
+window.contentRender = exports;
+export default exports;

package/templates/platform/agents/assistant/src/Frontend/contentRender.json

@@ -0,0 +1,10 @@
+{
+  "dependencies": {
+    "react": "^18.2.0 (fixed)",
+    "react-dom": "^18.2.0 (fixed)",
+    "@mui/material": "^5.16.1 (fixed)",
+    "@mui/icons-material": "^5.16.1 (fixed)",
+    "@emotion/react": "^11.10.6 (fixed)",
+    "@emotion/styled": "^11.10.6 (fixed)"
+  }
+}

package/templates/platform/functions/api/index.mjs

@@ -0,0 +1,69 @@
+/**
+ * Example API function for {{APP_NAME}} platform
+ *
+ * Endpoint: https://fn.openkbs.com/YOUR_KB_ID/api
+ *
+ * This function has access to:
+ * - process.env.POSTGRES_URL (if postgres enabled)
+ * - process.env.KB_ID (your whitelabel kbId)
+ */
+
+export const handler = async (event) => {
+    const body = JSON.parse(event.body || '{}');
+    const { action, data } = body;
+
+    // CORS headers
+    const headers = {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type'
+    };
+
+    // Handle preflight
+    if (event.httpMethod === 'OPTIONS') {
+        return { statusCode: 200, headers, body: '' };
+    }
+
+    try {
+        switch (action) {
+            case 'hello':
+                return {
+                    statusCode: 200,
+                    headers,
+                    body: JSON.stringify({
+                        message: 'Hello from {{APP_NAME}} API!',
+                        timestamp: new Date().toISOString(),
+                        input: data
+                    })
+                };
+
+            case 'health':
+                return {
+                    statusCode: 200,
+                    headers,
+                    body: JSON.stringify({
+                        status: 'healthy',
+                        kbId: process.env.KB_ID,
+                        hasPostgres: !!process.env.POSTGRES_URL
+                    })
+                };
+
+            default:
+                return {
+                    statusCode: 400,
+                    headers,
+                    body: JSON.stringify({
+                        error: 'Unknown action',
+                        availableActions: ['hello', 'health']
+                    })
+                };
+        }
+    } catch (error) {
+        return {
+            statusCode: 500,
+            headers,
+            body: JSON.stringify({ error: error.message })
+        };
+    }
+};

package/templates/platform/openkbs.json

@@ -0,0 +1,14 @@
+{
+  "elastic": {
+    "postgres": true,
+    "storage": true,
+    "pulse": true,
+    "functions": {
+      "api": {
+        "runtime": "nodejs22.x",
+        "memory": 512,
+        "timeout": 30
+      }
+    }
+  }
+}