# lean-dojo/leancopilot architecture

> Architecture diagram of the GitHub repository lean-dojo/leancopilot, 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/leancopilot
- Repository: https://github.com/lean-dojo/leancopilot

## Overview

##### Main Components
- Core Lean Copilot Package: Represent the Lean code, including files like LeanCopilot.lean, LeanCopilot/Frontend.lean, LeanCopilot/Tactics.lean, and related option/configuration files. This part implements tactics such as suggest_tactics, search_proof, and select_premises.
- Model Infrastructure: Show the different model modules under LeanCopilot/Models, e.g., Builtin, ByT5, External, FFI, Generic, Interface, Native, and Registry. They are key in abstracting different “model types” (generators and encoders) and their APIs.
- Model Checkpoint Manager: Include the separate component (ModelCheckpointManager directory) that handles downloading and managing model checkpoint files.
- External Integration:
- C++ Integration: The cpp directory (with ct2.cpp and headers) provides C++ integration for native model inference with CTranslate2, used via Lean’s FFI.
- Python API Server: The python directory illustrates an external server component that wraps around various external models (see python/external_models/*) and exposes them using an API (supported by external_model_api.yaml).
- Build and Testing Infrastructure: Represent build tools and scripts (Dockerfile, .dockerignore, build scripts in scripts/, lakefile.lean and lake-manifest.json) as well as the test suite (LeanCopilotTests directory).

##### Detail the Relationships and Interactions
- That the Lean Copilot core acts as the orchestration layer:
- It calls the Model APIs (via abstract interfaces defined in the Models directory) to generate tactic suggestions, perform proof search, and select premises.
- There is a direct connection between the core tactics and the underlying model activations.
- Distinguish between the native and external model flows:
- Native flow: Illustrate that when using the native generators/encoders, Lean Copilot relies on FFI to interact with the C++ component (cpp/) and CTranslate2 libraries.
- Also, show the model checkpoint/management component that interacts with both native and external model lifecycles (e.g., downloading or updating checkpoints).

##### Architectural Patterns and Design Principles
- Modular design: The clear separation between core Lean tactics and model adapters (generator and encoder interfaces) suggests a layered design.
- Abstraction: Emphasize the use of typeclasses (e.g., TextToText, TextToVec) that enable plug-and-play of different models.
- Interoperability: Note the integration of Lean with external components in C++ (using FFI) and Python, showing a multi-language, multi-backend architecture.
- Testing and Continuous Integration: Include components that represent the test suites and CI configurations (.github/workflows).

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["Lean Theorem Prover"]:::lean
    CoreStatic["Lean Copilot Core Package"]:::lean
    ModelsStatic["Model Infrastructure"]:::models
    CheckpointStatic["Model Checkpoint Manager"]:::checkpoint
    CPPStatic["C++ Integration"]:::cpp
    PythonStatic["Python API Server"]:::python
    BuildStatic["Build & Testing Infrastructure"]:::build

    User -->|"invokes"| CoreStatic
    CoreStatic -->|"callsModelAPIs"| ModelsStatic
    ModelsStatic -->|"nativeFlow"| CPPStatic
    ModelsStatic -->|"externalFlow"| PythonStatic
    ModelsStatic -->|"checkpointMgmt"| CheckpointStatic
    CheckpointStatic -->|"updatesNative"| CPPStatic
    CheckpointStatic -->|"updatesExternal"| PythonStatic
    CoreStatic -->|"builtTestedBy"| BuildStatic

    subgraph "Lean Copilot Core Package Details"
        Core["Core: LeanCopilot.lean"]:::lean
        Frontend["Frontend: LeanCopilot/Frontend.lean"]:::lean
        Tactics["Tactics: LeanCopilot/Tactics.lean"]:::lean
        Options["Options: LeanCopilot/Options.lean"]:::lean
    end

    subgraph "Model Infrastructure Details"
        M1["Models Abstraction: LeanCopilot/Models.lean"]:::models
        M2["Builtin Adapter: LeanCopilot/Models/Builtin.lean"]:::models
        M3["ByT5 Adapter: LeanCopilot/Models/ByT5.lean"]:::models
        M4["External Adapter: LeanCopilot/Models/External.lean"]:::models
        M5["FFI Adapter: LeanCopilot/Models/FFI.lean"]:::models
        M6["Generic Adapter: LeanCopilot/Models/Generic.lean"]:::models
        M7["Interface: LeanCopilot/Models/Interface.lean"]:::models
        M8["Native Adapter: LeanCopilot/Models/Native.lean"]:::models
        M9["Registry: LeanCopilot/Models/Registry.lean"]:::models
    end

    subgraph "Model Checkpoint Manager Details"
        CP1["Checkpoint Entry: ModelCheckpointManager.lean"]:::checkpoint
        CP2["Download: ModelCheckpointManager/Download.lean"]:::checkpoint
        CP3["Main Manager: ModelCheckpointManager/Main.lean"]:::checkpoint
        CP4["URL Manager: ModelCheckpointManager/Url.lean"]:::checkpoint
    end

    subgraph "C++ Integration Details"
        C1["ct2 Integration: cpp/ct2.cpp"]:::cpp
        C2["JSON Utility: cpp/json.hpp"]:::cpp
        C3["NPY Utility: cpp/npy.hpp"]:::cpp
    end

    subgraph "Python API Server Details"
        P1["Python Server: python/server.py"]:::python
        subgraph "External Models Adapters"
            P2["Init Adapter: python/external_models/__init__.py"]:::python
            P3["Claude Runner: python/external_models/claude_runner.py"]:::python
            P4["External Parser: python/external_models/external_parser.py"]:::python
            P5["Gemini Runner: python/external_models/gemini_runner.py"]:::python
            P6["HF Runner: python/external_models/hf_runner.py"]:::python
            P7["OAI Runner: python/external_models/oai_runner.py"]:::python
            P8["VLLM Runner: python/external_models/vllm_runner.py"]:::python
        end
        P9["Python Models Utility: python/models.py"]:::python
    end

    subgraph "Build & Testing Infrastructure Details"
        B1["Dockerfile: Dockerfile"]:::build
        B2[".dockerignore: .dockerignore"]:::build
        B3["Lakefile: lakefile.lean"]:::build
        B4["Lake Manifest: lake-manifest.json"]:::build
        B5["Build Script: build.sh"]:::build
        B6["Build Example: build_example.sh"]:::build
        B7["Convert T5: convert_t5encoder_to_ct2.py"]:::build
        B8["Format C++: format_cpp.sh"]:::build
        B9["Unpickle: unpickle_premises.py"]:::build
        B10["Validate Retrieval: validate_retrieval.py"]:::build
        B11["CI Workflow: push_pr.yml"]:::build
        B12["Test Suite: LeanCopilotTests"]:::build
    end

    click Core "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot.lean"
    click Frontend "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Frontend.lean"
    click Tactics "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Tactics.lean"
    click Options "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Options.lean"

    click M1 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models.lean"
    click M2 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/Builtin.lean"
    click M3 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/ByT5.lean"
    click M4 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/External.lean"
    click M5 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/FFI.lean"
    click M6 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/Generic.lean"
    click M7 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/Interface.lean"
    click M8 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/Native.lean"
    click M9 "https://github.com/lean-dojo/leancopilot/blob/main/LeanCopilot/Models/Registry.lean"

    click CP1 "https://github.com/lean-dojo/leancopilot/blob/main/ModelCheckpointManager.lean"
    click CP2 "https://github.com/lean-dojo/leancopilot/blob/main/ModelCheckpointManager/Download.lean"
    click CP3 "https://github.com/lean-dojo/leancopilot/blob/main/ModelCheckpointManager/Main.lean"
    click CP4 "https://github.com/lean-dojo/leancopilot/blob/main/ModelCheckpointManager/Url.lean"

    click C1 "https://github.com/lean-dojo/leancopilot/blob/main/cpp/ct2.cpp"
    click C2 "https://github.com/lean-dojo/leancopilot/blob/main/cpp/json.hpp"
    click C3 "https://github.com/lean-dojo/leancopilot/blob/main/cpp/npy.hpp"

    click P1 "https://github.com/lean-dojo/leancopilot/blob/main/python/server.py"
    click P2 "https://github.com/lean-dojo/leancopilot/blob/main/python/external_models/__init__.py"
    click P3 "https://github.com/lean-dojo/leancopilot/blob/main/python/external_models/claude_runner.py"
    click P4 "https://github.com/lean-dojo/leancopilot/blob/main/python/external_models/external_parser.py"
    click P5 "https://github.com/lean-dojo/leancopilot/blob/main/python/external_models/gemini_runner.py"
    click P6 "https://github.com/lean-dojo/leancopilot/blob/main/python/external_models/hf_runner.py"
    click P7 "https://github.com/lean-dojo/leancopilot/blob/main/python/external_models/oai_runner.py"
    click P8 "https://github.com/lean-dojo/leancopilot/blob/main/python/external_models/vllm_runner.py"
    click P9 "https://github.com/lean-dojo/leancopilot/blob/main/python/models.py"

    click B1 "https://github.com/lean-dojo/leancopilot/tree/main/Dockerfile"
    click B2 "https://github.com/lean-dojo/leancopilot/blob/main/.dockerignore"
    click B3 "https://github.com/lean-dojo/leancopilot/blob/main/lakefile.lean"
    click B4 "https://github.com/lean-dojo/leancopilot/blob/main/lake-manifest.json"
    click B5 "https://github.com/lean-dojo/leancopilot/blob/main/scripts/build.sh"
    click B6 "https://github.com/lean-dojo/leancopilot/blob/main/scripts/build_example.sh"
    click B7 "https://github.com/lean-dojo/leancopilot/blob/main/scripts/convert_t5encoder_to_ct2.py"
    click B8 "https://github.com/lean-dojo/leancopilot/blob/main/scripts/format_cpp.sh"
    click B9 "https://github.com/lean-dojo/leancopilot/blob/main/scripts/unpickle_premises.py"
    click B10 "https://github.com/lean-dojo/leancopilot/blob/main/scripts/validate_retrieval.py"
    click B11 "https://github.com/lean-dojo/leancopilot/blob/main/.github/workflows/push_pr.yml"
    click B12 "https://github.com/lean-dojo/leancopilot/tree/main/LeanCopilotTests"

    classDef lean fill:#add8e6,stroke:#000,stroke-width:2px;
    classDef models fill:#90ee90,stroke:#000,stroke-width:2px;
    classDef cpp fill:#f4a460,stroke:#000,stroke-width:2px;
    classDef python fill:#dda0dd,stroke:#000,stroke-width:2px;
    classDef checkpoint fill:#ffe4b5,stroke:#000,stroke-width:2px;
    classDef build fill:#d3d3d3,stroke:#000,stroke-width:2px;
```
