High-Level Architecture

AIDE ML is designed as a modular system with several key components that work together to execute the agentic tree search. Understanding this architecture is helpful for extending the system or interpreting its behavior.

Conceptual Flow Diagram

Core Components

  1. Runner (aide/run.py)

    • This is the main entry point for the CLI (aide command).
    • It handles loading the configuration, preparing the agent's workspace, and orchestrating the main loop.
    • It uses the rich library to provide a real-time terminal user interface that displays the task description, progress, and a live view of the solution tree.

  2. Agent (aide/agent.py)

    • This is the "brain" of the system. The Agent class holds the core logic for the agentic tree search.
    • It compiles and sends prompts to the LLM backend to generate code.
    • It contains the logic for the three primary actions: drafting a new solution, improving an existing one, and debugging a buggy one.
    • It implements the search_policy to decide which node in the tree to work on next.
    • It also uses an LLM to parse and analyze the results of code execution to extract metrics and generate feedback.

  3. Interpreter (aide/interpreter.py)

    • This component provides a secure, sandboxed environment for executing the Python code generated by the agent.
    • It runs the code in a separate process using Python's multiprocessing library to isolate it from the main agent process.
    • It captures all standard output (stdout), standard error (stderr), and exceptions, returning them in a structured ExecutionResult object.
    • It enforces a configurable timeout to prevent code from running indefinitely.

  4. Journal (aide/journal.py)

    • This is the central data structure of the system, acting as the agent's memory.
    • The Journal class holds a list of all Node objects generated during a run.
    • Each Node represents a single attempt (a script and its result) and is linked to its parent, forming the solution tree.
    • The Journal provides helper methods to query the state of the search, such as get_best_node(), buggy_nodes, and good_nodes.

  5. LLM Backend (aide/backend/)

    • This is a modular interface for communicating with various LLM providers.
    • The __init__.py file contains a provider-agnostic query function that automatically routes requests to the correct backend based on the model name (e.g., gpt-, claude-).
    • It currently supports OpenAI, Anthropic, Gemini, and OpenRouter, making the agent model-neutral.
    • It handles prompt compilation, API-specific formatting (like function calling/tool use), and backoff/retry logic for API requests.

Workflow

A typical run proceeds as follows:

  1. The Runner initializes the Agent, Interpreter, and an empty Journal.
  2. The Runner enters a loop for the configured number of steps.
  3. In each step, the Agent's search_policy selects a parent node (or None to draft).
  4. The Agent generates a new plan and code, creating a new Node.
  5. The new Node's code is passed to the Interpreter for execution.
  6. The ExecutionResult is returned to the Agent.
  7. The Agent uses the LLM Backend to analyze the result, extracting a metric and generating analysis.
  8. The fully populated Node is appended to the Journal.
  9. The Runner saves the updated journal and visualization, and the loop continues.