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

FractalCore is the central server, control plane, and model compilation engine for the Fractal decentralized compute ecosystem.
Overview | Quickstart SDK | Key Results & Benchmarks | Industry & Community Recognition | Control Plane UI | Architecture | Core Components | Data Flow | API Summary | Deployment | Security | Theoretical Foundations
Install the lightweight runtime package (numpy core codec + CLI, optional server and slicer extras) and run the reproducible outlier-resilience benchmark locally in seconds:
pip install -e ".[server]"
fractal doctor
fractal bench
python scripts/quickstart_demo.py
Or run the zero-setup walkthrough in examples/colab_quickstart.ipynb.
The Problem: Centralized federated aggregators face network ingress bandwidth saturation when orchestrating edge fleets: receiving uncompressed FP32 checkpoints from hundreds of mobile devices consumes gigabits of bandwidth and triggers severe client timeout drops (>5 minutes per round). Naive 4-bit compression destroys model attention layers (Layer 5 collapses to 0.6990).
The FractalCore Achievement:
- 7.11x Ingress Bandwidth Relief: Compresses model broadcast and client upload payloads by 85.9%, dropping round latency from 321.2s to 46.2s at 10 Mbps.
- Zero Accuracy Degradation: 64-element micro-block quantization isolates outliers, sustaining 0.9878 mean cosine similarity and guaranteeing stable FedAvg/FedProx convergence.
- Automated Model Slicing: ATen graph compiler slices multi-billion parameter models into memory-safe ExecuTorch
.ptesub-graphs sized dynamically to client RAM budgets.
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:
FedAvg).inference-model-maker/slicer) to produce memory-safe .pte layer partitions for mobile nodes.FractalCore model slicer and parameter aggregation engine are benchmarked across 253,755,392 real transformer parameters from TinyLlama-1.1B (22 layers, 2048 hidden dimension, 5632 intermediate dimension) and MobileNetV3. All metrics are calculated directly from matrix quantization operations and physical network transmission models.
| Metric Dimension | Uncompressed Baseline (FP32) | Half-Precision (FP16) | Standard Uniform INT8 (QSGD) | Global Tensor INT4 | FRACTAL Micro-Block INT4 | Empirical Impact |
|---|---|---|---|---|---|---|
| TinyLlama Wire Payload | 4,196 MB | 2,098 MB | 1,049 MB | 524 MB | 590 MB | 7.1x wire payload reduction |
| Reconstruction Fidelity | 1.0000 | >0.9999 | 0.9924 | 0.8296 (Fails) | 0.9878 | Zero divergence across 22 layers |
| Mean Squared Error (MSE) | 0.000000 | <0.000001 | 0.000018 | 0.000433 | 0.000043 | 10x lower error vs Global INT4 |
| 10 Mbps Uplink Latency (100M) | 321.2 s | 161.2 s | 81.2 s | 41.2 s | 46.2 s | 86% reduction in radio duty cycle |
| Training Viability | Lossless (Stable) | Lossless (Stable) | High Fidelity (Stable) | Catastrophic Divergence | Pareto Optimal (Stable) | Enables true 4-bit edge convergence |
| Method / Framework | Target Representation | TinyLlama-1.1B Payload | Wire Reduction Ratio | Mean Layer Cosine Sim | 10 Mbps Uplink Latency | Physical Hardware Impact | Edge Index (EOI) | Training Viability |
|---|---|---|---|---|---|---|---|---|
| FRACTAL (Micro-Block INT4) | Packed Int4 + Scale | 590 MB | 7.1x | 0.9878 | 46.2 s | mmap streaming (Zero LMK) | 92 / 100 | PARETO OPTIMAL (Stable) |
| Flower (QSGD INT8) | Uniform Int8 | 1,049 MB | 4.0x | 0.9924 | 81.2 s | Standard Python/JVM heap | 71 / 100 | High Fidelity (Stable) |
| NVIDIA FLARE (Enterprise) | Float16 (16-bit) | 2,098 MB | 2.0x | >0.9999 | 161.2 s | High Ingress Saturation | 65 / 100 | Lossless (Stable) |
| FedML (HeteroFL Slicing) | Dynamic FP16 | ~1,500 MB | 2.8x | 0.9650 | ~110.0 s | Sub-graph slicing overhead | 61 / 100 | Moderate Fidelity |
| PySyft (OpenMined INT8) | Int8 Encrypted | 1,049 MB | 4.0x | 0.9900 | 81.2 s | Cryptographic CPU drain | 56 / 100 | Secure Aggregation (Stable) |
| TensorFlow Federated (TFF) | Float32 Baseline | 4,196 MB | 1.0x | 1.0000 | 321.2 s | Frequent Mobile LMK Eviction | 48 / 100 | Severe Edge Stragglers |
| PyTorch RPC (Uncompressed) | Float32 Baseline | 4,196 MB | 1.0x | 1.0000 | 321.2 s | Thermal Throttling (>42°C) | 44 / 100 | Raw Socket (Unsafe Edge) |
| Global Tensor INT4 | Standard Int4 | 524 MB | 8.0x | 0.8296 | 41.2 s | Low wire, zero convergence | 21 / 100 | FAILS: Severe Divergence |
Critical Note on Global INT4 vs FRACTAL: While Global INT4 appears 5 seconds faster on paper (41.2s vs 46.2s), it is completely unviable in practice. Single attention outliers inflate the global scale factor, forcing 99.9% of normal weights into zero bins and causing model output to collapse (cosine similarity dropping to 0.699 in deeper layers). FRACTAL pays a negligible 5-second scale overhead to rescue fidelity from 0.8296 back to 0.9878, making 4-bit edge training actually converge.
# Reproduce benchmarks and generate figures
python scripts/benchmark_evaluation.py
In transformer architectures, linear projections across multi-head self-attention and feed-forward networks (FFN) govern the primary parameter volume: $$W_q, W_k, W_v, W_o \in \mathbb{R}^{d_{\text{model}} \times d_{\text{model}}}, \quad W_{\text{gate}}, W_{\text{up}} \in \mathbb{R}^{d_{\text{ffn}} \times d_{\text{model}}}, \quad W_{\text{down}} \in \mathbb{R}^{d_{\text{model}} \times d_{\text{ffn}}}$$ During model training and adaptation, these matrices exhibit emergent heavy-tailed feature outliers where a minute fraction of parameters (less than 0.1%) reach magnitudes exceeding ten times the layer standard deviation ($|w| > 10\sigma_W$).
Standard uniform 4-bit quantization computes a single global scale across the entire weight tensor $W \in \mathbb{R}^{M \times N}$: $$\gamma_{\text{global}} = \frac{\max_{w \in W} |w|}{7.0}$$ When an extreme outlier satisfies $|w^*| \ge 10\sigma_W$, the global divisor becomes $\gamma_{\text{global}} \ge 1.43\sigma_W$. For normal in-distribution parameters satisfying $|w_i| \le 0.5\sigma_W$, the normalized quotient falls below the quantization threshold: $$\left| \frac{w_i}{\gamma_{\text{global}}} \right| \le \frac{0.5\sigma_W}{1.43\sigma_W} \approx 0.35 < 0.50$$ The nearest-integer rounding operator maps these parameters directly to zero: $$q_i = \text{clamp}\left( \left\lfloor \frac{w_i}{\gamma_{\text{global}}} \right\rceil, -8, 7 \right) = 0$$ This dynamic range collapse decimates $99.9%$ of active weight trajectories. Layer cosine similarity craters to 0.8296 overall (and 0.6990 in deeper self-attention projections), destroying gradient directionality and inducing catastrophic divergence during federated weight averaging.
FractalCore slicer and parameter aggregation engine partition flattened parameter arrays into micro-blocks of $B_k \in \mathbb{R}^{64}$: $$\gamma_k = \frac{\max_{w \in B_k} |w|}{7.0}$$ $$q_i = \text{clamp}\left( \left\lfloor \frac{w_i}{\gamma_k} \right\rceil, -8, 7 \right), \quad \forall w_i \in B_k$$ Pairs of signed 4-bit values $q_{2j}$ and $q_{2j+1}$ are bit-packed into single uint8 bytes: $$\text{packed}j = (q{2j} \ & \ \text{0x0F}) \ | \ ((q_{2j+1} \ & \ \text{0x0F}) \ll 4)$$
The architectural breakthroughs, hardware telemetry gating, and sub-byte parameter quantization methods introduced in FractalCore have garnered significant independent analysis from systems engineering communities and edge artificial intelligence researchers.
A multi-part architectural deep dive published on CSDN GitBlog examines FractalCore's low-level systems implementation across edge orchestration, memory management, and model graph compilation:
inference-model-maker/slicer toolchain, covering ATen static tracing, XNNPACK backend lowering, and dynamic .pte sub-graph generation tailored for edge memory limits.X-Auth-Token ingress gateway, filesystem-level tenant data isolation, and single-use task dispatch replay protection.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
src/fractal_server/server.py)data/tenants/{username}/) for datasets, training bins, uploaded checkpoints, and compiled global models.X-Auth-Token header (secrets.token_hex(32)), backed by a thread-safe token registry with zero cookie leakage between browser tabs or clients.ActiveTask) referencing specific binary data bins to available Android nodes based on hardware telemetry proofs.src/inference-model-maker/slicer/)torchao INT4, group size 128) targeting linear attention and MLP projections to reduce layer memory footprints below 150MB.sequenceDiagram
autonumber
actor Admin as Tenant / Admin
participant Server as FractalCore API
participant Aggregator as FedAvg Engine
participant Android as FractalAndroid Node
participant Firestore as Firestore Ledger
Admin->>Server: POST /api/admin/login (Credentials)
Server-->>Admin: X-Auth-Token
Admin->>Server: POST /api/admin/tenants (Create Tenant + Set TFLOP Quota)
Admin->>Server: POST /api/tenant/init-data (Upload Dataset & Target Model)
loop Model Training Iteration
Android->>Server: GET /api/task/current (Header: X-Auth-Token)
Server-->>Android: ActiveTask (Model Slices + Assigned Bins)
Note over Android: Execute Local Gradient Descent on Device
Android->>Server: POST /api/model/upload (Checkpoint Delta .ckpt)
Server->>Aggregator: Register Checkpoint Delta
Server->>Firestore: Increment Liquid MBs for Device ID
opt Round Threshold Reached
Aggregator->>Aggregator: Compute Parameter Summation (FedAvg)
Aggregator->>Server: Deploy New Model Checkpoint
end
end
All administrative and client communications occur over standard REST endpoints. Secured routes strictly require X-Auth-Token authentication:
| Endpoint | Method | Access Level | Description |
|---|---|---|---|
/api/admin/login |
POST |
Public | Authenticates administrator and yields scoped session token. |
/api/admin/tenants |
GET |
Admin | Lists active tenant silos, quotas, and node activity. |
/api/admin/tenants |
POST |
Admin | Provisions a new isolated tenant namespace with allocated compute quotas. |
/api/task/current |
GET |
Node | Fetches assigned computation task descriptor and target model parameters. |
/api/model/upload |
POST |
Node | Ingests client checkpoint delta payload (.ckpt) for federated aggregation. |
/api/node/register |
POST |
Node | Enrolls device hardware configuration and initial telemetry baseline. |
FractalCore/
|-- Dockerfile # Production container build specification
|-- docker-compose.yml # Local multi-service orchestrator
|-- requirements.txt # Pinned Python package dependencies
|-- .env.example # Environment configuration template
|-- scripts/ # Verification scripts & synthetic benchmarks
| `-- benchmark_evaluation.py # Empirical benchmark suite & chart generator
|-- src/
| |-- fractal_server/ # Control Plane Server & API Routes
| | |-- server.py # Main Flask application & endpoint handlers
| | |-- templates/ # Server-rendered administrative and tenant dashboards
| | `-- static/ # CSS styling, asset libraries, and telemetry scripts
| `-- inference-model-maker/ # Model Compilation & Graph Slicer
| |-- run.py # CLI entry point for graph partitioning
| `-- slicer/ # Core slicing, INT4 quantization, and export pipeline
`-- docs/ # Architecture diagrams, benchmark reports, and schemas
# 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
X-Auth-Token validation without cookie fallback prevents cross-session bleeding.task_Id assignment prevents duplicate or stale weight injection.For full vulnerability reporting procedures, refer to SECURITY.md.
FractalCore aggregation engine, model graph slicing pipeline, and multi-tenant task scheduler are grounded in landmark research across federated optimization and distributed model execution:
FractalCore is source-available research and systems software owned exclusively by Fractal Compute Orchestrations and governed by the FRACTAL Proprietary Source-Available & Non-Commercial Restrictive License v3.1 (see NOTICE and CITATION.cff).
For commercial licensing or institutional partnerships, contact Fractal Compute Orchestrations ([email protected]).
FractalCore is engineered and governed by Fractal Compute Orchestrations.