Fractal-Compute-Orchestrations/FractalCore

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.

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
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: Tenant creation, TFLOPs computation caps, MB reward rates, and multi-tenant fleet roster.	Authentication Gate: Tab-isolated per-session tokenized access control with Genos typography.

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

• Tenant Sandboxing: Maintains physically separated storage paths (data/tenants/{username}/) for datasets, training bins, uploaded checkpoints, and compiled global models.
• Session Isolation: Authentication relies strictly on the X-Auth-Token header (secrets.token_hex(32)), backed by a thread-safe token registry with zero cookie leakage between browser tabs or clients.
• TFLOPs Budget Management: Enforces per-tenant compute limits, monitoring compute capacity and round progression in real time.

• Task Dispatching: Distributes tasks (ActiveTask) referencing specific binary data bins to available Android nodes based on hardware telemetry proofs.
• Deterministic Averaging: Validates uploaded checkpoints against the active task registry and executes FedAvg weight summation using TensorFlow/NumPy upon reaching the round threshold.
• Model Checkpointing: Serializes and archives aggregated model weights, updating the active model served to subsequent rounds.

• Block Ingestion: Ingests monolithic Hugging Face models (e.g., Llama 3 8B, TinyLlama) and extracts isolated decoder transformer blocks without breaking weight references.
• INT4 Quantization: Applies grouped weight-only quantization (torchao INT4, group size 128) targeting linear attention and MLP projections to reduce layer memory footprints below 150MB.
• Static ATen Tracing: Freezes dynamic Python operations into static computational graphs via torch.export.
• XNNPACK Lowering & Export: Lowering to ExecuTorch Edge dialect with XNNPACK microkernels, serialized into .pte binaries for zero-copy mmap ingestion on Android nodes.

• Hardware Telemetry Verification: Inspects device IDs and task receipts.
• Liquid MB Settlement: Credits compute tokens ("Liquid MBs") directly to user profiles in Google Cloud Firestore upon successful checkpoint verification.

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

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

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

# 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

# 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

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

• Zero Data Ingress: The server never accesses raw user data; all computation occurs locally on edge devices.
• Header-Bound Authentication: Enforced X-Auth-Token validation without cookie fallback prevents cross-session bleeding.
• Tenant Sandboxing: Filesystem-level isolation prevents cross-tenant access to datasets, task queues, or checkpoint models.
• Replay Protection: Single-use task_Id assignment prevents duplicate or stale weight injection.

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

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.