shared_metrics_install.py 8.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203
  1. """Install-snapshot fields for version lag, release channel and coarse hardware.
  2. Everything here is read offline: the installed version's own commit date, the install stamp and
  3. per-install channel record, the update check's cached result (never a network call), and cached
  4. ``hermes_platform.host`` facts. Only closed enums and buckets leave; the git remote, branch names,
  5. paths and endpoint URLs stay local.
  6. """
  7. from __future__ import annotations
  8. import json
  9. import logging
  10. import time
  11. from pathlib import Path
  12. from typing import Any
  13. from . import shared_metrics_contract as contract
  14. from .shared_metrics_contract import _bucket, _norm
  15. logger = logging.getLogger(__name__)
  16. _DAY_S = 86_400
  17. _VERSION_AGE_THRESHOLDS = ((7 * _DAY_S, "lt_7d"), (30 * _DAY_S, "7d_to_30d"), (90 * _DAY_S, "30d_to_90d"))
  18. _GIB = 1024 ** 3
  19. # The OS reports installed RAM minus firmware/iGPU reservations (a 16 GB laptop shows ~15.5 GiB),
  20. # so the total is scaled up before bucketing to land on the nominal size users buy.
  21. _RAM_NOMINAL_FACTOR = 1.1
  22. _RAM_THRESHOLDS = (
  23. (8, "lt_8g"), (16, "8g_to_16g"), (32, "16g_to_32g"), (64, "32g_to_64g"), (128, "64g_to_128g"),
  24. )
  25. # A cached behind count this old no longer says anything about how current the install is.
  26. _BEHIND_MAX_AGE_S = 7 * _DAY_S
  27. _CHANNELS = {"stable": "stable", "main": "main", "canary": "main"}
  28. _MAIN_BRANCHES = frozenset({"main", "master"})
  29. # Provider ids that always name a server on the user's own machine or network.
  30. _LOCAL_PROVIDER_ALIASES = frozenset({"ollama", "local", "vllm", "llamacpp", "llama.cpp", "llama-cpp", "lmstudio"})
  31. _INHERITS_MAIN = frozenset({"", "auto", "main"})
  32. def _sub(config: Any, key: str) -> Any:
  33. return config.get(key) if isinstance(config, dict) else None
  34. def _safe(reader, default: str) -> str:
  35. try:
  36. return reader()
  37. except Exception:
  38. logger.debug("Shared-metrics install field %s unavailable", getattr(reader, "__name__", reader), exc_info=True)
  39. return default
  40. def _version_info():
  41. from hermes_cli.version_info import get_version_info
  42. return get_version_info()
  43. def _project_root() -> Path:
  44. from hermes_cli.config import get_project_root
  45. return get_project_root()
  46. def detect_client_install_method() -> str:
  47. """``detect_install_method()``, except the Microsoft Store build, which the stamp names and
  48. that function's update-gating vocabulary has no word for (it would read ``unknown``).
  49. Kept out of ``detect_install_method`` on purpose: update and uninstall branch on its result."""
  50. from hermes_cli.config import detect_install_method
  51. from hermes_cli.steward import read_install_stamp
  52. root = _project_root()
  53. if read_install_stamp(root).get("updateMechanism") == "microsoft-store":
  54. return "microsoft-store"
  55. return detect_install_method(root)
  56. def release_channel(config: dict[str, Any]) -> str:
  57. """The channel this install follows: a package's baked channel, a source install's channel
  58. record, else the checkout's branch (``main`` for main/master, ``dev`` for any other)."""
  59. from hermes_cli.update_channel import _package_channel, _read_stamp, resolve_update_channel
  60. root = _project_root()
  61. resolved = resolve_update_channel(config, root)
  62. if resolved != "main" or _package_channel(_read_stamp(root)):
  63. return _CHANNELS.get(resolved, "unknown")
  64. branch = _version_info().branch
  65. if not branch:
  66. return "unknown"
  67. return "main" if branch in _MAIN_BRANCHES else "dev"
  68. def version_age_bucket(now: float | None = None) -> str:
  69. """Age of the INSTALLED version, from its own commit date (stamp or checkout)."""
  70. committed = _version_info().commit_date
  71. if not isinstance(committed, int) or committed <= 0:
  72. return "unknown"
  73. age = max(0.0, (now or time.time()) - committed)
  74. return _bucket(age, _VERSION_AGE_THRESHOLDS, "gte_90d")
  75. def behind_bucket(home: Path | None = None, now: float | None = None) -> str:
  76. """Commits/releases behind, from the update check's cached result for this exact revision."""
  77. from hermes_cli.update_channel import install_id
  78. from hermes_constants import get_hermes_home
  79. root = _project_root()
  80. cache_file = (home or get_hermes_home()) / "source-checks" / f"{install_id(root)}.json"
  81. try:
  82. cached = json.loads(cache_file.read_text(encoding="utf-8-sig"))
  83. except (OSError, ValueError):
  84. return "unknown"
  85. if not isinstance(cached, dict):
  86. return "unknown"
  87. status, identity, ts = cached.get("status"), cached.get("identity"), cached.get("ts")
  88. behind = status.get("behind") if isinstance(status, dict) else None
  89. head = identity.get("head") if isinstance(identity, dict) else None
  90. commit = _version_info().commit
  91. if (
  92. isinstance(behind, bool) or not isinstance(behind, int) or behind < 0
  93. or not isinstance(ts, (int, float)) or not 0 <= (now or time.time()) - ts < _BEHIND_MAX_AGE_S
  94. or (head and commit and head != commit)
  95. ):
  96. return "unknown"
  97. return contract.count_bucket(behind)
  98. def ram_bucket() -> str:
  99. from hermes_platform.host.facts import ram_total_bytes
  100. total = ram_total_bytes()
  101. if not total:
  102. return "unknown"
  103. return _bucket(total * _RAM_NOMINAL_FACTOR / _GIB, _RAM_THRESHOLDS, "gte_128g")
  104. def gpu_class() -> str:
  105. from hermes_platform.host.facts import gpu_class as host_gpu_class
  106. value = host_gpu_class()
  107. return value if value in contract.GPU_CLASSES else "unknown"
  108. def _is_local_endpoint(base_url: Any) -> bool:
  109. if not isinstance(base_url, str) or not base_url.strip():
  110. return False
  111. from agent.model_metadata import is_local_endpoint
  112. return is_local_endpoint(base_url)
  113. def _custom_base_url(provider: str) -> Any:
  114. """A ``providers:`` / ``custom_providers:`` entry's endpoint, by ``custom:<name>`` or bare name
  115. (built-in ids shadow entries, as at runtime)."""
  116. from hermes_cli.runtime_provider_custom import _get_named_custom_provider
  117. entry = _get_named_custom_provider(provider)
  118. return entry.get("base_url") if isinstance(entry, dict) else None
  119. def _slot_is_local(slot: Any) -> bool:
  120. provider = _norm(_sub(slot, "provider"))
  121. if provider in _LOCAL_PROVIDER_ALIASES:
  122. return True
  123. if _is_local_endpoint(_sub(slot, "base_url")):
  124. return True
  125. from .shared_metrics_catalog import CUSTOM, _safe as catalog_safe, user_named_model_providers
  126. if provider in catalog_safe(user_named_model_providers) - {CUSTOM}:
  127. return True
  128. return provider not in _INHERITS_MAIN and _is_local_endpoint(_custom_base_url(provider))
  129. def _aux_slot_routes_itself(slot: dict[str, Any]) -> bool:
  130. """An auxiliary task off the main model: a named provider, or (mirroring
  131. ``agent.auxiliary_client._resolve_task_provider_model``) a bare ``base_url`` + ``api_key``,
  132. which the runtime sends to that endpoint as ``custom`` even under ``provider: auto``."""
  133. if _norm(slot.get("provider")) not in _INHERITS_MAIN:
  134. return True
  135. return all(isinstance(slot.get(k), str) and slot[k].strip() for k in ("base_url", "api_key"))
  136. def local_model_provider_used(config: dict[str, Any]) -> str:
  137. """``yes`` when the main model or any auxiliary task runs on a local/self-hosted server."""
  138. model = _sub(config, "model")
  139. auxiliary = _sub(config, "auxiliary")
  140. slots = [model] if isinstance(model, dict) else []
  141. if isinstance(auxiliary, dict):
  142. slots += [s for s in auxiliary.values() if isinstance(s, dict) and _aux_slot_routes_itself(s)]
  143. return "yes" if any(_slot_is_local(slot) for slot in slots) else "no"
  144. def install_v4_snapshot_fields(config: dict[str, Any]) -> dict[str, str]:
  145. """The version-lag, channel and hardware dimensions of the daily snapshot."""
  146. fields = {
  147. "behind_bucket": _safe(behind_bucket, "unknown"),
  148. "gpu_class": _safe(gpu_class, "unknown"),
  149. "local_model_provider_used": _safe(lambda: local_model_provider_used(config), "no"),
  150. "ram_bucket": _safe(ram_bucket, "unknown"),
  151. "release_channel": _safe(lambda: release_channel(config), "unknown"),
  152. "version_age_bucket": _safe(version_age_bucket, "unknown"),
  153. }
  154. allowed = contract._INSTALL_V4_SNAPSHOT_DIMENSIONS
  155. return {k: v if v in allowed[k] else ("no" if k == "local_model_provider_used" else "unknown") for k, v in fields.items()}