OS Detector

os_detector

OS detection for the Linux AI NPU Assistant.

Detects the running Linux distribution and environment so the AI assistant can generate distro-accurate commands (e.g. apt on Ubuntu/Debian, dnf on Fedora, pacman on Arch, etc.).

Detection sources (in priority order)

1. /etc/os-release — machine-readable, present on all modern distros.
2. platform.freedesktop_os_release() — Python 3.10+ stdlib wrapper for the same file (used when available).
3. /etc/lsb-release, /etc/redhat-release, /etc/arch-release, /etc/alpine-release — legacy fallbacks for older systems.

All detection is read-only, uses no network, and runs in < 5 ms. Results are cached after the first call so repeated access is free.

OSInfo dataclass

OSInfo(id='', name='', pretty_name='', version='', codename='', id_like='', package_manager='', install_command='', architecture='', kernel='', init_system='', desktop='', hostname='', extra=dict())

Detected operating-system information.

All fields are strings so they can be safely embedded in prompts. Unknown values are represented as empty strings.

id class-attribute instance-attribute

id = ''

Machine-readable distro ID, e.g. ubuntu, fedora, arch.

name class-attribute instance-attribute

name = ''

Human-friendly distro name, e.g. Ubuntu, Fedora Linux.

pretty_name class-attribute instance-attribute

pretty_name = ''

Full name + version, e.g. Ubuntu 24.04.4 LTS (Noble Numbat).

version class-attribute instance-attribute

version = ''

Version string, e.g. 24.04, 39, rolling.

codename class-attribute instance-attribute

codename = ''

Release codename, e.g. noble, bookworm (empty if not set).

id_like class-attribute instance-attribute

id_like = ''

Space-separated parent distro IDs, e.g. debian or rhel fedora.

package_manager class-attribute instance-attribute

package_manager = ''

Primary package manager: apt, dnf, pacman, etc.

install_command class-attribute instance-attribute

install_command = ''

Template install command, e.g. sudo apt install {package}.

architecture class-attribute instance-attribute

architecture = ''

CPU architecture, e.g. x86_64, aarch64.

kernel class-attribute instance-attribute

kernel = ''

Kernel version string, e.g. 6.8.0-57-generic.

init_system class-attribute instance-attribute

init_system = ''

Init system: systemd, openrc, runit, sysv, or unknown.

desktop class-attribute instance-attribute

desktop = ''

Current desktop environment or none (headless).

hostname class-attribute instance-attribute

hostname = ''

Machine hostname.

extra class-attribute instance-attribute

extra = field(default_factory=dict)

Any additional keys from /etc/os-release not captured above.

to_system_prompt_block

to_system_prompt_block()

Return a concise block suitable for injection into the system prompt.

The block tells the AI exactly which distro, version, and package manager are active so every command suggestion is accurate.

Source code in src/os_detector.py

def to_system_prompt_block(self) -> str:
    """Return a concise block suitable for injection into the system prompt.

    The block tells the AI exactly which distro, version, and package
    manager are active so every command suggestion is accurate.
    """
    lines = ["## System information"]
    if self.pretty_name:
        lines.append(f"- Distribution: {self.pretty_name}")
    elif self.name:
        lines.append(f"- Distribution: {self.name} {self.version}".strip())
    if self.codename:
        lines.append(f"- Release codename: {self.codename}")
    if self.package_manager:
        lines.append(f"- Package manager: {self.package_manager}")
        if self.install_command:
            lines.append(f"- Install command: {self.install_command}")
    if self.architecture:
        lines.append(f"- Architecture: {self.architecture}")
    if self.kernel:
        lines.append(f"- Kernel: {self.kernel}")
    if self.init_system and self.init_system != "unknown":
        lines.append(f"- Init system: {self.init_system}")
    if self.desktop and self.desktop != "unknown":
        lines.append(f"- Desktop environment: {self.desktop}")
    lines.append(
        "\nAlways use the correct package manager and command syntax "
        "for this specific distribution when suggesting commands."
    )
    return "\n".join(lines)

detect cached

detect()

Detect the current OS and return an :class:OSInfo instance.

Results are cached after the first call (lru_cache) so subsequent accesses are free. Call :func:detect.cache_clear in tests to reset.

Source code in src/os_detector.py

@lru_cache(maxsize=1)
def detect() -> OSInfo:
    """Detect the current OS and return an :class:`OSInfo` instance.

    Results are cached after the first call (``lru_cache``) so subsequent
    accesses are free.  Call :func:`detect.cache_clear` in tests to reset.
    """
    raw = _read_os_release()
    if not raw:
        raw = _read_legacy_release()

    distro_id   = raw.get("ID", "").lower()
    name        = raw.get("NAME", "")
    pretty_name = raw.get("PRETTY_NAME", "")
    version     = raw.get("VERSION_ID", raw.get("VERSION", ""))
    codename    = raw.get("VERSION_CODENAME", raw.get("UBUNTU_CODENAME", ""))
    id_like     = raw.get("ID_LIKE", "")

    # Strip keys already captured from the "extra" bucket
    _known = {
        "ID", "NAME", "PRETTY_NAME", "VERSION_ID", "VERSION",
        "VERSION_CODENAME", "UBUNTU_CODENAME", "ID_LIKE",
        "HOME_URL", "SUPPORT_URL", "BUG_REPORT_URL",
        "PRIVACY_POLICY_URL", "LOGO",
    }
    extra = {k: v for k, v in raw.items() if k not in _known}

    pm = _detect_package_manager(distro_id, id_like)
    install_cmd = _INSTALL_CMD.get(pm, "")

    info = OSInfo(
        id=distro_id,
        name=name,
        pretty_name=pretty_name,
        version=version,
        codename=codename,
        id_like=id_like,
        package_manager=pm,
        install_command=install_cmd,
        architecture=platform.machine(),
        kernel=platform.release(),
        init_system=_detect_init(),
        desktop=_detect_desktop(),
        hostname=platform.node(),
        extra=extra,
    )

    logger.debug("Detected OS: %s", info)
    return info