Placement & Fit Scoring

How the coordinator selects the best Island for each job — multi-dimensional scoring, GPU bandwidth estimation, and runtime-specific strategies

Placement & Fit Scoring

When a job is submitted, the coordinator doesn’t just find any qualifying Island — it ranks candidates by how well they can run the Cargo and picks the best one. This is the fit scoring system.

Overview

Traditional placement checks binary requirements: “does this Island have enough VRAM?” Fit scoring goes further by estimating how well the Cargo will perform on each candidate, producing a composite 0–100 score across multiple dimensions.

Job submitted
    │
    ▼
Filter: online, approved, not in cooldown,
        runtime compatible, meets min requirements
    │
    ▼
Score: up to 10 candidates ranked by fit
    │
    ▼
Select: highest composite score wins
    │
    ▼
Region tiebreaker: same region > adjacent > any

The system is implemented in Coordinator.Placement.FitScoring and Coordinator.Placement.GpuSpecs.

Scoring Dimensions

Every candidate Island is scored on three dimensions, each 0–100:

The composite score is a weighted average. Weights vary by runtime type:

Fit Levels

Based on dimension scores, each Island gets a fit level:

Islands scored as “Too tight” are never selected. The remaining candidates are sorted by composite score.

Runtime-Specific Scoring

LLM Cargos (llmcpp)

The LLM scorer estimates tokens per second using GPU memory bandwidth:

tok/s = gpu_bandwidth_GB/s / model_size_GB × 0.55 × mode_factor

Where:

• gpu_bandwidth is looked up from a 120+ GPU model table (or reported by the Island in heartbeats)
• model_size is estimated from the Cargo’s VRAM requirement (~70% of required VRAM)
• 0.55 is an empirical efficiency factor
• mode_factor is 1.0 for full GPU, 0.5 for CPU offload, 0.3 for CPU-only

Speed score: (tok_s / 40) × 100 — targeting 40 tok/s for interactive chat.

Fit score: VRAM utilization sweet spot:

• 50–80% utilization → 100
• Under 50% → 60–100 (wasting resources)
• Over 90% → 20–70 (risk of OOM, KV cache pressure)

Container Cargos

Speed: CPU ratio — how many times the Island exceeds the requirement. An Island with 16 cores running a 4-core Cargo scores higher than one with 4 cores.

Fit: Average of CPU and RAM utilization. The sweet spot is 30–70% utilization.

Headroom: Based on available concurrent slots: max(cpu_cores / required_cores, 1) - active_jobs.

WASM Cargos

WASM modules are lightweight and single-threaded. Scoring emphasizes:

• Speed: CPU core count as proxy for quality
• Fit: RAM utilization (WASM linear memory vs available)
• Headroom: Many can run concurrently — scored generously

Mobile Cargos (coreml, onnx)

Mobile scoring accounts for hardware accelerators and device health:

• Speed: Neural Engine (CoreML) or NPU (ONNX) presence is the primary factor. Metal GPU adds a bonus.
• Fit: Available device memory vs model size. Considers memory_used_mb if reported.
• Penalties: Thermal state (critical = -30, serious = -15) and low battery without charging (-10 to -20).

GPU Bandwidth Table

The coordinator maintains a lookup table mapping GPU model names to memory bandwidth in GB/s. This is the primary input for LLM performance estimation.

When a GPU model isn’t found in the table, the system falls back to a conservative estimate based on VRAM size (~40 GB/s per GB of VRAM).

Performance Estimates in Heartbeats

The Island node agent computes and reports performance estimates with every heartbeat (every 10 seconds):

These estimates are stored in the performance_estimates JSONB column on the hosts table and used by the fit scorer to improve accuracy over time.

Integration Points

Job Dispatch (find_host_for_workload)

The main entry point is Coordinator.Hosts.find_host_for_workload/2. It:

1. Filters candidates by binary requirements (online, approved, runtime, VRAM, CPU, RAM)
2. Fetches up to 10 qualifying candidates
3. Scores all candidates with FitScoring.rank_hosts/2
4. Selects the highest composite score
5. Falls back to DB-ordered first candidate if all score :too_tight

Regional preference is applied as a tiered fallback: same region → adjacent regions → any region.

Cargo Registry

Each Cargo card in the Cargo Registry shows network availability:

• Number of Islands ready to serve it
• Best fit level and composite score
• Estimated throughput
• Fit level breakdown across available Islands

Island Dashboard

The Island dashboard shows a “Compatible Cargos” section listing every Cargo the Island can run, sorted by fit score. This helps Island operators understand what their hardware is best suited for.

Pricing

Fit scoring is separate from pricing. The hardware tier system determines pricing multipliers (enterprise 2.0×, high-end 1.5×, etc.), while fit scoring determines which Island gets the job. A more capable Island earns more per job through tier multipliers, and fit scoring ensures it gets matched to appropriate Cargos.

Source Code

See Also

• Cargos — Runtime types, requirements matching, trust levels
• Karma System — How reputation affects Island selection priority
• Credits & Pricing — Hardware tiers, pricing multipliers, billing