# google-deepmind/alphageometry architecture

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

- Interactive diagram: https://gitdiagram.com/google-deepmind/alphageometry
- Repository: https://github.com/google-deepmind/alphageometry

## Overview

##### Project type and purpose
- This is a research‐quality, CLI-driven Python application that implements two geometry theorem provers—DDAR (a purely symbolic Depth-Difference + Angle-Razor solver) and AlphaGeometry (a hybrid symbolic + transformer-based solver).
- It reads geometry problems from text files, constructs a proof state graph, attempts a symbolic proof (DDAR), and—if that fails—invokes a transformer language model to propose new auxiliary constructions, feeding them back into the symbolic engine until the proof is found or resources are exhausted.

##### Key components (based on file structure and README)
A. CLI / Orchestration
- alphageometry.py: main entrypoint.
- run.sh, download.sh, run_tests.sh: automation scripts.
B. Configuration
- Gin config files (e.g., geometry_150M_generate.gin) + gin-config library.
- defs.txt, rules.txt: symbolic-engine definitions and deduction rules.
C. Input layer
- problem.py, examples.txt, imo_ag_30.txt, jgex_ag_231.txt: problem loading and parsing.
D. Symbolic engine
- graph.py + graph_utils.py: build and manipulate proof‐state graphs.
- geometry.py, numericals.py: geometry primitives and numeric reasoning.
- dd.py, ar.py, trace_back.py: DD and AR algorithms and traceback.
- ddar.py: orchestrates DD+AR.
- pretty.py: formats and prints proofs.
E. ML engine
- transformer_layer.py, decoder_stack.py, models.py: defines the Transformer model in Flax/JAX.
- lm_inference.py: tokenization (SentencePiece) and LM interface.
- beam_search.py: beam-search decoding logic.
F. External dependencies
- Meliad library (external git subtree).
- JAX, Flax, Abseil, NumPy, SciPy, TensorFlow, SentencePiece, Gin.
G. Data artifacts
- Model checkpoint & vocabulary (downloaded via download.sh).
- defs.txt, rules.txt, gin files.

##### Relationships & data flow
1. User invokes “python -m alphageometry …” (or run.sh).
2. The CLI loads Gin configs + flags, reads the problem file.
3. problem.py → graph_utils.py → graph.py: builds the initial proof state graph.
4. Call ddar.py (DD+AR) with defs.txt & rules.txt:
– If a proof is found, pretty.py formats & prints it.
– Else, in “alphageometry” mode:
a. Export current graph state into a linearized input.
b. lm_inference.py + beam_search.py invokes the Transformer (models.py) to propose k auxiliary constructions.
c. Parse LM output back into symbolic construction actions.
d. Append these constructions to the graph and re-invoke ddar.py.
e. Repeat until success or search limits reached.
5. Final output is printed or saved to file.

##### Architectural patterns & principles
- Layered modular design:
- CLI/Orchestrator layer
- Configuration layer (Gin)
- Core symbolic‐reasoning layer
- ML inference layer
- Data/resource layer
- Clear separation of concerns: symbolic vs ML code, representation vs algorithms, config vs implementation.
- Extensibility points: can plug in different search strategies (beam size, depth, DD/AR), or swap in alternative LM checkpoints.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CLI Layer
    subgraph "CLI / Orchestration"
        direction TB
        ALPHA["alphageometry.py"]:::cli
        RUNSH["run.sh"]:::cli
        DOWNLOADSH["download.sh"]:::cli
        RUNTESTSH["run_tests.sh"]:::cli
    end

    %% Configuration Layer
    subgraph "Configuration / Data"
        direction TB
        GIN["geometry_150M_generate.gin"]:::config
        DEFS["defs.txt"]:::config
        RULES["rules.txt"]:::config
    end

    %% Input Layer
    subgraph "Input Layer"
        direction TB
        PROB["problem.py"]:::symbol
        EXAMPLES["examples.txt"]:::config
        IMO["imo_ag_30.txt"]:::config
        JGEX["jgex_ag_231.txt"]:::config
    end

    %% Symbolic Engine
    subgraph "Symbolic Engine"
        direction TB
        GRAPHUTIL["graph_utils.py"]:::symbol
        GRAPH["graph.py"]:::symbol
        GEOM["geometry.py"]:::symbol
        NUM["numericals.py"]:::symbol
        DD["dd.py"]:::symbol
        AR["ar.py"]:::symbol
        TRACE["trace_back.py"]:::symbol
        DDAR["ddar.py"]:::symbol
        PRETTY["pretty.py"]:::symbol
    end

    %% ML Engine
    subgraph "ML Engine"
        direction TB
        TRANSFORMER["transformer_layer.py"]:::ml
        DECODER["decoder_stack.py"]:::ml
        MODELS["models.py"]:::ml
        LMINF["lm_inference.py"]:::ml
        BEAM["beam_search.py"]:::ml
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        MELIAD["Meliad Library"]:::external
        JAX["JAX/Flax"]:::external
        OTHERLIBS["TensorFlow, NumPy, SciPy, SentencePiece, Gin"]:::external
    end

    %% Data Artifacts
    subgraph "Model & Artifacts"
        direction TB
        CHECKPT["Model Checkpoint & Vocab"]:::config
    end

    %% Data Flow
    ALPHA -->|"load configs & flags"| GIN
    ALPHA -->|"read problem file"| PROB

    PROB -->|"parsed problem"| GRAPHUTIL
    GRAPHUTIL -->|"build proof graph"| GRAPH

    GRAPH -->|"initial graph state"| DDAR
    DEFS --> DDAR
    RULES --> DDAR

    DDAR -->|proof found| PRETTY
    PRETTY -->|"formatted proof"| OUTPUT["Console / Output File"]:::config

    DDAR -->|fail: export graph state| LMINF
    LMINF -->|"tokenized sequence"| BEAM
    BEAM -->|"auxiliary constructions"| DDAR

    %% ML model dependencies
    LMINF --> MODELS
    MODELS --> TRANSFORMER
    TRANSFORMER --> DECODER

    %% External
    DDAR -.-> MELIAD
    LMINF -.-> OTHERLIBS
    ALPHA -.-> JAX
    CHECKPT -.-> LMINF

    %% Click Events
    click ALPHA "https://github.com/google-deepmind/alphageometry/blob/main/alphageometry.py"
    click RUNSH "https://github.com/google-deepmind/alphageometry/blob/main/run.sh"
    click DOWNLOADSH "https://github.com/google-deepmind/alphageometry/blob/main/download.sh"
    click RUNTESTSH "https://github.com/google-deepmind/alphageometry/blob/main/run_tests.sh"
    click GIN "https://github.com/google-deepmind/alphageometry/blob/main/geometry_150M_generate.gin"
    click DEFS "https://github.com/google-deepmind/alphageometry/blob/main/defs.txt"
    click RULES "https://github.com/google-deepmind/alphageometry/blob/main/rules.txt"
    click PROB "https://github.com/google-deepmind/alphageometry/blob/main/problem.py"
    click EXAMPLES "https://github.com/google-deepmind/alphageometry/blob/main/examples.txt"
    click IMO "https://github.com/google-deepmind/alphageometry/blob/main/imo_ag_30.txt"
    click JGEX "https://github.com/google-deepmind/alphageometry/blob/main/jgex_ag_231.txt"
    click GRAPHUTIL "https://github.com/google-deepmind/alphageometry/blob/main/graph_utils.py"
    click GRAPH "https://github.com/google-deepmind/alphageometry/blob/main/graph.py"
    click GEOM "https://github.com/google-deepmind/alphageometry/blob/main/geometry.py"
    click NUM "https://github.com/google-deepmind/alphageometry/blob/main/numericals.py"
    click DD "https://github.com/google-deepmind/alphageometry/blob/main/dd.py"
    click AR "https://github.com/google-deepmind/alphageometry/blob/main/ar.py"
    click TRACE "https://github.com/google-deepmind/alphageometry/blob/main/trace_back.py"
    click DDAR "https://github.com/google-deepmind/alphageometry/blob/main/ddar.py"
    click PRETTY "https://github.com/google-deepmind/alphageometry/blob/main/pretty.py"
    click TRANSFORMER "https://github.com/google-deepmind/alphageometry/blob/main/transformer_layer.py"
    click DECODER "https://github.com/google-deepmind/alphageometry/blob/main/decoder_stack.py"
    click MODELS "https://github.com/google-deepmind/alphageometry/blob/main/models.py"
    click LMINF "https://github.com/google-deepmind/alphageometry/blob/main/lm_inference.py"
    click BEAM "https://github.com/google-deepmind/alphageometry/blob/main/beam_search.py"

    %% Styles
    classDef cli fill:#fdd,stroke:#f00
    classDef config fill:#ffd,stroke:#cc0
    classDef symbol fill:#ddf,stroke:#00f
    classDef ml fill:#dfd,stroke:#0a0
    classDef external fill:#eee,stroke:#888
```
