@semantictools/ai-toolbox 0.1.0

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@semantictools/ai-toolbox",
+  "version": "0.1.0",
+  "description": "A flexible tool manager for managing and executing AI function calling toolboxes",
+  "main": "src/toolmanager.mjs",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "function-calling",
+    "tool-manager",
+    "toolbox",
+    "anthropic",
+    "openai"
+  ],
+  "author": "Dusty Wilhelm Murray / Semantic Tools",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/semantictools/ai-toolbox.git"
+  },
+  "bugs": {
+    "url": "https://github.com/semantictools/ai-toolbox/issues"
+  },
+  "homepage": "https://github.com/semantictools/ai-toolbox#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "src",
+    "src/translators",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/toolmanager.mjs

@@ -0,0 +1,605 @@
+import * as atfuncTranslator from './translators/atfunc.mjs';
+
+let rootToolBox = null;
+let toolBoxes = {};
+let functions = {};
+let converter = null;
+const truncateLengthDefault = 5000;
+let truncateLength = truncateLengthDefault;
+
+let toolCalls = 0;
+let functionCalls = 0;
+
+// Case sensitivity - determined by translator (default: case-sensitive)
+let caseSensitive = true;
+
+// Standard translator registry
+const standardTranslators = {
+  'atfunc': atfuncTranslator
+};
+
+// Translator constants for convenience
+export const TRANSLATOR_ATFUNC = 'atfunc';
+
+// Helper function to normalize names based on case sensitivity
+function normalizeName(name) {
+  return caseSensitive ? name : name.toLowerCase();
+}
+
+// ============================================================================
+// Validation Functions
+// ============================================================================
+
+/**
+ * Validate that a function interface matches the expected structure
+ * @param {object} interfaceObj - The interface object to validate
+ * @param {string} toolboxName - The toolbox name for domain validation
+ * @throws {Error} If validation fails
+ */
+function validateInterface(interfaceObj, toolboxName) {
+  if (!interfaceObj || typeof interfaceObj !== 'object') {
+    throw new Error('Interface must be an object');
+  }
+
+  // Check required fields
+  const requiredFields = ['domain', 'name', 'type', 'description', 'returns'];
+  for (const field of requiredFields) {
+    if (!interfaceObj[field]) {
+      throw new Error(`Interface missing required field: '${field}'`);
+    }
+  }
+
+  // Validate type
+  if (interfaceObj.type !== 'function' && interfaceObj.type !== 'api-wrapper') {
+    throw new Error(`Interface type must be 'function' or 'api-wrapper', got: '${interfaceObj.type}'`);
+  }
+
+  // Validate domain matches toolbox name
+  const normalizedDomain = normalizeName(interfaceObj.domain);
+  const normalizedToolboxName = normalizeName(toolboxName);
+  if (normalizedDomain !== normalizedToolboxName) {
+    throw new Error(`Interface domain '${interfaceObj.domain}' does not match toolbox name '${toolboxName}'`);
+  }
+
+  // Validate params structure (if present)
+  if (interfaceObj.params) {
+    if (typeof interfaceObj.params !== 'object') {
+      throw new Error('Interface params must be an object');
+    }
+
+    for (const [paramName, paramDef] of Object.entries(interfaceObj.params)) {
+      if (!paramDef || typeof paramDef !== 'object') {
+        throw new Error(`Parameter '${paramName}' must be an object`);
+      }
+
+      if (!paramDef.type) {
+        throw new Error(`Parameter '${paramName}' missing required field: 'type'`);
+      }
+
+      if (paramDef.isRequired === undefined) {
+        throw new Error(`Parameter '${paramName}' missing required field: 'isRequired'`);
+      }
+
+      if (!paramDef.description) {
+        throw new Error(`Parameter '${paramName}' missing required field: 'description'`);
+      }
+    }
+  }
+
+  // For API wrappers, validate additional fields if present
+  if (interfaceObj.type === 'api-wrapper') {
+    ['path_params', 'query_params'].forEach(fieldName => {
+      if (interfaceObj[fieldName]) {
+        if (typeof interfaceObj[fieldName] !== 'object') {
+          throw new Error(`Interface ${fieldName} must be an object`);
+        }
+      }
+    });
+  }
+}
+
+/**
+ * Validate that required parameters are present in a function call
+ * @param {object} funcInterface - The function interface
+ * @param {object} params - The parameters passed to the function
+ * @throws {Error} If required parameters are missing
+ */
+function validateParameters(funcInterface, params) {
+  if (!funcInterface.params) {
+    return; // No params defined, nothing to validate
+  }
+
+  const missingParams = [];
+
+  for (const [paramName, paramDef] of Object.entries(funcInterface.params)) {
+    if (paramDef.isRequired) {
+      // Check if param exists in call
+      if (!params || !params[paramName]) {
+        missingParams.push(paramName);
+      }
+    }
+  }
+
+  if (missingParams.length > 0) {
+    const functionName = `${funcInterface.domain}.${funcInterface.name}`;
+    throw new Error(
+      `Missing required parameter${missingParams.length > 1 ? 's' : ''} for function '${functionName}': ${missingParams.join(', ')}`
+    );
+  }
+}
+
+function getStats() {
+    return {
+        toolCalls,
+        functionCalls
+    }
+}
+
+function resetStats() {
+
+  toolCalls = 0;
+  functionCalls = 0;
+
+}
+
+function setRootToolBox( toolBoxName ) {
+  if( !toolBoxName ) {
+    throw new Error("Tool box name is required to set root tool box");
+  }
+  const normalizedName = normalizeName(toolBoxName);
+  if( !toolBoxes[normalizedName] ) {
+    throw new Error(`Tool box '${toolBoxName}' not registered, cannot set as root tool box`);
+  }
+  rootToolBox = normalizedName;
+}
+
+function setFunctionTranslator( converterObject ) {
+  // If a string is passed, treat it as a translator name and load it
+  if (typeof converterObject === 'string') {
+    converter = getTranslator(converterObject);
+  } else {
+    converter = converterObject;
+  }
+
+  // Read translator's case sensitivity preference (default: case-sensitive)
+  caseSensitive = converter.caseSensitive ?? true;
+}
+
+function getTranslator( name ) {
+  if (!name) {
+    throw new Error("Translator name is required");
+  }
+
+  const translatorName = name.toLowerCase();
+  if (!standardTranslators[translatorName]) {
+    throw new Error(`Translator '${name}' not found. Available translators: ${Object.keys(standardTranslators).join(', ')}`);
+  }
+
+  return standardTranslators[translatorName];
+}
+
+function getStandardTranslatorList() {
+  return Object.keys(standardTranslators);
+}
+
+function findFunction( toolPath ) {
+  if(!toolPath) {
+    throw new Error("Tool path is required");
+  }
+
+  const normalizedPath = normalizeName(toolPath);
+  let toolcomponents = normalizedPath.split('.');
+  let toolBox;
+  let toolFunction;
+  if( toolcomponents.length < 2) {
+    toolBox = toolBoxes[rootToolBox];
+    toolFunction = toolcomponents[0];
+  }
+  else {
+    toolBox = toolBoxes[toolcomponents[0]];
+    toolFunction = toolcomponents[1];
+  }
+
+  if (!toolBox) {
+        throw new Error(`Tool box '${toolcomponents[0]}' not registered`);
+  }
+
+  let tfunc = toolBox.getFunction( toolFunction );
+  if (!tfunc || !tfunc.f) {
+        return null;
+  }
+
+  return tfunc;
+}
+
+
+async function call(toolPath, args, truncateLength = 5000) {
+
+  let tfunc = findFunction( toolPath );
+
+  // Validate parameters before calling
+  if (tfunc.interface) {
+    validateParameters(tfunc.interface, args);
+  }
+
+  return await tfunc.f( args || {}, truncateLength );
+}
+
+function register(toolBox) {
+
+  if(!toolBox || !toolBox.getName()) {
+    throw new Error("Tool box with a valid name is required for registration");
+  }
+
+  const toolboxName = toolBox.getName();
+
+  // Validate all function interfaces in the toolbox
+  if (toolBox.functions) {
+    for (const functionName of Object.keys(toolBox.functions)) {
+      const funcObj = toolBox.getFunction(functionName);
+      if (funcObj && funcObj.interface) {
+        try {
+          validateInterface(funcObj.interface, toolboxName);
+        } catch (e) {
+          throw new Error(`Validation failed for function '${functionName}' in toolbox '${toolboxName}': ${e.message}`);
+        }
+      }
+    }
+  }
+
+  const normalizedName = normalizeName(toolboxName);
+  toolBoxes[normalizedName] = toolBox;
+}
+
+
+
+
+function getFunctions(toolBoxName) {
+  /* toolBoxName can also be null or undefined, then we list all functions */
+  let functionsList = [];
+  if(toolBoxName) {
+    const normalizedName = normalizeName(toolBoxName);
+    let toolBox = toolBoxes[normalizedName];
+    if (!toolBox) {
+          throw new Error(`Tool box '${toolBoxName}' not registered`);
+    }
+    for (let fname in toolBox.functions) {
+      functionsList.push( toolBox.getName() + "." + fname );
+    }
+  } else {
+    for (let tbName in toolBoxes) {
+      let toolBox = toolBoxes[tbName];
+      for (let fname in toolBox.functions) {
+
+        let fullName = fname;
+
+        if( tbName != rootToolBox ) {
+          fullName = tbName + "." + fname;
+        }
+        functionsList.push( fullName );
+      }
+    }
+  }
+  return functionsList;
+}
+
+
+
+function getName() {
+  return "toolmanager";
+}
+
+function getFunction(fname) {
+    if (fname in functions) {
+        return functions[fname];
+    } else {
+        return null;
+    }
+};
+
+function getRootInterfaceAsText() {
+
+  let functions = getFunctions();
+  let output = "";
+
+  for( let i=0; i<functions.length; i++) {
+    let fn = functions[i];  
+    let f = findFunction( fn );
+    let descr = converter.generateFunctionIfText( f.interface );
+
+    if( descr ) {
+      output += descr;
+    }
+    
+  }
+
+  return output;
+  
+}
+
+function makeInterfaceText( def, separator ) {
+  return converter.generateFunctionIfText( def, separator );
+}
+
+function getFunctionCallsFromTextResponse( text ) {
+  
+  let allFunctions = getFunctions();
+  let interfaces = [];
+  for( let i=0; i<allFunctions.length; i++ ) {
+    let tfunc = findFunction( allFunctions[i] );
+    interfaces.push( tfunc.interface );
+  }
+  return converter.getFunctionCallsFromText( text, interfaces, rootToolBox );
+}
+
+async function executeResponseFunctions( promptText ) {
+
+    let fCalls = getFunctionCallsFromTextResponse( promptText );
+
+    for( let f=0; f<fCalls.length; f++ ) {
+
+        let fCall = fCalls[f];
+        let fParams = fCall.params;
+
+        if( !fCall.error  ) {
+          try {
+            let result = await call( fCall.name, fCall.params, truncateLength );
+            fCall.result = result;
+            if( fCall.interface.returns === "object"  ) {
+
+
+              let resultString = JSON.stringify( result, null, 2 );
+
+              //truncate result if too long
+              if( resultString.length > truncateLength ) {
+                resultString = resultString.substring(0, truncateLength) + "...(truncated)";
+              }
+
+              fCall.result = resultString;
+            }
+          } catch (e) {
+            fCall.error = true;
+            fCall.result = `Error: ${e.message}`;
+          }
+        }
+        else {
+          fCall.result = "Error: function not found";
+        }
+    }
+
+    if(!truncateLength == truncateLengthDefault) {
+      truncateLength = truncateLengthDefault;
+      console.log("Truncate length reset to default of ", truncateLengthDefault );
+    }
+    
+    let output = converter.formatFunctionCallResults( fCalls );
+
+    return { functionsOutput: output, functionCalCount: fCalls.length  };
+
+}
+
+
+
+function getBoxes() {
+  return Object.keys(toolBoxes);
+}
+
+function setTruncate( args ) {
+  console.log("Warning, setting global truncate length for tool outputs to ", args.length.value, " characters." );
+  truncateLength = args.length.value;
+}
+
+
+function getFunctionInterface( args ) {
+  let tfunc = findFunction( args.function_name.value );
+
+  let separator = false;
+  if( args.separator && args.separator.value ) {
+    separator = args.separator.value;
+  }
+
+  return makeInterfaceText( tfunc.interface, separator );
+}
+
+// ============================================================================
+// Control Functions Toolbox (domain: "tools")
+// ============================================================================
+
+const controlFunctions = {
+  get_toolboxes: {
+    f: async (args) => {
+      return getBoxes();
+    },
+    interface: {
+      domain: 'tools',
+      name: 'get_toolboxes',
+      type: 'function',
+      description: 'Get all toolboxes registered in the tool manager',
+      params: {},
+      returns: 'array'
+    }
+  },
+
+  get_functions: {
+    f: async (args) => {
+      const toolboxName = args.toolbox ? args.toolbox.value : null;
+      return getFunctions(toolboxName);
+    },
+    interface: {
+      domain: 'tools',
+      name: 'get_functions',
+      type: 'function',
+      description: 'Get all functions in the tool manager, or in a specific toolbox',
+      params: {
+        toolbox: {
+          type: 'string',
+          isRequired: false,
+          description: 'Toolbox name to filter functions'
+        }
+      },
+      returns: 'array'
+    }
+  },
+
+  get_function_interface: {
+    f: async (args) => {
+      return getFunctionInterface(args);
+    },
+    interface: {
+      domain: 'tools',
+      name: 'get_function_interface',
+      type: 'function',
+      description: 'Get the interface definition of a specific function',
+      params: {
+        function_name: {
+          type: 'string',
+          isRequired: true,
+          description: 'Full function name including toolbox, e.g., "toolbox.function"'
+        },
+        separator: {
+          type: 'boolean',
+          isRequired: false,
+          description: 'Add visual separator (useful when requesting multiple interfaces)'
+        }
+      },
+      returns: 'string'
+    }
+  },
+
+  set_truncate_length: {
+    f: async (args) => {
+      setTruncate(args);
+      return `Truncate length set to ${args.length.value} characters`;
+    },
+    interface: {
+      domain: 'tools',
+      name: 'set_truncate_length',
+      type: 'function',
+      description: 'Set the truncate length for all tool outputs (resets after each execution)',
+      params: {
+        length: {
+          type: 'number',
+          isRequired: true,
+          description: 'Truncation length in characters'
+        }
+      },
+      returns: 'string'
+    }
+  }
+};
+
+const controlToolbox = {
+  getName: () => 'tools',
+  getFunction: (fname) => {
+    return controlFunctions[fname] || null;
+  },
+  functions: Object.keys(controlFunctions).reduce((acc, key) => {
+    acc[key] = true;
+    return acc;
+  }, {})
+};
+
+function registerControlFunctions() {
+  register(controlToolbox);
+}
+
+function unregisterControlFunctions() {
+  const normalizedName = normalizeName('tools');
+  delete toolBoxes[normalizedName];
+}
+
+function registerControlFunction(functionName) {
+  if (!controlFunctions[functionName]) {
+    throw new Error(`Control function '${functionName}' not found. Available: ${Object.keys(controlFunctions).join(', ')}`);
+  }
+
+  // Check if tools toolbox exists
+  const normalizedName = normalizeName('tools');
+  if (!toolBoxes[normalizedName]) {
+    // Create a partial toolbox with just this function
+    const partialFunctions = { [functionName]: controlFunctions[functionName] };
+    const partialToolbox = {
+      getName: () => 'tools',
+      getFunction: (fname) => partialFunctions[fname] || null,
+      functions: { [functionName]: true }
+    };
+    register(partialToolbox);
+  } else {
+    // Add to existing toolbox
+    toolBoxes[normalizedName].functions[functionName] = true;
+  }
+}
+
+function unregisterControlFunction(functionName) {
+  const normalizedName = normalizeName('tools');
+  if (toolBoxes[normalizedName] && toolBoxes[normalizedName].functions) {
+    delete toolBoxes[normalizedName].functions[functionName];
+
+    // If no functions left, remove the toolbox
+    if (Object.keys(toolBoxes[normalizedName].functions).length === 0) {
+      delete toolBoxes[normalizedName];
+    }
+  }
+}
+
+// Register control functions by default
+registerControlFunctions();
+
+/*
+selfRegisterFunction( "get_toolboxes", "Get all toolboxes registered in the tool manager.",
+  if_getBoxes,
+  null,
+  "object"
+ );
+
+ selfRegisterFunction( "get_functions", "Get all functions in the tool manager, or in a specific toolbox.",
+  if_getFunctions,
+  {
+    "toolbox": { type: "string", required: false, description: "Toolbox name to filter functions." }
+  },
+  "array"
+ );
+
+selfRegisterFunction( "get_function_if", "Get the interface definition of a specific function.",
+  if_getFunctionInterface,
+  {
+    "function_name": { type: "string", required: true, description: "Full function name including toolbox, e.g., 'toolbox.function'." },
+    "separator": { type: "boolean", required: true, description: "visual separator, when asking for multiple function interaces at once." },
+  },
+  "string"
+  
+);
+
+selfRegisterFunction( "set_truncate_length", "Set the truncatelength of all tool outputs. It will be reset after each call.",
+  if_setTruncate,
+  {
+    "length": { 
+      type: "integer", required: true, description: "Truncation length in characters." },
+  }
+ );
+*/
+
+
+
+//register( selfInstanceAsToolBox );
+//rootToolBox = getName();
+
+export {
+  register, call,
+  setFunctionTranslator, getTranslator, getStandardTranslatorList,
+  getFunctionCallsFromTextResponse,
+  executeResponseFunctions,
+  getRootInterfaceAsText,
+  setRootToolBox,
+
+  getFunctions, getBoxes, makeInterfaceText, setTruncate, getFunctionInterface,
+  findFunction,
+
+  getStats, resetStats,
+
+  // Control functions management
+  registerControlFunctions,
+  unregisterControlFunctions,
+  registerControlFunction,
+  unregisterControlFunction
+}