# mlsysops/mle-agent architecture

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

- Interactive diagram: https://gitdiagram.com/mlsysops/mle-agent
- Repository: https://github.com/mlsysops/mle-agent

## Overview

##### Project type and purpose
- This is a full-stack AI-assistant application (“MLE-Agent”) combining:
- A Python core library (the “mle” package) implementing autonomous multi-agent workflows for ML engineering tasks.
- A CLI interface (`mle` commands) for interactive and automated pipelines (baseline creation, Kaggle competitions, reporting).
- A backend server (in `mle/server/app.py`) exposing API endpoints.
- A Next.js + Tailwind CSS web frontend (in `web/`) for report generation and possibly chat.
- Integrations with external services: LLM providers (OpenAI, Anthropic, Gemini, etc.), Kaggle, GitHub, Google Calendar, Papers with Code/Arxiv.

##### File structure
- Top-level crates:
- `.github/`, `tests/`, `assets/`, `README.md`, `setup.py`, etc.
- `mle/`: the Python library
‑ `agents/`: strategies (advisor, planner, coder, debugger, summarizer, reporter, chat)
‑ `function/`: domain-specific helper functions (data I/O, execution, search, interaction)
‑ `integration/`: connectors to GitHub, Kaggle, Google Calendar, local git
‑ `model/`: wrappers around LLM endpoints/providers (OpenAI, Anthropic, Mistral, Gemini, VLLM, etc.)
‑ `workflow/`: orchestrations for chat, Kaggle tasks, report generation, baseline workflows
‑ `server/`: the HTTP server entrypoint and routes
‑ `cli.py`: CLI command definitions and argument parsing
‑ `utils/`: caching, parsing, memory, system utilities
- `web/`: Next.js frontend
‑ `web/app/`: React components and pages (`layout.tsx`, `page.tsx`)
‑ config files (`next.config.mjs`, `tailwind.config.ts`, `tsconfig.json`, etc.)

##### README for additional insights
- Describes key features: autonomous baseline build, end-to-end Kaggle participation, web + CLI report generation, interactive chat, smart debugging, advisor recommendations.
- Lists commands (`mle start`, `mle chat`, `mle report`, `mle kaggle`) and web UI on `http://localhost:3000/`.
- Highlights external integrations and LLM providers.

##### Main components & interactions
a. Presentation Layer
1. CLI Client (“mle” commands) – Python entrypoint invoking `cli.py`.
2. Web UI – Next.js frontend served on port 3000.
b. Application Layer
3. Python HTTP Server – FastAPI/Flask app in `mle/server/app.py` (serves REST or WebSocket for chat & reporting).
c. Domain Logic Layer (Python Library)
4. Agent Orchestrator – picks and coordinates Agents (advisor, planner, coder, debugger, summarizer, reporter, chat).
5. Workflow Engine – end-to-end flows (baseline, Kaggle, report, chat).
d. Services Layer
6. Function Modules – data I/O, code execution, file system operations.
7. Integration Modules – connectors for GitHub, Kaggle, Google Calendar, local git, web search (Arxiv, Papers with Code).
8. Model Modules – interface to LLM providers (OpenAI, Anthropic, Mistral, Gemini, VLLM, Ollama).
e. Infrastructure & External Systems
9. External APIs – LLM endpoints, Kaggle competition API, GitHub API, Google Calendar API, web search APIs.
10. Local Resources – local file system, local Python environment, cache store.

##### Relationships & data flows
- CLI → Python Library: invokes workflows and agents directly.
- Web UI → HTTP Server → Python Library: web requests map to workflows/agents.
- Agent Orchestrator ↔ Model Modules: sends prompts and receives LLM responses.
- Agents ↔ Function Modules: calls code execution, file operations, search.
- Agents ↔ Integration Modules: fetches external data (competition data, calendar events, GitHub commits).
- Workflow Engine → Agents: orchestrates sequential or parallel agent interactions.
- Caching & Utils support all layers for performance and parsing.

##### Architectural patterns & design principles
- Layered architecture: Presentation → Application → Domain Logic → Infrastructure.
- Plugin-style extensibility: Model and integration modules register new providers/connectors.
- Multi-agent orchestration: each agent encapsulates a specialized role.
- Clear separation of concerns: workflows define “what to do,” agents define “how to do it,” integrations handle I/O.

##### Technologies & frameworks to annotate
- Python: FastAPI/Flask (server), Click/argparse (CLI), pytest (tests).
- JavaScript/TypeScript: Next.js (web frontend), Tailwind CSS.
- LLM SDKs: openai-python, anthropic-sdk, vllm.
- CI/CD: GitHub Actions (lint, test, publish workflows).

##### Essential elements
- Clear labels on every component.
- Notes on key technologies (e.g., “Next.js,” “FastAPI,” “OpenAI API”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI["CLI Client"]:::presentation
        subgraph "Web UI"
            Layout["layout.tsx"]:::presentation
            Page["page.tsx"]:::presentation
            Config["next.config.mjs<br/>tailwind.config.ts<br/>tsconfig.json"]:::presentation
        end
    end

    %% Application Layer
    subgraph "Application Layer"
        Server["HTTP Server (FastAPI/Flask)"]:::application
    end

    %% Domain Logic Layer
    subgraph "Domain Logic Layer"
        subgraph "Agent Modules"
            Advisor["Advisor Agent"]:::domain
            Planner["Planner Agent"]:::domain
            Coder["Coder Agent"]:::domain
            Debugger["Debugger Agent"]:::domain
            Summarizer["Summarizer Agent"]:::domain
            ReporterAgent["Reporter Agent"]:::domain
            ChatAgent["Chat Agent"]:::domain
        end
        subgraph "Workflow Engine"
            BaselineWF["Baseline Workflow"]:::domain
            ChatWF["Chat Workflow"]:::domain
            KaggleWF["Kaggle Workflow"]:::domain
            ReportWF["Report Workflow"]:::domain
        end
    end

    %% Services Layer
    subgraph "Services Layer"
        subgraph "Function Modules"
            DataFn["Data I/O"]:::service
            ExecFn["Execution"]:::service
            FilesFn["File Ops"]:::service
            InteractionFn["Interaction"]:::service
            SearchFn["Search"]:::service
        end
        subgraph "Integration Modules"
            GitHubInt["GitHub"]:::service
            KaggleInt["Kaggle"]:::service
            CalendarInt["Google Calendar"]:::service
            GitInt["Local Git"]:::service
        end
        subgraph "Model Modules"
            OpenAI["OpenAI"]:::service
            Anthropic["Anthropic"]:::service
            Mistral["Mistral"]:::service
            Gemini["Gemini"]:::service
            VLLM["VLLM"]:::service
            Ollama["Ollama"]:::service
            Deepseek["Deepseek"]:::service
        end
    end

    %% Infrastructure & External
    subgraph "Infrastructure & External"
        ExternalLLM["External LLM APIs"]:::external
        ExternalKaggle["Kaggle API"]:::external
        ExternalGitHub["GitHub API"]:::external
        ExternalCalendar["Google Calendar API"]:::external
        ExtSearch["Web Search APIs"]:::external
        LocalFS["Local File System / Cache"]:::external
    end

    %% Utilities & Version
    Utils["Utilities & Caching"]:::utility
    Version["Versioning"]:::utility

    %% Relationships
    CLI -->|"invokes workflows"| BaselineWF
    CLI -->|"invokes workflows"| ChatWF
    CLI -->|"invokes workflows"| KaggleWF
    CLI -->|"invokes workflows"| ReportWF
    CLI -->|"CLI command"| Server

    Layout -->|"HTTP/JSON"| Server
    Page -->|"HTTP/JSON"| Server
    Config -->|"HTTP/JSON"| Server

    Server -->|"calls"| BaselineWF
    Server -->|"calls"| ChatWF
    Server -->|"calls"| KaggleWF
    Server -->|"calls"| ReportWF

    BaselineWF -->|"orchestrates"| Advisor
    ChatWF -->|"orchestrates"| ChatAgent
    KaggleWF -->|"orchestrates"| Planner
    ReportWF -->|"orchestrates"| ReporterAgent

    Advisor -->|"uses"| DataFn
    Planner -->|"uses"| ExecFn
    Coder -->|"uses"| FilesFn
    Debugger -->|"uses"| InteractionFn
    Summarizer -->|"uses"| SearchFn

    Advisor -->|"integrates"| GitHubInt
    Planner -->|"integrates"| KaggleInt
    Coder -->|"integrates"| CalendarInt
    Debugger -->|"integrates"| GitInt

    Advisor -->|"prompts"| OpenAI
    Planner -->|"prompts"| Anthropic
    Coder -->|"prompts"| Mistral
    Debugger -->|"prompts"| Gemini
    Summarizer -->|"prompts"| VLLM
    ReporterAgent -->|"prompts"| Ollama
    ChatAgent -->|"prompts"| Deepseek

    OpenAI -->|"API"| ExternalLLM
    Anthropic -->|"API"| ExternalLLM
    Mistral -->|"API"| ExternalLLM
    Gemini -->|"API"| ExternalLLM
    VLLM -->|"API"| ExternalLLM
    Ollama -->|"API"| ExternalLLM
    Deepseek -->|"API"| ExternalLLM

    GitHubInt -->|"REST API"| ExternalGitHub
    KaggleInt -->|"REST API"| ExternalKaggle
    CalendarInt -->|"REST API"| ExternalCalendar
    GitInt -->|"FS ops"| LocalFS

    DataFn -->|"file I/O"| LocalFS
    ExecFn -->|"exec"| LocalFS
    FilesFn -->|"fs ops"| LocalFS
    InteractionFn -->|"network"| ExtSearch
    SearchFn -->|"web API"| ExtSearch

    Utils -.-> CLI
    Utils -.-> Server
    Utils -.-> Advisor
    Utils -.-> BaselineWF

    Version -.-> CLI
    Version -.-> Server
    Version -.-> BaselineWF

    %% Click Events
    click CLI "https://github.com/mlsysops/mle-agent/blob/main/mle/cli.py"
    click Layout "https://github.com/mlsysops/mle-agent/blob/main/web/app/layout.tsx"
    click Page "https://github.com/mlsysops/mle-agent/blob/main/web/app/page.tsx"
    click Config "https://github.com/mlsysops/mle-agent/blob/main/web/next.config.mjs"
    click Server "https://github.com/mlsysops/mle-agent/blob/main/mle/server/app.py"
    click Advisor "https://github.com/mlsysops/mle-agent/blob/main/mle/agents/advisor.py"
    click Planner "https://github.com/mlsysops/mle-agent/blob/main/mle/agents/planner.py"
    click Coder "https://github.com/mlsysops/mle-agent/blob/main/mle/agents/coder.py"
    click Debugger "https://github.com/mlsysops/mle-agent/blob/main/mle/agents/debugger.py"
    click Summarizer "https://github.com/mlsysops/mle-agent/blob/main/mle/agents/summarizer.py"
    click ReporterAgent "https://github.com/mlsysops/mle-agent/blob/main/mle/agents/reporter.py"
    click ChatAgent "https://github.com/mlsysops/mle-agent/blob/main/mle/agents/chat.py"
    click BaselineWF "https://github.com/mlsysops/mle-agent/blob/main/mle/workflow/baseline.py"
    click ChatWF "https://github.com/mlsysops/mle-agent/blob/main/mle/workflow/chat.py"
    click KaggleWF "https://github.com/mlsysops/mle-agent/blob/main/mle/workflow/kaggle.py"
    click ReportWF "https://github.com/mlsysops/mle-agent/blob/main/mle/workflow/report.py"
    click DataFn "https://github.com/mlsysops/mle-agent/blob/main/mle/function/data.py"
    click ExecFn "https://github.com/mlsysops/mle-agent/blob/main/mle/function/execution.py"
    click FilesFn "https://github.com/mlsysops/mle-agent/blob/main/mle/function/files.py"
    click InteractionFn "https://github.com/mlsysops/mle-agent/blob/main/mle/function/interaction.py"
    click SearchFn "https://github.com/mlsysops/mle-agent/blob/main/mle/function/search.py"
    click GitHubInt "https://github.com/mlsysops/mle-agent/blob/main/mle/integration/github.py"
    click KaggleInt "https://github.com/mlsysops/mle-agent/blob/main/mle/integration/kaggle.py"
    click CalendarInt "https://github.com/mlsysops/mle-agent/blob/main/mle/integration/google_calendar.py"
    click GitInt "https://github.com/mlsysops/mle-agent/blob/main/mle/integration/local_git.py"
    click OpenAI "https://github.com/mlsysops/mle-agent/blob/main/mle/model/openai.py"
    click Anthropic "https://github.com/mlsysops/mle-agent/blob/main/mle/model/anthropic.py"
    click Mistral "https://github.com/mlsysops/mle-agent/blob/main/mle/model/mistral.py"
    click Gemini "https://github.com/mlsysops/mle-agent/blob/main/mle/model/gemini.py"
    click VLLM "https://github.com/mlsysops/mle-agent/blob/main/mle/model/vllm.py"
    click Ollama "https://github.com/mlsysops/mle-agent/blob/main/mle/model/ollama.py"
    click Deepseek "https://github.com/mlsysops/mle-agent/blob/main/mle/model/deepseek.py"

    %% Styles
    classDef presentation fill:#acf,stroke:#069,stroke-width:2px
    classDef application fill:#cfc,stroke:#393,stroke-width:2px
    classDef domain fill:#ffc,stroke:#aa0,stroke-width:2px
    classDef service fill:#fcf,stroke:#939,stroke-width:2px
    classDef external fill:#eee,stroke:#666,stroke-width:2px,stroke-dasharray: 3 3
    classDef utility fill:#ddd,stroke:#666,stroke-width:1px,stroke-dasharray: 2 2
```
