openkbs 0.0.66 → 0.0.70

package/templates/.claude/skills/openkbs/patterns/file-upload.md

@@ -0,0 +1,205 @@
+# File Upload Pattern
+
+Complete working code for uploading files to KB storage using presigned URLs.
+
+## actions.js
+
+```javascript
+// Upload files from URLs to permanent storage
+[/<uploadFiles>([\s\S]*?)<\/uploadFiles>/s, async (match) => {
+    try {
+        const content = match[1].trim();
+
+        // Parse URLs - support newline-separated or JSON array
+        let fileUrls = [];
+        try {
+            const parsed = JSON.parse(content);
+            if (Array.isArray(parsed)) fileUrls = parsed;
+        } catch (e) {
+            // Not JSON, treat as newline-separated URLs
+            fileUrls = content
+                .split('\n')
+                .map(line => line.trim())
+                .filter(line => line.startsWith('http'));
+        }
+
+        if (fileUrls.length === 0) {
+            return { error: 'No valid URLs found', ...meta };
+        }
+
+        const uploadResults = [];
+
+        for (let i = 0; i < fileUrls.length; i++) {
+            const fileUrl = fileUrls[i];
+
+            try {
+                // 1. Fetch the file
+                const fileResponse = await axios.get(fileUrl, { responseType: 'arraybuffer' });
+                const fileBuffer = fileResponse.data;
+
+                // 2. Determine filename and content type
+                const urlPath = new URL(fileUrl).pathname;
+                let filename = urlPath.split('/').pop();
+
+                // Generate filename if none
+                if (!filename || !filename.includes('.')) {
+                    const contentType = fileResponse.headers['content-type'] || 'application/octet-stream';
+                    const extMap = {
+                        'image/jpeg': 'jpg', 'image/png': 'png', 'image/gif': 'gif',
+                        'image/webp': 'webp', 'video/mp4': 'mp4', 'application/pdf': 'pdf'
+                    };
+                    const ext = extMap[contentType] || 'bin';
+                    filename = `file_${i + 1}.${ext}`;
+                }
+
+                // Add timestamp for uniqueness
+                const timestamp = Date.now();
+                const parts = filename.split('.');
+                const ext = parts.pop();
+                filename = `${parts.join('.')}_${timestamp}.${ext}`;
+
+                const contentType = fileResponse.headers['content-type'] || 'application/octet-stream';
+
+                // 3. Get presigned URL
+                const presignedUrl = await openkbs.kb({
+                    action: 'createPresignedURL',
+                    namespace: 'files',
+                    fileName: filename,
+                    fileType: contentType,
+                    presignedOperation: 'putObject'
+                });
+
+                // 4. Upload to S3
+                await axios.put(presignedUrl, fileBuffer, {
+                    headers: {
+                        'Content-Type': contentType,
+                        'Content-Length': fileBuffer.length
+                    }
+                });
+
+                // 5. Construct public URL
+                const publicUrl = `https://yourdomain.com/media/${filename}`;
+
+                uploadResults.push({
+                    sourceUrl: fileUrl,
+                    status: 'success',
+                    uploadedUrl: publicUrl,
+                    filename,
+                    size: fileBuffer.length
+                });
+
+            } catch (error) {
+                uploadResults.push({
+                    sourceUrl: fileUrl,
+                    status: 'failed',
+                    error: error.message
+                });
+            }
+        }
+
+        const successCount = uploadResults.filter(r => r.status === 'success').length;
+
+        return {
+            type: "FILES_UPLOADED",
+            summary: `Uploaded ${successCount} of ${fileUrls.length} files`,
+            results: uploadResults,
+            uploadedUrls: uploadResults.filter(r => r.status === 'success').map(r => r.uploadedUrl),
+            ...meta
+        };
+
+    } catch (e) {
+        return { error: e.message, ...meta };
+    }
+}]
+```
+
+## Direct Image Upload (from generateImage)
+
+```javascript
+// Helper 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
+    };
+};
+```
+
+## HTML/Text Upload
+
+```javascript
+// Upload HTML content
+const uploadHtmlContent = async (htmlContent, filename) => {
+    // Get presigned URL
+    const presignedUrl = await openkbs.kb({
+        action: 'createPresignedURL',
+        namespace: 'files',
+        fileName: filename,
+        fileType: 'text/html',
+        presignedOperation: 'putObject'
+    });
+
+    // Upload as UTF-8 Buffer
+    const htmlBuffer = Buffer.from(htmlContent, 'utf8');
+    await axios.put(presignedUrl, htmlBuffer, {
+        headers: {
+            'Content-Type': 'text/html',
+            'Content-Length': htmlBuffer.length
+        }
+    });
+
+    return `https://yourdomain.com/media/${filename}`;
+};
+```
+
+## Frontend File Upload (contentRender.js)
+
+```javascript
+// Using openkbs.Files API in frontend
+const handleFileUpload = async (file, onProgress) => {
+    try {
+        await openkbs.Files.uploadFileAPI(file, 'files', onProgress);
+        const publicUrl = `https://yourdomain.com/media/${file.name}`;
+        return publicUrl;
+    } catch (error) {
+        console.error('Upload failed:', error);
+        throw error;
+    }
+};
+
+// List files
+const files = await openkbs.Files.listFiles('files');
+// Returns: [{ Key: 'files/kbId/filename.jpg', Size: 12345 }]
+
+// Delete file
+await openkbs.Files.deleteRawKBFile('filename.jpg', 'files');
+```
+
+## instructions.txt (LLM prompt)
+
+```
+File Upload:
+
+Upload files from URLs:
+<uploadFiles>
+https://example.com/image1.jpg
+https://example.com/document.pdf
+</uploadFiles>
+
+Or as JSON array:
+<uploadFiles>["https://example.com/file1.jpg", "https://example.com/file2.png"]</uploadFiles>
+
+Files are stored permanently and accessible via CDN.
+```
+
+## Key Points
+
+1. **Presigned URL flow**: Get URL → Upload to S3 → Construct public URL
+2. **CDN access**: Files accessible at `yourdomain.com/media/filename`
+3. **Content-Type matters**: Set correct MIME type for proper serving
+4. **Buffer for text**: Use `Buffer.from(content, 'utf8')` for text/HTML
+5. **Timestamps**: Add to filename for uniqueness
+6. **openkbs.uploadImage**: Shortcut for base64 image upload

package/templates/.claude/skills/openkbs/patterns/image-generation.md

@@ -0,0 +1,139 @@
+# Image Generation Pattern
+
+Complete working code for AI image generation with proper upload and display.
+
+## actions.js
+
+```javascript
+// Helper - reuse across all image generation commands
+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',  // Core magic type - renders image in chat
+        data: { imageUrl: uploadResult.url },
+        ...meta
+    };
+};
+
+// Command handler
+[/<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 };
+
+        // Gemini-specific params
+        if (model.includes('gemini')) {
+            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';
+            if (data.imageUrls?.length > 0) params.imageUrls = data.imageUrls;
+        }
+
+        // GPT-specific params
+        if (model.includes('gpt')) {
+            const validSizes = ['1024x1024', '1536x1024', '1024x1536', 'auto'];
+            params.size = validSizes.includes(data.size) ? data.size : '1024x1024';
+            params.quality = 'high';
+        }
+
+        const images = await openkbs.generateImage(data.prompt, params);
+        return await uploadGeneratedImage(images[0].b64_json, meta);
+    } catch (error) {
+        return { error: error.message || 'Image creation failed', ...meta };
+    }
+}]
+```
+
+## contentRender.js
+
+```javascript
+import ImageWithDownload from './ImageWithDownload';
+
+// In isVisualResult function
+const isVisualResult = (r) => {
+    return (r?.type === 'CHAT_IMAGE' && r?.data?.imageUrl);
+};
+
+// In renderVisualResults function
+if (item?.type === 'CHAT_IMAGE' && item?.data?.imageUrl) {
+    return (
+        <div key={`img-${idx}`} style={{ flex: '1 1 calc(50% - 6px)', minWidth: 200, maxWidth: 400 }}>
+            <ImageWithDownload imageUrl={item.data.imageUrl} />
+        </div>
+    );
+}
+```
+
+## ImageWithDownload.js Component
+
+```javascript
+import React from 'react';
+import { IconButton, Box } from '@mui/material';
+import DownloadIcon from '@mui/icons-material/Download';
+
+const ImageWithDownload = ({ imageUrl }) => {
+    const handleDownload = async () => {
+        try {
+            const response = await fetch(imageUrl);
+            const blob = await response.blob();
+            const url = window.URL.createObjectURL(blob);
+            const a = document.createElement('a');
+            a.href = url;
+            a.download = `image-${Date.now()}.png`;
+            document.body.appendChild(a);
+            a.click();
+            document.body.removeChild(a);
+            window.URL.revokeObjectURL(url);
+        } catch (error) {
+            console.error('Download failed:', error);
+        }
+    };
+
+    return (
+        <Box sx={{ position: 'relative', display: 'inline-block' }}>
+            <img
+                src={imageUrl}
+                alt="Generated"
+                style={{ maxWidth: '100%', borderRadius: 8 }}
+            />
+            <IconButton
+                onClick={handleDownload}
+                sx={{
+                    position: 'absolute',
+                    top: 8,
+                    right: 8,
+                    backgroundColor: 'rgba(255,255,255,0.9)',
+                    '&:hover': { backgroundColor: 'white' }
+                }}
+            >
+                <DownloadIcon />
+            </IconButton>
+        </Box>
+    );
+};
+
+export default ImageWithDownload;
+```
+
+## instructions.txt (LLM prompt)
+
+```
+To generate an image:
+<createAIImage>{"prompt": "detailed description", "model": "gemini-2.5-flash-image", "aspect_ratio": "16:9"}</createAIImage>
+
+Models:
+- gemini-2.5-flash-image: General images, supports editing with imageUrls
+- gpt-image-1: Better for text in images
+
+Gemini params: aspect_ratio (1:1, 16:9, 9:16, etc.), imageUrls (for editing)
+GPT params: size (1024x1024, 1536x1024, 1024x1536)
+```
+
+## Key Points
+
+1. **Always use helper** - `uploadGeneratedImage` converts base64 → URL → CHAT_IMAGE
+2. **CHAT_IMAGE is core magic** - OpenKBS renders it automatically as image
+3. **Spread ...meta** - Preserves message context for proper rendering
+4. **Error handling** - Return error object with ...meta, not throw

package/templates/.claude/skills/openkbs/patterns/memory-system.md

@@ -0,0 +1,264 @@
+# Memory System Pattern
+
+Complete working code for memory CRUD operations with atomic updates.
+
+## memoryHelpers.js
+
+Create this file for reusable memory operations:
+
+```javascript
+// Memory Helpers - Atomic operations without race conditions
+
+/**
+ * Generic upsert (update or create)
+ */
+async function _upsertItem(itemType, itemId, body) {
+    try {
+        await openkbs.updateItem({ itemType, itemId, body });
+    } catch (e) {
+        await openkbs.createItem({ itemType, itemId, body });
+    }
+    return { success: true, itemId };
+}
+
+/**
+ * Set a memory value atomically
+ * @param {string} itemId - Must start with "memory_"
+ * @param {*} value - Any JSON-serializable value
+ * @param {number} expirationInMinutes - Optional expiration
+ */
+export async function setMemoryValue(itemId, value, expirationInMinutes = null) {
+    if (!itemId.startsWith('memory_')) {
+        throw new Error(`Invalid itemId: "${itemId}". Must start with "memory_"`);
+    }
+
+    const body = {
+        value,
+        updatedAt: new Date().toISOString()
+    };
+
+    if (expirationInMinutes != null) {
+        body.exp = new Date(Date.now() + expirationInMinutes * 60 * 1000).toISOString();
+    }
+
+    return _upsertItem('memory', itemId, body);
+}
+
+/**
+ * Delete any item by itemId
+ */
+export async function deleteItem(itemId) {
+    try {
+        await openkbs.deleteItem(itemId);
+        return { success: true };
+    } catch (e) {
+        return { success: false, error: e.message };
+    }
+}
+
+/**
+ * Set agent setting (for configuration that persists)
+ */
+export async function setAgentSetting(itemId, value) {
+    if (!itemId.startsWith('agent_')) {
+        itemId = `agent_${itemId}`;
+    }
+    return _upsertItem('agent', itemId, { value, updatedAt: new Date().toISOString() });
+}
+
+/**
+ * Get agent setting
+ */
+export async function getAgentSetting(itemId) {
+    try {
+        const item = await openkbs.getItem(itemId);
+        return item?.item?.body?.value;
+    } catch (e) {
+        return null;
+    }
+}
+```
+
+## actions.js
+
+```javascript
+import { setMemoryValue, deleteItem } from './memoryHelpers.js';
+
+// Set memory command
+[/<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"]
+            };
+        }
+
+        await setMemoryValue(data.itemId, data.value, data.expirationInMinutes);
+
+        return {
+            type: "MEMORY_UPDATED",
+            itemId: data.itemId,
+            expires: data.expirationInMinutes ? `in ${data.expirationInMinutes} minutes` : 'never',
+            _meta_actions: ["REQUEST_CHAT_MODEL"]
+        };
+    } catch (e) {
+        return {
+            type: "MEMORY_ERROR",
+            error: e.message,
+            _meta_actions: ["REQUEST_CHAT_MODEL"]
+        };
+    }
+}],
+
+// Delete item command
+[/<deleteItem>([\s\S]*?)<\/deleteItem>/s, async (match) => {
+    try {
+        const data = JSON.parse(match[1].trim());
+        const result = await deleteItem(data.itemId);
+
+        if (!result.success) {
+            return {
+                type: "DELETE_ERROR",
+                error: result.error || "Failed to delete item",
+                _meta_actions: ["REQUEST_CHAT_MODEL"]
+            };
+        }
+
+        return {
+            type: "ITEM_DELETED",
+            itemId: data.itemId,
+            _meta_actions: ["REQUEST_CHAT_MODEL"]
+        };
+    } catch (e) {
+        return {
+            type: "DELETE_ERROR",
+            error: e.message,
+            _meta_actions: ["REQUEST_CHAT_MODEL"]
+        };
+    }
+}]
+```
+
+## onRequest.js - Inject Memory into Context
+
+```javascript
+export const handler = async (event) => {
+    // Fetch all memory items to inject into LLM context
+    const memoryItems = await openkbs.fetchItems({
+        itemType: 'memory',
+        beginsWith: 'memory_',
+        limit: 100
+    });
+
+    // Format for context injection
+    let memoryContext = '';
+    if (memoryItems?.items?.length > 0) {
+        memoryContext = '\n\n## Current Memory State:\n';
+        for (const { meta, item } of memoryItems.items) {
+            const value = typeof item.body.value === 'string'
+                ? item.body.value
+                : JSON.stringify(item.body.value);
+            memoryContext += `- ${meta.itemId}: ${value}\n`;
+        }
+    }
+
+    // Inject into system message
+    return {
+        ...event,
+        payload: {
+            ...event.payload,
+            messages: event.payload.messages.map((msg, idx) => {
+                if (idx === 0 && msg.role === 'system') {
+                    return { ...msg, content: msg.content + memoryContext };
+                }
+                return msg;
+            })
+        }
+    };
+};
+```
+
+## instructions.txt (LLM prompt)
+
+```
+Memory Commands:
+
+Save to memory:
+<setMemory>{"itemId": "memory_user_preference", "value": "dark mode"}</setMemory>
+
+Save with expiration (60 minutes):
+<setMemory>{"itemId": "memory_session_data", "value": {...}, "expirationInMinutes": 60}</setMemory>
+
+Delete item:
+<deleteItem>{"itemId": "memory_old_data"}</deleteItem>
+
+Memory items are automatically loaded into your context. Check "Current Memory State" section.
+```
+
+## settings.json - Priority Items Configuration
+
+Priority items are **automatically injected** into LLM context without needing onRequest.js:
+
+```json
+{
+  "model": "gemini-3-pro",
+  "embeddingModel": "text-embedding-3-large",
+  "embeddingDimension": 3072,
+  "searchEngine": "VectorDB",
+  "itemTypes": {
+    "memory": {
+      "attributes": [
+        { "attrName": "itemId", "attrType": "itemId", "encrypted": false },
+        { "attrName": "body", "attrType": "body", "encrypted": true }
+      ]
+    },
+    "archive": {
+      "attributes": [
+        { "attrName": "itemId", "attrType": "itemId", "encrypted": false },
+        { "attrName": "body", "attrType": "body", "encrypted": true }
+      ]
+    }
+  },
+  "options": {
+    "priorityItems": [
+      { "limit": 100, "prefix": "memory" },
+      { "limit": 50, "prefix": "agent" }
+    ],
+    "vectorDBMaxTokens": 25000,
+    "vectorDBTopK": 30,
+    "vectorDBMinScore": 90
+  }
+}
+```
+
+### How Priority Items Work
+
+1. **Auto-injection** - Items matching prefix are automatically added to LLM context
+2. **No onRequest.js needed** - OpenKBS core handles this
+3. **Limit per prefix** - Control how many items are injected
+4. **Multiple prefixes** - Can have memory_, agent_, telegram_, etc.
+
+### VectorDB for Long-term Memory
+
+For semantic search (archive), configure:
+- `searchEngine: "VectorDB"` - Enable vector search
+- `embeddingModel` - Which model to use for embeddings
+- `embeddingDimension` - Must match model (3072 for text-embedding-3-large)
+- `vectorDBTopK` - How many results to return
+- `vectorDBMinScore` - Minimum similarity score (0-100)
+
+## Key Points
+
+1. **Prefix requirement** - All memory items must start with `memory_`
+2. **Upsert pattern** - Try update first, create if fails (handles both new and existing)
+3. **Expiration** - Use `exp` field with ISO timestamp for auto-cleanup
+4. **Auto-encryption** - Body is encrypted automatically by OpenKBS
+5. **REQUEST_CHAT_MODEL** - Memory operations continue LLM loop for confirmation
+6. **Priority items** - Configure in settings.json for auto-injection into context
+7. **Two storage types**:
+   - **Priority items** (memory_, agent_) - Fast key-value, auto-injected
+   - **VectorDB items** (archive_) - Semantic search, for long-term memory