_common.py 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320
  1. """Shared helpers for the bundled ``image_gen`` provider plugins. Providers are loaded by path
  2. (``hermes_plugins.image_gen__<name>``) and resolve this via the repo root on ``sys.path``;
  3. not a plugin itself (the scanner only looks at directories)."""
  4. from __future__ import annotations
  5. import logging
  6. import os
  7. from dataclasses import dataclass
  8. from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple
  9. from agent.image_gen_provider import (
  10. ImageGenProvider, error_response, normalize_reference_images, save_b64_image, save_url_image)
  11. logger = logging.getLogger(__name__)
  12. # OpenAI-style ``size`` per semantic aspect, shared by every OpenAI-compatible backend.
  13. OPENAI_SIZES: dict[str, str] = {"landscape": "1536x1024", "square": "1024x1024", "portrait": "1024x1536"}
  14. # gpt-image-2 quality tiers as virtual model ids (same API model, different ``quality`` knob).
  15. GPT_IMAGE_2_API_MODEL = "gpt-image-2"
  16. GPT_IMAGE_2_DEFAULT = "gpt-image-2-medium"
  17. GPT_IMAGE_2_TIERS: dict[str, dict[str, Any]] = {
  18. "gpt-image-2-low": {
  19. "display": "GPT Image 2 (Low)",
  20. "speed": "~15s",
  21. "strengths": "Fast iteration, lowest cost",
  22. "quality": "low",
  23. },
  24. "gpt-image-2-medium": {
  25. "display": "GPT Image 2 (Medium)",
  26. "speed": "~40s",
  27. "strengths": "Balanced — default",
  28. "quality": "medium",
  29. },
  30. "gpt-image-2-high": {
  31. "display": "GPT Image 2 (High)",
  32. "speed": "~2min",
  33. "strengths": "Highest fidelity, strongest prompt adherence",
  34. "quality": "high",
  35. },
  36. }
  37. PROMPT_REQUIRED = "Prompt is required and must be a non-empty string"
  38. OPENAI_MISSING = "openai Python package not installed (pip install openai)"
  39. ErrorFn = Callable[..., dict[str, Any]]
  40. def size_for(aspect: str) -> str:
  41. """OpenAI ``size`` string for a semantic aspect (square when unknown)."""
  42. return OPENAI_SIZES.get(aspect, OPENAI_SIZES["square"])
  43. def load_image_gen_config(sub: Optional[str] = None) -> dict[str, Any]:
  44. """Read ``image_gen`` (or ``image_gen.<sub>``) from config.yaml; ``{}`` on any failure."""
  45. label = "image_gen" if sub is None else f"image_gen.{sub}"
  46. try:
  47. from hermes_cli.config import load_config
  48. cfg = load_config()
  49. section = cfg.get("image_gen") if isinstance(cfg, dict) else None
  50. if sub is not None:
  51. section = section.get(sub) if isinstance(section, dict) else None
  52. return section if isinstance(section, dict) else {}
  53. except Exception as exc:
  54. logger.debug("Could not load %s config: %s", label, exc)
  55. return {}
  56. def resolve_static_model(
  57. models: dict[str, dict[str, Any]], default: str, *, env_var: str, config_key: str,
  58. explicit: Optional[str] = None, include_top_level: bool = True,
  59. config: Optional[dict[str, Any]] = None, passthrough: bool = False,
  60. ) -> tuple[str, dict[str, Any]]:
  61. """``(model_id, meta)`` from a fixed catalog; first *known* id wins (unknown ids fall through):
  62. explicit → ``env_var`` → ``image_gen.<config_key>.model`` → ``image_gen.model`` → ``default``.
  63. ``passthrough``: an unknown id from ``env_var`` or the provider-scoped ``image_gen.<config_key>.model``
  64. is sent verbatim as the API model with no ``quality`` (OpenAI-compatible gateways serve their own
  65. image model names and reject unknown enum values, #97928). The shared top-level ``image_gen.model``
  66. never passes through — it may hold another provider's id."""
  67. if isinstance(explicit, str) and explicit.strip() in models:
  68. return explicit.strip(), models[explicit.strip()]
  69. env_override = os.environ.get(env_var)
  70. if env_override and env_override in models:
  71. return env_override, models[env_override]
  72. cfg = load_image_gen_config() if config is None else config
  73. scoped = cfg.get(config_key)
  74. candidates = [scoped.get("model") if isinstance(scoped, dict) else None]
  75. if include_top_level:
  76. candidates.append(cfg.get("model"))
  77. for candidate in candidates:
  78. if isinstance(candidate, str) and candidate in models:
  79. return candidate, models[candidate]
  80. if passthrough:
  81. custom = next((c.strip() for c in (env_override, candidates[0]) if isinstance(c, str) and c.strip()), "")
  82. if custom:
  83. return custom, {"display": custom, "api_model": custom, "quality": None}
  84. return default, models[default]
  85. def collect_source_images(
  86. image_url: Optional[str], reference_image_urls: Optional[list[str]], limit: Optional[int] = None
  87. ) -> list[str]:
  88. """Primary ``image_url`` first, then normalized references, clamped to ``limit``."""
  89. sources: list[str] = []
  90. if isinstance(image_url, str) and image_url.strip():
  91. sources.append(image_url.strip())
  92. sources.extend(normalize_reference_images(reference_image_urls) or [])
  93. return sources[:limit] if limit is not None else sources
  94. def catalog_rows(
  95. models: dict[str, dict[str, Any]],
  96. fields: Iterable[str] = ("display", "speed", "strengths", "price"), *,
  97. price: Optional[str] = None,
  98. ) -> list[dict[str, Any]]:
  99. """Picker rows: ``id`` + ``fields`` (missing ``display`` → id, else ``""``); ``price`` overrides."""
  100. rows = []
  101. for model_id, meta in models.items():
  102. row: dict[str, Any] = {"id": model_id}
  103. for field in fields:
  104. row[field] = meta.get(field, model_id if field == "display" else "")
  105. if price is not None:
  106. row["price"] = price
  107. rows.append(row)
  108. return rows
  109. def api_key_setup_schema(
  110. name: str, badge: str, tag: str, *, key: str, prompt: str, url: str
  111. ) -> dict[str, Any]:
  112. """``get_setup_schema()`` dict for a provider authenticated by one env var."""
  113. return {
  114. "name": name, "badge": badge, "tag": tag, "env_vars": [{"key": key, "prompt": prompt, "url": url}],
  115. }
  116. class StaticImageGenProvider(ImageGenProvider):
  117. """Identity + picker surface from class attributes: ``provider_id``/``label``; fixed catalog via
  118. ``models`` (+ ``default_model_id``, ``price``, ``catalog_fields``); single-env-var auth via
  119. ``setup`` (kwargs for :func:`api_key_setup_schema`). Dynamic providers override methods."""
  120. provider_id: str
  121. label: str
  122. models: dict[str, dict[str, Any]] = {}
  123. default_model_id: Optional[str] = None
  124. price: Optional[str] = None
  125. catalog_fields: tuple[str, ...] = ("display", "speed", "strengths", "price")
  126. setup: dict[str, Any] = {}
  127. @property
  128. def name(self) -> str:
  129. return self.provider_id
  130. @property
  131. def display_name(self) -> str:
  132. return self.label
  133. def list_models(self) -> list[dict[str, Any]]:
  134. return catalog_rows(self.models, self.catalog_fields, price=self.price)
  135. def default_model(self) -> Optional[str]:
  136. return self.default_model_id
  137. def get_setup_schema(self) -> dict[str, Any]:
  138. return api_key_setup_schema(**self.setup)
  139. def error_factory(provider: str, aspect: str, *, model: str = "", prompt: str = "") -> ErrorFn:
  140. """Return ``fail(error, error_type, **override)`` pre-bound to this call's context."""
  141. def fail(error: str, error_type: str, **override: Any) -> dict[str, Any]:
  142. kwargs = dict(provider=provider, model=model, prompt=prompt, aspect_ratio=aspect)
  143. kwargs.update(override)
  144. return error_response(error=error, error_type=error_type, **kwargs)
  145. return fail
  146. def prompt_required_error(provider: str, aspect: str) -> dict[str, Any]:
  147. return error_factory(provider, aspect)(PROMPT_REQUIRED, "invalid_argument")
  148. def openai_importable() -> bool:
  149. return import_openai("", "")[0] is not None
  150. def import_openai(provider: str, aspect: str) -> tuple[Any, Optional[dict[str, Any]]]:
  151. """Return ``(openai_module, None)`` or ``(None, missing_dependency error)``."""
  152. try:
  153. import openai
  154. except ImportError:
  155. return None, error_factory(provider, aspect)(OPENAI_MISSING, "missing_dependency")
  156. return openai, None
  157. def materialize_image(
  158. b64: Optional[str], url: Optional[str], *, prefix: str, label: str, provider: str, model: str,
  159. prompt: str, aspect: str, log: logging.Logger = logger,
  160. on_url_fail: Optional[Callable[[Exception], None]] = None,
  161. ) -> tuple[Optional[str], Optional[dict[str, Any]]]:
  162. """``(image_ref, None)`` or ``(None, error)`` for a ``(b64_json, url)`` pair. Base64 is always
  163. cached (write failure → ``io_error``); a URL is cached best-effort, falling back to the bare URL."""
  164. fail = error_factory(provider, aspect, model=model, prompt=prompt)
  165. if b64:
  166. try:
  167. return str(save_b64_image(b64, prefix=prefix)), None
  168. except Exception as exc:
  169. return None, fail(f"Could not save image to cache: {exc}", "io_error")
  170. if url:
  171. return cache_url_best_effort(url, prefix=prefix, label=label, log=log, on_fail=on_url_fail), None
  172. return None, fail(f"{label} response contained neither b64_json nor URL", "empty_response")
  173. def cache_url_best_effort(
  174. url: str, *, prefix: str, label: str, log: logging.Logger = logger,
  175. on_fail: Optional[Callable[[Exception], None]] = None,
  176. ) -> str:
  177. """Cache ``url`` locally; on failure warn (or call ``on_fail``) and return the bare URL."""
  178. try:
  179. return str(save_url_image(url, prefix=prefix))
  180. except Exception as exc:
  181. if on_fail is not None:
  182. on_fail(exc)
  183. else:
  184. log.warning("%s image URL %s could not be cached (%s); falling back to bare URL.", label, url, exc)
  185. return url
  186. def requests_error_message(response: Any, exc: Exception) -> str:
  187. """``error.message`` from an HTTP error body, else the first 300 chars of it."""
  188. try:
  189. return response.json().get("error", {}).get("message", response.text[:300])
  190. except Exception:
  191. return response.text[:300] if response is not None else str(exc)
  192. @dataclass
  193. class HttpFailure:
  194. """One failed ``post_json`` attempt as ``(error, error_type)``. ``kind`` ∈ http / timeout /
  195. unreachable (DNS failure or refused connection: nothing was sent) / connection (dropped
  196. after connecting) / request / invalid_json; ``message`` = HTTP error text or decode error;
  197. ``status`` / ``response`` are set for ``http`` only."""
  198. kind: str
  199. error: str
  200. error_type: str
  201. status: int = 0
  202. message: str = ""
  203. response: Any = None
  204. def record_token_usage(usage: Any, *, model: str, provider: str, base_url: Optional[str] = None) -> None:
  205. """Record a token-billed image call against the ambient session as task ``image_generation``.
  206. Token-metered image models (OpenRouter chat-image and Image API models, OpenAI ``gpt-image``)
  207. bill exactly like a chat completion, so they get a ``session_model_usage`` row through the
  208. same chokepoint as auxiliary calls. ``usage`` is the response's usage block (dict or SDK
  209. object). Per-image backends (FAL, xAI, Krea, ...) return no token usage and never call this;
  210. a body without tokens is a no-op inside ``record_aux_usage``, as is running outside a turn.
  211. """
  212. if not usage:
  213. return
  214. from types import SimpleNamespace
  215. from agent.aux_accounting import record_aux_usage
  216. record_aux_usage(
  217. SimpleNamespace(model=model, usage=usage), "image_generation", provider=provider, base_url=base_url)
  218. def _never_connected(exc: Exception) -> bool:
  219. """True when the last connection attempt never connected, so no server accepted the request body
  220. (a redirect hop may have answered earlier, but a redirect accepts nothing)."""
  221. from urllib3.exceptions import MaxRetryError, NameResolutionError, NewConnectionError
  222. cause = exc.args[0] if exc.args else None
  223. reason = cause.reason if isinstance(cause, MaxRetryError) else cause
  224. return isinstance(reason, (NewConnectionError, NameResolutionError))
  225. def post_json(
  226. url: str, *, headers: dict[str, str], payload: dict[str, Any], timeout: Any, label: str,
  227. error_message: Callable[[Any, Exception], str] = requests_error_message,
  228. catch_request_exception: bool = False,
  229. ) -> tuple[Optional[Any], Optional[HttpFailure]]:
  230. """POST ``payload`` → ``(json_body, None)`` or ``(None, failure)``. ``timeout`` goes to ``requests``
  231. verbatim (message reports the read component); ``error_message(response, exc)`` extracts the
  232. backend-specific HTTP error text."""
  233. import requests
  234. read_timeout = timeout[1] if isinstance(timeout, tuple) else timeout
  235. try:
  236. response = requests.post(url, headers=headers, json=payload, timeout=timeout)
  237. response.raise_for_status()
  238. except requests.HTTPError as exc:
  239. resp = exc.response
  240. status = resp.status_code if resp is not None else 0
  241. message = error_message(resp, exc)
  242. return None, HttpFailure(
  243. "http", f"{label} image generation failed ({status}): {message}", "api_error",
  244. status=status, message=message, response=resp)
  245. except requests.Timeout:
  246. return None, HttpFailure(
  247. "timeout", f"{label} image generation timed out ({int(read_timeout)}s)", "timeout")
  248. except requests.ConnectionError as exc:
  249. kind = "unreachable" if _never_connected(exc) else "connection"
  250. return None, HttpFailure(kind, f"{label} connection error: {exc}", "connection_error")
  251. except requests.RequestException as exc:
  252. if not catch_request_exception:
  253. raise
  254. return None, HttpFailure("request", f"{label} request failed: {exc}", "api_error")
  255. try:
  256. return response.json(), None
  257. except Exception as exc:
  258. return None, HttpFailure(
  259. "invalid_json", f"{label} returned invalid JSON: {exc}", "invalid_response", message=str(exc),
  260. )