openkbs 0.0.82 → 0.0.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openkbs",
-  "version": "0.0.82",
+  "version": "0.0.83",
   "description": "OpenKBS - Command Line Interface",
   "main": "src/index.js",
   "scripts": {

package/src/actions.js

@@ -307,6 +307,63 @@ async function loginAction() {
     });
 }
 
+async function authAction(kbJWT) {
+    try {
+        // Decode JWT to validate format (without verification - that's done server-side)
+        const parts = kbJWT.split('.');
+        if (parts.length !== 3) {
+            return console.red('Invalid token format. Expected a JWT token.');
+        }
+
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64').toString());
+
+        // Basic validation
+        if (!payload.kbUserId || !payload.myUserId) {
+            return console.red('Invalid token. Missing required fields (kbUserId, myUserId).');
+        }
+
+        if (!payload.serverURL) {
+            return console.red('Invalid token. Missing serverURL field. Token must be from a hosted studio.');
+        }
+
+        if (payload.kbUserId !== payload.myUserId) {
+            return console.red('Only KB owners can use this command. The token must be from the KB owner.');
+        }
+
+        console.log(`Server: ${payload.serverURL}`);
+
+        console.log('Exchanging kbJWT for clientJWT...');
+
+        // Call lambda-auth to exchange the token
+        const response = await fetch('https://auth.openkbs.com/exchangeKbToken', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ token: kbJWT })
+        });
+
+        if (!response.ok) {
+            const error = await response.json();
+            return console.red(`Authentication failed: ${error.error || error.message || 'Unknown error'}`);
+        }
+
+        const data = await response.json();
+
+        if (!data.clientJWT) {
+            return console.red('Authentication failed: No clientJWT received.');
+        }
+
+        // Save the clientJWT
+        await fs.ensureDir(path.dirname(jwtPath));
+        await fs.writeFile(jwtPath, data.clientJWT, 'utf8');
+
+        console.green('Authentication successful! CLI is now authenticated.');
+        console.log('You can now use all OpenKBS CLI commands.');
+
+    } catch (error) {
+        console.red(`Authentication failed: ${error.message}`);
+    }
+}
+
 async function pullAction(location = 'origin', targetFile) {
     try {
         // Remove './' prefix if present
@@ -2759,6 +2816,7 @@ module.exports = {
     signAction,
     serviceAction,
     loginAction,
+    authAction,
     pullAction,
     pushAction,
     cloneAction,

package/src/index.js

@@ -6,6 +6,7 @@ const {
     signAction,
     serviceAction,
     loginAction,
+    authAction,
     pullAction,
     pushAction,
     cloneAction,
@@ -51,6 +52,11 @@ program
     .description('Login to OpenKBS and store session locally.')
     .action(loginAction);
 
+program
+    .command('auth <kbJWT>')
+    .description('Authenticate CLI using a kbJWT token (for container/CI environments)')
+    .action(authAction);
+
 program
     .command('create <app-name>')
     .description('Create a new KB application')

package/templates/.claude/skills/openkbs/metadata.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.9"
+  "version": "0.1.16"
 }

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

@@ -157,25 +157,72 @@ const uploadHtmlContent = async (htmlContent, filename) => {
 
 ## Frontend File Upload (contentRender.js)
 
+**IMPORTANT:** `openkbs` is passed as a **prop** to components - it's NOT global!
+
 ```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;
-    }
+// File upload button component - receives openkbs as prop
+const FileUploadButton = ({ openkbs, setSystemAlert }) => {
+    const [uploading, setUploading] = useState(false);
+    const [progress, setProgress] = useState(0);
+    const fileInputRef = useRef(null);
+
+    const handleUpload = async (e) => {
+        const file = e.target.files?.[0];
+        if (!file) return;
+
+        setUploading(true);
+        try {
+            // Upload file to storage with progress callback
+            await openkbs.Files.uploadFileAPI(file, 'files', (percent) => {
+                setProgress(percent);
+            });
+
+            setSystemAlert?.({ severity: 'success', message: `Uploaded ${file.name}` });
+        } catch (error) {
+            setSystemAlert?.({ severity: 'error', message: error.message });
+        } finally {
+            setUploading(false);
+            setProgress(0);
+        }
+    };
+
+    return (
+        <div>
+            <button onClick={() => fileInputRef.current?.click()} disabled={uploading}>
+                {uploading ? `Uploading ${progress}%` : 'Upload File'}
+            </button>
+            <input
+                ref={fileInputRef}
+                type="file"
+                onChange={handleUpload}
+                style={{ display: 'none' }}
+            />
+        </div>
+    );
+};
+
+// Header must pass openkbs to child components
+const Header = ({ setRenderSettings, openkbs, setSystemAlert }) => {
+    return (
+        <div>
+            <FileUploadButton openkbs={openkbs} setSystemAlert={setSystemAlert} />
+        </div>
+    );
 };
+```
 
-// List files
+### Other Files API Methods
+
+```javascript
+// List files (inside a component that receives openkbs as prop)
 const files = await openkbs.Files.listFiles('files');
-// Returns: [{ Key: 'files/kbId/filename.jpg', Size: 12345 }]
+// Returns: [{ Key: 'files/kbId/filename.jpg', Size: 12345, LastModified }]
 
 // Delete file
 await openkbs.Files.deleteRawKBFile('filename.jpg', 'files');
+
+// Rename file
+await openkbs.Files.renameFile('old.jpg', 'new.jpg', 'files');
 ```
 
 ## instructions.txt (LLM prompt)

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

@@ -364,43 +364,197 @@ await axios.put(presignedUrl, fileBuffer, {
 
 ## VectorDB (Semantic Search)
 
-### items() - VectorDB Operations
+### items() - Create Items with Filterable Attributes
 
-Create and search items with embeddings for semantic search.
+For filtering to work, items must be created with filterable attributes (keyword, integer, boolean, etc.).
 
 ```javascript
-// Create embeddings first
+// 1. Create embeddings from content
 const { embeddings, totalTokens } = await openkbs.createEmbeddings(
-    'text to embed',
-    'text-embedding-3-large'  // 3072 dimensions
+    'Fix login bug - users cannot login with SSO',
+    'text-embedding-3-large'
 );
 
-// Create item with embeddings
+// 2. Create item with filterable attributes
 await openkbs.items({
     action: 'createItem',
-    itemType: 'archive',
-    itemId: 'archive_doc_123',
+    itemType: 'task',
+    itemId: `task_${Date.now()}`,
     attributes: [
         { attrType: 'itemId', attrName: 'itemId', encrypted: false },
-        { attrType: 'body', attrName: 'body', encrypted: true }
+        { attrType: 'body', attrName: 'body', encrypted: true },
+        // Filterable attributes - map user-friendly names to generic types
+        { attrType: 'keyword1', attrName: 'category', encrypted: false },
+        { attrType: 'keyword2', attrName: 'status', encrypted: false },
+        { attrType: 'integer1', attrName: 'priority', encrypted: false },
+        { attrType: 'boolean1', attrName: 'isUrgent', encrypted: false }
     ],
-    item: { body: await openkbs.encrypt(JSON.stringify(data)) },
+    item: {
+        body: await openkbs.encrypt(JSON.stringify({
+            title: 'Fix login bug',
+            description: 'Users cannot login with SSO'
+        })),
+        // Filterable field values
+        category: 'bug',
+        status: 'open',
+        priority: 1,
+        isUrgent: true
+    },
     totalTokens,
     embeddings: embeddings.slice(0, 3072),
     embeddingModel: 'text-embedding-3-large',
     embeddingDimension: 3072
 });
+```
+
+### Filterable Attribute Types
+
+| attrType | S3 Vectors Type | Operators |
+|----------|-----------------|-----------|
+| keyword1-20 | String | $eq, $ne, $in, $nin |
+| text1-20 | String | $eq, $ne, $in, $nin |
+| integer1-20 | Number | $eq, $ne, $gt, $gte, $lt, $lte |
+| float1-20 | Number | $eq, $ne, $gt, $gte, $lt, $lte |
+| boolean1-9 | Boolean | $eq, $ne |
+| date1-9 | Number | $gt, $gte, $lt, $lte |
+
+### Vector Metadata Limits
 
-// Semantic search
+S3 Vectors has two types of metadata:
+- **Filterable** (keyword1, integer1, etc.): 2KB limit - used for filtering in queries
+- **Non-filterable** (itemData): 40KB limit - stored for retrieval only
+
+By default, `itemData` is configured as non-filterable, so full item content (up to 40KB) is stored and returned in search results.
+
+### vectorMetadata - Optional Override (Advanced)
+
+For items > 40KB, use `vectorMetadata` to control what gets stored in S3 Vectors. The full item is always stored in DynamoDB.
+
+```javascript
+// Very large document (> 40KB) - store only essential fields in vector
+await openkbs.items({
+    action: 'createItem',
+    itemType: 'document',
+    itemId: `doc_${Date.now()}`,
+    attributes: [...],
+    item: {
+        body: JSON.stringify({ fileName, fileUrl, hugeText }), // Full in DynamoDB
+        standard: 'IFS'
+    },
+    // Only these fields in S3 Vectors (for items > 40KB)
+    vectorMetadata: {
+        standard: 'IFS',
+        fileName: 'large-doc.pdf',
+        textPreview: hugeText.substring(0, 5000)
+    },
+    totalTokens,
+    embeddings,
+    embeddingModel: 'text-embedding-3-large',
+    embeddingDimension: 3072
+});
+```
+
+**Note**: For most use cases (items < 40KB), `vectorMetadata` is not needed.
+
+### searchVectorDBItems - Vector Search with Filter
+
+```javascript
+// Simple search (no filter)
 const results = await openkbs.items({
     action: 'searchVectorDBItems',
-    queryText: 'find similar documents',
-    topK: 10,
-    minScore: 0
+    queryText: 'login issues',
+    topK: 10
 });
 
-// Results: { items: [{ itemId, body, score }, ...] }
-// Note: body is encrypted, use openkbs.decrypt() to read
+// Search with filter - use user-friendly field names
+const filtered = await openkbs.items({
+    action: 'searchVectorDBItems',
+    queryText: 'login authentication issues',
+    topK: 20,
+    minScore: 70,
+    itemType: 'task',  // Required for filter translation!
+    filter: {
+        category: 'bug',
+        status: 'open'
+    }
+});
+
+// Comparison operators
+const highPriority = await openkbs.items({
+    action: 'searchVectorDBItems',
+    queryText: 'performance problems',
+    itemType: 'task',
+    filter: {
+        priority: { "$lte": 2 },
+        status: { "$ne": "done" }
+    }
+});
+
+// Complex filter with $or
+const urgentOrHighPriority = await openkbs.items({
+    action: 'searchVectorDBItems',
+    queryText: 'critical issues',
+    itemType: 'task',
+    filter: {
+        "$or": [
+            { priority: 1 },
+            { isUrgent: true }
+        ]
+    }
+});
+
+// $in operator - match any value in array
+const multipleCats = await openkbs.items({
+    action: 'searchVectorDBItems',
+    queryText: 'issues',
+    itemType: 'task',
+    filter: {
+        category: { "$in": ["bug", "hotfix"] },
+        status: { "$nin": ["done", "cancelled"] }
+    }
+});
+```
+
+### Response Format
+
+```javascript
+{
+    items: [
+        {
+            itemId: 'task_1705123456789',
+            body: 'encrypted...',       // Use openkbs.decrypt()
+            category: 'bug',            // Filterable fields returned
+            status: 'open',
+            priority: 1,
+            isUrgent: true,
+            score: 0.92,                // Similarity score (0-1)
+            distance: 0.08,
+            totalTokens: 45
+        }
+    ]
+}
+```
+
+### settings.json - itemTypes Configuration
+
+Define attribute mappings in KB settings for automatic filter translation:
+
+```json
+{
+    "itemTypes": {
+        "task": {
+            "attributes": [
+                { "attrName": "itemId", "attrType": "itemId", "encrypted": false },
+                { "attrName": "body", "attrType": "body", "encrypted": true },
+                { "attrName": "category", "attrType": "keyword1", "encrypted": false },
+                { "attrName": "status", "attrType": "keyword2", "encrypted": false },
+                { "attrName": "priority", "attrType": "integer1", "encrypted": false },
+                { "attrName": "isUrgent", "attrType": "boolean1", "encrypted": false }
+            ],
+            "embeddingTemplate": "${item.body.title} ${item.body.description}"
+        }
+    }
+}
 ```
 
 ## Utilities

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

@@ -61,10 +61,10 @@ return JSON.stringify({ type: 'HIDDEN_MESSAGE' });
 
 ## Header Component
 
-Customize the chat header:
+Customize the chat header. **Important:** Receive `openkbs` and `setSystemAlert` as props!
 
 ```javascript
-const Header = ({ setRenderSettings }) => {
+const Header = ({ setRenderSettings, openkbs, setSystemAlert }) => {
     useEffect(() => {
         setRenderSettings({
             disableShareButton: true,
@@ -72,10 +72,99 @@ const Header = ({ setRenderSettings }) => {
         });
     }, [setRenderSettings]);
 
+    // Now you can use openkbs.Files, openkbs.createItem, etc.
+    // Pass openkbs to child components that need it
+
     return <div>Custom Header</div>;
 };
 ```
 
+### Available Header Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `setRenderSettings` | function | Configure UI options |
+| `openkbs` | object | SDK object with Files, createItem, etc. |
+| `setSystemAlert` | function | Show alerts: `{ severity: 'success'/'error', message }` |
+| `setBlockingLoading` | function | Show/hide loading overlay |
+
+### Render Settings Options
+
+Configure UI behavior via `setRenderSettings()`:
+
+```javascript
+setRenderSettings({
+    // UI toggles
+    disableShareButton: true,
+    disableBalanceView: true,
+    disableChatModelsSelect: true,
+    disableEmojiButton: true,
+    disableCodeExecuteButton: true,
+    disableSentLabel: true,
+    disableChatAvatar: true,
+    disableAutoscroll: true,
+    disableInitialScroll: true,
+    disableAutoFocusChatInput: true,
+    disableContextItems: true,
+    disableCopyButton: true,
+    disableTextToSpeechButton: true,
+    disablePushNotificationsButton: true,
+    disableMultichat: true,
+    disableImageUploadText: true,
+
+    // Layout
+    setMessageWidth: () => '85%',
+    chatContainerHeight: 600,
+    backgroundOpacity: 0.5,
+
+    // Behavior
+    inputLabelsQuickSend: true,        // Quick send on label click
+    chatTimeoutMs: 30000,              // Chat timeout in ms
+    onChatTimeout: () => {},           // Callback on timeout
+
+    // Message transform hook
+    onBeforeSendMessage: (message) => message,
+
+    // Custom components
+    sendIcon: () => <span>Send</span>,
+    formatMessageTime: (timestamp) => '...'
+});
+```
+
+### onBeforeSendMessage Hook
+
+Transform user messages before sending to the LLM. Useful for adding prefixes, filters, or modifying content.
+
+```javascript
+const Header = ({ setRenderSettings, openkbs }) => {
+    const [filter, setFilter] = useState('all');
+
+    useEffect(() => {
+        setRenderSettings({
+            onBeforeSendMessage: (message) => {
+                // Add prefix based on filter selection
+                if (filter === 'all') return message;
+                return `[Category: ${filter}] ${message}`;
+            }
+        });
+    }, [setRenderSettings, filter]);
+
+    return (
+        <select value={filter} onChange={(e) => setFilter(e.target.value)}>
+            <option value="all">All</option>
+            <option value="tech">Tech</option>
+            <option value="sales">Sales</option>
+        </select>
+    );
+};
+```
+
+**Use cases:**
+- Add category/filter prefixes to messages
+- Inject context or metadata
+- Transform or sanitize user input
+- Add routing hints for the LLM
+
 ## Command Rendering Pattern
 
 Define commands with icons:
@@ -205,7 +294,21 @@ The `(fixed)` suffix indicates built-in libraries that don't need bundling.
 
 ## Frontend openkbs Object
 
-The `openkbs` object is available globally in frontend code.
+**IMPORTANT:** The `openkbs` object is passed as a **prop** to Header and other components - it is NOT a global variable.
+
+```javascript
+// CORRECT - receive openkbs as prop
+const Header = ({ setRenderSettings, openkbs, setSystemAlert }) => {
+    // Now you can use openkbs.Files, openkbs.createItem, etc.
+};
+
+// WRONG - openkbs is not global in frontend
+const Header = ({ setRenderSettings }) => {
+    await openkbs.Files.listFiles(); // ERROR: openkbs is undefined
+};
+```
+
+Always destructure `openkbs` from props before using it.
 
 ### Item CRUD
 

package/version.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.82",
-  "releaseDate": "2026-01-20",
-  "releaseNotes": "OpenKBS CLI version 0.0.82"
+  "version": "0.0.83",
+  "releaseDate": "2026-01-26",
+  "releaseNotes": "OpenKBS CLI version 0.0.83"
 }