"""Install-snapshot fields for version lag, release channel and coarse hardware. Everything here is read offline: the installed version's own commit date, the install stamp and per-install channel record, the update check's cached result (never a network call), and cached ``hermes_platform.host`` facts. Only closed enums and buckets leave; the git remote, branch names, paths and endpoint URLs stay local. """ from __future__ import annotations import json import logging import time from pathlib import Path from typing import Any from . import shared_metrics_contract as contract from .shared_metrics_contract import _bucket, _norm logger = logging.getLogger(__name__) _DAY_S = 86_400 _VERSION_AGE_THRESHOLDS = ((7 * _DAY_S, "lt_7d"), (30 * _DAY_S, "7d_to_30d"), (90 * _DAY_S, "30d_to_90d")) _GIB = 1024 ** 3 # The OS reports installed RAM minus firmware/iGPU reservations (a 16 GB laptop shows ~15.5 GiB), # so the total is scaled up before bucketing to land on the nominal size users buy. _RAM_NOMINAL_FACTOR = 1.1 _RAM_THRESHOLDS = ( (8, "lt_8g"), (16, "8g_to_16g"), (32, "16g_to_32g"), (64, "32g_to_64g"), (128, "64g_to_128g"), ) # A cached behind count this old no longer says anything about how current the install is. _BEHIND_MAX_AGE_S = 7 * _DAY_S _CHANNELS = {"stable": "stable", "main": "main", "canary": "main"} _MAIN_BRANCHES = frozenset({"main", "master"}) # Provider ids that always name a server on the user's own machine or network. _LOCAL_PROVIDER_ALIASES = frozenset({"ollama", "local", "vllm", "llamacpp", "llama.cpp", "llama-cpp", "lmstudio"}) _INHERITS_MAIN = frozenset({"", "auto", "main"}) def _sub(config: Any, key: str) -> Any: return config.get(key) if isinstance(config, dict) else None def _safe(reader, default: str) -> str: try: return reader() except Exception: logger.debug("Shared-metrics install field %s unavailable", getattr(reader, "__name__", reader), exc_info=True) return default def _version_info(): from hermes_cli.version_info import get_version_info return get_version_info() def _project_root() -> Path: from hermes_cli.config import get_project_root return get_project_root() def detect_client_install_method() -> str: """``detect_install_method()``, except the Microsoft Store build, which the stamp names and that function's update-gating vocabulary has no word for (it would read ``unknown``). Kept out of ``detect_install_method`` on purpose: update and uninstall branch on its result.""" from hermes_cli.config import detect_install_method from hermes_cli.steward import read_install_stamp root = _project_root() if read_install_stamp(root).get("updateMechanism") == "microsoft-store": return "microsoft-store" return detect_install_method(root) def release_channel(config: dict[str, Any]) -> str: """The channel this install follows: a package's baked channel, a source install's channel record, else the checkout's branch (``main`` for main/master, ``dev`` for any other).""" from hermes_cli.update_channel import _package_channel, _read_stamp, resolve_update_channel root = _project_root() resolved = resolve_update_channel(config, root) if resolved != "main" or _package_channel(_read_stamp(root)): return _CHANNELS.get(resolved, "unknown") branch = _version_info().branch if not branch: return "unknown" return "main" if branch in _MAIN_BRANCHES else "dev" def version_age_bucket(now: float | None = None) -> str: """Age of the INSTALLED version, from its own commit date (stamp or checkout).""" committed = _version_info().commit_date if not isinstance(committed, int) or committed <= 0: return "unknown" age = max(0.0, (now or time.time()) - committed) return _bucket(age, _VERSION_AGE_THRESHOLDS, "gte_90d") def behind_bucket(home: Path | None = None, now: float | None = None) -> str: """Commits/releases behind, from the update check's cached result for this exact revision.""" from hermes_cli.update_channel import install_id from hermes_constants import get_hermes_home root = _project_root() cache_file = (home or get_hermes_home()) / "source-checks" / f"{install_id(root)}.json" try: cached = json.loads(cache_file.read_text(encoding="utf-8-sig")) except (OSError, ValueError): return "unknown" if not isinstance(cached, dict): return "unknown" status, identity, ts = cached.get("status"), cached.get("identity"), cached.get("ts") behind = status.get("behind") if isinstance(status, dict) else None head = identity.get("head") if isinstance(identity, dict) else None commit = _version_info().commit if ( isinstance(behind, bool) or not isinstance(behind, int) or behind < 0 or not isinstance(ts, (int, float)) or not 0 <= (now or time.time()) - ts < _BEHIND_MAX_AGE_S or (head and commit and head != commit) ): return "unknown" return contract.count_bucket(behind) def ram_bucket() -> str: from hermes_platform.host.facts import ram_total_bytes total = ram_total_bytes() if not total: return "unknown" return _bucket(total * _RAM_NOMINAL_FACTOR / _GIB, _RAM_THRESHOLDS, "gte_128g") def gpu_class() -> str: from hermes_platform.host.facts import gpu_class as host_gpu_class value = host_gpu_class() return value if value in contract.GPU_CLASSES else "unknown" def _is_local_endpoint(base_url: Any) -> bool: if not isinstance(base_url, str) or not base_url.strip(): return False from agent.model_metadata import is_local_endpoint return is_local_endpoint(base_url) def _custom_base_url(provider: str) -> Any: """A ``providers:`` / ``custom_providers:`` entry's endpoint, by ``custom:`` or bare name (built-in ids shadow entries, as at runtime).""" from hermes_cli.runtime_provider_custom import _get_named_custom_provider entry = _get_named_custom_provider(provider) return entry.get("base_url") if isinstance(entry, dict) else None def _slot_is_local(slot: Any) -> bool: provider = _norm(_sub(slot, "provider")) if provider in _LOCAL_PROVIDER_ALIASES: return True if _is_local_endpoint(_sub(slot, "base_url")): return True from .shared_metrics_catalog import CUSTOM, _safe as catalog_safe, user_named_model_providers if provider in catalog_safe(user_named_model_providers) - {CUSTOM}: return True return provider not in _INHERITS_MAIN and _is_local_endpoint(_custom_base_url(provider)) def _aux_slot_routes_itself(slot: dict[str, Any]) -> bool: """An auxiliary task off the main model: a named provider, or (mirroring ``agent.auxiliary_client._resolve_task_provider_model``) a bare ``base_url`` + ``api_key``, which the runtime sends to that endpoint as ``custom`` even under ``provider: auto``.""" if _norm(slot.get("provider")) not in _INHERITS_MAIN: return True return all(isinstance(slot.get(k), str) and slot[k].strip() for k in ("base_url", "api_key")) def local_model_provider_used(config: dict[str, Any]) -> str: """``yes`` when the main model or any auxiliary task runs on a local/self-hosted server.""" model = _sub(config, "model") auxiliary = _sub(config, "auxiliary") slots = [model] if isinstance(model, dict) else [] if isinstance(auxiliary, dict): slots += [s for s in auxiliary.values() if isinstance(s, dict) and _aux_slot_routes_itself(s)] return "yes" if any(_slot_is_local(slot) for slot in slots) else "no" def install_v4_snapshot_fields(config: dict[str, Any]) -> dict[str, str]: """The version-lag, channel and hardware dimensions of the daily snapshot.""" fields = { "behind_bucket": _safe(behind_bucket, "unknown"), "gpu_class": _safe(gpu_class, "unknown"), "local_model_provider_used": _safe(lambda: local_model_provider_used(config), "no"), "ram_bucket": _safe(ram_bucket, "unknown"), "release_channel": _safe(lambda: release_channel(config), "unknown"), "version_age_bucket": _safe(version_age_bucket, "unknown"), } allowed = contract._INSTALL_V4_SNAPSHOT_DIMENSIONS return {k: v if v in allowed[k] else ("no" if k == "local_model_provider_used" else "unknown") for k, v in fields.items()}