How ODS Maps Hardware Capabilities to Deployment Tiers: A Technical Deep Dive

ODS maps hardware capabilities to deployment tiers through a two-step pipeline: detection scripts analyze GPU vendor, architecture, and VRAM to set a TIER environment variable, while resolution scripts map that variable to concrete LLM models, GGUF files, and context limits.

The Osmantic/ODS repository automates LLM deployment by bridging hardware detection with software configuration. This article examines the precise mechanisms in ods/installers/lib/detection.sh and ods/installers/lib/tier-map.sh that transform raw hardware specifications into optimized deployment configurations.

Phase 1: Hardware Detection and Tier Assignment

ODS begins the mapping process by executing detection routines that inspect the host system's compute capabilities. The primary detection logic resides in ods/installers/lib/detection.sh, which populates the TIER environment variable based on detected hardware characteristics.

GPU Detection and Classification

The detect_gpu function serves as the entry point for hardware classification. According to the ODS source code, this function identifies the GPU vendor (NVIDIA, AMD, Apple), architecture generation, and available VRAM. For NVIDIA hardware, the system sources specialized helper functions from ods/installers/lib/nvidia-topo.sh to handle topology detection and unified memory identification.

The detection script distinguishes between several tier categories:

• Tier 0-4: Progressive capability levels typically assigned to CPU-only or entry-level GPU systems
• NV_ULTRA: Blackwell-class NVIDIA GPUs with high VRAM capacity
• SH_LARGE and SH_COMPACT: Apple Silicon variants for high-memory and constrained deployments
• ARC: Intel Arc GPU configurations

Architecture and Memory Detection

Supporting functions like detect_host_arch complement GPU detection by determining CPU architecture and system memory topology. When unified memory is detected—common in Apple Silicon and certain integrated GPU configurations—the system adjusts tier assignment to leverage shared memory pools effectively.

Phase 2: Tier-to-Model Resolution

Once the TIER variable is established, ODS transitions to the resolution phase by sourcing ods/installers/lib/tier-map.sh and invoking resolve_tier_config(). This function implements the hardware capabilities to deployment tiers mapping by translating abstract tier identifiers into specific software artifacts.

The resolve_tier_config Function

The resolve_tier_config function operates as a lookup mechanism that matches the current TIER value against predefined configuration blocks. As implemented in Osmantic/ODS, each tier block exports specific variables that define the deployment payload:

• TIER_NAME: Human-readable tier identifier
• LLM_MODEL: The specific model architecture (e.g., Qwen3.6-35B-A3B)
• GGUF_FILE: The quantized model filename
• GGUF_URL: Download endpoint for the model weights
• GGUF_SHA256: Cryptographic checksum for verification
• MAX_CONTEXT: Maximum token context window

Configuration Block Example

For high-end NVIDIA hardware, the tier map contains explicit definitions such as:

# NV_ULTRA (Blackwell-class GPUs)

TIER="NV_ULTRA"
LLM_MODEL="Qwen3.6-35B-A3B"
GGUF_FILE="Qwen3.6-35B-A3B-UD-Q4_K_M.gguf"
GGUF_URL="https://huggingface.co/unsloth/Qwen3.6-35B-A3B-GGUF/resolve/main/Qwen3.6-35B-A3B-UD-Q4_K_M.gguf"
MAX_CONTEXT=16384

Similar blocks exist for AMD GPUs, various Apple Silicon tiers (SH_LARGE, SH_COMPACT), and CPU-only deployments, ensuring the selected model fits within the device's memory and compute constraints.

Practical Implementation Workflow

Deploying ODS typically involves chaining these two phases in installation scripts. The following pattern demonstrates the complete hardware capabilities to deployment tiers pipeline:

# Detect hardware and set the TIER variable

source "ods/installers/lib/detection.sh"
detect_gpu   # populates TIER among other vars

# Resolve the tier to concrete model details

source "ods/installers/lib/tier-map.sh"
resolve_tier_config   # fills LLM_MODEL, GGUF_FILE, etc.

# Use the resolved values

echo "Selected tier: $TIER"
echo "Model: $LLM_MODEL"
echo "GGUF download: $GGUF_URL"

Running this sequence on a fresh ODS installation automatically selects the optimal configuration: a Blackwell GPU triggers NV_ULTRA, an Apple M2 selects SH_COMPACT, and a CPU-only system defaults to tier 0.

Key Files in the Mapping Pipeline

The hardware-to-tier mapping logic spans several critical files in the Osmantic/ODS repository:

• ods/installers/lib/detection.sh: Contains the primary hardware detection logic and TIER variable assignment
• ods/installers/lib/nvidia-topo.sh: Implements NVIDIA-specific topology detection and VRAM analysis
• ods/installers/lib/tier-map.sh: Houses resolve_tier_config and the complete tier-to-model mapping definitions
• ods/tests/test-tier-map.sh: Validates that resolve_tier_config functions correctly for every defined tier
• ods/tests/test-tier-map-parity.sh: Ensures macOS-specific tier mappings remain synchronized with the canonical tier map

Summary

ODS implements hardware capabilities to deployment tiers mapping through a clean separation of concerns:

• Detection scripts analyze GPU vendor, architecture, VRAM, and memory topology to classify hardware into discrete tiers
• Resolution scripts transform tier identifiers into concrete deployment artifacts including quantized model files and context limits
• Environment variables (TIER, LLM_MODEL, MAX_CONTEXT, etc.) serve as the interface between hardware detection and software configuration
• Test coverage in test-tier-map.sh and test-tier-map-parity.sh ensures mapping consistency across platforms

Frequently Asked Questions

How does ODS handle Apple Silicon hardware detection?

For Apple Silicon systems, the detection scripts identify the specific chip generation and unified memory configuration, assigning either SH_LARGE for high-memory Macs or SH_COMPACT for constrained deployments. The test-tier-map-parity.sh script specifically ensures these macOS tier mappings remain consistent with the canonical tier definitions.

What occurs if hardware detection fails to identify a compatible GPU?

If detect_gpu cannot identify a supported GPU or detects insufficient VRAM, the system defaults to tier 0 or CPU-only configurations. This fallback ensures ODS remains functional on minimal hardware, though with reduced model capabilities and context windows.

Where can developers verify tier mapping functionality?

The repository includes ods/tests/test-tier-map.sh, which exercises resolve_tier_config against every defined tier to verify correct variable export. Developers can run this test suite to confirm that hardware capabilities correctly map to deployment tiers without executing full installations.

How are new GPU architectures added to the tier system?

New architectures like Blackwell-class GPUs are integrated by extending ods/installers/lib/detection.sh with updated detection logic and adding corresponding blocks to ods/installers/lib/tier-map.sh. The modular design allows maintainers to introduce tiers such as NV_ULTRA by defining new hardware signatures in detection scripts and linking them to appropriate model configurations in the tier map.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}