# trueagi-io/petta architecture

> Architecture diagram of the GitHub repository trueagi-io/petta, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/trueagi-io/petta
- Repository: https://github.com/trueagi-io/petta

## Overview

PeTTa is a MeTTa language implementation in Prolog. Its user-facing workflow is to run MeTTa code through the SWI-Prolog entry point, or submit files and strings through the Python API, which consults the runtime and invokes helper predicates. The tree also identifies parsing, translation, spaces, specialization, and extension modules, plus optional MORK/FAISS support and extension libraries. Internal Prolog call relationships are not shown in the supplied excerpts, so those connections are omitted; optional space integrations are documented in the README.

Main entry points: [`python/petta/__init__.py`](https://github.com/trueagi-io/petta/blob/main/python/petta/__init__.py) (Python API), [`src/main.pl`](https://github.com/trueagi-io/petta/blob/main/src/main.pl) (Runtime Entry), [`src/spaces.pl`](https://github.com/trueagi-io/petta/blob/main/src/spaces.pl) (Atom Spaces), [`python/helper.pl`](https://github.com/trueagi-io/petta/blob/main/python/helper.pl) (Python Helpers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Prolog Runtime"]
  node_main["Runtime Entry<br/>[main.pl]"]
  node_parser["Parser<br/>[parser.pl]"]
  node_translator["Translator<br/>[translator.pl]"]
  node_spaces[("Atom Spaces<br/>[spaces.pl]")]
  node_specializer["Specializer<br/>[specializer.pl]"]
  node_filereader["File Reader<br/>[filereader.pl]"]
  node_extpoints["Extension Points<br/>[ext_points.pl]"]
end

subgraph group_interfaces["Python Interfaces"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_python_cli["Python CLI<br/>[cli.py]"]
  node_helper["Python Helpers<br/>[helper.pl]"]
end

subgraph group_extensions["Extensions"]
  node_mork[("MORK Spaces")]
  node_faiss[("FAISS Vectors")]
  node_git_import["Git Imports<br/>[lib_import.metta]"]
  node_llm["LLM Integration<br/>[lib_llm.py]"]
end

node_user(("MeTTa User"))
node_openrouter["OpenRouter"]

node_user -->|"runs code"| node_main
node_python_cli -->|"starts entry"| node_main
node_python_api -->|"consults runtime"| node_main
node_python_api -->|"consults helper"| node_helper
node_python_api -->|"queries helpers"| node_helper
node_spaces -.->|"optional spaces"| node_mork
node_spaces -.->|"optional vectors"| node_faiss
node_llm -->|"sends requests"| node_openrouter

click node_main "https://github.com/trueagi-io/petta/blob/main/src/main.pl"
click node_parser "https://github.com/trueagi-io/petta/blob/main/src/parser.pl"
click node_translator "https://github.com/trueagi-io/petta/blob/main/src/translator.pl"
click node_spaces "https://github.com/trueagi-io/petta/blob/main/src/spaces.pl"
click node_specializer "https://github.com/trueagi-io/petta/blob/main/src/specializer.pl"
click node_filereader "https://github.com/trueagi-io/petta/blob/main/src/filereader.pl"
click node_extpoints "https://github.com/trueagi-io/petta/blob/main/src/ext_points.pl"
click node_python_api "https://github.com/trueagi-io/petta/blob/main/python/petta/__init__.py"
click node_python_cli "https://github.com/trueagi-io/petta/blob/main/python/petta/cli.py"
click node_helper "https://github.com/trueagi-io/petta/blob/main/python/helper.pl"
click node_git_import "https://github.com/trueagi-io/petta/blob/main/lib/lib_import.metta"
click node_llm "https://github.com/trueagi-io/petta/blob/main/lib/lib_llm.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_parser,node_translator,node_spaces,node_specializer,node_filereader,node_extpoints,node_user toneBlue
class node_python_api,node_python_cli,node_helper toneAmber
class node_mork,node_faiss,node_git_import,node_llm,node_openrouter toneMint
```

## Components

### Prolog Runtime

- [Runtime Entry](https://github.com/trueagi-io/petta/blob/main/src/main.pl): `src/main.pl`
- [Parser](https://github.com/trueagi-io/petta/blob/main/src/parser.pl): `src/parser.pl`
- [Translator](https://github.com/trueagi-io/petta/blob/main/src/translator.pl): `src/translator.pl`
- [Atom Spaces](https://github.com/trueagi-io/petta/blob/main/src/spaces.pl): `src/spaces.pl`
- [Specializer](https://github.com/trueagi-io/petta/blob/main/src/specializer.pl): `src/specializer.pl`
- [File Reader](https://github.com/trueagi-io/petta/blob/main/src/filereader.pl): `src/filereader.pl`
- [Extension Points](https://github.com/trueagi-io/petta/blob/main/src/ext_points.pl): `src/ext_points.pl`

### Python Interfaces

- [Python API](https://github.com/trueagi-io/petta/blob/main/python/petta/__init__.py): `python/petta/__init__.py`
- [Python CLI](https://github.com/trueagi-io/petta/blob/main/python/petta/cli.py): `python/petta/cli.py`
- [Python Helpers](https://github.com/trueagi-io/petta/blob/main/python/helper.pl): `python/helper.pl`

### Extensions

- **MORK Spaces**
- **FAISS Vectors**
- [Git Imports](https://github.com/trueagi-io/petta/blob/main/lib/lib_import.metta): `lib/lib_import.metta`
- [LLM Integration](https://github.com/trueagi-io/petta/blob/main/lib/lib_llm.py): `lib/lib_llm.py`

### Other components

- **MeTTa User**
- **OpenRouter**

## Connections

- MeTTa User → Runtime Entry: runs code (evidence: `README.md`)
- Python CLI → Runtime Entry: starts entry (evidence: `python/petta/cli.py`)
- Python API → Runtime Entry: consults runtime (evidence: `python/petta/__init__.py`)
- Python API → Python Helpers: consults helper (evidence: `python/petta/__init__.py`)
- Python API → Python Helpers: queries helpers (evidence: `python/petta/__init__.py`)
- Atom Spaces → MORK Spaces: optional spaces (evidence: `README.md`)
- Atom Spaces → FAISS Vectors: optional vectors (evidence: `README.md`)
- LLM Integration → OpenRouter: sends requests (evidence: `lib/lib_llm.py`)
