tips.py 2.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778
  1. """Random tips shown at CLI session start to help users discover features.
  2. The tip text lives in the i18n catalog (``locales/<lang>.yaml`` under ``tips.tNNN`` and
  3. ``tips.placeholder.pNN``), so language packs translate it like every other user-facing string.
  4. The English catalog is the source of truth for HOW MANY tips exist (key parity is enforced by
  5. tests/agent/test_i18n.py); the pickers resolve each key through ``t()`` for the active language.
  6. """
  7. from __future__ import annotations
  8. import random
  9. import threading
  10. from agent.i18n import DEFAULT_LANGUAGE, t
  11. TIP_KEY_PREFIX = "tips.t"
  12. PLACEHOLDER_KEY_PREFIX = "tips.placeholder.p"
  13. _TIP_KEY_WIDTH = 3
  14. _PLACEHOLDER_KEY_WIDTH = 2
  15. # Hard stop for the contiguous-key probe so a pathological catalog can never spin.
  16. _MAX_KEYS = 10_000
  17. _keys_lock = threading.Lock()
  18. _keys_cache: dict[str, tuple[str, ...]] = {}
  19. def _catalog_keys(prefix: str, width: int) -> tuple[str, ...]:
  20. """Contiguous ``<prefix><NN…>`` keys present in the English catalog, cached per prefix.
  21. Counted against English (the parity baseline) so a partial translation never shrinks the
  22. pool: a missing translated key falls back to English inside ``t()``. The count only changes
  23. when the bundled catalog changes, i.e. on a code change, so a process-lifetime cache is safe.
  24. """
  25. with _keys_lock:
  26. cached = _keys_cache.get(prefix)
  27. if cached is not None:
  28. return cached
  29. keys: list[str] = []
  30. for index in range(1, _MAX_KEYS):
  31. key = f"{prefix}{index:0{width}d}"
  32. if t(key, lang=DEFAULT_LANGUAGE) == key: # bare-key echo == not in the catalog
  33. break
  34. keys.append(key)
  35. found = tuple(keys)
  36. with _keys_lock:
  37. _keys_cache[prefix] = found
  38. return found
  39. def reset_tips_cache() -> None:
  40. """Forget the probed key lists (tests that swap the locales dir call this)."""
  41. with _keys_lock:
  42. _keys_cache.clear()
  43. def tip_keys() -> tuple[str, ...]:
  44. """Catalog keys of every startup tip, in catalog order."""
  45. return _catalog_keys(TIP_KEY_PREFIX, _TIP_KEY_WIDTH)
  46. def composer_placeholder_keys() -> tuple[str, ...]:
  47. """Catalog keys of every empty-composer example prompt, in catalog order."""
  48. return _catalog_keys(PLACEHOLDER_KEY_PREFIX, _PLACEHOLDER_KEY_WIDTH)
  49. def get_random_tip(exclude_recent: int = 0) -> str:
  50. """Return a random tip string in the active language ("" if the catalog has none)."""
  51. keys = tip_keys()
  52. return t(random.choice(keys)) if keys else ""
  53. def get_random_composer_placeholder() -> str:
  54. """Return a rotating task-oriented placeholder for the empty composer, in the active language.
  55. Kept generic — Hermes is not a coding-only agent, so the prompts must fit any project or none.
  56. """
  57. keys = composer_placeholder_keys()
  58. return t(random.choice(keys)) if keys else ""