PL jUdZddlZddlZddlZddlZddlZddlZddlmZm Z m Z m Z ddl m Z daeed<defdZddlmZdd lmZdd lmZmZmZejeZd d d ddddddddddhddd dddddddddddd ddd!d"d#hd$d"d d%d&d'd(dddddd)d dddd*hd+dd d,d-d.d/d0d1d2d3dd dd!d4d5hd6dd d7d8d9d:d;ddd?d dd@hdAdd dBdCdDdEddFddGdd?d dd@hdHdd dIdJdKdLddddddMd"dNdOhdPdd dQd-dRdSddddddTdihdUdd dVdWdXdYddddddZd[d dd\d]hd^dd d_ Ze ee eeffed`<daZdbZdZ dcZ!ddZ"dZ#deZ$dfZ%dgZ&dhZ'dZ(diZ)edjdklZ*da+da,ej-Z.dmZ/dnedefdoZ0GdpdqZ1drZ2dsedte eeffduZ3dve4de e5fdwZ6de7fdxZ8eddfdyedzed0ed{e e5d|e e eefde eeff d}Z9d~edede e eeffdZ:edddddfdzed0ede e5de e;de e5de ed{e e5defdZdefdZ?de=fdZ@edkreAdeAde>s,eAdeAdeAdeBd eAd ddlaeAdn#eC$reAdeBd wxYwe8\ZDZEeAdeEFdeDdeDdeAdeEFdddeEFddeAdeEFdrdndeAdeGD]O\ZHZIeHeDkrdndZJeAdeHddeIFddddeIFddeJPe*jKreAde*jLddlMmNZNmOZOdddddddePe dedddzgddZQdZRdZSdzed0efdZTdZUeNjVddeQeUe@gdddS)u Image Generation Tools Module Provides image generation via FAL.ai. Multiple FAL models are supported and selectable via ``hermes tools`` → Image Generation; the active model is persisted to ``image_gen.model`` in ``config.yaml``. Architecture: - ``FAL_MODELS`` is a catalog of supported models with per-model metadata (size-style family, defaults, ``supports`` whitelist, upscaler flag). - ``_build_fal_payload()`` translates the agent's unified inputs (prompt + aspect_ratio) into the model-specific payload and filters to the ``supports`` whitelist so models never receive rejected keys. - Upscaling via FAL's Clarity Upscaler is gated per-model via the ``upscale`` flag — on for FLUX 2 Pro (backward-compat), off for all faster/newer models where upscaling would either hurt latency or add marginal quality. Pricing shown in UI strings is as-of the initial commit; we accept drift and update when it's noticed. N)AnyDictOptionalUnion) urlencode fal_clientreturncttS ddlm}|ddn9#t$rYn-t$r!}tt |d}~wwxYwddl}|atS)u'Lazily import fal_client and rebind the module global on first use. Idempotent. Returns the (now-loaded) ``fal_client`` module reference. Skips the import if the global is already truthy — this preserves the test pattern of monkeypatching the module global to install a mock. Nr)ensurez image.falF)prompt)rtools.lazy_depsr ImportError Exceptionstr) _lazy_ensuree _fal_clients ?/home/kuhnn/.hermes/hermes-agent/tools/image_generation_tool.py_load_fal_clientr-s":::::: [/////      """#a&&!!!"$$$$J s$ A AAA) DebugSession)resolve_managed_tool_gateway)fal_key_is_configuredmanaged_nous_tools_enabledprefers_gatewayzFLUX 2 Klein 9Bz<1szFast, crisp textz $0.006/MPimage_size_presetlandscape_16_9 square_hd portrait_16_9) landscapesquareportraitpngF)num_inference_steps output_formatenable_safety_checker>seedr image_sizer%r$r&) displayspeed strengthsprice size_stylesizesdefaultssupportsupscalez FLUX 2 Proz~6szStudio photorealismz$0.03/MP2g@5T)r$guidance_scale num_imagesr%r&safety_tolerance sync_mode> r'r r8r(r6r%r5r7r$r&z Z-Image Turboz~2szBilingual EN/CN, 6Bz $0.005/MP)r$r6r%r&enable_prompt_expansion>r'r r(r6r%r$r&r:z$Nano Banana Pro (Gemini 3 Pro Image)z~8sz-Gemini 3 Pro, reasoning depth, text renderingz$0.15/image (1K) aspect_ratioz16:9z1:1z9:161K)r6r%r7 resolution> r'r r8r6r=r;r%r7enable_web_searchlimit_generationsz GPT Image 1.5z~15szPrompt adherencez $0.034/image gpt_literal 1536x1024 1024x1024 1024x1536medium)qualityr6r%>r rEr8 backgroundr(r6r%z GPT Image 2z~20sz3SOTA text rendering + CJK, world-aware photorealismu$0.04–0.06/image landscape_4_3 portrait_4_3>r rEr8r(r6r%z Ideogram V3z~5szBest typographyz$0.03-0.09/imageBALANCEDAUTO)rendering_speed expand_promptstyle>r'rMr r(rLrKzRecraft V4 Proz'Design, brand systems, production-readyz $0.25/imager&>colorsr r(background_colorr&z Qwen Imagez~12szLLM-based, complex textz$0.02/MPg@regular)r$r5r6r% acceleration> r'r r8r(r6rRr%r5r$) fal-ai/flux-2/klein/9bzfal-ai/flux-2-prozfal-ai/z-image/turbozfal-ai/nano-banana-prozfal-ai/gpt-image-1.5zfal-ai/gpt-image-2zfal-ai/ideogram/v3z#fal-ai/recraft/v4/pro/text-to-imagezfal-ai/qwen-image FAL_MODELSrSrzfal-ai/clarity-upscalerz"masterpiece, best quality, highresz.(worst quality, low quality, normal quality:2)gffffff?g333333? image_toolsIMAGE_TOOLS_DEBUG)env_varc^trtdsdStdS)zsReturn managed fal-queue gateway config when the user prefers the gateway or direct FAL credentials are absent. image_genNz fal-queue)rrrr_resolve_managed_fal_gatewayr^cs4{'C'Ct ' 4 44r]queue_run_originct|pdd}|std|dS)N/z$Managed FAL queue origin is required)rstriprstrip ValueError)r_normalized_origins r_normalize_fal_queue_url_formatrgksW,23399;;BB3GG A?@@@ " " ""r]ceZdZdZdedefdZdddddddded eeefd ed eed eed edeeeefdee e e ffdZ dS)_ManagedFalSyncClientzPSmall per-instance wrapper around fal_client.SyncClient for managed queue hosts.keyr_ctttdd}|tdttdd}|tdt ||_|||_t|jdd|_t|dd|_t|dd|_ t|d d|_ t|d d|_ t|d d|_ t|d d|_ |jtd |j|j td|j tddS)N SyncClientz>fal_client.SyncClient is required for managed FAL gateway modeclientz:fal_client.client is required for managed FAL gateway mode)rj_client_maybe_retry_request_raise_for_statusSyncRequestHandleadd_hint_headeradd_priority_headeradd_timeout_headerzFfal_client.SyncClient._client is required for managed FAL gateway modezKfal_client.client request helpers are required for managed FAL gateway modezLfal_client.client.SyncRequestHandle is required for managed FAL gateway mode)rgetattrr RuntimeErrorrg_queue_url_format _sync_client _http_clientrorp_request_handle_class_add_hint_header_add_priority_header_add_timeout_header)selfrjr_sync_client_class client_modules r__init__z_ManagedFalSyncClient.__init__usu #J dCC  $_`` ` Hd;;  [\\ \!@AQ!R!R--#666#D$5y$GG$+M;QSW$X$X!!(8KT!R!R%,]/  / sm / c]/ / $sCx.)/  c5j 12/ / / / / / r]ric|jd|jf}t5tt |krtcdddSt |j|ja|atcdddS#1swxYwYdS)zQReuse the managed FAL client so its internal httpx.Client is not leaked per call.rbN)rjr_)gateway_originrdnous_user_token_managed_fal_client_lock_managed_fal_client_managed_fal_client_configri)managed_gateway client_configs r_get_managed_fal_clientrs &--c22'M " # #  */I]/Z/Z& # # # # # # # #4/,;   &3"" # # # # # # # # # # # # # # # # # #sA?#A??BBmodelrctdttji}t }|t j|||St|} ||||S#t$r>}t|}|'d|cxkrdkrnntd|d|d|d}~wwxYw) zKSubmit a FAL request using direct credentials or the managed queue gateway.zx-idempotency-keyN)rriiz*Nous Subscription gateway rejected model 'z' (HTTP u). This model may not yet be enabled on the Nous Portal's FAL proxy. Either: • Set FAL_KEY in your environment to use FAL.ai directly, or • Pick a different model via `hermes tools` → Image Generation.) rruuiduuid4r^rrrr_extract_http_statusre)rrrrmanaged_clientexcstatuss r_submit_fal_requestrs%*C ,=,=>O244O )_UUUU,_==N$$ #%    &c**  #"5"5"5"5#"5"5"5"5"5YUYYYYY    s(B C 9CCrct|dd}|(t|dd}t|tr|St|dd}t|tr|SdS)uReturn an HTTP status code from httpx/fal exceptions, else None. Defensive across exception shapes — httpx.HTTPStatusError exposes ``.response.status_code`` while fal_client wrappers may expose ``.status_code`` directly. rN status_code)ru isinstancer)rrrs rrrspsJ--H=$77 fc " " M S- . .F&# 4r]cd} ddlm}|}t|tr|dnd}t|tr>|d}t|t r|}n2#t$r%}t d|Yd}~nd}~wwxYw|s'tj dd}|stttfS|tvr:td |ttttfS|t|fS) zResolve the active FAL model from config.yaml (primary) or default. Returns (model_id, metadata_dict). Falls back to DEFAULT_MODEL if the configured model is unknown (logged as a warning). rar load_configr[Nrz.Could not load image_gen.model from config: %sFAL_IMAGE_MODELz4Unknown FAL model '%s' in config; falling back to %s)hermes_cli.configrrrgetrrcrloggerdebugosgetenv DEFAULT_MODELrTwarning)model_idrcfgimg_cfgrawrs r_resolve_fal_modelrsf H L111111kmm*4S$*?*?I#''+&&&T gt $ $ '++g&&C#s## '99;; LLL EsKKKKKKKKL <9.3399;; 8j777z!! B m   j777 Z) ))sBB CB>>Crr r' overridesc\ t|}|d}|d}|pt}||vrt}t |di} |pd| d<|dvr ||| d<n$|dkr ||| d<nt d ||t|tr|| d <|r!| D] \} } | | | | < |d  fd | DS)a)Build a FAL request payload for `model_id` from unified inputs. Translates aspect_ratio into the model's native size spec (preset enum, aspect-ratio enum, or GPT literal string), merges model defaults, applies caller overrides, then filters to the model's ``supports`` whitelist. r-r.r/rar >r@rr(r;zUnknown size_style: Nr'r0c$i|] \}}|v || Sr\r\).0kvr0s r z&_build_fal_payload..Ys$ > > >TQX Aq r]) rTDEFAULT_ASPECT_RATIOlowerrcrrrerritems) rr r;r'rmetar-r.aspectpayloadrrr0s @r_build_fal_payloadr1sX h Dl#J ME22 9 9 ; ; A A C CF U%"488J#;#;< >>??? JtS11OO%%  DAq} JH > > > >W]]__ > > >>r] image_urloriginal_promptc  td|td|ttt t tttd }tt|}| }|rd|vr|d}td| dd| d d|d | dd | d d d td St ddS#t$r(}t d|d Yd}~dSd}~wwxYw)zUpscale an image using FAL.ai's Clarity Upscaler. Returns upscaled image dict, or None on failure (caller falls back to the original image). z(Upscaling image with Clarity Upscaler...z, ) rr upscale_factornegative_prompt creativity resemblancer5r$r&rimagez$Image upscaled successfully to %sx%swidthunknownheightrrT)rrrupscaledrz"Upscaler returned invalid responseNzError upscaling image: %sexc_info)rinfoUPSCALER_DEFAULT_PROMPTUPSCALER_FACTORUPSCALER_NEGATIVE_PROMPTUPSCALER_CREATIVITYUPSCALER_RESEMBLANCEUPSCALER_GUIDANCE_SCALEUPSCALER_NUM_INFERENCE_STEPSUPSCALER_SAFETY_CHECKERrUPSCALER_MODELrerrorr)rrupscaler_argumentshandlerresultupscaled_imagers r_upscale_imager_sr % >???#0EEOEE-7-/5#?%<   &n@RSSS  g''#G_N KK6""7I66""8Y77    &e,'++GQ77(,,Xq99 "1    9:::t  0!d CCCtttttsD D( D(( E2EEr$r5r6r%c  t\}}||||||||dddddd} tj} |r:t|tr%t |dkrtdts)tstt|pt } | tvr(td|tt} i} ||| d<||| d <||| d <||| d <t!||| || } td |d|||ddt'|| }|}tj| z }|rd|vrtd|dg}|stdt+|dd}g}|D]}t|t,rd|vs|d|dd|ddd}|rZt/|d|}|r||tdd|d<|||stdt3d|D}tdt ||||d|r|ddndd}d| d <t || d!<|| d"<t4d#| t4t;j|d$d%S#t>$r}tj| z }d&t |}t d'|d(ddt |tC|j"d)}|| d*<|| d"<t4d#| t4t;j|d$d%cYd}~Sd}~wwxYw)+aGenerate an image from a text prompt using the configured FAL model. The agent-facing schema exposes only ``prompt`` and ``aspect_ratio``; the remaining kwargs are overrides for direct Python callers and are filtered per-model via the ``supports`` whitelist (unsupported overrides are silently dropped so legacy callers don't break when switching models). Returns a JSON string with ``{"success": bool, "image": url | None, "error": str, "error_type": str}``. )r r;r$r5r6r%r'NFr)r parametersrsuccessimages_generatedgeneration_timez1Prompt is required and must be a non-empty stringz-Invalid aspect_ratio '%s', defaulting to '%s'r$r5r6r%)r'ru,Generating image with %s (%s) — prompt: %sr)Primagesu7Invalid response from FAL.ai API — no images returnedzNo images were generatedr1rrr)rrrz1Using original image as fallback (upscale failed)rz%No valid image URLs returned from APIc3DK|]}|ddVdS)rr3N)r)rimgs r z&image_generate_tool..s3RR3cggj>Q>QRQRRRRRRr]z3Generated %s image(s) in %.1fs (%s upscaled) via %sT)rrrrrimage_generate_toolrU)indent ensure_asciizError generating image: z%srrrr error_typer)#rdatetimenowrrlenrcrerr^_build_no_backend_setup_messagerrVALID_ASPECT_RATIOSrrrrrr total_secondsboolrrappendsum_debuglog_callsaverdumpsrrtyper)r r;r$r5r6r%r'rrdebug_call_data start_time aspect_lcrrrrrrshould_upscaleformatted_imagesroriginal_imagerupscaled_count response_datar error_msgs rrrsM&())NHd(#6,$*  O""&&((JkG RZ44 RFLLNN8K8Kq8P8PPQQ Q%'' @+G+I+I @<>>?? ?!9%9@@BBHHJJ / / / NN?2   -I$&  */BI+ ,  %*8I& '  !&0Il #  $)6Io && fidi     : HHY ) )8VCRC[   &h)DDD#,0022Z?NNPP X//VWW WHb)) 9788 8dhhy%8899 4 4CsD)) esll5z!,,''(A..N  T!/E FLLNN!K!K!$++N;;;RSSS).N: &  # #N 3 3 3 3 FDEE ERR*:RRRRR A  ! !?NH   3CM%a(//  &* ".12B.C.C*+-<)*-??? z-FFFF GGG#,0022Z?NNPP7s1vv77  T9t 444VVq''*   $- -<)*-??? z-FFFFFFFFF#Gs NO S*CS S ScTttp tS)zDTrue if the FAL.ai API key (direct or managed gateway) is available.)r rr^r\r]rcheck_fal_api_keyr&s# %''I+G+I+I J JJr]cddg}|dtr|dn|d|d|d|dtr|d|d d |S) aRBuild an actionable error string when no FAL backend is reachable. Used by the in-tree FAL path. Mentions: - FAL_KEY signup link - managed-gateway status (if Nous tools are enabled) - plugin alternative pointer (so users on a stale ``image_gen.provider`` know the registry exists and how to inspect it) z4Image generation is unavailable in this environment.razMissing requirements:zA - FAL_KEY is not set and the managed FAL gateway is unreachablez+ - FAL_KEY environment variable is not setz&To enable image generation, do one of:z_ 1. Get a free API key at https://fal.ai and set FAL_KEY= (then restart the session)zX 2. Sign in to a Nous account that has the managed FAL gateway enabled (`hermes setup`)u 3. Configure a different image_gen provider via `hermes tools` → Image Generation (run `hermes plugins list` to see installed backends) )r rjoin)liness rrr+sDR HE LL()))!##D O      BCCC LL LL9::: LL 8"##   /    LL  99U  r]c  trtdSn#t$rYnwxYw ddlm}ddlm}||D]*} |rdS#t$rY'wxYwn#t$rYnwxYwdS)aTrue if any image gen backend is available. Providers are considered in this order: 1. The in-tree FAL backend (FAL_KEY or managed gateway). 2. Any plugin-registered provider whose ``is_available()`` returns True. Plugins win only when the in-tree FAL path is NOT ready, which matches the historical behavior: shipping hermes with a FAL key configured should still expose the tool. The active selection among ready providers is resolved per-call by ``image_gen.provider``. Tr)list_providers_ensure_plugins_discoveredF) rrragent.image_gen_registryr"hermes_cli.pluginsr$ is_availabler)r"r$providers r#check_image_generation_requirementsr)Os         4          ;;;;;;AAAAAA""$$$&((  H ((** 44              5sG! .."A>A-)A>,A>- A:7A>9A::A>> B  B __main__u:🎨 Image Generation Tools — FAL.ai multi-model supportz<============================================================u(❌ FAL_KEY environment variable not setz- Set it via: export FAL_KEY='your-key-here'z Get a key: https://fal.ai/u✅ FAL.ai API key foundu ✅ fal_client library availableu;❌ fal_client library not found — pip install fal-clientu🤖 Active model: r)z ()z Speed: r*ru · Price: r,z Upscaler: r1onoffz Available models:u ← activeraz z<32z<6u% 🐛 Debug mode enabled — session )registry tool_errorimage_generatea3Generate high-quality images from text prompts. The underlying backend (FAL, OpenAI, etc.) and model are user-configured and not selectable by the agent. Returns either a URL or an absolute file path in the `image` field; display it with markdown ![description](url-or-path) and the gateway will deliver it.objectstringzJThe text prompt describing the desired image. Be detailed and descriptive.)r descriptionzlThe aspect ratio of the generated image. 'landscape' is 16:9 wide, 'portrait' is 16:9 tall, 'square' is 1:1.)renumr3defaultr r;)r propertiesrequired)namer3rc ddlm}|}t|tr|dnd}t|trR|d}t|t r(|r|Sn2#t$r%}t d|Yd}~nd}~wwxYwdS)zBReturn the value of ``image_gen.model`` from config.yaml, or None.rrr[Nrz"Could not read image_gen.model: %s rrrrrrrcrrrrrsectionvaluers r_read_configured_image_modelr?s @111111kmm*4S$*?*?I#''+&&&T gt $ $ %KK((E%%% %%++-- %{{}}$ @@@ 93????????@ 4B"B&& C0CCc ddlm}|}t|tr|dnd}t|trR|d}t|t r(|r|Sn2#t$r%}t d|Yd}~nd}~wwxYwdS)uiReturn the value of ``image_gen.provider`` from config.yaml, or None. We only consult the plugin registry when this is explicitly set — an unset value keeps users on the legacy in-tree FAL path even when other providers happen to be registered (e.g. a user has OPENAI_API_KEY set for other features but never asked for OpenAI image gen). rrr[Nr(z%Could not read image_gen.provider: %sr;r<s r_read_configured_image_providerrBs C111111kmm*4S$*?*?I#''+&&&T gt $ $ %KK ++E%%% %%++-- %{{}}$ CCC rqs *   ------------"""""" C#,-,,,,,CCCCCC  8 $ $4%'))!'  $%"%*     ). *))!'  $&!"%* #     38#*))!'  $%"%*',      /4:D#$  " #      16#'#$!#   "      -2!J% *(!&   "      =B!&#))!'  *!     ).$>))!'   $U    ',,, .))!'  $&!"%      -Q`)`) Dd38n$ %```F) "9 +>K! m-@ A A A!)9>++ 555#c#c####O O O O O O O O d###(stCH~Bm * *E * * * *L-*. (?(?(? (?(? 3- (? S#X' (?  #s(^ (?(?(?(?\+c+C+HT#s(^>> -...jmm E $%%% 01111  KLLLjmm('))NHd E LH = = L L L L LMMM E Ttxx-- T TDHHWc