FractalAndroid README

README проекта с github.com/Fractal-Compute-Orchestrations/FractalAndroid. Одним файлом markdown: README.md.

FractalAndroid Header

FractalAndroid

Resource-Aware Edge Compute Node and Mobile Execution Engine

Kotlin Version Android API Design Architecture License Android CI

FractalAndroid is the distributed compute client and edge execution runtime for the Fractal decentralized intelligence framework.

Overview | Edge Benchmarks | Design Showcase | App UI Tour | WiFi Bank Rewards | Design Case Study | Architecture | Telemetry Gating | Lifecycle | Build & Setup | References


Overview

Executive Summary: Core Purpose & Bottom Line

The Problem: Running machine learning workloads on consumer smartphones traditionally causes rapid battery drain, thermal throttling (>42°C), user UI lag, and process termination by the Android Low Memory Killer (LMK).

The FractalAndroid Achievement:

  • Hardware-Gated Compute: Automatically pauses execution if SoC temperature exceeds 40°C, battery drops below 80%, or unmetered Wi-Fi is disconnected.
  • Zero LMK Evictions: Directly streams 4-bit partitioned .pte sub-graphs into unified LPDDR memory via mmap, avoiding JVM Garbage Collection overhead and keeping RAM usage well beneath device thresholds.
  • 85.6% Less RF Power: Slashes parameter upload time from 321.2s to 46.2s over 10 Mbps links, eliminating radio power amplifier heating and conserving device battery health.

FractalAndroid turns Android mobile devices into autonomous, privacy-preserving compute nodes within the Fractal distributed network. Operating in coordination with the central server (FractalCore), the application executes localized machine learning workloads, including on-device federated training (TFLite) and partitioned batch dataset training, without exposing user data or degrading host device performance.

The client is designed with strict resource empathy: the engine continuously monitors physical hardware telemetry (SoC temperature, battery level, charging status, RAM pressure) and dynamically gates computation to guarantee zero impact on user experience or battery longevity.


Mobile UI Design & Hardware Showcase

Active Node Telemetry Model Training Metrics Platform Architecture Dock Iconography
Active Compute Node
Live training telemetry & diamond meter
Model Training Metrics
Performance curves & parameter transfer
Platform Architecture
Decentralized cloud & studio identity
Dock Iconography
Light & dark adaptive icon variants

Mobile Application Interface

1. Onboarding, Device Authorization & Binding

Get Started Device Authorization Registered Info
Get Started: Platform onboarding introducing the decentralized compute harvesting paradigm. Device Authorization: Firebase auth & hardware ID binding (`ANDROID_ID`, CPU, RAM). Registered Info: Confirmed registration profile and assigned compute node telemetry.

2. Node Fleet States & Real-Time Compute

Home Inactive Home Active Node Settings
Home (Standby / Inactive): Idle state awaiting task assignment with live hardware monitors. Home (Active Compute): Active local training with pulsing fractal diamond indicator. Node Settings & Preferences: Autonomous telemetry thresholds and charging policies.

3. Telemetry, Analytics & Training Insights

Usage Insights Device Insights Model Training
Usage Insights: Time-series telemetry graphs for CPU, RAM, battery, and thermals. Device Insights: Detailed hardware profiling with one-tap memory optimization. Model Training: Live loss convergence curves, parameter transfer rates, and epoch progress.

WiFi Bank & Bandwidth Rewards

Fractal transforms idle consumer mobile hardware into active decentralized compute infrastructure through a fair, transparent reward exchange:

Internet Bank 0 GB Internet Bank 0.5 GB Internet Bank 0.7 GB Internet Bank 1.0 GB Internet Bank 1.5 GB Internet Bank 1.8 GB Internet Bank 2.0 GB
0.0 GB
Initial / Empty
0.5 GB
Wave Rising
0.7 GB
Accumulating
1.0 GB
50% Capacity
1.5 GB
75% Capacity
1.8 GB
90% Capacity
2.0 GB
Full Balance

System Architecture

The client application follows a decoupled Model-View-ViewModel (MVVM) architecture with strict separation between UI telemetry rendering, hardware gating controllers, execution runtimes, and network synchronization layers.

graph TD
    subgraph CentralServer ["FractalCore Control Plane"]
        TaskDistributor["Task & Segment Dispatcher"]
        ModelAggregator["Federated Model Aggregator"]
    end

    subgraph FractalAndroidClient ["FractalAndroid Compute Node"]
        direction TB

        subgraph PresentationLayer ["Presentation Layer (MVVM)"]
            UI["Dashboard, Insights & Telemetry UI"]
            VM["Telemetry & Task ViewModels"]
        end

        subgraph GatingLayer ["Hardware Governance"]
            OperationControl["OperationControl (Thermal & SoC Gating)"]
            TelemetrySensors["Battery, Thermal & Network Monitors"]
        end

        subgraph ExecutionLayer ["Compute Execution Engine"]
            ImageTrainer["Image_Trainer (TFLite Engine)"]
            DataManager["DataManager (ByteBuffer Batch Loader)"]
            CheckpointMgr["CheckpointManager (.ckpt Serialization)"]
        end

        subgraph NetworkLayer ["Data & Transport Tier"]
            ServerDAO["Server_DAO (Task Poller)"]
            Transmitter["ModelTransmitter (TLS Weight Egress)"]
        end
    end

    %% Wiring
    TaskDistributor <-->|"REST HTTPS (/api/task/current)"| ServerDAO
    ServerDAO --> OperationControl
    OperationControl --> TelemetrySensors
    TelemetrySensors --> VM
    VM --> UI

    OperationControl -->|"Permit: GRANTED"| ImageTrainer
    ImageTrainer --> DataManager
    ImageTrainer --> CheckpointMgr
    CheckpointMgr --> Transmitter
    Transmitter -->|"POST /api/model/upload"| ModelAggregator

Edge Performance Benchmarks & Transmission Efficiency

FractalAndroid is engineered to run foundation model training and inference within the physical constraints of consumer mobile hardware. The client runtime enforces strict memory bounds, thermal limits, and communication efficiency:

On-Device Metric Benchmarks

Metric / Dimension Uncompressed Baseline (FP32) Standard Uniform INT8 (QSGD) Global Tensor INT4 FRACTAL Block-wise INT4 Edge Benefit
TinyLlama Wire Checkpoint 4,196 MB 1,049 MB 524 MB 590 MB 7.1x smaller payload
10 Mbps Sync Latency (100M) 321.2 s 81.2 s 41.2 s 46.2 s 86% reduction in radio active duty cycle
Model Weight Fidelity (Cosine Sim) 1.0000 0.9924 0.8296 (Fails) 0.9878 Full numerical convergence sustained
Model Slice Memory Bound >1,000 MB ~500 MB <150 MB <150 MB Zero Android LMK (Low Memory Killer) evictions
Activation Frame Overhead 16.4 KB 4.1 KB N/A <=4,100 bytes Fits single non-fragmented Wi-Fi packet

Hardware Co-Design & Edge Longevity Engineering


Hardware Telemetry Gating

The client enforces strict multi-variable gating via OperationControl before and during computation:

Telemetry Parameter Operational Threshold Action on Violation
Battery State-of-Charge Level $\ge$ 50% or Charging == True Workload paused until charging connected
Battery Temperature Temp $\le$ 40.0 C Execution paused until thermal normalization
Network Connectivity Unmetered Wi-Fi Connected Checkpoint upload deferred
Memory Pressure System Memory Low == False Batch buffer size throttled

Execution Lifecycle

The lifecycle of a single federated compute round on the mobile client proceeds through automated telemetry checks, training execution, and encrypted checkpoint transmission.

sequenceDiagram
    participant Server as FractalCore Server
    participant Net as Server_DAO / Transmitter
    participant Gate as OperationControl
    participant Engine as Image_Trainer
    participant Storage as CheckpointManager

    Note over Net,Engine: Standby & Periodic Task Polling
    Net->>Server: GET /api/task/current (device_id)
    Server-->>Net: ActiveTask Payload (URLs + Hyperparams)

    Net->>Gate: Request Execution Permit
    Gate->>Gate: Sample Battery SoC, Thermals & Charging
    alt Thermals > 40C or Battery < 50%
        Gate-->>Net: Permit DENIED (Backoff & Sleep)
    else Hardware Telemetry Healthy
        Gate-->>Net: Permit GRANTED
    end

    Net->>Server: Download Model (.tflite) + Binary Data Bins
    Net->>Engine: Initialize Weights & Segment Inputs

    loop Epoch Loop
        Engine->>Engine: Execute Local Gradient Descent Batch
        Gate->>Gate: Continuous Thermal Check
        alt Thermal Spike Detected
            Gate->>Engine: Signal PAUSE (Preserve State)
            Note over Engine: Wait for Thermal Normalization
            Gate->>Engine: Signal RESUME
        end
    end

    Engine->>Storage: Serialize Local Weight Checkpoint (.ckpt)
    Storage->>Net: Pass Parameter Deltas
    Net->>Server: POST /api/model/upload (task_Id, device_id, .ckpt)
    Server-->>Net: 200 OK (Liquid MB Reward Credited)

Module Breakdown

FractalAndroid/
|-- app/src/main/java/
|   |-- AppBackend/
|   |   |-- DataManager/             # Dataset binary segment parsing and caching
|   |   |-- LocalTrainingModule/     # TFLite Gradient Descent, Image_Trainer
|   |   |-- Network/                 # Server_DAO, ModelTransmitter (TLS HTTP)
|   |   |-- ResourceManagement/      # OperationControl, Battery & Thermal Telemetry
|   |   |-- TaskContainer/           # ActiveTask DTOs and JSON serialization
|   |   `-- Validator/               # Accuracy validation & inference assertions
|   |-- AppFrontend/
|   |   |-- Auth/                    # Node Registration & Binding UI
|   |   |-- Home/                    # Real-Time Compute & Training Dashboard
|   |   |-- Insights/                # Real-Time Telemetry & Hardware Charts
|   |   `-- Settings/                # Target Server URL & Threshold Configuration
|   `-- AppGlobal/                   # Cross-cutting Constants & Utility Helpers
|-- build.gradle.kts                 # Root Kotlin DSL Build Configuration
|-- app/build.gradle.kts             # Application Module Build Configuration
`-- docs/                            # Architecture Diagrams (.drawio) and Assets

Technical Pipeline Specifications

Pipeline Stage Java/Kotlin Implementation Responsibility
Ingress Server_DAO Polling task endpoints with exponential backoff and payload decoding.
Gating OperationControl Real-time multi-variable telemetry gating (Thermal, Battery, RAM).
Execution Image_Trainer On-device gradient calculation using optimized TFLite mobile kernels.
Data Parsing DataManager / FileOperations Loading binary dataset batches into direct ByteBuffer structures.
Persistence CheckpointManager Serialization of intermediate parameter matrices (.ckpt).
Egress ModelTransmitter Encrypted transmission of .ckpt parameter updates to FractalCore.

Development and Build

Prerequisites

Build Workflow

# 1. Clone the repository
git clone https://github.com/Fractal-Compute-Orchestrations/FractalAndroid.git
cd FractalAndroid

# 2. Run JVM Unit Tests (FRQ4/FRQD codec, thermal gating, path safety)
./gradlew testDebugUnitTest

# 3. Build Debug APK
./gradlew assembleDebug

# 4. Install and Run on Connected Device
./gradlew installDebug

Wire-Compatible INT4 Codec & Storage Hardening


Security & Privacy Guarantee


FractalAndroid hardware-aware execution model, on-device telemetry gating, and mobile parameter exchange draw from key literature in mobile edge computing and on-device machine learning:

Resource-Aware On-Device Execution

Wireless Communication & Parameter Compression


Governance & Licensing

FractalAndroid is maintained and owned by Fractal Compute Orchestrations.

FractalAndroid (Fractal-Compute-Orchestrations/FractalAndroid)

Ищем в базе…

Что это такое?FractalAndroid — это Android-клиент, который превращает телефон в узел распределённых вычислений с сохранением приватности для распределённой сети искусственного интеллекта Fractal. Обучение федеративным методом (TFLite) выполняется прямо на устройстве в координации с центральным сервером под названием FractalCore.
Это самостоятельное приложение или ему нужен сервер?Это мобильное приложение, но само по себе оно не работает: оно опрашивает эндпоинты задач и загружает зашифрованные контрольные точки модели на отдельный бэкенд FractalCore, который не входит в этот репозиторий.
Как собрать и запустить это на своём телефоне?Откройте проект в Android Studio 2023.3.1 (Jellyfish) или новее с Compile SDK 34 и соберите и запустите его на физическом Android-устройстве, так как обратная связь по температуре и датчикам требует реального железа.
Какие инструменты нужны перед сборкой?Нужны Android Studio 2023.3.1+, Android SDK с Compile SDK 34 и Min SDK 24, а также JDK 17 (рекомендуется для Gradle 8+).
Будет ли оно разряжать батарею или работать постоянно?Нет — система контроля телеметрии (OperationControl) приостанавливает обучение, если устройство не заряжается и заряд батареи не выше 50%, температура батареи не выше 40°C, подключение идёт не по безлимитному Wi-Fi или нехватка памяти невелика.
Мои личные данные (фото, показания датчиков) куда-нибудь загружаются?Нет. Исходные данные пользователя остаются на устройстве; на сервер передаются только математические параметры контрольных точек модели, по зашифрованному HTTPS (TLS).
Можно ли использовать или изменять это в коммерческих целях?Нет. Это проприетарное программное обеспечение с открытым исходным кодом по строгой некоммерческой лицензии — все права защищены, коммерческое использование строго запрещено без письменного разрешения.
Что именно приложение обучает на моём устройстве?Оно выполняет вычисления градиентов прямо на устройстве с помощью оптимизированных мобильных ядер TFLite (через модуль ImageTrainer) на разделённых пакетных наборах данных, загруженных в структуры ByteBuffer, а затем сохраняет полученные параметры в файлах .ckpt.
Какая архитектура используется клиентом внутри?Клиент построен по паттерну MVVM с отдельными слоями: ServerDAO для опроса задач, OperationControl для контроля оборудования, ImageTrainer для выполнения, CheckpointManager для сохранения и ModelTransmitter для зашифрованной отправки данных.
Размер
15.6 MB
Звёзды
4.9K
Возраст
11 мес
Коммиты · 90 дней