availability.py 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117
  1. """Whether a catalog entry can be offered on this host, from its `app` and `requires` blocks.
  2. `availability` runs `locate`, `inspect` and the host's cached GPU fact only. It never probes, never spawns,
  3. never connects, and holds no cache: the callers that need a TTL (the tool registry) already have one.
  4. """
  5. from __future__ import annotations
  6. from dataclasses import dataclass
  7. import re
  8. from typing import Literal, Protocol
  9. from hermes_platform.host import facts
  10. from hermes_platform.resolver.app import AppDef, AppResolver
  11. from hermes_platform.resolver.core import Candidate, CheckState, Resolution
  12. AvailabilityState = Literal[
  13. "available",
  14. "installed_not_running",
  15. "missing_app",
  16. "version_too_old",
  17. "unsupported_os",
  18. "unsupported_gpu",
  19. "no_requirements",
  20. ]
  21. OFFERABLE: frozenset[str] = frozenset({"available", "no_requirements"})
  22. class _HasRequirements(Protocol):
  23. """The slice of a catalog entry `availability` reads; keeps this module free of `hermes_cli` imports."""
  24. @property
  25. def requires_app(self) -> bool: ...
  26. @property
  27. def min_version(self) -> str | None: ...
  28. @property
  29. def required_gpu(self) -> str | None: ...
  30. def app_for(self, os_family: str) -> AppDef | None: ...
  31. @dataclass(frozen=True)
  32. class Availability:
  33. state: AvailabilityState
  34. version: str | None = None
  35. path: str | None = None
  36. min_version: str | None = None
  37. @property
  38. def offerable(self) -> bool:
  39. return self.state in OFFERABLE
  40. def __bool__(self) -> bool:
  41. raise TypeError("Availability is not a boolean; read .offerable or .state")
  42. def as_dict(self) -> dict:
  43. return {"state": self.state, "version": self.version, "path": self.path, "min_version": self.min_version}
  44. def _version_parts(version: str) -> list[int] | None:
  45. if not re.fullmatch(r"[0-9]{1,9}(?:\.[0-9]{1,9})*", version):
  46. return None
  47. return [int(component) for component in version.split(".")]
  48. def version_at_least(found: str, minimum: str) -> bool:
  49. """Compare dot-separated decimal components, failing closed on invalid input."""
  50. a, b = _version_parts(found), _version_parts(minimum)
  51. if a is None or b is None:
  52. return False
  53. width = max(len(a), len(b))
  54. a += [0] * (width - len(a))
  55. b += [0] * (width - len(b))
  56. return a >= b
  57. def availability(entry: _HasRequirements, *, os_family: str | None = None) -> Availability:
  58. gpu = entry.required_gpu
  59. if not entry.requires_app and gpu is None:
  60. return Availability("no_requirements")
  61. osf = os_family or facts.os_family()
  62. definition = entry.app_for(osf) if entry.requires_app else None
  63. if entry.requires_app and definition is None:
  64. return Availability("unsupported_os", min_version=entry.min_version)
  65. # An unreadable GPU (`unknown`) passes: refusing on a failed registry or sysfs read would lock out
  66. # the machines that have the GPU, and the MCP connection check still applies.
  67. if gpu is not None and facts.gpu_class() not in (gpu, "unknown"):
  68. return Availability("unsupported_gpu", min_version=entry.min_version)
  69. if definition is None:
  70. return Availability("no_requirements")
  71. resolver = AppResolver(definition)
  72. res = resolver.locate()
  73. looked_at = res.command[0] if res.command else (res.candidates[0].value if res.candidates else None)
  74. if not res.found:
  75. return Availability("missing_app", path=looked_at, min_version=entry.min_version)
  76. if definition.version_kind == "none":
  77. return Availability("available", path=looked_at, min_version=entry.min_version)
  78. def version_of(copy: Candidate) -> str | None:
  79. obs = resolver.inspect(Resolution(res.kind, (copy,))).version
  80. return obs.value if obs.state is CheckState.PRESENT else None
  81. if not entry.min_version:
  82. return Availability("available", version=version_of(res.present[0]), path=looked_at)
  83. # Every present copy is read, so an old copy found first does not hide a newer one found later;
  84. # location order only breaks ties among copies that qualify.
  85. copies = [(copy.value, version_of(copy)) for copy in res.present]
  86. for path, version in copies:
  87. if version is not None and version_at_least(version, entry.min_version):
  88. return Availability("available", version=version, path=path, min_version=entry.min_version)
  89. readable = [(parts, path, version) for path, version in copies
  90. if version is not None and (parts := _version_parts(version)) is not None]
  91. _, path, version = max(readable, key=lambda item: item[0]) if readable else (None, looked_at, None)
  92. return Availability("version_too_old", version=version, path=path, min_version=entry.min_version)