profile_describer.py 8.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201
  1. """Profile describer — auto-generate ``description`` for a profile.
  2. Mirrors ``hermes_cli/kanban_specify.py``: lazy aux client import, lenient response parse,
  3. never raises on expected failure modes. Reads at most ``MAX_SKILLS_FOR_PROMPT`` skill
  4. names to keep the prompt bounded.
  5. """
  6. from __future__ import annotations
  7. import logging
  8. import re
  9. from dataclasses import dataclass
  10. from pathlib import Path
  11. from typing import Optional
  12. from hermes_cli import profiles as profiles_mod
  13. from agent.skill_utils import is_excluded_skill_path
  14. logger = logging.getLogger(__name__)
  15. # Cap on skill names fed to the LLM (200+ skill profiles would blow context).
  16. MAX_SKILLS_FOR_PROMPT = 60
  17. _SYSTEM_PROMPT = """You are a profile-describer for the Hermes Agent kanban board.
  18. A user runs multiple "profiles" — distinct agent identities, each with their
  19. own skills, model, and configuration. The kanban board's orchestrator routes
  20. work to whichever profile best fits each task. To do that well, every
  21. profile needs a short, concrete description of what it's good at.
  22. You are given a profile's:
  23. - Name
  24. - Model / provider
  25. - List of installed skill names (a strong signal of role / domain)
  26. Produce a single JSON object with exactly one key:
  27. {
  28. "description": "<1-2 sentence description, plain prose, no preamble>"
  29. }
  30. Rules:
  31. - The description is what an orchestrator will read to decide whether to
  32. route a task here. Lead with the profile's strongest capability.
  33. - Stay concrete. Bad: "an AI agent that helps users."
  34. Good: "Reads and modifies Python codebases — runs tests,
  35. refactors functions, opens GitHub PRs."
  36. - 1-2 sentences, <= 280 characters total.
  37. - Never invent capabilities the skills don't suggest.
  38. - Never write "Hermes Agent profile" or other meta-narration.
  39. - No code fences, no preamble, no closing remarks. Output only JSON.
  40. """
  41. _USER_TEMPLATE = """Profile name: {name}
  42. Default model: {model}
  43. Provider: {provider}
  44. Installed skill count: {skill_count}
  45. Notable skills (up to {skill_cap}):
  46. {skill_list}
  47. """
  48. _FENCE_RE = re.compile(r"^```(?:json)?\s*|\s*```$", re.MULTILINE | re.IGNORECASE)
  49. @dataclass
  50. class DescribeOutcome:
  51. """Result of describing a single profile."""
  52. profile_name: str
  53. ok: bool
  54. reason: str = ""
  55. description: Optional[str] = None
  56. def _collect_skills(profile_dir: Path) -> list[str]:
  57. """Sorted non-excluded skill names: ``category/skill_name`` (category = immediate subdir
  58. under ``skills/``), or bare ``skill_name`` for skills directly under ``skills/``."""
  59. skills_dir = profile_dir / "skills"
  60. if not skills_dir.is_dir():
  61. return []
  62. names: list[str] = []
  63. for md in skills_dir.rglob("SKILL.md"):
  64. if is_excluded_skill_path(md):
  65. continue
  66. try:
  67. parts = md.relative_to(skills_dir).parts[:-1] # drop SKILL.md
  68. except ValueError:
  69. continue
  70. if parts:
  71. names.append(parts[0] if len(parts) == 1 else f"{parts[0]}/{parts[-1]}")
  72. names.sort()
  73. return names
  74. def _sample_skills(names: list[str]) -> list[str]:
  75. """Cap *names* to the prompt budget with evenly-spaced picks: alphabetical position isn't
  76. importance, so a profile with skills A..Z must not read as "starts with A"."""
  77. if len(names) <= MAX_SKILLS_FOR_PROMPT:
  78. return names
  79. step = len(names) / MAX_SKILLS_FOR_PROMPT
  80. return [names[int(i * step)] for i in range(MAX_SKILLS_FOR_PROMPT)]
  81. def _extract_json_blob(raw: str) -> Optional[dict]:
  82. from hermes_cli.kanban_specify import _extract_json_blob as _extract
  83. return _extract(raw, _FENCE_RE)
  84. def describe_profile(profile_name: str, *, overwrite: bool = False, timeout: Optional[int] = None) -> DescribeOutcome:
  85. """Auto-generate a description for one profile. Expected failures (profile missing, no aux
  86. client, API error, malformed response) return ``ok=False`` so a sweep continues.
  87. ``overwrite`` allows replacing a user-authored (``description_auto: false``) description;
  88. auto-generated ones are always replaceable."""
  89. canon = profiles_mod.normalize_profile_name(profile_name)
  90. if not profiles_mod.profile_exists(canon): # handles the virtual "default" name
  91. return DescribeOutcome(canon, False, "profile not found")
  92. try:
  93. if canon == "default":
  94. from hermes_constants import get_hermes_home # type: ignore
  95. profile_dir = Path(get_hermes_home())
  96. else:
  97. profile_dir = profiles_mod.get_profile_dir(canon)
  98. except Exception as exc:
  99. return DescribeOutcome(canon, False, f"cannot resolve profile dir: {exc}")
  100. existing = profiles_mod.read_profile_meta(profile_dir)
  101. if existing.get("description") and not existing.get("description_auto") and not overwrite:
  102. return DescribeOutcome(
  103. canon, False, "profile already has a user-authored description (use --overwrite to replace)"
  104. )
  105. all_skills = _collect_skills(profile_dir)
  106. skill_list = "\n".join(f" - {n}" for n in _sample_skills(all_skills)) or " (no skills installed)"
  107. try:
  108. model, provider = profiles_mod._read_config_model(profile_dir)
  109. except Exception:
  110. model, provider = None, None
  111. try:
  112. from agent.auxiliary_client import call_llm # type: ignore
  113. except Exception as exc:
  114. logger.debug("describe: auxiliary client import failed: %s", exc)
  115. return DescribeOutcome(canon, False, "auxiliary client unavailable")
  116. user_msg = _USER_TEMPLATE.format(
  117. name=canon, model=(model or "(unset)"), provider=(provider or "(unset)"), skill_count=len(all_skills),
  118. skill_cap=MAX_SKILLS_FOR_PROMPT, skill_list=skill_list,
  119. )
  120. try:
  121. # call_llm applies auxiliary.profile_describer.* config (provider/model/base_url,
  122. # extra_body, reasoning_effort, retries); the direct-create path dropped extra_body.
  123. # See #35566.
  124. resp = call_llm(
  125. task="profile_describer",
  126. messages=[{"role": "system", "content": _SYSTEM_PROMPT}, {"role": "user", "content": user_msg}],
  127. temperature=0.3,
  128. max_tokens=400,
  129. timeout=timeout or 60,
  130. )
  131. except Exception as exc:
  132. logger.info("describe: API call failed for %s (%s)", canon, exc)
  133. return DescribeOutcome(canon, False, f"LLM error: {type(exc).__name__}")
  134. try:
  135. raw = resp.choices[0].message.content or ""
  136. except Exception:
  137. raw = ""
  138. parsed = _extract_json_blob(raw)
  139. if parsed is None:
  140. # JSON-shaped but unparseable = the requested object got cut off (#104067); the prose
  141. # fallback below is only for models that never attempted JSON.
  142. stripped = _FENCE_RE.sub("", raw.strip())
  143. if stripped.startswith("{"):
  144. logger.info(
  145. "describe: %s aux response looked JSON-shaped but failed to parse "
  146. "(likely truncated) -- refusing to persist the raw fragment", canon,
  147. )
  148. return DescribeOutcome(canon, False, "LLM returned malformed/truncated JSON response")
  149. # Fall back: raw text trimmed to one paragraph.
  150. text = raw.strip().split("\n\n", 1)[0]
  151. if not text:
  152. return DescribeOutcome(canon, False, "LLM returned an empty response")
  153. description = text[:280]
  154. else:
  155. val = parsed.get("description")
  156. if not isinstance(val, str) or not val.strip():
  157. return DescribeOutcome(canon, False, "LLM response missing 'description' field")
  158. description = val.strip()[:280]
  159. try:
  160. profiles_mod.write_profile_meta(profile_dir, description=description, description_auto=True)
  161. except Exception as exc:
  162. return DescribeOutcome(canon, False, f"failed to write profile.yaml: {exc}")
  163. return DescribeOutcome(canon, True, "described", description=description)
  164. def list_describable_profiles(*, missing_only: bool = True) -> list[str]:
  165. """Profile names that can be described; ``missing_only`` keeps only those without a
  166. user-authored description."""
  167. return [
  168. p.name for p in profiles_mod.list_profiles()
  169. if not (missing_only and (p.description or "").strip() and not p.description_auto)
  170. ]