# lean-dojo/leanagent architecture

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

- Interactive diagram: https://gitdiagram.com/lean-dojo/leanagent
- Repository: https://github.com/lean-dojo/leanagent

## Overview

##### Main Blocks
- Repository Management & Data Extraction: This block (documented in both README and file comments in leanagent.py) covers:
- Repository selection (checking for supported Lean versions)
- Tracing and parsing of Lean files (using functions inside repository management and trace modules)
- Extraction of theorem statements and proofs.
- Dynamic Database Management: Create a clearly labeled block representing the custom JSON-based database that holds:
- Metadata for repositories, theorems, premises, and files.
- Methods for serialization (to_dict/from_dict) and updating through new extractions.
- Curriculum Learning & Progressive Training: Show a pipeline block that:
- Uses complexity analysis (curriculum based on theorem difficulty) to schedule training.
- Dynamically trains the Tactic Generator and Retriever (modules in the generator and retrieval folders) using progressive epochs.
- Integrates evaluation metrics like recall@10.
- The “Prover” module (files in the prover folder like proof_search.py and search_tree.py) using best-first tree search.
- The workflow starting with retrieving relevant premises, generating tactic candidates (using beam search), and then applying Lean for proof checking.
- The feedback mechanism that sends successful proofs back to the Dynamic Database and even generates pull requests.
- Fisher Information Matrix (FIM) Computation for EWC: Include an auxiliary component that is executed (via compute_fisher.py and run_compute_fisher.sh) to compute gradients and scale them for EWC regularization during training.

##### Out the Relationships & Data Flow
- The Curriculum Learning block (which “schedules” or “retrieves” the proper data splits based on complexity),
- And the retrieval training pipeline.

##### Architectural Patterns & Technologies
- Modular separation:
- "Generator" for data extraction and dataset generation.
- "Retrieval" for training the retrieval model using BM25 and related models.
- "Prover" for design-specific proof search and tree navigation.
- That the system follows a pipeline/microservices-style architecture within the codebase where each standalone component (with distinct directories) interacts with others via clearly defined interfaces.
- Signal the use of distributed processing tools such as Ray for distributed computation and PyTorch Lightning for multi-GPU training (DDP), which can be shown as annotations or side notes on the training/compute sections.
- You may also denote that external processes (e.g., GitHub API calls, Lean toolchain invocations) are part of the data extraction and proof execution stages.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment Setup & External Dependencies
    EnvSetup["Environment Setup & Configuration"]:::setup
    ExtDeps["External Dependencies"]:::external

    %% Repository Management & Data Extraction
    RepoManage["Repository Management & Data Extraction"]:::data

    %% Dynamic Database Management
    DynDB["Dynamic Database Management"]:::db

    %% Curriculum Learning & Progressive Training Subgraph
    subgraph "Curriculum Learning & Progressive Training"
        Generator["Generator Module"]:::trainSub
        Retrieval["Retrieval Module"]:::trainSub
        CustomProgress["Custom Progress Module"]:::trainSub
    end

    %% Fisher Information Matrix Computation for EWC
    FIM["Fisher Information Matrix (FIM) Computation"]:::fim

    %% Theorem Proving / Proof Search Subgraph
    subgraph "Theorem Proving / Proof Search"
        ProverModule["Prover Module"]:::proverSub
    end

    %% Connections & Data Flow
    EnvSetup -->|"bootstrap"| RepoManage
    ExtDeps -->|"support"| RepoManage
    RepoManage -->|"ExtractTheoremData"| DynDB
    DynDB -->|"ScheduleData"| Retrieval
    DynDB <-->|"DataUpdate"| Generator
    DynDB <-->|"DataUpdate"| Retrieval
    Generator -->|"SendProgressData"| CustomProgress
    CustomProgress -->|"MonitorProgress"| Generator
    Generator -->|"TrainingEpoch"| FIM
    FIM -->|"ApplyFIM"| Generator
    Retrieval -->|"RetrieveTop-KPremises"| ProverModule
    ProverModule -->|"SuccessfulProofFeedback"| DynDB

    %% Click Events for Environment Setup & Configuration
    click EnvSetup "https://github.com/lean-dojo/leanagent/blob/main/run_leanagent.sh"
    click EnvSetup "https://github.com/lean-dojo/leanagent/blob/main/run_compute_fisher.sh"
    click EnvSetup "https://github.com/lean-dojo/leanagent/blob/main/replace_files.sh"
    click EnvSetup "https://github.com/lean-dojo/leanagent/blob/main/requirements.txt"
    click EnvSetup "https://github.com/lean-dojo/leanagent/blob/main/README.md"

    %% Click Events for Repository Management & Data Extraction
    click RepoManage "https://github.com/lean-dojo/leanagent/blob/main/leanagent.py"
    click RepoManage "https://github.com/lean-dojo/leanagent/blob/main/custom_traced_data.py"
    click RepoManage "https://github.com/lean-dojo/leanagent/blob/main/generate_benchmark_lean4.py"
    click RepoManage "https://github.com/lean-dojo/leanagent/blob/main/common.py"

    %% Click Events for Dynamic Database Management
    click DynDB "https://github.com/lean-dojo/leanagent/blob/main/dynamic_database.py"
    click DynDB "https://github.com/lean-dojo/leanagent/blob/main/unittest_dynamic_database.py"

    %% Click Events for Generator Module
    click Generator "https://github.com/lean-dojo/leanagent/blob/main/generator/main.py"
    click Generator "https://github.com/lean-dojo/leanagent/blob/main/generator/datamodule.py"
    click Generator "https://github.com/lean-dojo/leanagent/blob/main/generator/model.py"
    click Generator "https://github.com/lean-dojo/leanagent/tree/main/generator/confs/"

    %% Click Events for Retrieval Module
    click Retrieval "https://github.com/lean-dojo/leanagent/blob/main/retrieval/main.py"
    click Retrieval "https://github.com/lean-dojo/leanagent/blob/main/retrieval/datamodule.py"
    click Retrieval "https://github.com/lean-dojo/leanagent/tree/main/retrieval/confs/"
    click Retrieval "https://github.com/lean-dojo/leanagent/blob/main/retrieval/train_tokenizer.py"
    click Retrieval "https://github.com/lean-dojo/leanagent/blob/main/retrieval/index.py"

    %% Click Event for Custom Progress Module
    click CustomProgress "https://github.com/lean-dojo/leanagent/blob/main/custom_progress.py"

    %% Click Events for Prover Module
    click ProverModule "https://github.com/lean-dojo/leanagent/blob/main/prover/proof_search.py"
    click ProverModule "https://github.com/lean-dojo/leanagent/blob/main/prover/search_tree.py"
    click ProverModule "https://github.com/lean-dojo/leanagent/blob/main/prover/evaluate.py"

    %% Click Events for FIM Computation
    click FIM "https://github.com/lean-dojo/leanagent/blob/main/compute_fisher.py"
    click FIM "https://github.com/lean-dojo/leanagent/blob/main/retrieval/fisher_computation_module.py"
    click FIM "https://github.com/lean-dojo/leanagent/blob/main/run_compute_fisher.sh"

    %% Styles
    classDef setup fill:#f9c,stroke:#333,stroke-width:2px;
    classDef external fill:#bbf,stroke:#333,stroke-width:2px;
    classDef data fill:#ff9,stroke:#333,stroke-width:2px;
    classDef db fill:#9f9,stroke:#333,stroke-width:2px;
    classDef train fill:#fc9,stroke:#333,stroke-width:2px;
    classDef fim fill:#c9f,stroke:#333,stroke-width:2px;
    classDef prover fill:#f99,stroke:#333,stroke-width:2px;
    classDef trainSub fill:#fcf,stroke:#333,stroke-width:1px;
    classDef proverSub fill:#fcc,stroke:#333,stroke-width:1px;
```
