# biruk-gebru/metta-moses architecture

> Architecture diagram of the GitHub repository biruk-gebru/metta-moses, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/biruk-gebru/metta-moses
- Repository: https://github.com/biruk-gebru/metta-moses

## Overview

##### Project Type and Purpose
- This is a domain-specific library/tool: a MeTTa-based reimplementation of the MOSES evolutionary program learner.
- It is not a typical frontend/backend web app but a pipeline of MeTTa modules implementing genetic-programming operators, reduction functions, scoring, and orchestration code.

##### High-Level Architecture (Main Components)
a. Runtime Environment (External Service)
- MeTTa interpreter / hyperon-experimental library (v0.1.12)
- Optional metta-run binary on Windows
b. Core Modules (MeTTa Files)
1. Types (`types.metta`, `experimentalTypes.metta`)
2. Utilities (`utilities/`)
3. Optimization Strategies (`optimization/`)
- PGE (probabilistic grammar evolution)
- SGE (stochastic grammar evolution)
- SGGGP (stochastic grammar-guided genetic programming)
4. Reduction Engine (`reduct/boolean-reduct/`)
5. Scoring Engine (`scoring/fitness.metta`)
6. Entry Points (`exec.metta`)
c. Orchestration & Tests
- Python test runner (`scripts/run-tests.py`)
- Test suites under each module’s `test/` directories

##### Relationships and Data Flow
1. Input dataset & parameters → MeTTa interpreter
2. exec.metta & types load definitions → initialize population
3. Optimization Engine
→ picks exemplar trees → calls Reduction Engine to simplify candidates
→ calls Scoring Engine to evaluate fitness
→ selects survivors & repeats (loop back)
4. Utilities module called by both Reduction and Scoring for shared helpers
5. Final best program(s) returned or printed via exec.metta

##### Architectural Patterns and Principles
- Pipeline pattern: distinct stages (generation → reduction → scoring)
- Plugin-style strategy modules (PGE/SGE/SGGP) implementing a common interface
- Separation of concerns: types, helpers, core logic, and test code each in its own directory
- Test-driven development: each module has corresponding tests

##### Technologies and Frameworks
- MeTTa language for core logic
- Python for orchestration/test script
- GitHub Actions (MeTTa-CI.yml) for CI
- Standard GitHub workflows and issue templates

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Input
    Input["Input Dataset & Parameters"]:::external

    %% Runtime Environment
    subgraph "Runtime Environment"
        MI["MeTTa Interpreter / hyperon-experimental"]:::runtime
    end

    %% Core Modules
    subgraph "Core Modules"
        subgraph "Types"
            T1["types.metta"]:::core
            T2["experimentalTypes.metta"]:::core
        end
        subgraph "Utilities"
            Umod["utilities/"]:::helper
        end
        subgraph "Optimization Strategies"
            subgraph "PGE"
                PGE1["pge-eda.metta"]:::core
                PGE2["pge2.metta"]:::core
            end
            subgraph "SGE"
                SGE["sge-and-tests.metta"]:::core
            end
            subgraph "SGGGP"
                SGG["sggp-algorithm-with-tests.metta"]:::core
            end
        end
        subgraph "Reduction Engine"
            RED["boolean-reduct/"]:::core
        end
        subgraph "Scoring Engine"
            SC["fitness.metta"]:::core
        end
        EP["exec.metta"]:::core
    end

    %% Orchestration & CI
    subgraph "Orchestration & CI"
        RTest["scripts/run-tests.py"]:::orchestration
        CI[".github/workflows/MeTTa-CI.yml"]:::orchestration
    end

    %% Data Flow
    Input --> EP
    EP --> T1
    EP --> T2
    T1 --> PGE1
    T2 --> PGE1
    T1 --> PGE2
    T2 --> PGE2
    T1 --> SGE
    T2 --> SGE
    T1 --> SGG
    T2 --> SGG
    T1 --> RED
    T2 --> RED
    T1 --> SC
    T2 --> SC

    PGE1 --> RED
    PGE2 --> RED
    SGE --> RED
    SGG --> RED

    RED --> SC
    SC --> PGE1
    SC --> PGE2

    SC -->|"Final Best Program"| Output["Output Best Program"]:::external

    %% Utilities usage
    Umod --> RED
    Umod --> SC

    %% Orchestration connections
    CI --> RTest
    RTest --> Umod
    RTest --> PGE1
    RTest --> PGE2
    RTest --> SGE
    RTest --> SGG
    RTest --> RED
    RTest --> SC

    %% Click Events
    click T1 "https://github.com/biruk-gebru/metta-moses/blob/main/types.metta"
    click T2 "https://github.com/biruk-gebru/metta-moses/blob/main/experimentalTypes.metta"
    click Umod "https://github.com/biruk-gebru/metta-moses/tree/main/utilities/"
    click PGE1 "https://github.com/biruk-gebru/metta-moses/blob/main/optimization/pge/pge-eda.metta"
    click PGE2 "https://github.com/biruk-gebru/metta-moses/blob/main/optimization/pge/pge2.metta"
    click SGE "https://github.com/biruk-gebru/metta-moses/blob/main/optimization/sge/sge-and-tests.metta"
    click SGG "https://github.com/biruk-gebru/metta-moses/blob/main/optimization/sggp/sggp-algorithm-with-tests.metta"
    click RED "https://github.com/biruk-gebru/metta-moses/tree/main/reduct/boolean-reduct/"
    click SC "https://github.com/biruk-gebru/metta-moses/blob/main/scoring/fitness.metta"
    click EP "https://github.com/biruk-gebru/metta-moses/blob/main/exec.metta"
    click RTest "https://github.com/biruk-gebru/metta-moses/blob/main/scripts/run-tests.py"
    click CI "https://github.com/biruk-gebru/metta-moses/blob/main/.github/workflows/MeTTa-CI.yml"

    %% Styles
    classDef external fill:#DDDDDD,stroke:#333,stroke-width:1px
    classDef runtime fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef helper fill:#90ee90,stroke:#333,stroke-width:1px
    classDef orchestration fill:#FFA500,stroke:#333,stroke-width:1px
```
