xai_retirement.py 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182
  1. """Detect xAI models retired on May 15, 2026 and migrate config.yaml references."""
  2. from __future__ import annotations
  3. import io
  4. from dataclasses import dataclass
  5. from pathlib import Path
  6. from typing import Any, Dict, List, Optional
  7. MIGRATION_GUIDE_URL = "https://docs.x.ai/developers/migration/may-15-retirement"
  8. RETIREMENT_DATE = "May 15, 2026"
  9. # Official mapping per xAI migration guide. ``grok-4.3`` reasons by default, so ``*-non-reasoning``
  10. # variants need ``reasoning_effort="none"`` to emulate their behavior.
  11. _RETIRED_MODELS: dict[str, dict[str, Optional[str]]] = {
  12. "grok-4-0709": {"replacement": "grok-4.3", "reasoning_effort": None, "note": None},
  13. "grok-4-fast-reasoning": {"replacement": "grok-4.3", "reasoning_effort": None, "note": None},
  14. "grok-4-fast-non-reasoning": {"replacement": "grok-4.3", "reasoning_effort": "none", "note": None},
  15. "grok-4-1-fast-reasoning": {"replacement": "grok-4.3", "reasoning_effort": None, "note": None},
  16. "grok-4-1-fast-non-reasoning": {"replacement": "grok-4.3", "reasoning_effort": "none", "note": None},
  17. "grok-code-fast-1": {"replacement": "grok-4.3", "reasoning_effort": None, "note": None},
  18. "grok-3": {"replacement": "grok-4.3", "reasoning_effort": None, "note": None},
  19. "grok-imagine-image-pro": {"replacement": "grok-imagine-image-quality", "reasoning_effort": None, "note": None},
  20. }
  21. @dataclass(frozen=True)
  22. class RetirementIssue:
  23. """A reference to a retired xAI model found in a Hermes config."""
  24. config_path: str # e.g. "principal.model" or "auxiliary.vision.model"
  25. current_model: str # exact value found in config (preserves casing/prefix)
  26. replacement: str
  27. reasoning_effort: Optional[str] = None # set for non-reasoning variant migration
  28. note: Optional[str] = None
  29. def _normalize(model_id: str) -> str:
  30. """Strip provider prefix (``x-ai/grok-4`` → ``grok-4``) and lowercase."""
  31. m = model_id.strip().lower()
  32. for prefix in ("x-ai/", "xai/"):
  33. if m.startswith(prefix):
  34. return m[len(prefix):]
  35. return m
  36. def _looks_like_xai(model_id: Optional[str]) -> bool:
  37. return isinstance(model_id, str) and _normalize(model_id).startswith("grok-")
  38. def find_retired_xai_refs(config: dict[str, Any]) -> list[RetirementIssue]:
  39. """Walk all model slots in a Hermes config and return retirement issues.
  40. Slots scanned: ``principal.model``, ``auxiliary.<any>.model`` (introspective, covers future
  41. aux slots), ``delegation.model``, ``tts.xai.model``, ``plugins.image_gen.xai.model``.
  42. """
  43. issues: list[RetirementIssue] = []
  44. if not isinstance(config, dict):
  45. return issues
  46. def _check(path: str, model: Any) -> None:
  47. entry = _RETIRED_MODELS.get(_normalize(model)) if _looks_like_xai(model) else None
  48. if entry is not None:
  49. issues.append(RetirementIssue(
  50. config_path=path,
  51. current_model=model,
  52. replacement=entry["replacement"],
  53. reasoning_effort=entry.get("reasoning_effort"),
  54. note=entry.get("note")))
  55. def _section(*keys: str) -> Optional[dict[str, Any]]:
  56. node: Any = config
  57. for key in keys:
  58. if not isinstance(node, dict):
  59. return None
  60. node = node.get(key)
  61. return node if isinstance(node, dict) else None
  62. def _check_section(*path: str) -> None:
  63. section = _section(*path)
  64. if section is not None:
  65. _check(".".join(path) + ".model", section.get("model"))
  66. _check_section("principal")
  67. for slot_name, slot_cfg in (_section("auxiliary") or {}).items():
  68. if isinstance(slot_cfg, dict):
  69. _check(f"auxiliary.{slot_name}.model", slot_cfg.get("model"))
  70. for path in (("delegation",), ("tts", "xai"), ("plugins", "image_gen", "xai")):
  71. _check_section(*path)
  72. return issues
  73. def format_issue(issue: RetirementIssue) -> str:
  74. """One-line human-readable rendering of a retirement issue."""
  75. parts = [f"{issue.config_path}: {issue.current_model!r} → use {issue.replacement!r}"]
  76. if issue.reasoning_effort:
  77. parts.append(f'(set reasoning_effort: "{issue.reasoning_effort}")')
  78. if issue.note:
  79. parts.append(f"[note: {issue.note}]")
  80. return " ".join(parts)
  81. @dataclass(frozen=True)
  82. class ApplyResult:
  83. """Outcome of an apply_migration call."""
  84. file_path: Path
  85. backup_path: Optional[Path]
  86. issues_resolved: list[RetirementIssue]
  87. config_changed: bool
  88. def _walk_to_parent(yaml_doc: Any, dotted_path: str) -> tuple[Any, str]:
  89. """Resolve a dotted slot path to (parent_mapping, leaf_key)."""
  90. *parents, leaf = dotted_path.split(".")
  91. if not parents:
  92. raise ValueError(f"Path must have at least one parent: {dotted_path!r}")
  93. node = yaml_doc
  94. for segment in parents:
  95. if not isinstance(node, dict) or segment not in node:
  96. raise KeyError(f"Path segment {segment!r} missing in {dotted_path!r}")
  97. node = node[segment]
  98. return node, leaf
  99. def apply_migration(
  100. config_path: Path, issues: list[RetirementIssue], backup: bool = True) -> ApplyResult:
  101. """Rewrite ``config_path`` in place (ruamel round-trip: comments, order, type literals kept).
  102. Unless ``backup=False`` a copy goes to ``backups/config/`` (reason ``pre-migrate-xai``).
  103. """
  104. from ruamel.yaml import YAML # local import — avoid hard dep at module load
  105. from hermes_cli.config_backend import require_file_tooling
  106. # A type-literal-preserving rewrite of the file itself; a non-file backend has no file.
  107. require_file_tooling("The xAI model migration")
  108. config_path = Path(config_path)
  109. if not config_path.exists(): # config-reader: ok — file tooling, gated on supports_file_tooling()
  110. raise FileNotFoundError(config_path)
  111. unchanged = ApplyResult(file_path=config_path, backup_path=None, issues_resolved=[], config_changed=False)
  112. if not issues:
  113. return unchanged
  114. from hermes_yaml import ROUNDTRIP_YAML_WIDTH
  115. yaml = YAML(typ="rt")
  116. yaml.width = ROUNDTRIP_YAML_WIDTH
  117. yaml.preserve_quotes = True
  118. with config_path.open("r", encoding="utf-8-sig") as fh: # config-reader: ok — file tooling (gated above)
  119. doc = yaml.load(fh)
  120. if doc is None:
  121. return unchanged
  122. resolved: list[RetirementIssue] = []
  123. for issue in issues:
  124. try:
  125. parent, leaf = _walk_to_parent(doc, issue.config_path)
  126. except KeyError:
  127. continue # slot vanished between scan and apply
  128. parent[leaf] = issue.replacement
  129. if issue.reasoning_effort:
  130. parent["reasoning_effort"] = issue.reasoning_effort
  131. resolved.append(issue)
  132. if not resolved:
  133. return unchanged
  134. backup_path: Optional[Path] = None
  135. if backup:
  136. from hermes_cli.config_backups import backup_config
  137. backup_path = backup_config(config_path, "pre-migrate-xai")
  138. from hermes_cli.config import require_readable_config_before_write
  139. from utils import atomic_write_text
  140. require_readable_config_before_write(config_path)
  141. # Dump to a buffer, then atomic-write: ``open(path, "w")`` truncates before the dump runs, so a
  142. # crash mid-write would leave config.yaml empty (and with ``--no-backup`` that is the only
  143. # copy; the ``doc is None`` early return would then hide the damage). atomic_replace also keeps
  144. # a symlinked config.yaml intact. preserve_mode keeps permission bits AND owner (managed NixOS
  145. # 0640 / container installs; a root-run migration must not flip ownership).
  146. buf = io.StringIO()
  147. yaml.dump(doc, buf)
  148. atomic_write_text(config_path, buf.getvalue(), preserve_mode=True) # config-reader: ok — file tooling (gated above)
  149. return ApplyResult(file_path=config_path, backup_path=backup_path, issues_resolved=resolved, config_changed=True)