# trishullab/proof-wala architecture

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

- Interactive diagram: https://gitdiagram.com/trishullab/proof-wala
- Repository: https://github.com/trishullab/proof-wala

## Overview

Based on our analysis of the file structure and README, ProofWala is a framework designed for multilingual proof data synthesis and automated theorem proving in interactive theorem provers (ITPs) like Coq and Lean. The system incorporates three main components: (1) an interface module that interacts with the ITPs (executing tactics, proof steps, etc.), (2) a proof step generation and training module for creating and training neural models that suggest proof steps, and (3) a parallel proof search module that leverages these models to run efficient, end-to-end proof searches (using Ray for distributed compute).

##### Main Components
a. User/Client Interface – where commands (e.g., training or proof search) are initiated.
b. ITP Interface Module – interfacing with external theorem-provers (Lean and Coq). Note that this module interacts with the itp-interface repository.
c. Data Collection Layer – managing the standardized multilingual proof step data. This layer includes the storage of training data, prompts, and recorded proof search outputs.
d. Proof Step Generation & Training Module – reading formatted training data, applying neural network models (built with frameworks like PyTorch), and training them.
e. Parallel Proof Search Module – executing end-to-end proof search guided by the trained models. This module handles configuration (via Hydra config files), distributed execution (using Ray), and logging of proof search sessions.
f. External Dependencies & Tools – such as graphviz for visualizing proof trees, and Torch, Hugging Face, and associated packages for deep learning and model inference.

##### Relationships and Interactions
- The User Interface triggers either training (via proof-wala-train) or proof search (via proof-wala-search).
- The Training Module accesses data from the Data Layer (prompts, proof trees, etc.) and relies on external deep learning libraries (PyTorch; Hugging Face Transformers).
- The ITP Interface Module interacts directly with Lean/Coq toolchains (as described in the README – see build steps in a Lean project folder and Coq directories).
- The Distributed Proof Search Module communicates with an already running Ray cluster (which is started by the init_ray scripts) and uses the configuration files within the "src/proof_wala/main/config" directory.

##### Architectural Patterns and Design Principles
- Modularity: Each of the main modules (interface, training, and search) is relatively self-contained and interacts via clearly defined configuration files and data formats.
- Extensibility: The system is designed to support cross-lingual proof synthesis, and it allows adding new ITPs or experimental configurations without major rework.
- Distributed Computation: The use of Ray for distributed proof search (parallel processing) is central to the architecture.
- Standardization: The proof data, prompts, and proofs are organized in a standardized way (as evidenced by the clear folder structure in src/proof_wala/data).

##### Technologies, Frameworks, and Libraries
- Python is clearly the main driver with files like pyproject.toml, requirements.txt, and many .py files.
- PyTorch (for training deep neural networks) and Hugging Face Transformers (for model inference and pipelines).
- Hydra for managing configuration during training and evaluation.
- Ray for distributed execution of proof search tasks.
- Graphviz for visualizing generated proof trees.
- Additional bash scripts (opam_script.sh, per_node_job.sh, etc.) for orchestration on clusters and SLURM/TACC compatibility.

##### Additional Detail
- Under “Proof Step Generation & Training,” note the role of files like "run_training.py", "training_data_formatter.py", and the various configuration YAML files.
- In “Parallel Proof Search,” mention scripts like "run_proof_search.py" and the importance of the session file (session_latest) for linking Ray nodes.
- That the system supports experiments via multiple benchmark configurations (as seen by the diverse config files in the "benchmark", "eval_settings", "training_settings" folders).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend / Control Layer
    subgraph "Frontend / Control Layer"
        UI["User/Client Interface"] 
    end

    %% Backend Modules
    subgraph "Backend Modules"
        %% ITP Interface Module
        subgraph "ITP Interface Module"
            ITP_Main["ITP Main"]
            Formatter1["Training Formatter"]
            Formatter2["Copra Formatter"]
            Formatter3["Proof Model Formatter"]
        end

        %% Data Collection Layer
        subgraph "Data Collection Layer"
            DataStorage["Data Storage"]
            Prompts["Prompts"]
            Proofs["Proofs"]
        end

        %% Proof Step Generation & Training Module
        subgraph "Proof Step Generation & Training Module"
            Training["run_training.py"]
            TrainConfig["Training Config"]
            NeuralHelpers["Neural Model Helpers"]
        end

        %% Parallel Proof Search Module
        subgraph "Parallel Proof Search Module"
            ProofSearch["run_proof_search.py"]
            SearchComponent["Proof Search Component"]
            SearchModule["Search Module"]
            RayInit["Ray Init"]
        end
    end

    %% External Services
    subgraph "External Services"
        ITP_Tools["ITP Tools (Lean/Coq)"]
        RayCluster["Ray Cluster"]
        DeepLearning["Deep Learning Libraries (PyTorch, HuggingFace)"]
        Hydra["Hydra Configuration"]
        Graphviz["Graphviz"]
    end

    %% Connections from Frontend to Modules
    UI -->|"triggers"| ITP_Main
    UI -->|"initiates_training"| Training
    UI -->|"initiates_search"| ProofSearch

    %% ITP Module interactions
    ITP_Main -->|"executes_tactics"| ITP_Tools
    ITP_Main -.-> Formatter1
    ITP_Main -.-> Formatter2
    ITP_Main -.-> Formatter3

    %% Data Flow Connections
    Training -->|"reads_data_from"| DataStorage
    ProofSearch -->|"fetches_data_from"| DataStorage
    DataStorage -->|"contains"| Prompts
    DataStorage -->|"contains"| Proofs

    %% Training Module internal interactions
    TrainConfig -->|"configures"| NeuralHelpers
    Training -->|"applies_config"| Hydra
    NeuralHelpers -->|"leverages"| DeepLearning

    %% Proof Search Module internal interactions
    SearchComponent -->|"works_with"| SearchModule
    ProofSearch -->|"initiates_distributed_search"| RayInit
    RayInit -->|"connects_to"| RayCluster

    %% Frontend interactions with ITP and External Modules
    ITP_Main -->|"communicates_with"| ITP_Tools

    %% Click Events
    click UI "https://github.com/trishullab/proof-wala/blob/main/src/proof_wala/main/run.py"
    click ITP_Main "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/itp"
    click Formatter1 "https://github.com/trishullab/proof-wala/blob/main/src/proof_wala/itp/training_data_formatter.py"
    click Formatter2 "https://github.com/trishullab/proof-wala/blob/main/src/proof_wala/itp/copra_training_data_formatter.py"
    click Formatter3 "https://github.com/trishullab/proof-wala/blob/main/src/proof_wala/itp/proof_model_training_data_formatter.py"
    click DataStorage "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/data"
    click Prompts "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/data/prompts"
    click Proofs "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/data/proofs"
    click Training "https://github.com/trishullab/proof-wala/blob/main/src/proof_wala/main/run_training.py"
    click TrainConfig "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/main/config/training_settings"
    click NeuralHelpers "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/llm_helpers"
    click ProofSearch "https://github.com/trishullab/proof-wala/blob/main/src/proof_wala/main/run_proof_search.py"
    click SearchComponent "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/proof_search"
    click SearchModule "https://github.com/trishullab/proof-wala/tree/main/src/proof_wala/search"
    click RayInit "https://github.com/trishullab/proof-wala/blob/main/src/proof_wala/main/init_ray.py"

    %% Class styles
    class UI client
    class ITP_Main,Formatter1,Formatter2,Formatter3 itp
    class DataStorage,Prompts,Proofs dataLayer
    class Training,TrainConfig,NeuralHelpers,ProofSearch,SearchComponent,SearchModule,RayInit backend
    class ITP_Tools,RayCluster,DeepLearning,Hydra,Graphviz external

    classDef client fill:#ffeb99,stroke:#333,stroke-width:2px
    classDef backend fill:#cce5ff,stroke:#333,stroke-width:2px
    classDef dataLayer fill:#f7c6c7,stroke:#333,stroke-width:2px
    classDef itp fill:#d6bcfa,stroke:#333,stroke-width:2px
    classDef external fill:#d0f0c0,stroke:#333,stroke-width:2px
```
