g5ji50UdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z mZmZejeZdZded<d ZGd d ejZd;dZddZdddddd Zdd!d"d#d?d)Zd*dd+d@d4Zd5d6d6d6ed7dAd:ZdS)Bu* Image Generation Provider ABC ============================= Defines the pluggable-backend interface for image generation. Providers register instances via ``PluginContext.register_image_gen_provider()``; the active one (selected via ``image_gen.provider`` in ``config.yaml``) services every ``image_generate`` tool call. Providers live in ``/plugins/image_gen//`` (built-in, auto-loaded as ``kind: backend``) or ``~/.hermes/plugins/image_gen//`` (user, opt-in via ``plugins.enabled``). Unified surface --------------- One tool — ``image_generate`` — covers **text-to-image** and **image-to-image / image editing**. The router is the presence of ``image_url`` (and/or ``reference_image_urls``): if any source image is provided, the provider routes to its image-to-image / edit endpoint; if omitted, the provider routes to text-to-image. Users pick one **model** (e.g. nano-banana-pro, gpt-image-2, grok-imagine-image); the provider handles which underlying endpoint to hit. This mirrors the ``video_gen`` provider design (``agent/video_gen_provider.py``) so the two surfaces stay learnable together. Response shape -------------- All providers return a dict that :func:`success_response` / :func:`error_response` produce. The tool wrapper JSON-serializes it. Keys: success bool image str | None URL or absolute file path model str provider-specific model identifier prompt str echoed prompt aspect_ratio str "landscape" | "square" | "portrait" modality str "text" | "image" (which mode was used) provider str provider name (for diagnostics) error str only when success=False error_type str only when success=False ) annotationsN)Path)AnyDictListOptionalTuple) landscapesquareportraitzTuple[str, ...]VALID_ASPECT_RATIOSr ceZdZdZeejddZeddZddZ dd Z dd Z dd Z ddZ ejefdddddZdS)ImageGenProvideruAbstract base class for an image generation backend. Subclasses must implement :meth:`generate`. Everything else has sane defaults — override only what your provider needs. returnstrcdS)zStable short identifier used in ``image_gen.provider`` config. Lowercase, no spaces. Examples: ``fal``, ``openai``, ``replicate``. Nselfs >/home/rurouni/.hermes/hermes-agent/agent/image_gen_provider.pynamezImageGenProvider.nameGc4|jS)zMHuman-readable label shown in ``hermes tools``. Defaults to ``name.title()``.)rtitlers r display_namezImageGenProvider.display_nameOsy   rboolcdS)zReturn True when this provider can service calls. Typically checks for a required API key. Default: True (providers with no external dependencies are always available). Trrs r is_availablezImageGenProvider.is_availableTs trList[Dict[str, Any]]cgS)a Return catalog entries for ``hermes tools`` model picker. Each entry:: { "id": "gpt-image-1.5", # required "display": "GPT Image 1.5", # optional; defaults to id "speed": "~10s", # optional "strengths": "...", # optional "price": "$...", # optional } Default: empty list (provider has no user-selectable models). rrs r list_modelszImageGenProvider.list_models\s  rDict[str, Any]c|jddgdS)a5Return provider metadata for the ``hermes tools`` picker. Used by ``tools_config.py`` to inject this provider as a row in the Image Generation provider list. Shape:: { "name": "OpenAI", # picker label "badge": "paid", # optional short tag "tag": "One-line description...", # optional subtitle "env_vars": [ # keys to prompt for {"key": "OPENAI_API_KEY", "prompt": "OpenAI API key", "url": "https://platform.openai.com/api-keys"}, ], } Default: minimal entry derived from ``display_name``. Override to expose API key prompts and custom badges. )rbadgetagenv_vars)rrs rget_setup_schemaz!ImageGenProvider.get_setup_schemams"*%    r Optional[str]ch|}|r|ddSdS)z7Return the default model id, or None if not applicable.ridN)r"get)rmodelss r default_modelzImageGenProvider.default_models6!!##  '!9==&& &trcdgddS)uReturn what this provider supports. Returned dict (all keys optional):: { "modalities": ["text", "image"], # which inputs the backend accepts "max_reference_images": 9, # cap for reference_image_urls } ``modalities`` declares whether the active backend/model supports text-to-image (``"text"``), image-to-image / editing (``"image"``), or both. The tool layer surfaces this in the dynamic schema so the model knows when ``image_url`` is honored. Used by ``hermes tools`` for the picker too. Default: text-only (backward compatible — a provider that doesn't override this advertises text-to-image only). textr) modalitiesmax_reference_imagesrrs r capabilitieszImageGenProvider.capabilitiess$"($%   rN) image_urlreference_image_urlsprompt aspect_ratior5r6Optional[List[str]]kwargsrc dS)uGenerate an image from a text prompt, or edit/transform a source image. Routing: if ``image_url`` (or any ``reference_image_urls``) is provided, the provider should route to its image-to-image / edit endpoint; otherwise text-to-image. ``image_url`` is the primary source image to edit; ``reference_image_urls`` are additional style/composition references (provider clamps to its declared ``max_reference_images``). Implementations should return the dict from :func:`success_response` or :func:`error_response`. ``kwargs`` may contain forward-compat parameters future versions of the schema will expose — implementations MUST ignore unknown keys (no TypeError). Nr)rr7r8r5r6r:s rgeneratezImageGenProvider.generaterr)rr)rr)rr )rr#)rr*) r7rr8rr5r*r6r9r:rrr#)__name__ __module__ __qualname____doc__propertyabcabstractmethodrrrr"r)r/r4DEFAULT_ASPECT_RATIOr<rrrrr@s    X !!!X!"    6    , 1 $(48         rrvaluer*rrct|tstS|}|t vr|StS)zClamp an aspect_ratio value to the valid set, defaulting to landscape. Invalid values are coerced rather than rejected so the tool surface is forgiving of agent mistakes. ) isinstancerrDstriplowerr )rEvs rresolve_aspect_ratiorKsL eS ! !$## A  rrr9c,|dSt|tr|g}t|ttfsdSg}|D]R}t|tr;|r'||S|pdS)zCoerce a reference-image argument into a clean list of URL/path strings. Accepts a single string or a list; strips blanks and whitespace. Returns ``None`` when nothing usable remains so providers can treat "no refs" as a single sentinel. N)rGrlisttuplerHappend)rEoutitems rnormalize_reference_imagesrRs }t% edE] + +tC%% dC  %TZZ\\ % JJtzz|| $ $ $ ;$rrc`ddlm}|dz dz }|dd|S)zBReturn ``$HERMES_HOME/cache/images/``, creating parents as needed.r)get_hermes_homecacheimagesT)parentsexist_ok)hermes_constantsrTmkdir)rTpaths r_images_cache_dirr\sF000000 ?  w & 1DJJtdJ+++ Krimagepng)prefix extensionb64_datar_r`c2tj|}tjd}t jjdd}t|d|d|d|z }| ||S)zDecode base64 image data and write it under ``$HERMES_HOME/cache/images/``. Returns the absolute :class:`Path` to the saved file. Filename format: ``__.``. %Y%m%d_%H%M%SN_.) base64 b64decodedatetimenowstrftimeuuiduuid4hexr\ write_bytes)rar_r`rawtsshortr[s rsave_b64_imagerss  8 $ $C     ) )/ : :B JLL RaR E   F!E!ER!E!E%!E!E)!E!E EDS Krjpgwebpgif)z image/pngz image/jpegz image/jpgz image/webpz image/gifgN@i)r_timeout max_bytesurlrwfloatrxintc ddl}|||d}||jdpdddd}t|}|W|d dd}d D]&} |d | r | d krd n| }n'|d}tj d} tj jdd} t|d| d| d |z } d} | d5}|dD]}|s| t%|z } | |krS| | n#t*$rYnwxYwt-d|d|dzd|| dddn #1swxYwY| dkr9 | n#t*$rYnwxYwt-d|d| S)uDownload an image URL and write it under ``$HERMES_HOME/cache/images/``. Used by providers (xAI, fallback OpenAI) whose API returns an *ephemeral* URL instead of inline base64 — those URLs frequently expire before a downstream consumer (Telegram ``send_photo``, browser fetch) can resolve them, so we materialise the bytes locally at tool-completion time. Mirrors :func:`save_b64_image`'s shape so providers can swap in one line. Returns the absolute :class:`Path` to the saved file. Raises on any network / HTTP / oversize / non-image-content-type error so callers can fall back to returning the bare URL with a clear error message. rNT)rwstreamz Content-Typer%;?)r^rtjpegrurvrfrrtr^rcrdrewbi) chunk_sizez Image at z exceeds izMB cap; refusing to cache.z% returned 0 bytes; refusing to cache.)requestsr-raise_for_statusheaderssplitrHrI_URL_IMAGE_CONTENT_TYPESendswithrirjrkrlrmrnr\open iter_contentlencloseunlinkOSError ValueErrorwrite)ryr_rwrxrresponse content_typer`url_pathextrqrrr[ bytes_writtenfhchunks rsave_url_imagers &OOO||C|>>H  $((88>BEEc1MMaPVVXX^^``L(,,\::I99S!$$Q'--//8  C  S++ %(F]]EE       ) )/ : :B JLL RaR E   F!E!ER!E!E%!E!E)!E!E EDM 4B**i*@@  E  SZZ 'My(( KKMMMMD dddiK.Hddd HHUOOOO    KKMMMM    D OSOOOPPP KsIAH0G$#H0$ G1.H00G112H00H47H4I I$#I$r1)modalityextramodelr7r8providerrrOptional[Dict[str, Any]]r#c~d||||||d}|r0|D]\}} ||| |S)uBuild a uniform success response dict. ``image`` may be an HTTP URL or an absolute filesystem path (for b64 providers like OpenAI). ``modality`` is ``"text"`` (text-to-image) or ``"image"`` (image-to-image / editing) — indicates which endpoint was actually hit, useful for diagnostics. Callers that need to pass through additional backend-specific fields can supply ``extra``. T)successr]rr7r8rr)items setdefault) r]rr7r8rrrpayloadkrJs rsuccess_responserUsh&$G %KKMM % %DAq   q! $ $ $ $ Nrprovider_errorr%) error_typerrr7r8errorrc dd||||||dS)z$Build a uniform error response dict.FN)rr]rrrr7r8rr)rrrrr7r8s rerror_responservs+ $   r)rEr*rr)rErrr9)rr)rarr_rr`rrr) ryrr_rrwrzrxr{rr)r]rrrr7rr8rrrrrrrrr#)rrrrrrrrr7rr8rrr#) r@ __future__rrBrgriloggingrlpathlibrtypingrrrrr getLoggerr=loggerr __annotations__rDABCrrKrRr\rsrrrrrrrrs'''R#"""""  33333333333333  8 $ $(KJJJJ"| | | | | sw| | | H     ( 2 % BBBBBBX&*H',r