# claudiobors/robycode architecture

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

- Interactive diagram: https://gitdiagram.com/claudiobors/robycode
- Repository: https://github.com/claudiobors/robycode

## Overview

##### Project Type and Purpose
- This is a Python-based machine learning experimentation toolkit (“roby”) focused on three main analysis modes: referral, robustness, and uncertainty.
- It provides core engines for running neural-network experiments (ReferralNN, RobustnessNN, UncertaintyNN), collecting results, computing metrics, and generating visualizations.

##### High-Level File Structure Analysis
- Root scripts and batch files:
- run_roby.py – main entry point
- download_mnist.py – dataset fetcher
- *.bat files – Windows wrappers for common tasks (build, test, run)
- Configuration:
- json config/ – JSON templates driving experiment parameters (referral, robustness, uncertainty)
- Core library (roby/):
- Alterations.py, EnsembleTools.py, CloudTools.py, Utility.py – shared services (data transforms, cloud integration, utility functions)
- EnvironmentRTest.py, Reporter.py – environment management and logging
- ReferralNN.py, RobustnessNN.py, UncertaintyNN.py – three specialized experiment engines
- *_Results.py – result collectors for each mode
- Metrics and visualization:
- roby/metrics/ – modular metrics implementations (accuracies, calibration, curves, utility, area-based)
- roby/uncertainty/measures.py – uncertainty-specific measures
- roby/viz/ – plotting routines for referral, robustness

##### Identifying Main Components
a. Runner Layer (CLI & scripts):
– run_roby.py, batch wrappers → orchestrates the workflow.
b. Configuration Layer:
– JSON config files → parameter definitions for each analysis mode.
c. Data Layer:
– download_mnist.py → data ingestion; Alterations → data augmentation.
d. Core Processing Layer:
– ReferralNN, RobustnessNN, UncertaintyNN → load data + config, execute model training/evaluation.
– Utility, EnsembleTools, CloudTools → shared operations (model ensemble, cloud compute offloading).
e. Metrics Layer:
– roby/metrics + roby/uncertainty/measures → compute performance metrics post-run.
f. Visualization & Reporting Layer:
– roby/viz/referral.py, robustness.py → produce plots; Reporter → generate HTML logs.
g. Output Artifacts:
– log_*.html files, saved model checkpoints, result data structures.

##### Relationships & Data Flow
- Start: Runner reads CLI arguments → loads appropriate JSON config.
- Data ingestion: download_mnist → data repository → Alterations preprocesses data.
- Processing: Core engines (ReferralNN, etc.) consume data + config → train/evaluate models.
- Shared tools: Utilities, Ensembles, CloudTools invoked as needed.
- Metrics: Engines emit raw predictions → metrics layer computes statistics.
- Reporting: Reporter + viz modules generate HTML/logs/plots.

##### Architectural Patterns & Design Principles
- Layered architecture – clear separation of concerns (configuration, data, processing, metrics, viz).
- Modular plug-in structure – adding a new analysis mode or metric only requires dropping in a new module under roby/.
- Dependency injection via JSON config – experiment parameters externalized.
- Single-responsibility classes – each NN mode and results class handles its own logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration Layer"
        C1["config_referral.json"]:::config
        C2["config_referral_dottore.json"]:::config
        C3["config_robustness.json"]:::config
        C4["config_uncertainty.json"]:::config
    end

    %% Runner Layer
    subgraph "Runner Layer"
        R1["run_roby.py"]:::runner
        R2["apriconsole.bat"]:::runner
        R3["build.bat"]:::runner
        R4["test_referral.bat"]:::runner
        R5["test_robustness.bat"]:::runner
        R6["test_uncertainty.bat"]:::runner
        R7["test referral dottore.bat"]:::runner
        R8["test_mnist_completo.bat"]:::runner
        R9["test_mnist_uncertainty.bat"]:::runner
    end

    %% Data Layer
    subgraph "Data Layer"
        D1["download_mnist.py"]:::data
        D2["Alterations.py"]:::data
    end

    %% Core Processing Layer
    subgraph "Core Processing Layer"
        E1["ReferralNN.py"]:::core
        E2["RobustnessNN.py"]:::core
        E3["UncertaintyNN.py"]:::core
        U1["Utility.py"]:::core
        U2["EnsembleTools.py"]:::core
        U3["CloudTools.py"]:::core
    end

    %% Results Collection
    subgraph "Results Collection"
        RR["ReferralResults.py"]:::core
        RSR["RobustnessResults.py"]:::core
        UR["UncertaintyResults.py"]:::core
    end

    %% Metrics Layer
    subgraph "Metrics Layer"
        M1["accuracies.py"]:::metrics
        M2["area_based.py"]:::metrics
        M3["calibration.py"]:::metrics
        M4["curves.py"]:::metrics
        M5["utility.py"]:::metrics
        M6["measures.py"]:::metrics
    end

    %% Visualization & Reporting Layer
    subgraph "Visualization & Reporting Layer"
        V1["referral.py"]:::viz
        V2["robustness.py"]:::viz
        REP["Reporter.py"]:::viz
    end

    %% Output Artifacts
    subgraph "Output Artifacts"
        O1["log_referral_json.html"]:::output
        O2["log_robustness_json.html"]:::output
    end

    %% Connections
    C1 --> R1
    C2 --> R1
    C3 --> R1
    C4 --> R1

    R1 --> D1
    D1 --> D2
    D2 --> E1
    D2 --> E2
    D2 --> E3

    E1 --> RR
    E2 --> RSR
    E3 --> UR

    E1 --> U1
    E2 --> U1
    E3 --> U1
    E1 --> U2
    E2 --> U2
    E3 --> U2
    E1 --> U3
    E2 --> U3
    E3 --> U3

    RR --> M1
    RR --> M2
    RR --> M3
    RR --> M4
    RR --> M5
    RR --> M6

    RSR --> M1
    RSR --> M2
    RSR --> M3
    RSR --> M4
    RSR --> M5
    RSR --> M6

    UR --> M1
    UR --> M2
    UR --> M3
    UR --> M4
    UR --> M5
    UR --> M6

    M1 --> V1
    M2 --> V1
    M3 --> V1
    M4 --> V1
    M5 --> V1
    M6 --> V1

    M1 --> V2
    M2 --> V2
    M3 --> V2
    M4 --> V2
    M5 --> V2
    M6 --> V2

    V1 --> REP
    V2 --> REP
    REP --> O1
    REP --> O2

    %% Click Events
    click R1 "https://github.com/claudiobors/robycode/blob/main/roby/run_roby.py"
    click R2 "https://github.com/claudiobors/robycode/blob/main/apriconsole.bat"
    click R3 "https://github.com/claudiobors/robycode/blob/main/build.bat"
    click R4 "https://github.com/claudiobors/robycode/blob/main/test_referral.bat"
    click R5 "https://github.com/claudiobors/robycode/blob/main/test_robustness.bat"
    click R6 "https://github.com/claudiobors/robycode/blob/main/test_uncertainty.bat"
    click R7 "https://github.com/claudiobors/robycode/blob/main/test referral dottore.bat"
    click R8 "https://github.com/claudiobors/robycode/blob/main/test_mnist_completo.bat"
    click R9 "https://github.com/claudiobors/robycode/blob/main/test_mnist_uncertainty.bat"
    click C1 "https://github.com/claudiobors/robycode/blob/main/json config/config_referral.json"
    click C2 "https://github.com/claudiobors/robycode/blob/main/json config/config_referral_dottore.json"
    click C3 "https://github.com/claudiobors/robycode/blob/main/json config/config_robustness.json"
    click C4 "https://github.com/claudiobors/robycode/blob/main/json config/config_uncertainty.json"
    click D1 "https://github.com/claudiobors/robycode/blob/main/download_mnist.py"
    click D2 "https://github.com/claudiobors/robycode/blob/main/roby/Alterations.py"
    click E1 "https://github.com/claudiobors/robycode/blob/main/roby/ReferralNN.py"
    click E2 "https://github.com/claudiobors/robycode/blob/main/roby/RobustnessNN.py"
    click E3 "https://github.com/claudiobors/robycode/blob/main/roby/UncertaintyNN.py"
    click U1 "https://github.com/claudiobors/robycode/blob/main/roby/Utility.py"
    click U2 "https://github.com/claudiobors/robycode/blob/main/roby/EnsembleTools.py"
    click U3 "https://github.com/claudiobors/robycode/blob/main/roby/CloudTools.py"
    click RR "https://github.com/claudiobors/robycode/blob/main/roby/ReferralResults.py"
    click RSR "https://github.com/claudiobors/robycode/blob/main/roby/RobustnessResults.py"
    click UR "https://github.com/claudiobors/robycode/blob/main/roby/UncertaintyResults.py"
    click M1 "https://github.com/claudiobors/robycode/blob/main/roby/metrics/accuracies.py"
    click M2 "https://github.com/claudiobors/robycode/blob/main/roby/metrics/area_based.py"
    click M3 "https://github.com/claudiobors/robycode/blob/main/roby/metrics/calibration.py"
    click M4 "https://github.com/claudiobors/robycode/blob/main/roby/metrics/curves.py"
    click M5 "https://github.com/claudiobors/robycode/blob/main/roby/metrics/utility.py"
    click M6 "https://github.com/claudiobors/robycode/blob/main/roby/uncertainty/measures.py"
    click V1 "https://github.com/claudiobors/robycode/blob/main/roby/viz/referral.py"
    click V2 "https://github.com/claudiobors/robycode/blob/main/roby/viz/robustness.py"
    click REP "https://github.com/claudiobors/robycode/blob/main/roby/Reporter.py"

    %% Styles
    classDef config fill:#A0D995,stroke:#333,stroke-width:1px
    classDef runner fill:#9FC5E8,stroke:#333,stroke-width:1px
    classDef data fill:#8ED1B2,stroke:#333,stroke-width:1px
    classDef core fill:#6D9EEB,stroke:#333,stroke-width:1px
    classDef metrics fill:#B4A7D6,stroke:#333,stroke-width:1px
    classDef viz fill:#F9CB9C,stroke:#333,stroke-width:1px
    classDef output fill:#CCCCCC,stroke:#333,stroke-width:1px
```
