OctoTools Documentation

Memory acts as a project logbook or scratchpad for the octotools system. It does not perform reasoning or actions itself; instead, it serves as a centralized container that records the context of a problem-solving journey. This context is essential for the Planner to make informed decisions about subsequent steps.

Memory tracks three primary types of information:

1. The Original Request: The initial query provided to the Solver.
2. Files: Any files (images, documents, etc.) provided with the query, including their descriptions.
3. Action History: A detailed log of every step taken by the Solver, including which Tool was used, the specific sub_goal, the exact command executed, and the result obtained.

The Planner is the strategic component of the octotools framework. It acts as a navigator or strategist that guides the problem-solving process by analyzing the user's goal, the current progress recorded in Memory, and the available Tools.

To determine the next course of action, the Planner evaluates three key inputs:

1. The Destination (Query): The final goal provided by the user.
2. Current Location & Trip Log (Memory): The history of actions taken and information gathered so far.
3. Map & Vehicle Options (Tools): The list of available tools and their descriptions.

Based on these inputs, the Planner decides on the next sub-goal and the specific tool selection required to achieve it.

The Solver is the central coordinator (the "brain") of an octotools agent. It manages the problem-solving process by orchestrating three specialist components:

1. Planner: The strategist that breaks down the main goal into smaller, actionable steps and decides which tools to use.
2. Executor: The hands-on specialist that generates specific commands for tools and executes them.
3. Memory: The project logbook that records all steps taken, commands used, and results obtained to provide context for the Planner.

The Solver operates in a loop: it analyzes the query, asks the Planner for the next step, tells the Executor to run a command, records the result in Memory, and asks the Planner if the goal has been met. This continues until the goal is achieved or limits (like max_steps or max_time) are reached.

The Initializer acts as the setup crew for an octotools project. It prepares the environment before the Solver begins its work by performing three main tasks:

1. Discovering Tools: Scanning the project to find available Tools (e.g., Web_Search_Tool). You can specify specific tools or request all of them.
2. Loading Metadata: For each tool, it loads the 'instruction manual' containing:
   • tool_name: The name of the tool.
   • tool_description: What the tool does.
   • input_types: Required inputs.
   • output_type: Produced outputs.
   • require_llm_engine: Whether the tool requires an LLM Engine.
3. Checking Availability (Optional): Running checks or 'demo commands' to ensure tools are functional in the current environment (e.g., verifying API keys).

OctoTools is an agentic framework designed for complex reasoning across diverse domains. It is training-free and easily extensible. The framework relies on three core components:

1. Tool cards: Standardized metadata that encapsulates tool functionality, allowing for the integration of heterogeneous tools without additional training.
2. Planner: Manages both high-level and low-level planning to address global objectives and refine actions step-by-step.
3. Executor: Instantiates tool calls by generating executable commands and saving structured results into the context.

The framework also includes a task-specific toolset optimization algorithm that identifies the most beneficial subset of tools for specific downstream tasks.

The LLM Engine is the component in octotools that manages communication with Large Language Models (LLMs) like OpenAI's GPT, Anthropic's Claude, or Google's Gemini. It acts as an adapter and communication manager for the rest of the framework (such as the Planner and Executor).

Key responsibilities include:

• Connection & Communication: Handling API connections and formatting requests for specific providers.
• Translation: Converting LLM responses back into a format usable by octotools.
• Reliability: Automatically retrying requests if connections fail or the LLM is busy.
• Efficiency: Caching results so that identical subsequent requests are served from memory instead of re-calling the API.
• Flexibility: Supporting various LLM providers through a unified interface.

A Tool is a specialized capability that extends the basic knowledge of the LLM Engine. While the LLM provides reasoning, Tools allow the system to interact with the real world or perform specific technical tasks.

Every tool consists of three core components:

1. Defined Inputs: The specific information required to perform the task (e.g., a search query).
2. Defined Outputs: The result produced by the tool (e.g., a list of search results).
3. Metadata: Descriptive information (name, description, version, examples) that allows the Planner to select the correct tool for a given problem.

Common examples include Web Search, Image Captioning, Object Detection, Code Execution, and ArXiv Paper Searching.

The LLM Engine acts as a bridge between the framework and external LLM providers. It manages three main concerns:

• Abstraction: The create_llm_engine factory allows you to switch between different 'brains' (GPT, Claude, Gemini) without changing your core logic.
• Reliability: Engines implement retry logic (e.g., via @retry decorators) to manage transient API failures.
• Efficiency: Through the CachedEngine implementation, the engine uses diskcache to store and retrieve responses based on a SHA-256 hash of the prompt, reducing latency and API costs for repeated queries.