What Is the Role of the `installers/lib/` Directory in ODS?

The installers/lib/ directory in ODS serves as a pure-function library layer containing Bash scripts that define constants, detect hardware capabilities, and provide reusable utilities, all sourced by install-core.sh before any installation phase executes.

The installers/lib/ directory sits at the heart of the Osmantic/ODS (Open Deep Search) installer architecture. This folder houses the foundational Bash scripts that enable the installer to remain modular, testable, and platform-agnostic. According to the source code, these files establish the "functional core" that drives decision-making across Linux, macOS, and Windows WSL2 environments.

Core Responsibilities of the Installers lib Directory

The library layer is organized around four primary responsibilities that separate computation from execution.

Define Core Constants and Environment Defaults

The constants.sh file establishes global configuration values that the entire installer relies upon. It sets version strings, default installation paths, log locations, and terminal color codes used for formatted output throughout the installation process.

Hardware Detection and Tier Mapping

Scripts like detection.sh analyze GPU and CPU capabilities to determine the appropriate hardware tier. The tier-map.sh file then transforms these capabilities into concrete LLM configurations, mapping tiers to specific model names, GGUF files, download URLs, and context window sizes.

Reusable Utility Functions

The directory exposes side-effect-free helpers for logging (logging.sh), terminal progress indicators (progress.sh), cross-platform path resolution (path-utils.sh), Docker image handling (docker-images.sh), and Docker-Compose overlay selection (compose-select.sh).

Functional Core Architecture

Every script in installers/lib/ adheres to a strict "pure functions first" philosophy. These files contain no side effects—they perform no I/O operations, execute no docker commands, and make no network calls. Instead, they compute values and return them, allowing the imperative "phase" scripts in installers/phases/ to handle the actual execution.

Key Files in the Installers lib Directory

Here are the primary components that constitute this library layer:

• constants.sh – Global constants, path resolution logic, and color palette definitions.
• detection.sh – GPU/CPU detection algorithms and tier assignment logic.
• tier-map.sh – Maps hardware tiers to specific LLM model names, GGUF filenames, download URLs, and context sizes.
• logging.sh – Unified logging helpers for consistent output formatting.
• progress.sh – Simple terminal progress indicators for user feedback.
• path-utils.sh – Cross-platform path utilities used throughout the installer.
• docker-images.sh – Functions for resolving and handling Docker image names and tags.
• compose-select.sh – Logic for selecting the appropriate Docker-Compose configuration overlay.

Integration with the Installer Orchestrator

The install-core.sh script sources the entire library layer before running any installation phase. This ensures that all functions and constants are available globally to subsequent phase scripts.

# Sourcing the library layer in the installer orchestrator

source "$SCRIPT_DIR/installers/lib/constants.sh"
source "$SCRIPT_DIR/installers/lib/detection.sh"
source "$SCRIPT_DIR/installers/lib/tier-map.sh"

Once sourced, the phase scripts can invoke these pure functions to drive decision-making without redefining common logic.

Practical Usage Examples

Hardware detection and tier resolution follow a functional pipeline:

# Resolve hardware tier and pick an LLM model

detect_hardware          # defined in detection.sh

resolve_tier_config      # defined in tier-map.sh

echo "Selected model: $LLM_MODEL"

Utility functions provide consistent logging and progress reporting across all installer phases:

# Using utility functions from the lib

log_info "Starting ODS installation…"   # from logging.sh

_progress_start "Downloading model"

Summary

• The installers/lib/ directory contains the pure-function library layer of the ODS installer.
• Key scripts include constants.sh, detection.sh, and tier-map.sh, which handle configuration, hardware detection, and model mapping.
• All scripts are sourced by install-core.sh before installation phases begin.
• The architecture enforces no side effects, separating computation from imperative execution.
• This design ensures cross-platform compatibility across Linux, macOS, and Windows WSL2.

Frequently Asked Questions

What is the purpose of the installers/lib/ directory in ODS?

The installers/lib/ directory houses pure Bash functions that define constants, detect hardware, map capabilities to LLM models, and provide utility functions. These scripts form the computational foundation that the installer orchestrator and phase scripts rely upon to execute consistently across platforms.

How does the functional core architecture benefit the ODS installer?

By restricting installers/lib/ scripts to pure functions with no side effects (no I/O, Docker commands, or network calls), the codebase becomes more testable, predictable, and maintainable. The phase scripts in installers/phases/ handle all imperative actions while the library layer handles calculations and configuration logic.

Which script sources the files in the installers/lib/ directory?

The install-core.sh orchestrator script sources all library files at startup using source commands, loading constants and functions into the shell environment before any installation phase executes.

What platforms does the installers/lib/ directory support?

The library layer is designed to be platform-agnostic, supporting Linux, macOS, and Windows (WSL2) through cross-platform path utilities and environment detection logic contained in scripts like path-utils.sh and constants.sh.

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