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

> Explore the ODS installer library architecture and deep dive into how installers/lib handles hardware detection, tier-to-model mapping, and package abstraction for intelligent deployments.

- Repository: [Osmantic/ODS](https://github.com/Osmantic/ODS)
- Tags: architecture
- Published: 2026-09-02

---

**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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/amd-topo.sh) probes AMD GPU layouts using roc-smi and sysfs fallbacks
- [`nvidia-topo.sh`](https://github.com/Osmantic/ODS/blob/main/nvidia-topo.sh) detects NVIDIA topology, NVLink status, and MIG configurations
- [`llama-memory-budget.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/logging.sh) (structured logging with `log()`, `warn()`, and `ai_*` helpers), [`ui.sh`](https://github.com/Osmantic/ODS/blob/main/ui.sh) (terminal colors and progress indicators), [`constants.sh`](https://github.com/Osmantic/ODS/blob/main/constants.sh) (global path and version definitions), and [`path-utils.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/02-gpu-detect.sh)) calls `detect_gpu()` to populate hardware variables. The tier-mapping phase ([`03-model-select.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/04-download-model.sh) and [`05-compose-stack.sh`](https://github.com/Osmantic/ODS/blob/main/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

```bash

# 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`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/detection.sh) defines both `detect_gpu()` and `load_capability_profile()`.

### Resolving Tier Configuration

```bash
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`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/tier-map.sh) contains the `case` statement mapping tier codes to model metadata.

### Installing System Dependencies

```bash
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`](https://github.com/Osmantic/ODS/blob/main/ods/installers/lib/packaging.sh).

### Calculating CPU Budget for Inference

```bash
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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/detection.sh)** handles GPU/CPU topology, container detection, and Secure Boot fixes for NVIDIA systems.
- **[`tier-map.sh`](https://github.com/Osmantic/ODS/blob/main/tier-map.sh)** translates hardware tiers (0-4, ARC, NV_ULTRA) into downloadable model specifications via `resolve_tier_config()`.
- **[`packaging.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/amd-topo.sh) or [`nvidia-topo.sh`](https://github.com/Osmantic/ODS/blob/main/nvidia-topo.sh)) or extending the `detect_gpu()` function in [`detection.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/tier-map.sh).

### How does tier mapping handle unavailable or custom models?

The `resolve_tier_config()` function in [`ods/installers/lib/tier-map.sh`](https://github.com/Osmantic/ODS/blob/main/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`](https://github.com/Osmantic/ODS/blob/main/path-utils.sh) or [`logging.sh`](https://github.com/Osmantic/ODS/blob/main/logging.sh) that have minimal dependencies on the installer environment.