How the ODS Installer Library (installers/lib) Works: Architecture and Deep Dive

The ODS installer library provides a pure-function core under ods/installers/lib/ that handles hardware detection, tier-to-model mapping, and package abstraction, enabling the multi-phase installer to make intelligent, hardware-aware deployment decisions.

The ODS installer library is the backbone of the Osmantic/ODS deployment system, residing in the ods/installers/lib/ directory. It supplies the pure-function core that powers the multi-phase install-core.sh orchestrator, abstracting hardware complexity into reusable, testable shell functions. This modular architecture allows the installer to detect GPU capabilities, map hardware tiers to specific LLM models, and manage cross-distro package installations without polluting the main control flow with low-level detection logic.

Core Responsibilities of the ODS Installer Library

The library is organized into single-purpose modules that each handle a distinct concern within the deployment pipeline.

Hardware Detection and Capability Profiling

At the heart of the library, detection.sh provides the environmental intelligence required for hardware-aware deployments. It exposes detect_gpu(), which populates global variables like GPU_NAME, GPU_VENDOR, and GPU_TIER by probing the system topology. The function load_capability_profile() checks for pre-generated hardware profiles, while ods_in_container() detects Docker or Podman environments to trigger container-aware resource budgeting.

For NVIDIA-specific edge cases, detection.sh includes fix_nvidia_secure_boot(), which automatically enrolls locked Secure Boot keys to allow proprietary driver loading. CPU-bound workloads use calculate_llama_cpu_budget() (also in detection.sh) to determine thread limits and memory reservations based on host capacity, critical for Llama.cpp backend sizing.

Tier-to-Model Mapping

The tier-map.sh module translates abstract hardware tiers into concrete deployment artifacts. Its primary function, resolve_tier_config(), accepts a tier identifier (0-4, ARC, NV_ULTRA, etc.) and maps it to specific variables: LLM_MODEL, GGUF_FILE, DOWNLOAD_URL, and MAX_CONTEXT. This separation of concerns ensures that the actual download and deployment phases (in installers/phases/) consume standardized variables without hardcoding model metadata.

Package Manager Abstraction

Distribution heterogeneity is handled by packaging.sh, which provides a thin abstraction over system package managers. The detect_pkg_manager() function identifies the underlying tool (apt, yum, apk, etc.) and sets PKG_MANAGER. Subsequent calls to pkg_update() and pkg_install <package> execute the appropriate native commands, allowing the installer to remain agnostic of the host Linux distribution.

GPU-Specific Topology Helpers

Dedicated modules handle vendor-specific complexity:

• amd-topo.sh probes AMD GPU layouts using roc-smi and sysfs fallbacks
• nvidia-topo.sh detects NVIDIA topology, NVLink status, and MIG configurations
• llama-memory-budget.sh calculates VRAM and system RAM constraints for model loading

These helpers are sourced on-demand by the detection phase rather than bloating the global namespace.

Utility and UI Components

Supporting infrastructure includes logging.sh (structured logging with log(), warn(), and ai_* helpers), ui.sh (terminal colors and progress indicators), constants.sh (global path and version definitions), and path-utils.sh (filesystem normalization). These ensure consistent output formatting across all installer phases.

Architectural Flow and Integration

The ODS installer library follows a strict sourcing pattern that maintains separation between pure logic and side-effect orchestration.

install-core.sh initializes global variables (SCRIPT_DIR, LOG_FILE, TIER) and sequentially sources each library file. The pure functions remain dormant until invoked by the sequential phases located in installers/phases/.

The detection phase (02-gpu-detect.sh) calls detect_gpu() to populate hardware variables. The tier-mapping phase (03-model-select.sh) then invokes resolve_tier_config() to determine which GGUF file and Docker image to deploy. Subsequent phases like 04-download-model.sh and 05-compose-stack.sh consume these pre-set variables, ensuring that no logic-heavy code resides in the phase scripts themselves.

This architecture treats the library as a side-effect-free function collection (except where deliberately updating the installer environment), making the system highly testable and mockable.

Practical Code Examples

Detecting Hardware and Loading Profiles

# Typical invocation within a phase script

source "${SCRIPT_DIR}/installers/lib/detection.sh"

# Detect GPU vendor and tier

detect_gpu

# Load existing capability profile if present

load_capability_profile  # Sets CAP_PROFILE_LOADED=true on success

Source: ods/installers/lib/detection.sh defines both detect_gpu() and load_capability_profile().

Resolving Tier Configuration

source "${SCRIPT_DIR}/installers/lib/tier-map.sh"

# Assuming $TIER was determined by detection

resolve_tier_config  # Exports TIER_NAME, LLM_MODEL, GGUF_FILE, MAX_CONTEXT

Source: ods/installers/lib/tier-map.sh contains the case statement mapping tier codes to model metadata.

Installing System Dependencies

source "${SCRIPT_DIR}/installers/lib/packaging.sh"

# Initialize package manager detection

detect_pkg_manager  # Sets PKG_MANAGER="apt" (or yum, apk, etc.)

pkg_update
pkg_install curl

Source: Packaging abstraction implemented in ods/installers/lib/packaging.sh.

Calculating CPU Budget for Inference

source "${SCRIPT_DIR}/installers/lib/detection.sh"

# Backend-specific budgeting (e.g., AMD)

calculate_llama_cpu_budget amd

# Returns: "<limit> <reservation> <available>" for container limits

Source: calculate_llama_cpu_budget() defined in ods/installers/lib/detection.sh.

Design Principles Reflected in the Library

Pure Functions: Most helpers return values or set well-documented global variables without mutating unrelated state, enabling unit testing outside the installer context.

Single Responsibility: Each file focuses on one domain—GPU detection, tier mapping, or packaging—adhering to KISS and SOLID principles. Adding a new GPU vendor requires only extending detection.sh or adding a new helper script rather than refactoring the core.

Modder-Friendly Hooks: Header comments containing Purpose, Provides, and Modder notes guide contributors on safe extension points, ensuring custom logic can be injected without breaking backend contracts.

Summary

• The ODS installer library in ods/installers/lib/ provides pure, modular shell functions for hardware detection, model mapping, and package management.
• detection.sh handles GPU/CPU topology, container detection, and Secure Boot fixes for NVIDIA systems.
• tier-map.sh translates hardware tiers (0-4, ARC, NV_ULTRA) into downloadable model specifications via resolve_tier_config().
• packaging.sh abstracts distro-specific package commands through detect_pkg_manager() and pkg_install().
• The library is consumed by sequential phase scripts in installers/phases/, maintaining clean separation between logic and orchestration.
• Side-effect-free design and comprehensive modder documentation make the system extensible and testable.

Frequently Asked Questions

How does the ODS installer library detect if it is running inside a container?

The library provides ods_in_container() in ods/installers/lib/detection.sh, which checks for container-specific indicators such as cgroup hierarchies and the presence of .dockerenv or Podman-specific environment variables. When detected, the installer activates container-aware resource budgeting through calculate_llama_cpu_budget() to prevent the AI stack from overcommitting host CPU or VRAM resources.

Can I extend the library to support a new GPU vendor?

Yes. The modular architecture allows extension by either adding a new topology script (following the pattern of amd-topo.sh or nvidia-topo.sh) or extending the detect_gpu() function in detection.sh. The library uses header comments marking Modder notes to indicate safe injection points, ensuring new vendor logic integrates cleanly with the existing tier-mapping system in tier-map.sh.

How does tier mapping handle unavailable or custom models?

The resolve_tier_config() function in ods/installers/lib/tier-map.sh uses a deterministic case statement that maps specific tier identifiers to hardcoded model metadata. If a tier is unrecognized, the function falls back to conservative defaults or fails gracefully with logged warnings, allowing the installer to halt before attempting invalid downloads.

Is it safe to source the library functions outside the main installer?

While the library is designed as side-effect-free pure functions, certain utilities assume the presence of installer-global variables like SCRIPT_DIR and LOG_FILE. For external use, ensure these variables are pre-initialized, or source only specific modules like path-utils.sh or logging.sh that have minimal dependencies on the installer environment.

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