eiUdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z mZmZejeZdZded<d ZGd d ejZd)dZd*dZdddd+dZddd,d"Zd#d$d$d$ed%d-d(ZdS).au 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``). 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" 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 eje fddZdS)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/div/.hermes/hermes-agent/agent/image_gen_provider.pynamezImageGenProvider.name:c4|jS)zMHuman-readable label shown in ``hermes tools``. Defaults to ``name.title()``.)rtitlers r display_namezImageGenProvider.display_nameBsy   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_availableGs 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_modelsOs  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_schema`s"*%    r Optional[str]ch|}|r|ddSdS)z7Return the default model id, or None if not applicable.ridN)r"get)rmodelss r default_modelzImageGenProvider.default_model{s6!!##  '!9==&& &trprompt aspect_ratiokwargsrc dS)u'Generate an image. 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 should ignore unknown keys. Nr)rr0r1r2s rgeneratezImageGenProvider.generaterrN)rr)rr)rr )rr#)rr*)r0rr1rr2rrr#)__name__ __module__ __qualname____doc__propertyabcabstractmethodrrrr"r)r/DEFAULT_ASPECT_RATIOr4rrrrr3s    X !!!X!"    6 1         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. ) isinstancerr<striplowerr )r=vs rresolve_aspect_ratiorCsL eS ! !$## A  rrc`ddlm}|dz dz }|dd|S)zBReturn ``$HERMES_HOME/cache/images/``, creating parents as needed.r)get_hermes_homecacheimagesT)parentsexist_ok)hermes_constantsrEmkdir)rEpaths r_images_cache_dirrMsF000000 ?  w & 1DJJtdJ+++ Krimagepng)prefix extensionb64_datarPrQc2tj|}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: ``__.``. z %Y%m%d_%H%M%SN_.) base64 b64decodedatetimenowstrftimeuuiduuid4hexrM write_bytes)rRrPrQrawtsshortrLs rsave_b64_imagercs  8 $ $C     ) )/ : :B JLL RaR E   F!E!ER!E!E%!E!E)!E!E EDS Kr)extramodelr0r1providerrdOptional[Dict[str, Any]]r#c|d|||||d}|r0|D]\}}||||S)zBuild a uniform success response dict. ``image`` may be an HTTP URL or an absolute filesystem path (for b64 providers like OpenAI). Callers that need to pass through additional backend-specific fields can supply ``extra``. T)successrNrer0r1rf)items setdefault) rNrer0r1rfrdpayloadkrBs rsuccess_responsernse $ G %KKMM % %DAq   q! $ $ $ $ Nrprovider_errorr%) error_typerfrer0r1errorrpc dd||||||dS)z$Build a uniform error response dict.FN)rirNrqrprer0r1rfr)rqrprfrer0r1s rerror_responserss+ $   r)r=r*rr)rr)rRrrPrrQrrr)rNrrerr0rr1rrfrrdrgrr#)rqrrprrfrrerr0rr1rrr#)r8 __future__rr:rWrYloggingr\pathlibrtypingrrrrr getLoggerr5loggerr __annotations__r<ABCrrCrMrcrnrsrrrr|s8#"""""  33333333333333  8 $ $(KJJJJ"\ \ \ \ \ sw\ \ \ H      6'+@',r