| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203 |
- """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:<name>`` 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()}
|