# jennyzzt/dgm architecture

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

- Interactive diagram: https://gitdiagram.com/jennyzzt/dgm
- Repository: https://github.com/jennyzzt/dgm

## Overview

##### Project Type and Purpose
- This is a command-line, self-improving AI system (“Darwin Gödel Machine”) written in Python.
- It orchestrates an open-ended evolution loop: an LLM-based agent proposes code patches to itself, those patches are sandbox-tested via Docker against two benchmarks (SWE-bench and Polyglot), and performance data feeds back to drive further improvements.

##### High-Level Components
A. DGM Controller
- **DGM_outer.py**: the main entry point. Coordinates the self-improvement loop.
- **self_improve_step.py**: encapsulates one iteration: request patch, apply patch, evaluate, log results.
B. LLM Agent
- **coding_agent.py** & **coding_agent_polyglot.py**: implement the logic for the initial agent in each domain.
- **llm.py** & **llm_withtools.py**: wrap calls to OpenAI/Anthropic APIs and expose tool-use abstractions.
- **prompts/**: modular prompt templates used by the agent (e.g., `testrepo_prompt.py`, `diagnose_improvement_prompt.py`).
- **tools/**: Python implementations of “tools” the agent can invoke in-prompt (e.g., `bash.py`, `edit.py`).
C. Sandbox & Evaluation
- **Docker orchestration**:
- `polyglot/docker_build.py`, `polyglot/docker_utils.py`, `utils/docker_utils.py` build and manage containers.
- Individual patch evaluations run in isolated containers to protect the host.
- **Benchmark harnesses**:
- `swe_bench/harness.py` and its `ref_agent_results/` for SWE-bench tasks.
- `polyglot/harness.py` for Polyglot tasks.
- **Logging & Data**:
- `initial/` and `initial_polyglot/`: baseline run logs, patch diffs, reports, and predictions.
- Predictions in JSON/MD plus Docker logs and eval scripts.
D. Analysis & Visualization
- **analysis/**: scripts (`plot_comparison.py`, `plot_progress.py`, `visualize_archive.py`) to process logs and generate charts.
E. Utilities
- **utils/**: shared helper code (`common_utils.py`, `eval_utils.py`, `git_utils.py`, `evo_utils.py`, `swe_log_parsers.py`).
- **polyglot/**: dataset preparation and evaluation orchestration (`prepare_polyglot_dataset.py`, `run_evaluation.py`).
F. Testing & CI
- **tests/**: Pytest tests for tool wrappers and end-to-end DGM functionality (`test_swebench.py`, `test_bash_tool.py`, etc.).
- **pytest.ini**, **requirements.txt**, **Dockerfile** for reproducible environment setup.

##### Component Interactions & Data Flow
- **Control Flow (DGM_outer)** → invokes **self_improve_step**
↳ calls **LLM Agent** → uses **prompts** & **tools** → returns **patch.diff**
↳ applies patch (via **git_utils.py**) to sandbox copy of the code
↳ spins up **Docker containers** (via **docker_utils**)
- Runs **swe_bench/harness** and **polyglot/harness** in separate containers
- Produces test coverage, performance metrics, logs, and reports
↳ collects results (using **eval_utils**, **swe_log_parsers**)
↳ writes logs/metrics to filesystem under `output_dgm/` (and initial folders)
↳ loop repeats until termination condition
- **Analysis scripts** read these logs to generate final plots and archives.

##### Architectural Patterns & Design Principles
- **Modular CLI services**: clear separation between the DGM controller, LLM agent, evaluation harnesses, and analysis.
- **Sandboxing** with Docker: ensures safety when executing untrusted, model-generated code.
- **Tool abstractions** for prompting: agents see standardized “tools” to inspect files or run shell commands.
- **Benchmark plugins**: SWE-bench and Polyglot harnesses plug into the same evaluation interface, making the system extensible to new benchmarks.
- **Data-driven loop**: each iteration feeds results back into the next, embodying self-improving, evolutionary principles.

##### Technologies & Frameworks
- Python 3.8+; uses virtual environments.
- LLM APIs: OpenAI, Anthropic (via `llm.py`).
- Docker for isolation.
- Pytest for testing.
- Graphviz (optional) for analysis visuals.

##### Essential Elements
- Clear component names and boundaries
- External dependencies (LLM endpoints, Docker)
- Storage areas for logs, predictions, archives

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Controller Layer"
        direction TB
        DGM_outer["DGM_outer.py"]:::core
        self_step["self_improve_step.py"]:::core
    end

    subgraph "Agent/LLM Layer"
        direction TB
        coding_agent["coding_agent.py"]:::core
        coding_agent_poly["coding_agent_polyglot.py"]:::core
        llm["llm.py"]:::core
        llm_tools["llm_withtools.py"]:::core
        subgraph "Prompts"
            direction TB
            pr1["testrepo_prompt.py"]:::core
            pr2["diagnose_improvement_prompt.py"]:::core
            pr3["self_improvement_prompt.py"]:::core
            pr4["tooluse_prompt.py"]:::core
        end
        subgraph "Tools"
            direction TB
            t1["bash.py"]:::core
            t2["edit.py"]:::core
        end
        LLM_API(("LLM APIs")):::external
    end

    subgraph "Sandbox & Evaluation Layer"
        direction TB
        Docker(("Docker")):::external
        subgraph "Docker Orchestration"
            direction TB
            dbuild["polyglot/docker_build.py"]:::eval
            dutils1["polyglot/docker_utils.py"]:::eval
            dutils2["utils/docker_utils.py"]:::eval
        end
        subgraph "Polyglot Benchmark"
            direction TB
            phar["polyglot/harness.py"]:::eval
            pev["polyglot/run_evaluation.py"]:::eval
        end
        subgraph "SWE-bench Benchmark"
            direction TB
            shar["swe_bench/harness.py"]:::eval
            shref["swe_bench/ref_agent_results/"]:::eval
        end
    end

    subgraph "Data Storage Layer"
        direction TB
        storage["output_dgm/, initial/, initial_polyglot/"]:::storage
    end

    subgraph "Analysis Layer"
        direction TB
        a1["plot_comparison.py"]:::analysis
        a2["plot_progress.py"]:::analysis
        a3["visualize_archive.py"]:::analysis
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        u1["common_utils.py"]:::core
        u2["eval_utils.py"]:::core
        u3["git_utils.py"]:::core
        u4["evo_utils.py"]:::core
        u5["swe_log_parsers.py"]:::core
    end

    %% Dataset Preparation
    ppd["prepare_polyglot_dataset.py"]:::core

    %% Testing & CI
    subgraph "Testing & CI"
        direction TB
        tconf["tests/conftest.py"]:::core
        tbt["tests/test_bash_tool.py"]:::core
        tet["tests/test_edit_tool.py"]:::core
        tsw["tests/test_swebench.py"]:::core
        pytestini["pytest.ini"]:::core
        req["requirements.txt"]:::core
        reqd["requirements_dev.txt"]:::core
        df["Dockerfile"]:::core
    end

    %% Connections
    DGM_outer -->|"invokes"| self_step
    self_step -->|"request patch"| coding_agent
    self_step -->|"request patch"| coding_agent_poly
    coding_agent -->|"uses prompts/tools"| pr1
    coding_agent --> pr2
    coding_agent --> pr3
    coding_agent --> pr4
    coding_agent --> t1
    coding_agent --> t2
    coding_agent_poly --> pr1
    coding_agent_poly --> pr2
    coding_agent_poly --> pr3
    coding_agent_poly --> pr4
    coding_agent_poly --> t1
    coding_agent_poly --> t2
    coding_agent -->|"calls LLM"| llm
    coding_agent_poly --> llm
    llm_tools -->|"wraps"| llm
    llm -->|"API calls"| LLM_API
    self_step -->|"apply patch & sandbox"| Docker
    Docker --> dbuild
    Docker --> dutils1
    Docker --> dutils2
    Docker --> phar
    Docker --> pev
    Docker --> shar
    Docker --> shref
    phar -->|"produces metrics"| storage
    shar --> storage
    pev --> storage
    storage -->|"feedback data"| self_step
    storage --> a1
    storage --> a2
    storage --> a3
    self_step --> u3
    self_step --> u2
    self_step --> u5
    Docker --> u1
    Docker --> u4
    ppd --> pev
    tests_links --> df
    tests_links --> pytestini
    tests_links --> req
    tests_links --> reqd

    %% Click Events
    click DGM_outer "https://github.com/jennyzzt/dgm/blob/main/DGM_outer.py"
    click self_step "https://github.com/jennyzzt/dgm/blob/main/self_improve_step.py"
    click coding_agent "https://github.com/jennyzzt/dgm/blob/main/coding_agent.py"
    click coding_agent_poly "https://github.com/jennyzzt/dgm/blob/main/coding_agent_polyglot.py"
    click llm "https://github.com/jennyzzt/dgm/blob/main/llm.py"
    click llm_tools "https://github.com/jennyzzt/dgm/blob/main/llm_withtools.py"
    click pr1 "https://github.com/jennyzzt/dgm/blob/main/prompts/testrepo_prompt.py"
    click pr2 "https://github.com/jennyzzt/dgm/blob/main/prompts/diagnose_improvement_prompt.py"
    click pr3 "https://github.com/jennyzzt/dgm/blob/main/prompts/self_improvement_prompt.py"
    click pr4 "https://github.com/jennyzzt/dgm/blob/main/prompts/tooluse_prompt.py"
    click t1 "https://github.com/jennyzzt/dgm/blob/main/tools/bash.py"
    click t2 "https://github.com/jennyzzt/dgm/blob/main/tools/edit.py"
    click dbuild "https://github.com/jennyzzt/dgm/blob/main/polyglot/docker_build.py"
    click dutils1 "https://github.com/jennyzzt/dgm/blob/main/polyglot/docker_utils.py"
    click dutils2 "https://github.com/jennyzzt/dgm/blob/main/utils/docker_utils.py"
    click phar "https://github.com/jennyzzt/dgm/blob/main/polyglot/harness.py"
    click pev "https://github.com/jennyzzt/dgm/blob/main/polyglot/run_evaluation.py"
    click shar "https://github.com/jennyzzt/dgm/blob/main/swe_bench/harness.py"
    click shref "https://github.com/jennyzzt/dgm/tree/main/swe_bench/ref_agent_results/"
    click a1 "https://github.com/jennyzzt/dgm/blob/main/analysis/plot_comparison.py"
    click a2 "https://github.com/jennyzzt/dgm/blob/main/analysis/plot_progress.py"
    click a3 "https://github.com/jennyzzt/dgm/blob/main/analysis/visualize_archive.py"
    click u1 "https://github.com/jennyzzt/dgm/blob/main/utils/common_utils.py"
    click u2 "https://github.com/jennyzzt/dgm/blob/main/utils/eval_utils.py"
    click u3 "https://github.com/jennyzzt/dgm/blob/main/utils/git_utils.py"
    click u4 "https://github.com/jennyzzt/dgm/blob/main/utils/evo_utils.py"
    click u5 "https://github.com/jennyzzt/dgm/blob/main/utils/swe_log_parsers.py"
    click ppd "https://github.com/jennyzzt/dgm/blob/main/polyglot/prepare_polyglot_dataset.py"
    click tconf "https://github.com/jennyzzt/dgm/blob/main/tests/conftest.py"
    click tbt "https://github.com/jennyzzt/dgm/blob/main/tests/test_bash_tool.py"
    click tet "https://github.com/jennyzzt/dgm/blob/main/tests/test_edit_tool.py"
    click tsw "https://github.com/jennyzzt/dgm/blob/main/tests/test_swebench.py"
    click pytestini "https://github.com/jennyzzt/dgm/blob/main/pytest.ini"
    click req "https://github.com/jennyzzt/dgm/blob/main/requirements.txt"
    click reqd "https://github.com/jennyzzt/dgm/blob/main/requirements_dev.txt"
    click df "https://github.com/jennyzzt/dgm/tree/main/Dockerfile"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#90EE90,stroke:#000,stroke-width:1px
    classDef eval fill:#FFA500,stroke:#000,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef analysis fill:#E6E6FA,stroke:#000,stroke-width:1px
```
