@semantictools/ai-toolbox 0.1.0 → 0.1.1

package/README.md

@@ -756,6 +756,81 @@ See the [examples](./examples) directory for complete working examples using the
 **Built-in Translator:**
 The `atfunc` translator is included as a built-in and can be used via the `TRANSLATOR_ATFUNC` constant or by name (`'atfunc'`). See the source at [src/translators/atfunc.mjs](./src/translators/atfunc.mjs).
 
+## Standard Toolboxes
+
+The package includes ready-to-use standard toolboxes that you can import and register:
+
+### File Toolbox
+
+A secure file operations toolbox that provides sandboxed access to a configured root folder.
+
+**Features:**
+- Operates within a configured root folder (prevents directory traversal)
+- Two setup methods: `.filetb` file (beginners) or programmatic (production with custom settings)
+- Support for basic file operations: read, write, delete, list, mkdir, rmdir
+
+**Setup (Beginner - using .filetb file):**
+
+```javascript
+import { register, setRootToolBox } from '@semantictools/ai-toolbox';
+import { fileToolbox, initialize } from '@semantictools/ai-toolbox/src/toolboxes/file.mjs';
+
+// 1. Create a .filetb config file with your root folder path
+// echo "/path/to/your/folder" > .filetb
+
+// 2. Initialize the file toolbox
+await initialize(); // Reads .filetb from current directory
+
+// 3. Register the toolbox
+register(fileToolbox);
+setRootToolBox('file');
+```
+
+**Setup (custom - programmatic):**
+
+```javascript
+import { register, setRootToolBox } from '@semantictools/ai-toolbox';
+import { fileToolbox, setRootFolder } from '@semantictools/ai-toolbox/src/toolboxes/file.mjs';
+
+// No .filetb file needed!
+const dataDir = process.env.DATA_DIR || '/var/app/data';
+await setRootFolder(dataDir);
+
+register(fileToolbox);
+setRootToolBox('file');
+```
+
+**Available Functions:**
+
+- `file.readfile(filepath)` - Read file contents
+- `file.writefile(filepath, content)` - Write content to file
+- `file.deletefile(filepath)` - Delete a file
+- `file.listfiles(subdir?)` - List files and directories (optional subdirectory)
+- `file.mkdir(dirpath)` - Create a directory
+- `file.rmdir(dirpath)` - Remove an empty directory
+
+**Example:**
+
+```javascript
+// Read a file
+const content = await call('readfile', {
+  filepath: { value: 'docs/readme.txt' }
+});
+
+// Write a file
+await call('writefile', {
+  filepath: { value: 'output/results.txt' },
+  content: { value: 'Processing complete!' }
+});
+
+// List files
+const files = await call('listfiles', {
+  subdir: { value: 'data' }
+});
+```
+
+See [examples/file-toolbox.mjs](./examples/file-toolbox.mjs) for a complete example.
+
 ## Use Cases
 
 - **AI Function Calling**: Provide tools for Claude, GPT, or other AI models

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semantictools/ai-toolbox",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "A flexible tool manager for managing and executing AI function calling toolboxes",
   "main": "src/toolmanager.mjs",
   "type": "module",
@@ -32,6 +32,7 @@
   "files": [
     "src",
     "src/translators",
+    "src/toolboxes",
     "README.md",
     "LICENSE"
   ]

package/src/toolboxes/README.md

@@ -0,0 +1,128 @@
+# Standard Toolboxes
+
+This directory contains ready-to-use standard toolboxes that implement common functionality following the ai-toolbox interface standard.
+
+## Available Toolboxes
+
+### File Toolbox (`file.mjs`)
+
+Provides secure file operations within a configured root folder.
+
+**Domain:** `file`
+
+**Configuration:**
+- Reads root folder path from `.filetb` file
+- Must call `initialize()` before registering the toolbox
+- All file paths are relative to the configured root folder
+- Security: Prevents directory traversal attacks
+
+**Functions:**
+- `readfile(filepath)` - Read file contents
+- `writefile(filepath, content)` - Write content to file
+- `deletefile(filepath)` - Delete a file
+- `listfiles(subdir?)` - List files and directories
+- `mkdir(dirpath)` - Create a directory
+- `rmdir(dirpath)` - Remove an empty directory
+
+**Usage Example:**
+
+```javascript
+import { register, setRootToolBox, call } from '@semantictools/ai-toolbox';
+import { fileToolbox, initialize } from '@semantictools/ai-toolbox/src/toolboxes/file.mjs';
+
+// Initialize with .filetb config file
+await initialize(); // Or: await initialize('/path/to/.filetb')
+
+// Register the toolbox
+register(fileToolbox);
+setRootToolBox('file');
+
+// Use the functions
+const files = await call('listfiles');
+const content = await call('readfile', { filepath: { value: 'data.txt' } });
+```
+
+See [examples/file-toolbox.mjs](../../examples/file-toolbox.mjs) for a complete example.
+
+## Creating Your Own Standard Toolbox
+
+To create a new standard toolbox:
+
+1. **Create a new file** in this directory (e.g., `mytoolbox.mjs`)
+
+2. **Define your functions** following the interface standard:
+
+```javascript
+const functions = {
+  my_function: {
+    f: async (args) => {
+      // Implementation
+      return result;
+    },
+    interface: {
+      domain: 'mytoolbox',
+      name: 'my_function',
+      type: 'function',
+      description: 'What the function does',
+      params: {
+        param1: {
+          type: 'string',
+          isRequired: true,
+          description: 'Parameter description'
+        }
+      },
+      returns: 'string'
+    }
+  }
+};
+```
+
+3. **Export the toolbox object**:
+
+```javascript
+export const myToolbox = {
+  getName: () => 'mytoolbox',
+  getFunction: (fname) => functions[fname] || null,
+  functions: Object.keys(functions).reduce((acc, key) => {
+    acc[key] = true;
+    return acc;
+  }, {})
+};
+```
+
+4. **Export any initialization functions** if needed:
+
+```javascript
+export async function initialize(config) {
+  // Setup code
+}
+```
+
+5. **Document your toolbox** in this README
+
+## Design Principles
+
+Standard toolboxes should follow these principles:
+
+1. **Self-contained** - Include all necessary code in the toolbox file
+2. **Secure** - Validate inputs and prevent security vulnerabilities
+3. **Well-documented** - Clear descriptions for all functions and parameters
+4. **Error handling** - Provide clear error messages
+5. **Follow the standard** - Use the official interface format
+6. **Configuration** - Support external configuration when appropriate
+7. **Examples** - Provide working examples in the examples directory
+
+## Testing Your Toolbox
+
+Create a test file in the examples directory that demonstrates all functions in your toolbox.
+
+## Contributing
+
+When adding a new standard toolbox:
+
+1. Create the toolbox file in this directory
+2. Follow the interface standard
+3. Add comprehensive error handling
+4. Create an example file in `examples/`
+5. Document it in this README
+6. Update the main README to list the new toolbox

package/src/toolboxes/file.mjs

@@ -0,0 +1,287 @@
+import fs from 'fs/promises';
+import path from 'path';
+
+let rootFolder = null;
+let configFile = '.filetb';
+
+/**
+ * Set the root folder directly (for programmatic use)
+ * @param {string} folderPath - Absolute path to the root folder
+ * @returns {Promise<string>} The validated root folder path
+ */
+async function setRootFolder(folderPath) {
+  if (!folderPath) {
+    throw new Error('Root folder path is required');
+  }
+
+  // Convert to absolute path if needed
+  const absolutePath = path.isAbsolute(folderPath) ? folderPath : path.resolve(folderPath);
+
+  // Verify the root folder exists
+  try {
+    const stats = await fs.stat(absolutePath);
+    if (!stats.isDirectory()) {
+      throw new Error(`Path ${absolutePath} is not a directory`);
+    }
+  } catch (error) {
+    throw new Error(`Root folder ${absolutePath} does not exist or is not accessible: ${error.message}`);
+  }
+
+  rootFolder = absolutePath;
+  return rootFolder;
+}
+
+/**
+ * Initialize the file toolbox by reading the root folder from config file
+ * Convenience method for beginners - enterprise users can use setRootFolder() directly
+ * @param {string} configPath - Optional path to config file (defaults to .filetb in cwd)
+ * @returns {Promise<string>} The configured root folder path
+ */
+async function initialize(configPath = null) {
+  const configFilePath = configPath || path.join(process.cwd(), configFile);
+
+  try {
+    const config = await fs.readFile(configFilePath, 'utf-8');
+    const folderPath = config.trim();
+    return await setRootFolder(folderPath);
+  } catch (error) {
+    throw new Error(`Failed to read config file ${configFilePath}: ${error.message}`);
+  }
+}
+
+/**
+ * Get the absolute path within the root folder
+ * @param {string} relativePath - Relative path within root folder
+ * @returns {string} Absolute path
+ */
+function getAbsolutePath(relativePath) {
+  if (!rootFolder) {
+    throw new Error('File toolbox not initialized. Call initialize() first or ensure .filetb file exists.');
+  }
+
+  const fullPath = path.join(rootFolder, relativePath);
+
+  // Security check: ensure the path is within rootFolder
+  if (!fullPath.startsWith(rootFolder)) {
+    throw new Error(`Access denied: path ${relativePath} is outside root folder`);
+  }
+
+  return fullPath;
+}
+
+// ============================================================================
+// File Operations
+// ============================================================================
+
+async function readFile(args) {
+  const filePath = getAbsolutePath(args.filepath.value);
+
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content;
+  } catch (error) {
+    throw new Error(`Failed to read file ${args.filepath.value}: ${error.message}`);
+  }
+}
+
+async function writeFile(args) {
+  const filePath = getAbsolutePath(args.filepath.value);
+  const content = args.content.value;
+
+  try {
+    // Ensure parent directory exists
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+    return `File ${args.filepath.value} written successfully`;
+  } catch (error) {
+    throw new Error(`Failed to write file ${args.filepath.value}: ${error.message}`);
+  }
+}
+
+async function deleteFile(args) {
+  const filePath = getAbsolutePath(args.filepath.value);
+
+  try {
+    await fs.unlink(filePath);
+    return `File ${args.filepath.value} deleted successfully`;
+  } catch (error) {
+    throw new Error(`Failed to delete file ${args.filepath.value}: ${error.message}`);
+  }
+}
+
+async function listFiles(args) {
+  const subdir = args.subdir ? args.subdir.value : '';
+  const dirPath = getAbsolutePath(subdir);
+
+  try {
+    const entries = await fs.readdir(dirPath, { withFileTypes: true });
+
+    const files = entries.map(entry => ({
+      name: entry.name,
+      type: entry.isDirectory() ? 'directory' : 'file',
+      path: path.join(subdir, entry.name)
+    }));
+
+    return files;
+  } catch (error) {
+    throw new Error(`Failed to list files in ${subdir || '/'}: ${error.message}`);
+  }
+}
+
+async function makeDirectory(args) {
+  const dirPath = getAbsolutePath(args.dirpath.value);
+
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+    return `Directory ${args.dirpath.value} created successfully`;
+  } catch (error) {
+    throw new Error(`Failed to create directory ${args.dirpath.value}: ${error.message}`);
+  }
+}
+
+async function removeDirectory(args) {
+  const dirPath = getAbsolutePath(args.dirpath.value);
+
+  try {
+    await fs.rmdir(dirPath);
+    return `Directory ${args.dirpath.value} removed successfully`;
+  } catch (error) {
+    throw new Error(`Failed to remove directory ${args.dirpath.value}: ${error.message}`);
+  }
+}
+
+// ============================================================================
+// Function Definitions
+// ============================================================================
+
+const functions = {
+  readfile: {
+    f: readFile,
+    interface: {
+      domain: 'file',
+      name: 'readfile',
+      type: 'function',
+      description: 'Read contents of a file within the configured root folder',
+      params: {
+        filepath: {
+          type: 'string',
+          isRequired: true,
+          description: 'Relative path to the file from root folder'
+        }
+      },
+      returns: 'string'
+    }
+  },
+
+  writefile: {
+    f: writeFile,
+    interface: {
+      domain: 'file',
+      name: 'writefile',
+      type: 'function',
+      description: 'Write content to a file within the configured root folder',
+      params: {
+        filepath: {
+          type: 'string',
+          isRequired: true,
+          description: 'Relative path to the file from root folder'
+        },
+        content: {
+          type: 'string',
+          isRequired: true,
+          description: 'Content to write to the file'
+        }
+      },
+      returns: 'string'
+    }
+  },
+
+  deletefile: {
+    f: deleteFile,
+    interface: {
+      domain: 'file',
+      name: 'deletefile',
+      type: 'function',
+      description: 'Delete a file within the configured root folder',
+      params: {
+        filepath: {
+          type: 'string',
+          isRequired: true,
+          description: 'Relative path to the file from root folder'
+        }
+      },
+      returns: 'string'
+    }
+  },
+
+  listfiles: {
+    f: listFiles,
+    interface: {
+      domain: 'file',
+      name: 'listfiles',
+      type: 'function',
+      description: 'List files and directories within the configured root folder',
+      params: {
+        subdir: {
+          type: 'string',
+          isRequired: false,
+          description: 'Optional subdirectory path to list (defaults to root folder)'
+        }
+      },
+      returns: 'array'
+    }
+  },
+
+  mkdir: {
+    f: makeDirectory,
+    interface: {
+      domain: 'file',
+      name: 'mkdir',
+      type: 'function',
+      description: 'Create a directory within the configured root folder',
+      params: {
+        dirpath: {
+          type: 'string',
+          isRequired: true,
+          description: 'Relative path to the directory from root folder'
+        }
+      },
+      returns: 'string'
+    }
+  },
+
+  rmdir: {
+    f: removeDirectory,
+    interface: {
+      domain: 'file',
+      name: 'rmdir',
+      type: 'function',
+      description: 'Remove an empty directory within the configured root folder',
+      params: {
+        dirpath: {
+          type: 'string',
+          isRequired: true,
+          description: 'Relative path to the directory from root folder'
+        }
+      },
+      returns: 'string'
+    }
+  }
+};
+
+// ============================================================================
+// Toolbox Interface
+// ============================================================================
+
+const fileToolbox = {
+  getName: () => 'file',
+  getFunction: (fname) => {
+    return functions[fname] || null;
+  },
+  functions: Object.keys(functions).reduce((acc, key) => {
+    acc[key] = true;
+    return acc;
+  }, {})
+};
+
+export { fileToolbox, initialize, setRootFolder, getAbsolutePath };