openkbs 0.0.28 → 0.0.31

package/MODIFY.md

@@ -0,0 +1,83 @@
+#### HUMAN-DEFINED REQUIREMENTS
+
+Define any additional features, integrations, or behavior modifications
+
+#### HUMAN-DEFINED REQUIREMENTS END
+
+
+# OpenKBS Framework Technical Guide (For AI Coding Agents)
+
+This guide provides a brief overview of developing backend and frontend logic for your OpenKBS app/agent.
+
+## Project Structure Overview
+
+A typical OpenKBS project has the following key directories:
+
+*   **`src/`**: Contains your custom source code.
+    *   **`Events/`**: Houses backend event handlers.
+        *   `actions.js`: Often used for shared logic/tool definitions (does not have own NPM dependencies).
+        *   `onRequest.js`: Handles incoming user messages before LLM processing.
+        *   `onRequest.json`: NPM dependencies for `onRequest.js`.
+        *   `onResponse.js`: Handles LLM responses before sending to the user.
+        *   `onResponse.json`: NPM dependencies for `onResponse.js`.
+        *   `onPublicAPIRequest.js`: Handles unauthenticated public API calls.
+        *   `onPublicAPIRequest.json`: Dependencies for `onPublicAPIRequest.js`.
+        *   `onAddMessages.js`: Handles messages added via the `chatAddMessages` API.
+        *   `onAddMessages.json`: Dependencies for `onAddMessages.js`.
+    *   **`Frontend/`**: Contains frontend customization logic.
+        *   `contentRender.js`: Custom UI rendering for chat messages, headers, etc.
+        *   `contentRender.json`: NPM dependencies for `contentRender.js`.
+*   **`app/`**: Application-level configuration.
+    *   `settings.json`: Core application settings (model, vendor, etc.).
+    *   `instructions.txt`: Instructions for the LLM.
+    *   `icon.png`: Application icon.
+
+#### onRequest and onResponse Handlers
+
+The core of the OpenKBS backend framework revolves around the `onRequest` and `onResponse` event handlers.  
+These handlers act as middleware, intercepting messages before and after they are processed by the LLM.
+
+* **`onRequest` Handler:** This handler is invoked every time a user sends a message to the chat. It provides an opportunity to pre-process the user's input, extract commands and perform actions based on the user's message.
+
+* **`onResponse` Handler:** This handler is invoked after the LLM generates a response. It allows post-processing of the LLM's output, execution of commands based on the LLM's intentions.
+
+
+## Backend Dependencies
+
+To use external NPM packages in your backend event handlers, you must declare them in the corresponding `.json` file.
+OpenKBS also provides a secure way to handle sensitive information using the `{{secrets.your_secret_name}}` syntax.
+
+**Example: Using axios with an API key**
+
+1. **Declare dependencies** in both `src/Events/onRequest.json` and `src/Events/onResponse.json` (as each handler have separate build):
+    ```json
+    {
+      "dependencies": {
+        "axios": "^1.6.2"
+      }
+    }
+    ```
+
+2.  **Implement and use in `src/Events/actions.js`**:
+    ```javascript
+    import axios from 'axios';
+
+    export const getActions = (meta) => {
+        return [
+            [/\/?getNews\("(.*)"\)/, async (match) => {
+                const topic = match[1];
+                const response = await axios.get('https://newsapi.org/v2/everything', {
+                    params: {
+                        q: topic,
+                        apiKey: '{{secrets.news_api_key}}' // Securely injected at runtime
+                    }
+                });
+                return { result: response.data.articles, ...meta };
+            }],
+            // ... other actions
+        ];
+    };
+    ```
+## Secrets Management
+Define `news_api_key` in your application's secrets manager on the OpenKBS platform.
+The platform will inject the actual value at runtime, keeping your credentials secure while enabling you to make API calls with authenticated services.

package/README.md

@@ -23,6 +23,7 @@ deploy and integrate AI agents and applications.
         - [onAddMessages Event Handler](#onaddmessages-event-handler)
         - [Meta Actions](#meta-actions)
         - [SDK](#sdk)
+        - [Managing Secrets](#managing-secrets)
         - [Application Settings](#application-settings)
         - [LLM Instructions](#llm-instructions)
         - [Execution Environment](#execution-environment)
@@ -631,6 +632,17 @@ const encryptedValue = await openkbs.encrypt(userData);
 
 ```
 
+#### Managing Secrets
+To securely manage sensitive information like API keys or database passwords within your backend event handlers (`onRequest`, `onResponse`, etc.), use the `{{secrets.your_secret_name}}` syntax.
+
+Define the placeholder in your code:
+
+```javascript
+const apiKey = '{{secrets.external_api_key}}';
+const dbPassword = '{{secrets.db_password}}';
+```
+The actual values for `external_api_key` and `db_password` are set securely within the OpenKBS platform's file manager for your application. These values are injected at runtime and are never committed to your code repository, ensuring your secrets remain confidential.
+
 #### Application Settings
 `app/settings.json`
 

package/package.json

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

package/src/actions.js

@@ -3,6 +3,7 @@ const os = require('os');
 const path = require('path');
 const express = require('express');
 const { exec, execSync } = require('child_process');
+const https = require('https');
 
 const {
     fetchLocalKBData, fetchKBJWT, createAccountIdFromPublicKey, signPayload, getUserProfile, getKB,
@@ -359,6 +360,20 @@ async function deleteKBAction(kbId) {
 }
 
 async function modifyAction(prompt, files, options) {
+    // Check if MODIFY.md file exists in current directory
+    const modifyFilePath = path.join(process.cwd(), 'MODIFY.md');
+    const modifyFileExists = await fs.pathExists(modifyFilePath);
+    
+    // If MODIFY.md doesn't exist, download it first
+    if (!modifyFileExists) {
+        console.yellow('MODIFY.md file not found. Downloading it first...');
+        try {
+            await downloadModifyAction();
+        } catch (error) {
+            console.yellow('Could not download MODIFY.md, continuing without it...');
+        }
+    }
+    
     const { kbId } = await fetchLocalKBData();
     const {kbToken} = await fetchKBJWT(kbId);
     const kbData = await getKB(kbToken);
@@ -455,6 +470,43 @@ function installFrontendPackageAction(packageName) {
     }
 }
 
+async function downloadModifyAction() {
+    const url = 'https://raw.githubusercontent.com/open-kbs/openkbs/refs/heads/main/MODIFY.md';
+    const filePath = path.join(process.cwd(), 'MODIFY.md');
+    
+    console.log(`Downloading MODIFY.md template from GitHub...`);
+    
+    return new Promise((resolve, reject) => {
+        https.get(url, (response) => {
+            if (response.statusCode === 200) {
+                const file = fs.createWriteStream(filePath);
+                response.pipe(file);
+                
+                file.on('finish', () => {
+                    file.close();
+                    console.green(`Successfully downloaded MODIFY.md to ${filePath}`);
+                    resolve();
+                });
+                
+                file.on('error', (err) => {
+                    fs.unlink(filePath, () => {}); // Delete the file if there was an error
+                    console.red(`Error writing to file: ${err.message}`);
+                    reject(err);
+                });
+            } else if (response.statusCode === 404) {
+                console.red(`File not found at ${url}`);
+                reject(new Error('File not found'));
+            } else {
+                console.red(`Failed to download file. Status code: ${response.statusCode}`);
+                reject(new Error(`HTTP Status Code: ${response.statusCode}`));
+            }
+        }).on('error', (err) => {
+            console.red(`Error downloading file: ${err.message}`);
+            reject(err);
+        });
+    });
+}
+
 module.exports = {
     signAction,
     loginAction,
@@ -470,5 +522,6 @@ module.exports = {
     initByTemplateAction,
     logoutAction,
     installFrontendPackageAction,
-    modifyAction
+    modifyAction,
+    downloadModifyAction
 };

package/src/index.js

@@ -12,7 +12,7 @@ const {
     deleteKBAction,
     deleteFileAction,
     describeAction, deployAction, createByTemplateAction, initByTemplateAction,
-    logoutAction, installFrontendPackageAction, modifyAction
+    logoutAction, installFrontendPackageAction, modifyAction, downloadModifyAction
 } = require('./actions');
 
 
@@ -141,4 +141,16 @@ program
     .description('Log out from OpenKBS by deleting the locally stored session token.')
     .action(logoutAction);
 
+program
+    .command('init-modify')
+    .description('Download the latest MODIFY.md template from GitHub to help with KB modifications')
+    .action(downloadModifyAction)
+    .addHelpText('after', `
+Examples:
+  $ openkbs init-modify
+  
+This will download the MODIFY.md template file from the OpenKBS GitHub repository to your current directory.
+This file will be automatically included when you run the 'openkbs modify' command.
+`);
+
 program.parse(process.argv);

package/src/utils.js

@@ -311,6 +311,18 @@ async function modifyKB(kbToken, kbData, prompt, files, options) {
     const { kbId, key } = kbData;
     const url = options?.chatURL || CHAT_API_URL;
 
+    // Try to find and add MODIFY.md file
+    const modifyFilePath = path.join(process.cwd(), 'MODIFY.md');
+    let hasModifyFile = false;
+    
+    try {
+        if (await fs.pathExists(modifyFilePath)) {
+            hasModifyFile = true;
+        }
+    } catch (error) {
+        console.error('Error checking for MODIFY.md:', error);
+    }
+    
     if (!files || files.length === 0) {
         try {
             const srcFiles = await getAllFiles('./src');
@@ -321,6 +333,11 @@ async function modifyKB(kbToken, kbData, prompt, files, options) {
         }
     }
 
+    // Add MODIFY.md to files list if it exists
+    if (hasModifyFile && !files.includes(modifyFilePath)) {
+        files.unshift(modifyFilePath);
+    }
+
     const fileContents = await Promise.all(files.map(async (filePath) => {
         try {
             const content = await fs.readFile(filePath, 'utf8');