`gji5UdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z mZmZej eZdZded<d ZGd d ej,Zd"d Zd#d Zd$dZddd d%dZddddddZdddd d&dZddd d'dZdddded  d(d!Zy))u* 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 ceZdZdZeej d dZed dZd dZ ddZ ddZ ddZ ddZ ej efd d d  dd Zy )ImageGenProvideruAbstract base class for an image generation backend. Subclasses must implement :meth:`generate`. Everything else has sane defaults — override only what your provider needs. cy)zStable short identifier used in ``image_gen.provider`` config. Lowercase, no spaces. Examples: ``fal``, ``openai``, ``replicate``. Nselfs K/root/.hermes/venv/lib/python3.12/site-packages/agent/image_gen_provider.pynamezImageGenProvider.nameGc6|jjS)zMHuman-readable label shown in ``hermes tools``. Defaults to ``name.title()``.)rtitlers r display_namezImageGenProvider.display_nameOsyy  rcy)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 rcgS)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  rc$|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 *%%   rcP|j}|r|djdSy)z7Return the default model id, or None if not applicable.ridN)rget)rmodelss r default_modelzImageGenProvider.default_models)!!# !9==& &rcdgddS)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_urlsc y)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)rprompt aspect_ratior/r0kwargss rgeneratezImageGenProvider.generaterr)returnstr)r6bool)r6zList[Dict[str, Any]])r6Dict[str, Any])r6 Optional[str]) r2r7r3r7r/r:r0Optional[List[str]]r4rr6r9)__name__ __module__ __qualname____doc__propertyabcabstractmethodrrrrr$r)r.DEFAULT_ASPECT_RATIOr5rrrrr@s   !!" 6 , 1 $(48    !  2      rrct|tstS|jj }|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. ) isinstancer7rCstriplowerr )valuevs rresolve_aspect_ratiorJs< eS !## A  rc|yt|tr|g}t|ttfsyg}|D]C}t|ts|j s%|j |j E|xsdS)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)rEr7listtuplerFappend)rHoutitems rnormalize_reference_imagesrQsr }% edE] +C% dC TZZ\ JJtzz| $% ;$rcRddlm}|dz dz }|jdd|S)zBReturn ``$HERMES_HOME/cache/images/``, creating parents as needed.r)get_hermes_homecacheimagesT)parentsexist_ok)hermes_constantsrSmkdir)rSpaths r_images_cache_dirr[s,0  w & 1DJJtdJ+ Krimagepng)prefix extensionctj|}tjjj d}t j jdd}t|d|d|d|z }|j||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)b64_datar^r_rawtsshortrZs rsave_b64_imagerrs   8 $C      ) )/ :B JJL  Ra E  F81RD%)!E EDS Krjpgwebpgif)z image/pngz image/jpegz image/jpgz image/webpz image/gifgN@i)r^timeout max_bytesc Fddl}|j||d}|j|jjdxsdj dddj j }tj|}|I|j d ddj }d D]!} |jd | s| d k(rd n| }n|d}tjjjd} tjjdd} t|d| d| d |z } d} | j!d5}|j#dD]_}|s| t%|z } | |kDr6|j' | j)t-d|d|dzd|j/|a ddd| dk(r | j)t-d|d| S#t*$rYcwxYw#1swY?xYw#t*$rY7wxYw)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)rvstreamz Content-Typer ;?)r]rsjpegrtrurdr}rsr]rarbrcwbi) chunk_sizez Image at z exceeds izMB cap; refusing to cache.z% returned 0 bytes; refusing to cache.)requestsr'raise_for_statusheaderssplitrFrG_URL_IMAGE_CONTENT_TYPESendswithrgrhrirjrkrlr[open iter_contentlencloseunlinkOSError ValueErrorwrite)urlr^rvrwrresponse content_typer_url_pathextrprqrZ bytes_writtenfhchunks rsave_url_imagers>&||C|>H  $$((8>BEEc1MaPVVX^^`L(,,\:I99S!$Q'--/8 C  1SE+%(F]E        ) )/ :B JJL  Ra E  F81RD%)!E EDM 4B**i*@ E SZ 'My( KKM!uIiK.H-IIcd HHUO    KKM9SE)NOPP K&   sBrs'R#  33   8 $(K_J"| sww| H  (     2 % B B B B  B  BX&*         $H',      r