L0&j UdZddlZddlZddlZddlZddlZddlZddlmZm Z m Z da ee d<defdZ ddlmZddlmZmZmZdd lmZdd lmZmZmZmZejeZd 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_d`dadbd0d1d2d3ddcd?ihdddd dedfdgdhd0d1d2d3ddcd?ihdddd di Ze ee eeffe dj<dkZ dlZ!dZ"dmZ#dnZ$dZ%doZ&dpZ'dqZ(drZ)dZ*dsZ+edtduvZ,da-da.ej/Z0dwZ1dxZ2dyedze eeffd{Z3de4fd|Z5e!ddfd}ed~ed0ede e6de e eefde eeff dZ7dedede e eeffdZ8dede9fdZ:dedzfdZ;dededzfdZddededzdefdZ?e!dddddfd~ed0ede e6de e@de e6de ede e6defdZAde9fdZBdefdZCde9fdZDedkreEdeEdeBs,eEdeEdeEdeFd eEd ddl a eEdn#eG$reEdeFd wxYwe5\ZHZIeEdeIJdeHdeHdeEdeIJdddeIJddeEdeIJdrdndeEdeKD]O\ZLZMeLeHkrdndZNeEdeLddeMJddddeMJddeNPe,jOreEde,jPddlQmRZRmSZSdddddddeTe"de!ddd~gddZUdZVd„ZWd~ed0efdÄZXdĄZYeRjZddeUeYeDgddƬǦdS)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)AnyDictOptional fal_clientreturncLttSddlm}|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. Nrimport_fal_client)rtools.fal_commonr r s @/home/ubuntu/.hermes/hermes-agent/tools/image_generation_tool.py_load_fal_clientr ,s6222222""$$J ) DebugSession)_ManagedFalSyncClient_extract_http_status_normalize_fal_queue_url_format)resolve_managed_tool_gateway)fal_key_is_configuredmanaged_nous_tools_enabled%nous_tool_gateway_unavailable_messageprefers_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>seedprompt 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%r6r&r4r"r3r5r!r#z Z-Image Turboz~2szBilingual EN/CN, 6Bz $0.005/MP)r!r4r"r#enable_prompt_expansion>r$r%r&r4r"r!r#r8z$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)r4r"r5 resolution> r$r%r6r4r;r9r"r5enable_web_searchlimit_generationsz GPT Image 1.5z~15szPrompt adherencez $0.034/image gpt_literal 1536x1024 1024x1024 1024x1536medium)qualityr4r">r%rCr6 backgroundr&r4r"z GPT Image 2z~20sz3SOTA text rendering + CJK, world-aware photorealismu$0.04–0.06/image landscape_4_3 portrait_4_3>r%rCr6r&r4r"z Ideogram V3z~5szBest typographyz$0.03-0.09/imageBALANCEDAUTO)rendering_speed expand_promptstyle>r$rKr%r&rJrIzRecraft 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!r3r4r" acceleration> r$r%r6r&r4rPr"r3r!z Krea 2 Mediumz~15-25sz9Illustration, anime, painting, expressive/artistic stylesz#$0.030 (text) / $0.035 (style refs) creativity>r$r%rQr9image_style_referencesz Krea 2 Largez~25-60sz;Photorealism, raw textured looks (motion blur, grain, film)z#$0.060 (text) / $0.065 (style refs)) 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-imagez#fal-ai/krea/v2/medium/text-to-imagez"fal-ai/krea/v2/large/text-to-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)rrrrr _resolve_managed_fal_gatewayr]s4{'C'Ct ' 4 44rc@|jd|jf}t5tt |krtcdddSt tt|j|ja|atcdddS#1swxYwYdS)zQReuse the managed FAL client so its internal httpx.Client is not leaked per call./N)keyqueue_run_origin) gateway_originrstripnous_user_token_managed_fal_client_lock_managed_fal_client_managed_fal_client_configr rr)managed_gateway client_configs r _get_managed_fal_clientrjs  &--c22'M " # #  */I]/Z/Z& # # # # # # # # 3 /,;    &3"" # # # # # # # # # # # # # # # # # #sB7BBBmodel argumentsc tdttji}t }|t j|||St|} ||||S#t$rZ}t|}|Cd|cxkrdkr6nn3d}|dvrdtd d z}td |d |d||d}~wwxYw)zKSubmit a FAL request using direct credentials or the managed queue gateway.zx-idempotency-keyN)rlheadersii>z managed FAL image generationT) force_freshz*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.) r struuiduuid4r]rsubmitrj Exceptionrr ValueError)rkrlrequest_headersrhmanaged_clientexcstatusgateway_messages r _submit_fal_requestrs`*C ,=,=>O244O )_UUUU,_==N$$ #%    &c**  #"5"5"5"5#"5"5"5"5"5 O((;6$( %U%%%% # %%  1s(B C$ ACC$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). ror load_configr[Nrkz.Could not load image_gen.model from config: %sFAL_IMAGE_MODELz4Unknown FAL model '%s' in config; falling back to %s)hermes_cli.configr isinstancedictgetrustripryloggerdebugosgetenv DEFAULT_MODELrTwarning)model_idrcfgimg_cfgrawr}s 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-ror%>r>rr&r9zUnknown size_style: Nr$r.c$i|] \}}|v || Sr\r\).0kvr.s r z&_build_fal_payload..*s$ > > >TQX Aq r) rTDEFAULT_ASPECT_RATIOlowerrrrrzrintitems) rr%r9r$rmetar+r,aspectpayloadrrr.s @r _build_fal_payloadrsX 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_promptrQ resemblancer3r!r#rlimagez$Image upscaled successfully to %sx%swidthunknownheighturlrT)rrrupscaledrz"Upscaler returned invalid responseNzError upscaling image: %sexc_info)rinfoUPSCALER_DEFAULT_PROMPTUPSCALER_FACTORUPSCALER_NEGATIVE_PROMPTUPSCALER_CREATIVITYUPSCALER_RESEMBLANCEUPSCALER_GUIDANCE_SCALEUPSCALER_NUM_INFERENCE_STEPSUPSCALER_SAFETY_CHECKERrUPSCALER_MODELrerrorry)rrupscaler_argumentshandlerresultupscaled_imagees r _upscale_imager0sr % >???#0EEOEE-7-/5#?%<   &n@RSSS  g''#G_N KK6""7I66""8Y77    &e,'++GQ77(,,Xq99 "1    9:::t  0!d CCCtttttsD D( D(( E2EEvaluec|rt|tsdS|}|drdStj|rdSt|dko|ddko |ddvS) NF)zhttp://zhttps://zdata:Tr1:rU>r_\)rrur startswithrpathisabslen)rrs r _looks_like_absolute_file_pathras  5#..u KKMME 899u w}}Ut u::? JuQx3 J58{3JJrtask_idc ddlm}||pdS#t$r&}td|Yd}~dSd}~wwxYw)Nr)get_active_envdefaultz1Could not inspect active terminal environment: %s)tools.terminal_toolrryrr)rrr}s r _active_terminal_envrlso666666~g2333  H#NNNttttts AAAenvc2|t|dd}t|rb |}|r"t|dSn2#t$r%}t d|Yd}~nd}~wwxYwt|dd}|r%t|ddS|jj}|dvrdStj dpd }|d vrdS|d krd SdS) Nagent_visible_cache_baser_z.active env agent_visible_cache_base failed: %s _remote_homez/.hermes>ModalEnvironmentDockerEnvironmentSingularityEnvironmentz /root/.hermes TERMINAL_ENVlocal>modaldocker singularitysshz ~/.hermes) getattrcallablerurcryrr __class____name__rrrr)rexplicitrr} remote_homeenv_namebackends r _agent_cache_base_for_envrvsZ  3 :DAA H   T T  2u::,,S1112 T T T MsSSSSSSSS Tc>488  =+&&--c22<<< <=) Z Z Z"? y((3G::<<BBDDG444%{ 4s-A BA==B host_pathct|sdSt|}|sdS ddlm}|||S#t$r%}t d|Yd}~nd}~wwxYwdS)Nr)map_cache_path_to_container)container_basez4Could not translate image cache path for backend: %s)rrtools.credential_filesrryrr)rr cache_baserr}s r _agent_visible_cache_pathrs )) 4 4t*3//J tRFFFFFF**9ZPPPP RRR KSQQQQQQQQR 4s9 A(A##A(ct|dd}|dS |ddS#t$r&}td|Yd}~dSd}~wwxYw)N _sync_managerTforcez1Could not force-sync generated image artifact: %s)rsyncryrr)r sync_managerr}s r _force_artifact_syncrs366LQ%%%%% QQQJCPPPPPPPPPQs/ AAArcF t|trtj|n|}n#t$r|cYSwxYwt|t r|ds|S|d}t|trt|s|St|}t||}|r||kr|S|t|| d|| d|tj |dS)aAnnotate successful local image results with backend-visible paths. ``image`` remains the host/gateway-deliverable path. When the active terminal backend has a different filesystem, ``agent_visible_image`` gives the path the agent can use with terminal/file tools. successrN host_imageagent_visible_imageF) ensure_ascii) rrujsonloadsryrrrrrr setdefaultdumps)rrrrr agent_paths r "_postprocess_image_generate_resultrs9%/S%9%9B$*S///s   gt $ $GKK ,B,B KK E eS ! !)G)N)N w ' 'C*5#66J u,,  S!!! |U+++ ,j999 :gE 2 2 22s +. ==r!r3r4r"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%r9r!r3r4r"r$NFr)rk parametersrrimages_generatedgeneration_timez1Prompt is required and must be a non-empty stringz-Invalid aspect_ratio '%s', defaulting to '%s'r!r3r4r")r$ru,Generating image with %s (%s) — prompt: %sr'Primagesu7Invalid response from FAL.ai API — no images returnedzNo images were generatedr/rrr)rrrz1Using original image as fallback (upscale failed)rz%No valid image URLs returned from APIc3DK|]}|ddVdS)rr1N)r)rimgs r z&image_generate_tool..Cs3RR3cggj>Q>QRQRRRRRRrz3Generated %s image(s) in %.1fs (%s upscaled) via %sT)rrrrrimage_generate_toolrU)indentrzError generating image: z%srrrr error_typer)#rdatetimenowrrurrrzrr]_build_no_backend_setup_messagerrVALID_ASPECT_RATIOSrrrrrr total_secondsboolrrappendsum_debuglog_callsaverrryrtyper)r%r9r!r3r4r"r$rrdebug_call_data start_time aspect_lcrrlrrrrshould_upscaleformatted_imagesr original_imagerupscaled_count response_datar error_msgs r r r sM&())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.)rrr]r\rr check_fal_api_keyr&js# %''I+G+I+I J JJrcddg}|dtr|dn>|dtd}|r|d||d|d|d tr|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.rozMissing requirements:zA - FAL_KEY is not set and the managed FAL gateway is unreachablez+ - FAL_KEY environment variable is not setrsz - z&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) )rrrjoin)linesrs r rros6DR HE LL()))!## 3 O      BCCC? *    3 LL111 2 2 2 LL LL9::: LL 8"##   /    LL  99U  rc  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) r&r ImportErroragent.image_gen_registryr,hermes_cli.pluginsr. is_availablery)r,r.providers r #check_image_generation_requirementsr4s         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(?u · Price: r*z Upscaler: r/onoffz Available models:u ← activeroz z<32z<6u% 🐛 Debug mode enabled — session )registry tool_errorimage_generateaGenerate 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. When the active terminal backend has a different filesystem, successful local-file results may also include `agent_visible_image` for follow-up terminal/file operations.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.)renumr?rr%r9)r propertiesrequired)namer?rc 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[Nrkz"Could not read image_gen.model: %s rrrrrrurryrrrrsectionrr}s r _read_configured_image_modelrI 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)uReturn 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 in-tree FAL fallback 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). ``"fal"`` explicitly routes through ``plugins/image_gen/fal/`` (which delegates back into this module's pipeline via call-time indirection — see issue #26241). rrr[Nr3z%Could not read image_gen.provider: %srFrGs r _read_configured_image_providerrLs C111111kmm*4S$*?*?I#''+&&&T gt $ $ %KK ++E%%% %%++-- %{{}}$ CCC > E+AE& E+&E+c :|dd}|stdS|dt}|d}t||}|t ||St ||}t ||S)Nr%roz'prompt is required for image generationr9r)rrA)rr;rrVrr )argskwr%r9r dispatchedrs r _handle_image_generater[s XXh # #F ECDDD88N,@AALffYG.flCCJ1*gNNNN !   C .c7 C C CCrr[u🎨)rDtoolsetschemarcheck_fn requires_envis_asyncemoji)N)[__doc__rloggingrr threadingrvtypingrrrr__annotations__r tools.debug_helpersrr rrrtools.managed_tool_gatewayrtools.tool_backend_helpersrrrr getLoggerrrrTrurrrrrrrrrrrrrrfrgLockrer]rjrtuplerrrrrrrrrrrfloatr r&rr4print SystemExitr/rrrrmidmmarkeractive session_idtools.registryr:r;listIMAGE_GENERATE_SCHEMArIrLrVr[registerr\rr rysA *   &&&&&&&&&& C #    -,,,,, DCCCCC  8 $ $4%'))!'  $%"%*     ). *))!'  $&!"%* #     38#*))!'  $%"%*',      /4:D#$  " #      16#'#$!#   "      -2!J% *(!&   "      =B!&#))!'  *!     ).$>))!'   $U    ',,, .))!'  $&!"%      ->#P6$   (    ),,."R6$  (    %++yP)P) Dd38n$ %PPPf) "9 +>K! m-@ A A A!)9>++ 555###0(s(tCH~((((\ *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   0LLCLLLL^DDD(   " 0        s ,K<<L