# uomi-network/uomi-node-ai architecture

> Architecture diagram of the GitHub repository uomi-network/uomi-node-ai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/uomi-network/uomi-node-ai
- Repository: https://github.com/uomi-network/uomi-node-ai

## Overview

##### Project Type and Purpose
- This is a standalone AI microservice (“UOMI Node AI”) written in Python. It runs as a systemd‐managed service (or in Docker), exposes a REST endpoint for model inference, and provides GPU–accelerated, deterministic AI outputs to support a UOMI blockchain validator node.

##### File Structure Analysis
- Top‐level files:
- uomi-ai.py – service entrypoint (starts the HTTP server).
- uomi-ai.service – systemd unit file.
- Dockerfile & docker-compose.yml – containerization and orchestration.
- install.sh – installer for cond a deps and service setup.
- lib/ (application code):
- config.py – configuration (port, GPU, seeds).
- runner.py – orchestrates request handling.
- executors.py – abstract compute/execution layer.
- SanaModelManager.py, TransformersModelManager.py, TestModelManager.py – model interfaces.
- system.py – system utilities (GPU discovery, logging setup).
- zipper.py – package/unpackage model artifacts.
- test/ – unit tests for runner, system, zipper.

##### README Insights
- Exposes POST /run on port 8888.
- Requires CUDA GPU, conda environment, systemd integration.
- Real‐time logging via journalctl.
- Deterministic model outputs, automatic GPU selection.

##### Main Components & Relationships
a. Client (Blockchain Validator or other)
→ sends JSON over HTTP POST to
b. HTTP Server (Flask/FastAPI in uomi-ai.py)
→ invokes
c. Runner (runner.py)
→ uses
d. Executors (executors.py)
→ dispatches to
e. Model Managers (TransformersModelManager, SanaModelManager, TestModelManager)
↔ load models (possibly via zipper.py)
→ perform inference on
f. GPU Device (CUDA)
→ returns results up the stack
→ HTTP Server responds to Client
g. Logging & Monitoring
- All components log to stdout → captured by systemd/journalctl
h. Configuration
- config.py centrally injects settings (port, seeds, device)

##### Architectural Patterns & Design Principles
- Layered architecture:
1) API Layer (HTTP service)
2) Service/Orchestration Layer (runner + executors)
3) Model abstraction Layer (model managers + zipper)
4) Infrastructure Layer (CUDA, system utilities)
- Separation of concerns: each module has a single responsibility.
- Determinism: fixed seeds in config ensure reproducible outputs.
- Extensibility: new ModelManager subclasses can be dropped in.

##### Technologies & Frameworks
- Python 3.x
- HTTP framework (Flask or FastAPI)
- PyTorch/Transformers (for GPU inference)
- CUDA Toolkit 11.x+
- Conda (environment management)
- systemd (service management)
- Docker/Docker‐Compose (optional deployment)

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Blockchain Validator"]:::external

    subgraph "Systemd/Docker Boundary" 
        direction TB
        API["HTTP Server<br/>uomi-ai.py"]:::api
        Runner["Runner<br/>lib/runner.py"]:::service
        Executors["Executors<br/>lib/executors.py"]:::service
        subgraph "Model Abstraction Layer"
            direction TB
            Transformers["TransformersModelManager<br/>lib/TransformersModelManager.py"]:::model
            Sana["SanaModelManager<br/>lib/SanaModelManager.py"]:::model
            TestM["TestModelManager<br/>lib/TestModelManager.py"]:::model
            Zipper["Zipper<br/>lib/zipper.py"]:::model
        end
        subgraph "Infrastructure Layer"
            direction TB
            GPU["CUDA GPU Device"]:::infra
            SystemUtil["System Utilities<br/>lib/system.py"]:::infra
            Config["Configuration<br/>lib/config.py"]:::infra
            ServiceDef["Systemd Service<br/>uomi-ai.service"]:::infra
        end
    end

    Journal["journalctl"]:::infra
    Dockerfile["Dockerfile"]:::infra
    Compose["docker-compose.yml"]:::infra
    InstallScript["install.sh"]:::infra
    Readme["README.md"]:::infra
    GitIgnore[".gitignore"]:::infra
    TestRunner["Runner Tests<br/>test/runner_test.py"]:::infra
    TestSystem["System Tests<br/>test/system_test.py"]:::infra
    TestZipper["Zipper Tests<br/>test/zipper_test.py"]:::infra

    Client -->|POST /run| API
    API -->|invoke runner| Runner
    Runner -->|use executors| Executors
    Executors -->|load model| Transformers
    Executors -->|load model| Sana
    Executors -->|load model| TestM
    Transformers -->|may use zipper| Zipper
    Sana -->|may use zipper| Zipper
    TestM -->|may use zipper| Zipper
    Executors -->|infer on GPU| GPU
    GPU -->|results| Executors
    Executors -->|return| Runner
    Runner -->|return| API
    API -->|response JSON| Client

    API -->|logs| Journal
    Runner -->|logs| Journal
    Executors -->|logs| Journal
    Transformers -->|logs| Journal

    SystemUtil -.->|supports| API
    SystemUtil -.->|supports| Runner
    SystemUtil -.->|supports| Executors

    Config -.->|inject settings| API
    Config -.->|inject settings| Runner
    Config -.->|inject settings| Executors
    Config -.->|inject settings| Transformers
    Config -.->|inject settings| Sana
    Config -.->|inject settings| TestM

    ServiceDef -->|manages| API

    Dockerfile -->|containerizes| API
    Compose -->|orchestrates| ServiceDef
    InstallScript -->|sets up| ServiceDef

    Readme -->|documents| API
    GitIgnore -->|ignores| API

    TestRunner -->|tests| Runner
    TestSystem -->|tests| SystemUtil
    TestZipper -->|tests| Zipper

    classDef api fill:#D0E8FF,stroke:#004085,color:#004085;
    classDef service fill:#DFF0D8,stroke:#3C763D,color:#3C763D;
    classDef model fill:#FFE5B4,stroke:#CC8400,color:#CC8400;
    classDef infra fill:#E2E3E5,stroke:#6C757D,color:#6C757D;
    classDef external fill:#FFF3CD,stroke:#856404,color:#856404;

    click API "https://github.com/uomi-network/uomi-node-ai/blob/main/uomi-ai.py"
    click Runner "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/runner.py"
    click Executors "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/executors.py"
    click Transformers "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/TransformersModelManager.py"
    click Sana "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/SanaModelManager.py"
    click TestM "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/TestModelManager.py"
    click Zipper "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/zipper.py"
    click SystemUtil "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/system.py"
    click Config "https://github.com/uomi-network/uomi-node-ai/blob/main/lib/config.py"
    click ServiceDef "https://github.com/uomi-network/uomi-node-ai/blob/main/uomi-ai.service"
    click Dockerfile "https://github.com/uomi-network/uomi-node-ai/tree/main/Dockerfile"
    click Compose "https://github.com/uomi-network/uomi-node-ai/blob/main/docker-compose.yml"
    click InstallScript "https://github.com/uomi-network/uomi-node-ai/blob/main/install.sh"
    click Readme "https://github.com/uomi-network/uomi-node-ai/blob/main/README.md"
    click GitIgnore "https://github.com/uomi-network/uomi-node-ai/blob/main/.gitignore"
    click TestRunner "https://github.com/uomi-network/uomi-node-ai/blob/main/test/runner_test.py"
    click TestSystem "https://github.com/uomi-network/uomi-node-ai/blob/main/test/system_test.py"
    click TestZipper "https://github.com/uomi-network/uomi-node-ai/blob/main/test/zipper_test.py"
```
