# jazzbox35/metta-wam architecture

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

- Interactive diagram: https://gitdiagram.com/jazzbox35/metta-wam
- Repository: https://github.com/jazzbox35/metta-wam

## Overview

##### Out the Major Components
- WAM Integration: The project is specifically designed to run on the Warren Abstract Machine using a SWI–Prolog base (often with Janus support). This runtime is integrated with the core engine.
- REPL/CLI Interface: The command–line front end is provided by the “mettalog” (or “metta_repl”) command. This interface accepts user input, runs scripts (e.g., from examples/ and scripts/), and shows interactive evaluations.
- Test and Development Suite: There is a comprehensive set of tests and examples (in directories like tests/, examples/, notebooks/) that serve for both validation and demonstration. Continuously integrated reports and Docker support further affirm a robust testing pipeline.
- External & Integration Layers:
– Python Integration: The python/ folder contains modules (hyperon_ref, mettalog, sandbox directories, integration tests) that provide wrappers and extensions to run or interoperate with MeTTa code.
– Jupyter Kernel: There is a dedicated “metta_jupyter_kernel.py” so that developers can work in notebooks, leveraging the language interactively.
– Additional Libraries: Various libraries (e.g., bioAS, dictoo, logicmoo_utils, swicli, predicate_streams) extend or support functionalities (sometimes domain–specific, like integration with FlyBase or graph loaders) and allow for extensibility.
- Docker & Installation: The presence of the Dockerfile, INSTALL.sh/INSTALL.BAT and CI scripts means the project supports containerized runs and multiple-platform deployment.
- Language Server (LSP): There is an LSP component (see libraries/lsp_server_metta) that helps with editor integration and better developer experience.

##### Interactions and Data Flow
- The user (via CLI, IDE, or Jupyter) interacts with the REPL/CLI front end.
- Input “.metta” files are parsed and handed off to the Core Engine for compilation and/or interpretation.
- The Compiler component takes code, translates it (possibly with optimizations or transpilation routines), and passes it to the interpreter.
- The Interpreter evaluates code on the WAM backend supported by SWI–Prolog libraries.
- Testing modules, continuous integration scripts and Docker scripts interact with the core engine to run automated tests and generate reports.
- Integration layers (Python, LSP, notebooks) serve as adapters that bridge MeTTa functionalities with external ecosystems.

##### Architectural Patterns and Design Principles
- Modular Separation: The design clearly separates the interpreter, compiler, debugger, loader and other utility routines. Each of these is its own module (or group of modules), often written in Prolog or in Python.
- Extensibility and Interoperability: In addition to its core functionality, the project is designed to support language extensions, external integrations (via Python bindings, Jupyter kernel, LSP) and external libraries.
- Containerization & Automated Testing: The Dockerfile and various CI scripts indicate an agile development approach based on containerized, repeatable builds and test runs.
- Multi-language Support: Although the core language is implemented in Prolog/Metta, there is strong interoperability with Python (as evidenced by the extensive python folder structure) and even hints of Rust support (e.g., the rust-wam directory).

##### Final Checklist for the Principal Software Engineer
- Notes on key design principles (modular separation, containerization, automated testing, multi–language support).
- External services (like Docker, version control/CI, external libraries) with additional annotations.

## Diagram (Mermaid)

```mermaid
graph TD
    %% User Interaction Layer
    subgraph "User Interaction"
        User["User"]:::frontend
        CLI["CLI/REPL Interface"]:::frontend
        mettalog["mettalog Command"]:::frontend
    end
    User -->|"inputs commands"| CLI
    CLI -->|"invokes"| mettalog

    %% Core Processing Layer
    subgraph "Core Processing"
        CoreEngine["Core Language Engine"]:::core
        WAM["WAM Integration (SWI–Prolog)"]:::core
    end
    CLI -->|"sends code to"| CoreEngine
    CoreEngine -->|"compiles/interprets"| WAM
    WAM -->|"evaluates and returns"| CoreEngine
    CoreEngine -->|"returns results"| CLI

    %% External Integrations Layer
    subgraph "External Integrations"
        PythonIntegration["Python Integration"]:::integration
        JupyterKernel["Jupyter Kernel"]:::integration
        LSP["Language Server (LSP)"]:::integration
    end
    CoreEngine -->|"accessibleBy"| PythonIntegration
    PythonIntegration -->|"supportsInteractiveUsage"| JupyterKernel
    CLI -->|"editorSupport"| LSP

    %% Testing Suite Layer
    subgraph "Testing Suite"
        Tests["Tests"]:::testing
        Examples["Examples"]:::testing
        Scripts["Scripts"]:::testing
        Notebooks["Notebooks"]:::testing
    end
    CoreEngine -->|"undergoesTests"| Tests
    CoreEngine -->|"demonstratedBy"| Examples
    CoreEngine -->|"utilizedIn"| Scripts
    CoreEngine -->|"interactiveDocs"| Notebooks

    %% Deployment & CI Layer
    subgraph "Deployment & CI"
        DockerDeployment["Docker & Installation"]:::deployment
        Installation["Installation Scripts"]:::deployment
        CI["CI Configurations"]:::deployment
    end
    CoreEngine -->|"containerizedBuild"| DockerDeployment
    DockerDeployment -->|"includes"| Installation
    DockerDeployment -->|"monitoredBy"| CI

    %% Click Events
    click CoreEngine "https://github.com/jazzbox35/metta-wam/tree/master/prolog/metta_lang"
    click WAM "https://github.com/jazzbox35/metta-wam/blob/master/prolog/metta_lang/swi_support.pl"
    click CLI "https://github.com/jazzbox35/metta-wam/blob/master/prolog/metta_lang/metta_repl.pl"
    click mettalog "https://github.com/jazzbox35/metta-wam/tree/master/mettalog"
    click Tests "https://github.com/jazzbox35/metta-wam/tree/master/tests"
    click Examples "https://github.com/jazzbox35/metta-wam/tree/master/examples"
    click Scripts "https://github.com/jazzbox35/metta-wam/tree/master/scripts"
    click Notebooks "https://github.com/jazzbox35/metta-wam/tree/master/notebooks"
    click PythonIntegration "https://github.com/jazzbox35/metta-wam/tree/master/python"
    click JupyterKernel "https://github.com/jazzbox35/metta-wam/blob/master/python/metta_jupyter_kernel.py"
    click LSP "https://github.com/jazzbox35/metta-wam/tree/master/libraries/lsp_server_metta"
    click DockerDeployment "https://github.com/jazzbox35/metta-wam/tree/master/Dockerfile"
    click Installation "https://github.com/jazzbox35/metta-wam/blob/master/INSTALL.sh"
    click CI "https://github.com/jazzbox35/metta-wam/blob/master/.github/workflows/ci.yml"

    %% Styles
    classDef frontend fill:#87CEFA,stroke:#000,stroke-width:2px;
    classDef core fill:#B0E0E6,stroke:#000,stroke-width:2px;
    classDef integration fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef testing fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef deployment fill:#FFA07A,stroke:#000,stroke-width:2px;
```
