+ lHj/Rt^RIHt^RIt^RIt^RIHtHtHtH t H t ^RI H t Rt RtR]/RR lltR R ltR R ltRRltRRltRRltRRltRRltRRlt!RR4tR#)uShared FAL.ai SDK plumbing: lazy import, managed-gateway sync client, small helpers. Holds the stateless atoms that every FAL-backed tool needs: * :func:`import_fal_client` — lazy import + ``pm.ensure_import`` so ``fal_client`` isn't pulled at cold start (it added ~64 ms per CLI invocation when imported eagerly). * :class:`_ManagedFalSyncClient` — wrapper that drives a Nous-managed fal-queue gateway through the standard ``fal_client.SyncClient`` primitives. * :func:`_normalize_fal_queue_url_format`, :func:`_extract_http_status` — small helpers used by both the managed client wrapper and ``_submit_fal_request``. Stateful pieces (cache globals, ``_managed_fal_client*`` selectors, ``_submit_fal_request``) intentionally stay on :mod:`tools.image_generation_tool`. That module is the patch target for existing test suites (``tests/tools/test_image_generation.py``, ``tests/tools/test_managed_media_gateways.py``) and for the ``plugins/image_gen/fal/`` plugin's ``_it`` indirection — moving the caches here would silently defeat ``monkeypatch.setattr(image_tool, "_managed_fal_client", None)`` because the lookups would go against ``fal_common``'s namespace instead. See the per-rule walkthrough at issue #26241 for details. ) annotationsN)AnyCallableDictOptionalUnion) urlencodeg>@g@intervalc$V^8dQhRRRRRR/#)handlerr floatreturn)formats"5/home/ubuntu/.hermes/hermes-agent/tools/fal_common.py __annotate__r*s"#EWZcVVPRVR7FpK VP4#)z``handle.get()`` without the SDK's 0.1 s status poll: drain ``iter_events`` at ``interval``, then ``get()`` sees Completed on its first status check and fetches the result.F) with_logsr ) iter_eventsget)r r _s&$ rwait_fal_queue_resultr*s.  %(  C D ::<rcV^8dQhRR/#)r rrr)rs"rrr2s3rc^RIHpV!R4^RIpT# \dL\dp\\ T44hRp?ii;i \dLFi;i)zImport ``fal_client`` (via ``pm`` when available) and return the module reference. Callers cache the result on their own module global so tests can monkeypatch it. ) ensure_importfalN)pmr ImportError Exceptionstr fal_client) _lazy_ensureexcr"s rimport_fal_clientr%2sc (4  (        (c#h' ' (    s/A  AAAAA AAc V^8dQhRRRR/#)r queue_run_originr!rr)rs"rrrIs##c#c#rc\T;'gR4P4PR4pV'g \R4hV R2#)/z$Managed FAL queue origin is required)r!striprstrip ValueError)r'normalized_origins& r_normalize_fal_queue_url_formatr/IsG,22399;BB3G ?@@  ""rc V^8dQhRRRR/#)r r$ BaseExceptionrz Optional[int]r)rs"rrrPs77m7 7rc\VRR4pVe&\VRR4p\V\4'dV#\VRR4p\V\4'dV#R#)zjHTTP status from httpx (``.response.status_code``) or fal_client (``.status_code``) exceptions, else None.responseN status_code)getattr isinstanceint)r$r3statuss& r_extract_http_statusr9Ps[sJ-H=$7 fc " "M S- .F,,66$6rc$V^8dQhRRRRRR/#)r r$r1whatr!r Optional[str]r)rs"rrr[s!Mrc\VRR4pVfR#VP4p\T\4'dTP R4MRp\T\4'dTP R4R8wdR#\TP R4\4'dTP R4M/p\TP R4\4'dTP R4M/pTP R4;'gTP R4;'gR pTP R4;'gR pTP R 4;'gR R T RT RT R2# \dR#i;i)zHuman-readable tail for a Nous managed-gateway ``BILLING_ERROR`` response, else None. ``what`` names the rejected thing ("model", "endpoint"); the wording is shared by the image and video callers so the two surfaces never drift. r3Nerrorcode BILLING_ERRORdetailsupstreamPayloadchargeIntentErrorCode billing_errorz-Nous Portal rejected the charge authorizationmessagezCharge authorization failedz (BILLING_ERROR; z: zu). This is a Nous Portal billing configuration issue, not a missing local API key. The managed route cannot run this zN until Nous enables its billing meter; a direct FAL_KEY is an optional bypass.)r5jsonr r6dictr) r$r;r3payloadr>rAupstreamr?details && r_managed_fal_billing_errorrK[sO sJ-H--/%/w$=$=GKK 4E eT " "eii&7?&J&091Et&L&Leii "RTG1;GKKHY retryAfter) r5r9hasattrrrFr r6rGr TypeErrorr-)r$r3rPrawr>s& r _managed_fal_retry_after_secondsrUwssJ-H/4;h 40G(/(;QV@W@W'++m $]aC { MMO''0E*4E4)@)@eii %d _uSz6$6    z "s*B9(C 7C 9 CC C C c(V^8dQhRRRRRRRR/#)r r;r!name retry_afterrMrr)rs"rrrs)#S[^rc4VeRVR R2MRpRV RV RV R2#) Nz retry after gszno Retry-After givenz'Nous Subscription gateway rate-limited z 'z ' (HTTP 429; uW). The model is enabled — retry later instead of switching models or setting FAL_KEY.r)r;rWrXhints&&& r_managed_fal_rate_limit_messager]s?.9.E\+a *KaD 1$r$}TFS_ _rc$V^8dQhRRRRRR/#)r submitzCallable[[dict[str, str]], Any]r;r!rWr)rs"rrrs)LL +L69LADLrc t^RIHpRF*pV!R\\P!44/4u# R# \ dp\ T4R8wdh\T4pT^8XgTe T\8d\\YT44Th\P!4T,p\P!4T8djT!4'd\\YT44Th\P!\R\RT\P!4, 444KRp?EK)Rp?ii;i)uCall ``submit(headers)`` with a fresh ``x-idempotency-key``; on a 429 whose Retry-After fits the cap, wait it out (interrupt-aware) and resubmit ONCE under a new key. A second 429, or one with an unknown/too-long Retry-After, raises ValueError naming the rate limit — it must never fall through to the callers' "model may not be enabled" 4xx text, which sends agents off to switch models. Every other exception propagates untouched. )is_interruptedx-idempotency-keyrONg?g)r )tools.interruptrar!uuiduuid4r r9rU(MANAGED_FAL_RATE_LIMIT_RETRY_CAP_SECONDSr-r]time monotonicsleepminmax)r_r;rWraattemptr$rXdeadlines&$$ r(submit_managed_fal_with_rate_limit_retryros/ L.DJJL0ABC C L#C(C/:3?K!|{2kDl6l !@[!YZ`cc~~'+5H.."X-!##$%DTQ\%]^dgg 3sCX8H-H$IJK. Ls%9 D7B D2AD22D7c$V^8dQhRRRRRR/#)r valuerr;r!rr)rs"rrrs!Cssrc*Vf\V R24hV#)Nz) is required for managed FAL gateway mode) RuntimeError)rqr;s&&r_requirerts }dV#LMNN Lrc N]tRt^tRtRRltRRRRRRR RR RR R/R R lltRtR#)_ManagedFalSyncClientzDrives a Nous-managed fal-queue gateway via ``fal_client.SyncClient`` primitives; carries its own ``fal_client`` reference so the caller decides which (possibly test-patched) module is used.c$V^8dQhRRRRRR/#)r r"rkeyr!r'r)rs"rr"_ManagedFalSyncClient.__annotate__s&VV3VVsVrc $\\VRR4R4p\\VRR4R4p\V4VnV!VR7Vn\\VPRR4R4Vn\VRR4Vn\VR R4VnVP eVPf \R 4h\\VR R4R 4Vn \VR R4Vn \VRR4Vn \VRR4Vn R#) SyncClientNzfal_client.SyncClientclientzfal_client.client)rx_clientzfal_client.SyncClient._client_maybe_retry_request_raise_for_statuszKfal_client.client request helpers are required for managed FAL gateway modeSyncRequestHandlez#fal_client.client.SyncRequestHandleadd_hint_headeradd_priority_headeradd_timeout_header) rtr5r/_queue_url_format _sync_client _http_clientr~rrs_request_handle_class_add_hint_header_add_priority_header_add_timeout_header)selfr"rxr'sync_client_class client_modules&&$$ r__init___ManagedFalSyncClient.__init__s$WZt%LNef Xt!DFYZ !@AQ!R-#6$WT->-> 4%PRqr$+M;QSW$X!!(8KT!R  $ $ ,0F0F0Nlm m%- M#6 =?d&f" ' 7H$ O$+M;PRV$W!#*=:NPT#U rpathr)r\N webhook_urlpriorityrP start_timeoutc8V^8dQhRRRRRRRRRRR R R R R R/#)r applicationr! argumentszdict[str, Any]rr\r<rrrrPzOptional[dict[str, str]]rzOptional[int | float]r)rs"rrrys\+d+d+d+9+dDG+d+d1>+dQT+d*+dBW+drc VPV,p V'd V RVPR4,, p VeV R\RV/4,, p \T;'g/4p Ve VPeVP WJ4Ve+VP f \ R4hVP Wj4Ve+VPf \ R4hVPW4RVR\VPRR4R V /p \;QJdR V 4F 'gK R M R M !R V 44p V 'd VPP!R V 3/V Bp MVP!VPR V 3/V Bp VPV 4V P4pVP!VR,VR,VR,VR,VPR7#)r*? fal_webhookzGfal_client.client.add_priority_header is required for priority requestszEfal_client.client.add_timeout_header is required for timeout requestsrFtimeoutdefault_timeoutg^@rPc3Z"TF!p\V4P4R8HxK# R#5i)rbN)r!lower).0rxs& r /_ManagedFalSyncClient.submit..s$" ?NCHNN  3 3s)+TFPOST request_id response_url status_url cancel_url)rrrrr|)rlstriprrGrrrsrr5ranyrrequestr~rrFr)rrrrr\rrrPrurlrequest_headersrequest_kwargshas_idempotency_keyr3datas&&&$$$$$$ rr__ManagedFalSyncClient.submits $${2  3S)) )C  " 3M;#?@@ @Cw}}"-   5 5 A  ! !$ 8  ((0"#lmm  % %h @  $''/"#jkk  $ $] D I wt002CUK  "c" ?N" ccc" ?N"   ((00OOH001B1BFCbSabH x(}}))L)^8LL)d<6HQUQbQb*d dr) rrrrr~rrrr)__name__ __module__ __qualname____firstlineno____doc__rr___static_attributes__rrrrvrvsVlV +dJL+d"+dAE+dW[+d-1+dZ^+d+drrv)r __future__rrhretypingrrrrr urllib.parserrgFAL_QUEUE_POLL_SECONDSrr%r/r9rKrUr]rortrvrrrrsp4# 77",0(