FractalCore README

The project's README from github.com/Fractal-Compute-Orchestrations/FractalCore. As one markdown file: README.md.

Fractal Server Header

FractalCore

High-Performance Orchestration Engine, Federated Aggregator, and Model Graph Slicer

Version License Design Security Maintainer

FractalCore is the central server, control plane, and model compilation engine for the Fractal decentralized compute ecosystem.

Overview | Control Plane UI | Design Case Study | Architecture | Core Components | Data Flow | API Summary | Deployment | Security

Overview

FractalCore serves as the centralized orchestration backbone that coordinates decentralized edge nodes (FractalAndroid). It handles the end-to-end lifecycle of distributed machine learning tasks, executing two primary operations:

  1. Federated Learning Orchestration: Multi-tenant data binning, task scheduling, client checkpoint verification, and deterministic parameter aggregation via Federated Averaging (FedAvg).
  2. Foundation Model Slicing: Offline neural graph surgery, INT4 weight quantization, static ATen graph tracing, and XNNPACK lowering (inference-model-maker/slicer) to produce memory-safe .pte layer partitions for mobile nodes.

Control Plane Web Interface

FractalCore provides a hardware-accelerated, high-density Web UI engineered for orchestrating federated learning tasks, monitoring compute budgets, and isolating tenant silos:

Tenant Operations Dashboard
Tenant Dashboard

Real-Time Tenant Dashboard: Live TFLOPs quota gauge, dynamic round progress, active mobile node telemetry, and streaming activity log.
Admin Fleet Console Node Authentication Portal
Admin Console

Admin Console: Tenant creation, TFLOPs computation caps, MB reward rates, and multi-tenant fleet roster.

 Login Portal

Authentication Gate: Tab-isolated per-session tokenized access control with Genos typography.

System Architecture

FractalCore decouples tenant session control from compute dispatching and storage silos:

graph TD
    subgraph ClientFleet ["Edge Client Fleet (FractalAndroid)"]
        Node1["Android Node 1"]
        Node2["Android Node 2"]
        NodeN["Android Node N"]
    end

    subgraph FractalCoreServer ["FractalCore Control Plane"]
        API["REST Gateway & Route Handlers"]
        AuthModule["X-Auth-Token Session Manager"]
        TenantMgr["Multi-Tenant Isolation Manager"]
        TaskScheduler["Task Queue & Segment Dispatcher"]
        AggEngine["Federated Averaging Engine (FedAvg)"]
        SlicerPipeline["Model Slicer & INT4 Quantizer"]
        RewardService["Liquid MB Reward Processor"]
    end

    subgraph StorageLayer ["Persistence & State"]
        FirestoreDB[("Firestore (Tenants / Devices / Ledger)")]
        DiskStorage[("Local Silos (tenants/username/bins, uploads, models)")]
    end

    %% Client Connections
    Node1 & Node2 & NodeN <-->|"REST HTTPS (X-Auth-Token / Task / Checkpoint)"| API

    %% Internal Wiring
    API --> AuthModule
    AuthModule --> TenantMgr
    TenantMgr --> TaskScheduler
    TaskScheduler --> DiskStorage
    TaskScheduler --> AggEngine
    AggEngine --> DiskStorage
    SlicerPipeline --> DiskStorage
    RewardService --> FirestoreDB
    API --> RewardService

Core Components

1. Multi-Tenant Orchestrator (src/fractal_server/server.py)

2. Federated Aggregation Engine

3. Model Slicing Compiler (src/inference-model-maker/slicer/)

4. Reward & Ledger Interface (src/fractal_server/firebase_reward.py)

Data Flow and Lifecycle

sequenceDiagram
    participant Admin as Tenant Admin
    participant Core as FractalCore Server
    participant Node as Android Client Node
    participant Firestore as Firestore Registry

    Admin->>Core: POST /api/admin/tenant (Configure Session & TFLOP Budget)
    Admin->>Core: Upload Training Data -> Generate Binary Bins
    Note over Core: Partition Bins into Segment Tasks

    loop Compute Round
        Node->>Core: GET /api/task/current (device_id)
        Core-->>Node: 200 OK (task_Id, model URL, bin URL, hyperparams)
        Node->>Core: GET /download/model & GET /download/images
        Note over Node: Local On-Device Training (TFLite)
        Node->>Core: POST /api/model/upload (task_Id, device_id, .ckpt)
        Core->>Core: Validate task_Id Against Dispatch Registry
        Core->>Firestore: Credit Liquid MB Reward
        alt Quorum Reached (N Checkpoints Uploaded)
            Core->>Core: Execute FedAvg Tensor Summation
            Core->>Core: Generate New Global Model Checkpoint
            Core->>Core: Increment Session Round
        end
    end

API Reference Summary

Full API schemas and contracts are documented in docs/api.md.

Endpoint Method Authentication Purpose
/api/admin/login POST None Authenticate admin / tenant and receive X-Auth-Token
/api/admin/tenants GET X-Auth-Token (Admin) List all registered tenants and compute budgets
/api/admin/tenant POST X-Auth-Token (Admin) Provision a new tenant and allocate TFLOP budget
/api/task/current GET None / Device ID Request active training task descriptor for a mobile node
/api/model/upload POST Multipart Form Upload computed local checkpoint delta (.ckpt)
/download/model GET Query param Download current global model checkpoint (.tflite)
/download/images GET Query param Download binary dataset image segment bin
/download/labels GET Query param Download binary dataset label segment bin

Directory Structure

FractalCore/
|-- src/
|   |-- fractal_server/              # Production Multi-Tenant Server
|   |   |-- server.py                # Main Flask Application & API Routes
|   |   `-- firebase_reward.py       # Firestore Ledger & Credit Processor
|   |-- inference-model-maker/       # Model Slicing & Partitioning System
|   |   |-- run_pipeline.py          # Slicer CLI Orchestrator
|   |   `-- slicer/                  # Workstations, Validators & Contracts
|   `-- legacy/                      # Single-user prototypes & migration assets
|-- scripts/                         # Operations, Sweepers & Global Model Testers
|-- docs/                            # Deep Technical Specs, API & Architecture
|-- Dockerfile                       # Production Container Definition
|-- docker-compose.yml               # Multi-Service Orchestration Config
|-- requirements.txt                 # Core Python Dependencies
`-- tests/                           # Unit and Integration Test Suites

Deployment and Execution

Docker Deployment (Production Standard)

# 1. Configure Environment Variables
cp .env.example .env

# 2. Build and Launch Container
docker-compose up --build -d

# 3. Stream Container Logs
docker-compose logs -f

Manual Host Execution

# 1. Create Virtual Environment
python3 -m venv venv
source venv/bin/activate

# 2. Install Dependencies
pip install -r requirements.txt

# 3. Launch with Gunicorn WSGI
gunicorn --bind 0.0.0.0:5000 src.fractal_server.server:app

Code Formatting & Quality Verification

All Python source files must adhere to black formatting and flake8 standards:

# Format Python source files
black .

# Check formatting compliance
black --check .

# Lint source files
flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics

Security Model

For full vulnerability reporting procedures, refer to SECURITY.md.

Governance & Licensing

FractalCore is proprietary, source-available software licensed under the Fractal Proprietary Source-Available & Non-Commercial Restrictive License v3.0. All Rights Reserved. Commercial use strictly prohibited without written authorization.

FractalCore -- Architected and maintained by Ahmad Hassan (B-Ted).

FractalCore (Fractal-Compute-Orchestrations/FractalCore)

Searching Database…

1.8K ·GitHub
FractalCore
What is this?FractalCore is the central backend orchestrator for the Fractal decentralized compute ecosystem. It coordinates federated learning tasks across Android edge nodes, manages multi-tenant TFLOPs budgets, and runs FedAvg weight aggregation to build a global model.
Is this an app I install, or a server I run myself?It is a self-hosted Python/Flask backend with a web-based admin and tenant dashboard, not a desktop or mobile app. You run it as a server that mobile edge nodes talk to over its API.
How do I get the server running?The README documents Docker deployment as the production standard, with manual host execution as an alternative for running the Flask server directly.
What stack does the server rely on?It's built on Python/Flask, uses TensorFlow and NumPy to run FedAvg aggregation, torchao/ExecuTorch/XNNPACK for model slicing, and Google Cloud Firestore for reward ledgering.
Can I use this commercially?No. It's source-available but proprietary, and the license explicitly forbids commercial use without written authorization from the author.
What kind of devices does it coordinate?It orchestrates Android edge nodes (from the companion FractalAndroid project) that train locally and upload checkpoints, while this repo is the centralized coordinator they report to.
Does the server see or store my raw training data?No. The security model claims zero data ingress: raw user data never leaves the edge device, only checkpoints and aggregated weights reach the server.
What does the FedAvg aggregation actually do?It validates uploaded client checkpoints against the active task registry and deterministically averages their weights once a training round hits its threshold, producing the next global model checkpoint.
What is the model slicer for?It ingests full Hugging Face models like Llama 3 8B or TinyLlama, applies INT4 quantization and static ATen graph tracing, then lowers them with XNNPACK into small .pte partitions that mobile nodes can mmap without blowing their memory budget.
What are Liquid MBs?They are the reward tokens credited to a tenant's Firestore profile after a mobile node's hardware telemetry and checkpoint are verified as genuine contributed compute.
How are different tenants kept from seeing each other's data?Each tenant gets a physically separate storage path on disk and must authenticate with a per-session X-Auth-Token header, so there's no shared cookie state or cross-tenant filesystem access.
What are similar projects?FractalWorkspace, GLM-5.3-Flash-EXL3-2x-DGX-Sparks-TensorFold, FractalWorkspace, InstinctFlash, decider, vllm-omni, openvino, Qwen3.8-Flash-Next-Dual-DGX-Sparks
Which topics is it in?federated-learning, orchestrator, flask, model-serving, edge-ai, tensorflow, iot, quantization, authentication, distributed-systems, inference, huggingface
Creator
Fractal-Compute-Orchestrations
Size
69.3 MB
Stars
1.8K
Updated
CommitAug 22
Age
5mo
Commits · 90 Days