FAQtiv Agent Toolkit uses genAI to write python or javascript code against a set of domain specific functions to perform tasks described in natural language. The functions, task descriptions, and a set of general instructions are all packaged into a project and a command line tool performs actions against that project to perform tasks.
The core idea behind the tool is that code generation is a powerful mechansim for leveraging LLMs to perform actions that require multiple steps, and that by providing a set of domain specific functions for them to target, we greatly increase the reliability of the generated code by constraining the LLMs to a particular limited view of the world.
Task descriptions are compiled into code by the tool to produce runnable tasks. The tasks can perform data retrieval, create file outputs, perform tasks against apis, etc. and can be parameterized to support greater reuse. Adding tasks to a project can be thought of as training an agent since the tasks both define specific capabilities of the agent as well as provide few shot examples for subsequent generation of new tasks. In fact, though the tool has value as a standalone utility, it is primarily intended to simplify the creation of intelligent tools/agents that be in used by higher level conversational AIs.
The name FAQtiv derives from an old side project that involved creating "Active FAQs" -- i.e. frequently asked questions that were answered by scripted live interaction with external systems.
You will need node.js to install and run the toolkit and optionally python if you are writing a python agent (unnecessary if you're writing a node.js/javascript agent).
You can install the toolkit from npm or install from source.
To install from the npm:
npm install -g @intellidimension/faqtiv-agent-toolkit
To install from source, clone this repository locally and:
npm install
When installing from source, it's often useful to use npm link so that you can use the command line directly to perform tasks:
npm link
To initialize a new project, use the init command:
faqtiv init <projectRoot> --runtime <value><projectRoot>: The root directory of the new project.--runtime <value>: The runtime environment, eitherjavascriptorpython. Defaults tojavascript.
Make sure to update the project .env with your OpenAI API credentials.
The toolkit uses the following environment variables:
OPENAI_ORGANIZATION: Your OpenAI organization ID.OPENAI_API_KEY: Your OpenAI API key.OPENAI_MODEL: The OpenAI model to use (defaults to 'gpt-4o' if not specified).LOG_DEBUG_AI: Set to 'true' to enable AI debugging logs.JS_CMD: The command to run JavaScript code (defaults to 'node' if not specified).PYTHON_CMD: The command to run Python code (defaults to 'python' if not specified).
You can set these variables in your project's .env file or in your system's environment.
Start by adding some functions and libs to your project. Functions will be provided to the LLM to use for code generation while libs are private dependencies that your functions may use but the LLM won't use directly. Be verbose in your function and argumaent naming and supply code docs as necessary to make clear to the LLM what the function does.
Note that the function code should not include library imports or requires, for that you can use the add-module command which will inject the dependencies for you.
In order to generate code first we need to generate function signature headers for your functions, use the update-headers command:
faqtiv update-headersTasks are stored as text files that live within the "tasks" folder of a project. You can add, edit, or delete files in that folder manually or you can use the commands below to do the same. The task name is the file name without the .txt extension.
To add a new task, use the add-task command:
faqtiv add-task <name> <description><name>: The name of the task.<description>: A brief description of the task.
To remove an existing task, use the remove-task command (not implemented):
faqtiv remove-task <name><name>: The name of the task.
To update an existing task, use the update-task command (not implemented):
faqtiv update-task <name> <description><name>: The name of the task.<description>: The updated description of the task.
To compile a specific task or all pending tasks, use the compile-task command:
faqtiv compile-task [taskName] --all[taskName]: The name of the task (optional).--all: Compile all pending tasks.
If the code is manually edited then this command will update the code's metadata without regenerating the code, this is needed to accurately track function dependencies for migrations.
To run a specific task, use the run-task command:
faqtiv run-task <taskName> [args...] --output <file> --error <file><taskName>: The name of the task.[args...]: Additional arguments for the task (optional).--output <file>: The result file path, defaults to stdout.--error <file>: The error log file path, defaults to/logs/err.log.--files <dir>: Directory where any artifacts generated by the task will be saved, defaults to current working directory.
Run metadata will be logged with runtime information.
The toolkit can detect changes based on the modification dates of functions and task text files in the ./tasks directory to determine if code regeneration is necessary.
To execute a migration plan, use the migrate-tasks command:
faqtiv migrate-tasks --dry--dry: Display the migration plan without executing it.
To list all existing tasks, use the list-tasks command:
faqtiv list-tasksTo setup the interpreter environment, use the setup-interpreter command:
faqtiv setup-interpreterThis command will install the necessary dependencies for the interpreter runtime environment.
Modules are external javascript or pythn libraries that are required by your function libraries.
To add a new module, use the add-module command:
faqtiv add-module <name> [alias] [version]<name>: The name of the module.[alias]: An alias for the module (optional), this is how the dependency will be avaiable to your functions.[version]: The version of the module (optional).
To remove an existing module, use the remove-module command:
faqtiv remove-module <name><name>: The name of the module.
To list all existing modules, use the list-modules command:
faqtiv list-modulesTo reinstall all modules, use the reinstall-modules command:
faqtiv reinstall-modulesBy default all compiled tasks will be added as an example for future code generation, this helps the LLM improve it's results. This can be changed by setting auto_add_examples: false in your project's faqtiv_config.yml file.
To add a task to examples, use the add-example command:
faqtiv add-example [taskName] --all[taskName]: The name of the task (optional).--all: Add all tasks as examples.
To remove a task from examples, use the remove-example command:
faqtiv remove-example [taskName] --all[taskName]: The name of the task (optional).--all: Remove all examples.
To list all existing examples, use the list-examples command:
faqtiv list-examplesFor help with any command, use the --help flag:
faqtiv <command> --helpHere is an example of initializing a new project:
faqtiv init my_project --runtime python