# wecoai/aideml architecture

> Architecture diagram of the GitHub repository wecoai/aideml, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wecoai/aideml
- Repository: https://github.com/wecoai/aideml

## Overview

##### Project Type and Purpose
- AIDE is an AI-driven agent focused on solving machine learning tasks by generating and iteratively refining code solutions from natural language descriptions. Its purpose is to empower data scientists by automating the end-to-end process of building ML pipelines—from code generation to testing, evaluation, and visualization.
- The README emphasizes multiple usage modes (web UI, command line, Docker) as well as different ways to run experiments. It also describes a unique “Solution Space Tree Search” process, which involves generating solution drafts, evaluating them, and selecting the best solution.

##### File Structure
- The core source code lies in the “aide” directory. Notice subdirectories like “backend” for integration with external APIs (OpenAI, Anthropic, Openrouter), “example_tasks” which serve as real-world data science challenges, and “utils” (for configuration, data preview, serialization, visualization templates) which support the agent’s operations.
- The “webui” subdirectory clearly contains all files (app.py, style.css) for the Streamlit-based interactive interface.
- Files such as “run.py”, “interpreter.py”, “journal.py”, and “journal2report.py” indicate modules that drive the iterative experimentation cycles and logging of solution attempts.
- Additional directories like “sample_results” hold outcomes or sample scripts from previous experiments, which could be thought of as artifacts or user examples.

a. Components to Include:
- User Interaction Components:
- Web UI (Streamlit-based, located in aide/webui)
- CLI Interface (run via aide/run.py with command line options)
- Core Engine Components:
- Agent Module (agent.py): The main orchestrator that takes in task descriptions and drives the iterative code generation.
- Backend Communication (aide/backend): Contains modules like backend_anthropic.py, backend_openai.py, and backend_openrouter.py to interface with different LLM providers.
- Interpreter and Evaluator (interpreter.py, journal.py, journal2report.py): Which manage the code execution, logging, and iterative improvements via the “Solution Space Tree Search”.
- Support and Utility Components:
- Utilities (aide/utils): Handles configurations (config.py and config.yaml), data preview, serialization of results, and visualization templates (viz_templates) for rendering the solution tree.
- Example Tasks (aide/example_tasks): Provide sample datasets and task descriptions to test the agent.
- External Interfacing and Deployment:
- Dockerfile and related configuration (.dockerignore, .github workflows): Indicating containerization and automated workflows for CI/CD.
- Environment variables and configuration (via README instructions): For API keys, local LLM setups, etc.
- Data Persistence and Logging:
- The logs and workspaces directories are used to store experiment metadata, best solution code, and visualization outputs.

b. Relationships and Interactions:
- User inputs their ML task description through the Web UI or CLI.
- The Agent receives the task and, via its backend modules, calls external LLMs (using the appropriate API based on configuration) to generate draft solutions.
- The Interpreter executes generated code, while the Evaluator (part of the journal modules) logs results and metrics.
- The iterative “Solution Space Tree Search” mechanism refines the solutions by using a feedback loop provided by the Evaluator and a selector mechanism embedded within the agent.
- Finally, final best solutions and experiments are stored in logs/workspaces for later review and possible export.

c. Architectural Patterns and Design Principles:
- Modular design is evident in the separation of concerns among UI, backend processing, evaluation, and utility functions.
- The iterative refinement pattern (as seen in the “Solution Space Tree Search”) highlights a feedback loop where code is repeatedly improved based on evaluation metrics.
- Clear separation between interface layers (Web UI, CLI) and processing modules (agent, backend communication, interpreter) aids in both maintainability and scalability.
- Use of configuration files and environment variables demonstrates the flexibility in deploying both cloud-based and local LLM setups.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interaction"
        UI["Web UI"]:::ui
        CLI["CLI Interface"]:::ui
    end

    subgraph "Core Engine"
        AGENT["Agent Module"]:::core
        BACKEND["Backend Communication"]:::core
        INTERPRETER["Interpreter & Evaluator"]:::core
    end

    subgraph "Support & Utilities"
        UTIL["Utilities & Visualization"]:::support
        EXTASK["Example Tasks"]:::support
    end

    subgraph "Deployment"
        DEPLOY["Containerization & CI/CD"]:::deploy
    end

    LOGS["Data Persistence & Logging"]:::logging
    EXTERNAL["External LLM Providers"]:::external

    UI -->|"sends_task"| AGENT
    CLI -->|"sends_task"| AGENT

    AGENT -->|"calls_API"| BACKEND
    BACKEND -->|"queries"| EXTERNAL
    EXTERNAL -->|"returns_response"| BACKEND

    AGENT -->|"generates_solution"| INTERPRETER
    INTERPRETER -->|"logs_results"| AGENT

    AGENT -->|"stores_outcomes"| LOGS
    INTERPRETER -->|"stores_logs"| LOGS

    UTIL -->|"renders_visuals"| LOGS
    AGENT -->|"fetches_config"| UTIL
    BACKEND -->|"uses_config"| UTIL

    AGENT -->|"uses_tasks"| EXTASK

    %% Styles
    classDef ui fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef support fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef deploy fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef logging fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;

    %% Click Events
    click UI "https://github.com/wecoai/aideml/blob/main/aide/webui/app.py"
    click UI "https://github.com/wecoai/aideml/blob/main/aide/webui/style.css"
    click CLI "https://github.com/wecoai/aideml/blob/main/aide/run.py"
    click AGENT "https://github.com/wecoai/aideml/blob/main/aide/agent.py"
    click BACKEND "https://github.com/wecoai/aideml/tree/main/aide/backend"
    click INTERPRETER "https://github.com/wecoai/aideml/blob/main/aide/interpreter.py"
    click INTERPRETER "https://github.com/wecoai/aideml/blob/main/aide/journal.py"
    click INTERPRETER "https://github.com/wecoai/aideml/blob/main/aide/journal2report.py"
    click UTIL "https://github.com/wecoai/aideml/tree/main/aide/utils"
    click UTIL "https://github.com/wecoai/aideml/tree/main/aide/utils/viz_templates"
    click EXTASK "https://github.com/wecoai/aideml/tree/main/aide/example_tasks"
    click DEPLOY "https://github.com/wecoai/aideml/tree/main/Dockerfile"
    click DEPLOY "https://github.com/wecoai/aideml/blob/main/.dockerignore"
    click DEPLOY "https://github.com/wecoai/aideml/blob/main/.github"
```
