fal_common.py 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243
  1. """Shared FAL.ai SDK plumbing: lazy import, managed-gateway sync client, small helpers.
  2. Holds the stateless atoms that every FAL-backed tool needs:
  3. * :func:`import_fal_client` — lazy import + ``pm.ensure_import`` so
  4. ``fal_client`` isn't pulled at cold start (it added ~64 ms per CLI
  5. invocation when imported eagerly).
  6. * :class:`_ManagedFalSyncClient` — wrapper that drives a Nous-managed
  7. fal-queue gateway through the standard ``fal_client.SyncClient``
  8. primitives.
  9. * :func:`_normalize_fal_queue_url_format`, :func:`_extract_http_status`
  10. — small helpers used by both the managed client wrapper and
  11. ``_submit_fal_request``.
  12. Stateful pieces (cache globals, ``_managed_fal_client*`` selectors,
  13. ``_submit_fal_request``) intentionally stay on
  14. :mod:`tools.image_generation_tool`. That module is the patch target for
  15. existing test suites (``tests/tools/test_image_generation.py``,
  16. ``tests/tools/test_managed_media_gateways.py``) and for the
  17. ``plugins/image_gen/fal/`` plugin's ``_it`` indirection — moving the
  18. caches here would silently defeat ``monkeypatch.setattr(image_tool,
  19. "_managed_fal_client", None)`` because the lookups would go against
  20. ``fal_common``'s namespace instead. See the per-rule walkthrough at
  21. issue #26241 for details.
  22. """
  23. from __future__ import annotations
  24. import time
  25. import uuid
  26. from typing import Any, Callable, Dict, Optional, Union
  27. from urllib.parse import urlencode
  28. # A 429 whose Retry-After is longer than this is reported, not waited out inside a tool call.
  29. MANAGED_FAL_RATE_LIMIT_RETRY_CAP_SECONDS = 30.0
  30. # Queue status poll cadence. ``handle.get()`` polls every 0.1 s (+RTT): one 12 s image cost
  31. # ~208 requests/min against the Nous gateway's 200/min window, so a second job 429s. 2 s is
  32. # ~25 requests/min per job (8 concurrent jobs fit) for at most +2 s latency per job.
  33. FAL_QUEUE_POLL_SECONDS = 2.0
  34. def wait_fal_queue_result(handle: Any, *, interval: float = FAL_QUEUE_POLL_SECONDS) -> Any:
  35. """``handle.get()`` without the SDK's 0.1 s status poll: drain ``iter_events`` at ``interval``,
  36. then ``get()`` sees Completed on its first status check and fetches the result."""
  37. for _ in handle.iter_events(with_logs=False, interval=interval):
  38. pass
  39. return handle.get()
  40. def import_fal_client() -> Any:
  41. """Import ``fal_client`` (via ``pm`` when available) and return
  42. the module reference.
  43. Callers cache the result on their own module global so tests can monkeypatch it.
  44. """
  45. try:
  46. from pm import ensure_import as _lazy_ensure
  47. except ImportError:
  48. # pm itself unavailable (externally-managed env, partial install) —
  49. # the plain import below is the authority on availability.
  50. pass
  51. else:
  52. try:
  53. _lazy_ensure("fal")
  54. except ImportError:
  55. pass # same authority rule: let the plain import decide
  56. except Exception as exc:
  57. raise ImportError(str(exc))
  58. import fal_client # type: ignore # noqa: WPS433 — intentionally lazy
  59. return fal_client
  60. def _normalize_fal_queue_url_format(queue_run_origin: str) -> str:
  61. normalized_origin = str(queue_run_origin or "").strip().rstrip("/")
  62. if not normalized_origin:
  63. raise ValueError("Managed FAL queue origin is required")
  64. return f"{normalized_origin}/"
  65. def _extract_http_status(exc: BaseException) -> Optional[int]:
  66. """HTTP status from httpx (``.response.status_code``) or fal_client (``.status_code``) exceptions, else None."""
  67. response = getattr(exc, "response", None)
  68. if response is not None:
  69. status = getattr(response, "status_code", None)
  70. if isinstance(status, int):
  71. return status
  72. status = getattr(exc, "status_code", None)
  73. return status if isinstance(status, int) else None
  74. def _managed_fal_billing_error(exc: BaseException, what: str) -> Optional[str]:
  75. """Human-readable tail for a Nous managed-gateway ``BILLING_ERROR`` response, else None.
  76. ``what`` names the rejected thing ("model", "endpoint"); the wording is shared by the image
  77. and video callers so the two surfaces never drift.
  78. """
  79. response = getattr(exc, "response", None)
  80. if response is None:
  81. return None
  82. try:
  83. payload = response.json()
  84. except Exception:
  85. return None
  86. error = payload.get("error") if isinstance(payload, dict) else None
  87. if not isinstance(error, dict) or error.get("code") != "BILLING_ERROR":
  88. return None
  89. details = error.get("details") if isinstance(error.get("details"), dict) else {}
  90. upstream = details.get("upstreamPayload") if isinstance(details.get("upstreamPayload"), dict) else {}
  91. code = upstream.get("code") or details.get("chargeIntentErrorCode") or "billing_error"
  92. detail = upstream.get("error") or "Nous Portal rejected the charge authorization"
  93. return (
  94. f"{error.get('message') or 'Charge authorization failed'} (BILLING_ERROR; {code}: {detail}). "
  95. "This is a Nous Portal billing configuration issue, not a missing local API key. "
  96. f"The managed route cannot run this {what} until Nous enables its billing meter; "
  97. "a direct FAL_KEY is an optional bypass."
  98. )
  99. def _managed_fal_retry_after_seconds(exc: BaseException) -> Optional[float]:
  100. """Seconds the managed gateway asked us to wait after a 429: the ``Retry-After`` header,
  101. else the body's ``error.retryAfter``; None when the status is not 429 or neither is present."""
  102. response = getattr(exc, "response", None)
  103. if response is None or _extract_http_status(exc) != 429:
  104. return None
  105. headers = getattr(response, "headers", None)
  106. raw = headers.get("Retry-After") if headers is not None and hasattr(headers, "get") else None
  107. if raw is None:
  108. try:
  109. error = response.json().get("error")
  110. except Exception:
  111. return None
  112. raw = error.get("retryAfter") if isinstance(error, dict) else None
  113. try:
  114. return float(raw) if raw is not None else None
  115. except (TypeError, ValueError):
  116. return None
  117. def _managed_fal_rate_limit_message(what: str, name: str, retry_after: Optional[float]) -> str:
  118. hint = f"retry after {retry_after:g}s" if retry_after is not None else "no Retry-After given"
  119. return (
  120. f"Nous Subscription gateway rate-limited {what} '{name}' (HTTP 429; {hint}). "
  121. "The model is enabled — retry later instead of switching models or setting FAL_KEY."
  122. )
  123. def submit_managed_fal_with_rate_limit_retry(
  124. submit: Callable[[dict[str, str]], Any], *, what: str, name: str,
  125. ):
  126. """Call ``submit(headers)`` with a fresh ``x-idempotency-key``; on a 429 whose Retry-After
  127. fits the cap, wait it out (interrupt-aware) and resubmit ONCE under a new key.
  128. A second 429, or one with an unknown/too-long Retry-After, raises ValueError naming the
  129. rate limit — it must never fall through to the callers' "model may not be enabled" 4xx text,
  130. which sends agents off to switch models. Every other exception propagates untouched.
  131. """
  132. from tools.interrupt import is_interrupted
  133. for attempt in (1, 2):
  134. try:
  135. return submit({"x-idempotency-key": str(uuid.uuid4())})
  136. except Exception as exc:
  137. if _extract_http_status(exc) != 429:
  138. raise
  139. retry_after = _managed_fal_retry_after_seconds(exc)
  140. if attempt == 2 or retry_after is None or retry_after > MANAGED_FAL_RATE_LIMIT_RETRY_CAP_SECONDS:
  141. raise ValueError(_managed_fal_rate_limit_message(what, name, retry_after)) from exc
  142. deadline = time.monotonic() + retry_after
  143. while time.monotonic() < deadline:
  144. if is_interrupted():
  145. raise ValueError(_managed_fal_rate_limit_message(what, name, retry_after)) from exc
  146. time.sleep(min(0.5, max(0.0, deadline - time.monotonic())))
  147. def _require(value: Any, what: str) -> Any:
  148. if value is None:
  149. raise RuntimeError(f"{what} is required for managed FAL gateway mode")
  150. return value
  151. class _ManagedFalSyncClient:
  152. """Drives a Nous-managed fal-queue gateway via ``fal_client.SyncClient`` primitives; carries
  153. its own ``fal_client`` reference so the caller decides which (possibly test-patched) module is used."""
  154. def __init__(self, fal_client: Any, *, key: str, queue_run_origin: str):
  155. sync_client_class = _require(getattr(fal_client, "SyncClient", None), "fal_client.SyncClient")
  156. client_module = _require(getattr(fal_client, "client", None), "fal_client.client")
  157. self._queue_url_format = _normalize_fal_queue_url_format(queue_run_origin)
  158. self._sync_client = sync_client_class(key=key)
  159. self._http_client = _require(getattr(self._sync_client, "_client", None), "fal_client.SyncClient._client")
  160. self._maybe_retry_request = getattr(client_module, "_maybe_retry_request", None)
  161. self._raise_for_status = getattr(client_module, "_raise_for_status", None)
  162. if self._maybe_retry_request is None or self._raise_for_status is None:
  163. raise RuntimeError("fal_client.client request helpers are required for managed FAL gateway mode")
  164. self._request_handle_class = _require(
  165. getattr(client_module, "SyncRequestHandle", None), "fal_client.client.SyncRequestHandle")
  166. self._add_hint_header = getattr(client_module, "add_hint_header", None)
  167. self._add_priority_header = getattr(client_module, "add_priority_header", None)
  168. self._add_timeout_header = getattr(client_module, "add_timeout_header", None)
  169. def submit(
  170. self, application: str, arguments: dict[str, Any], *, path: str = "",
  171. hint: Optional[str] = None, webhook_url: Optional[str] = None, priority: Any = None,
  172. headers: Optional[dict[str, str]] = None, start_timeout: Optional[int | float] = None,
  173. ):
  174. url = self._queue_url_format + application
  175. if path:
  176. url += "/" + path.lstrip("/")
  177. if webhook_url is not None:
  178. url += "?" + urlencode({"fal_webhook": webhook_url})
  179. request_headers = dict(headers or {})
  180. if hint is not None and self._add_hint_header is not None:
  181. self._add_hint_header(hint, request_headers)
  182. if priority is not None:
  183. if self._add_priority_header is None:
  184. raise RuntimeError("fal_client.client.add_priority_header is required for priority requests")
  185. self._add_priority_header(priority, request_headers)
  186. if start_timeout is not None:
  187. if self._add_timeout_header is None:
  188. raise RuntimeError("fal_client.client.add_timeout_header is required for timeout requests")
  189. self._add_timeout_header(start_timeout, request_headers)
  190. request_kwargs = {
  191. "json": arguments,
  192. "timeout": getattr(self._sync_client, "default_timeout", 120.0),
  193. "headers": request_headers,
  194. }
  195. # The Nous gateway currently records a keyed submission before billing
  196. # authorization finishes, but cannot replay the resulting error. The
  197. # SDK's automatic 409 retry therefore replaces the real billing error
  198. # with an idempotency conflict. Make one attempt when the caller supplied
  199. # a key; an ambiguous transport failure is safer than a possible duplicate
  200. # generation or a masked entitlement failure.
  201. has_idempotency_key = any(
  202. str(key).lower() == "x-idempotency-key" for key in request_headers
  203. )
  204. if has_idempotency_key:
  205. response = self._http_client.request("POST", url, **request_kwargs)
  206. else:
  207. response = self._maybe_retry_request(self._http_client, "POST", url, **request_kwargs)
  208. self._raise_for_status(response)
  209. data = response.json()
  210. return self._request_handle_class(
  211. request_id=data["request_id"], response_url=data["response_url"],
  212. status_url=data["status_url"], cancel_url=data["cancel_url"], client=self._http_client)