`gjTUdZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z mZmZej eZdZded<d Zd Zded <d ZGd dej0Zd&dZddd d'dZddd d(dZdddddZdddd d)dZddddd d*d Zd!ddddd" d+d#Z Gd$d%eZ!y),u Video Generation Provider ABC ============================= Defines the pluggable-backend interface for video generation. Providers register instances via ``PluginContext.register_video_gen_provider()``; the active one (selected via ``video_gen.provider`` in ``config.yaml``) services every ``video_generate`` tool call. Providers live in ``/plugins/video_gen//`` (built-in, auto-loaded as ``kind: backend``) or ``~/.hermes/plugins/video_gen//`` (user, opt-in via ``plugins.enabled``). Mirrors the ``image_gen`` provider design (``agent/image_gen_provider.py``) so the two surfaces stay learnable together. Unified surface --------------- One tool — ``video_generate`` — covers **text-to-video** and **image-to-video**. The router is the presence of ``image_url``: if it's set, the provider routes to its image-to-video endpoint; if it's omitted, the provider routes to text-to-video. Users pick one **model family** (e.g. Pixverse v6, Veo 3.1, Kling O3 Standard); the provider handles which underlying FAL/xAI endpoint to hit. Video edit and video extend are intentionally NOT exposed in this surface — the inconsistency across backends is too large for one unified tool. If those use cases warrant attention later they can ship as separate tools. Response shape -------------- All providers return a dict built by :func:`success_response` / :func:`error_response`. Keys: success bool video str | None URL or absolute file path model str provider-specific model identifier prompt str echoed prompt modality str "text" | "image" (which mode was used) aspect_ratio str provider-native (e.g. "16:9") or "" duration int seconds (0 if not applicable) provider str provider name (for diagnostics) error str only when success=False error_type str only when success=False ) annotationsN)Path)AnyDictListOptionalTuple)16:9z9:16z1:1z4:3z3:4z3:2z2:3zTuple[str, ...]COMMON_ASPECT_RATIOSr )480p540p720p1080pCOMMON_RESOLUTIONSrc eZdZdZeej d dZed dZd dZ ddZ ddZ ddZ ddZ ej d d d d eed d d d dd Zy )VideoGenProvideruAbstract base class for a video generation backend. Subclasses must implement :meth:`generate`. Everything else has sane defaults — override only what your provider needs. cy)zStable short identifier used in ``video_gen.provider`` config. Lowercase, no spaces. Examples: ``xai``, ``fal``, ``google``. Nselfs K/root/.hermes/venv/lib/python3.12/site-packages/agent/video_gen_provider.pynamezVideoGenProvider.nameRc6|jjS)zMHuman-readable label shown in ``hermes tools``. Defaults to ``name.title()``.)rtitlers r display_namezVideoGenProvider.display_nameZsyy  rcy)zReturn True when this provider can service calls. Typically checks for a required API key and optional-dependency import. Default: True. Trrs r is_availablezVideoGenProvider.is_available_s rcgS)aReturn catalog entries for ``hermes tools`` model picker. Each entry represents a **model family** that supports text-to-video and/or image-to-video routing internally:: { "id": "veo-3.1", # required "display": "Veo 3.1", # optional; defaults to id "speed": "~60s", # optional "strengths": "...", # optional "price": "$0.20/s", # optional "modalities": ["text", "image"], # optional, advisory } Default: empty list (provider has no user-selectable models). rrs r list_modelszVideoGenProvider.list_modelsgs " rc$|jddgdS)z9Return provider metadata for the ``hermes tools`` picker.)rbadgetagenv_vars)rrs rget_setup_schemaz!VideoGenProvider.get_setup_schemazs %%   rcP|j}|r|djdSy)z7Return the default model id, or None if not applicable.ridN)r!get)rmodelss r default_modelzVideoGenProvider.default_models)!!# !9==& &rc NdgttttddddddS)aReturn what this provider supports. Returned dict (all keys optional):: { "modalities": ["text", "image"], # which inputs the backend accepts "aspect_ratios": ["16:9", "9:16", ...], "resolutions": ["720p", "1080p"], "max_duration": 15, # seconds "min_duration": 1, "supports_audio": True, "supports_negative_prompt": True, "max_reference_images": 7, } Used by the tool layer for soft validation and by ``hermes tools`` for the picker. Default: text-only. text Fr) modalities aspect_ratios resolutions max_duration min_durationsupports_audiosupports_negative_promptmax_reference_images)listr rrs r capabilitieszVideoGenProvider.capabilitiess4("(!"67 23#(-$%  rN model image_urlreference_image_urlsduration aspect_ratio resolutionnegative_promptaudioseedc y)uGenerate a video from a prompt (text-to-video) or animate an image (image-to-video). Routing: if ``image_url`` is provided, the provider should route to its image-to-video endpoint; otherwise text-to-video. The plugin is responsible for picking the right underlying endpoint within the user's chosen model family. 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) rpromptr<r=r>r?r@rArBrCrDkwargss rgeneratezVideoGenProvider.generaterrreturnstrrJbool)rJzList[Dict[str, Any]])rJDict[str, Any])rJ Optional[str]rFrKr<rOr=rOr>zOptional[List[str]]r? Optional[int]r@rKrArKrBrOrCzOptional[bool]rDrQrGrrJrN)__name__ __module__ __qualname____doc__propertyabcabstractmethodrrrr!r'r,r:DEFAULT_ASPECT_RATIODEFAULT_RESOLUTIONrHrrrrrKs   !!&  <  $#'48"&0,)- $"    !  2      '       rrcRddlm}|dz dz }|jdd|S)zBReturn ``$HERMES_HOME/cache/videos/``, creating parents as needed.r)get_hermes_homecachevideosT)parentsexist_ok)hermes_constantsr\mkdir)r\paths r_videos_cache_dirrds,0  w & 1DJJtdJ+ Krvideomp4)prefix extensionctj|}tjjj d}t j jdd}t|d|d|d|z }|j||S)zDecode base64 video data and write under ``$HERMES_HOME/cache/videos/``. Returns the absolute :class:`Path` to the saved file. Filename format: ``__.``. %Y%m%d_%H%M%SN_.) base64 b64decodedatetimenowstrftimeuuiduuid4hexrd write_bytes)b64_datargrhrawtsshortrcs rsave_b64_videor{s   8 $C      ) )/ :B JJL  Ra E  F81RD%)!E EDS Krctjjjd}tjj dd}t |d|d|d|z }|j||S)z@Write raw video bytes (e.g. an HTTP download body) to the cache.rjNrkrlrm)rprqrrrsrtrurdrv)rxrgrhryrzrcs rsave_bytes_videor}sr      ) )/ :B JJL  Ra E  F81RD%)!E EDS Krwebmmovmkv)z video/mp4z video/webmzvideo/quicktimezvideo/x-matroskagf@i )rgtimeout max_bytesc 8ddl}|j||d}|j|jjdxsdj dddj j }tj|}|B|j d ddj }d D]} |jd | s| }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)aDownload a video URL and write it under ``$HERMES_HOME/cache/videos/``. The video twin of :func:`agent.image_gen_provider.save_url_image`: several backends (DeepInfra, FAL) return an *ephemeral* delivery URL that expires before a downstream consumer can fetch it, so we materialise the bytes locally at tool-completion time. Streams with a size cap. Raises on any network / HTTP / oversize error so callers can fall back to returning the bare URL. rNT)rstreamz Content-Typer#;r0?)rfr~rrrmrfrjrkrlwbi) chunk_sizez Video at z exceeds izMB cap; refusing to cache.z was empty (0 bytes).)requestsr*raise_for_statusheaderssplitstriplower_URL_VIDEO_CONTENT_TYPESendswithrprqrrrsrtrurdopen iter_contentlencloseunlinkOSError ValueErrorwrite)urlrgrrrresponse content_typerhurl_pathextryrzrc bytes_writtenfhchunks rsave_url_videors4"||C|>H $$((8>BEEc1MaPVVX^^`L(,,\:I99S!$Q'--/0 C  1SE+        ) )/ :B JJL  Ra E  F81RD%)!E EDM 4B**j*A E SZ 'My( KKM!uIiK.H-IIcd HHUO    KKM9SE)>?@@ K&   sB ;H=G>>HH  HHr.r#)modalityr@r?extrac d||||||r t|nd|d}|r*|jD]\} } |j| | |S)uBuild a uniform success response dict. ``video`` may be an HTTP URL or an absolute filesystem path. ``modality`` is ``"text"`` (text-to-video) or ``"image"`` (image-to-video) — indicates which endpoint was actually hit, useful for diagnostics. Tr)successrer<rFrr@r?provider)intitems setdefault) rer<rFrr@r?rrpayloadkvs rsuccess_responser?s^$$%-CM1 G KKM %DAq   q! $ % Nrprovider_error) error_typerr<rFr@c dd||||||dS)z$Build a uniform error response dict.FN)rreerrorrr<rFr@rrrrrr<rFr@s rerror_responser`s& $  rc eZdZUdZdZded<dZded<dZded <d Zded <dd Z dd Z ddZ ddZ dddde edddd ddZy) OpenAICompatibleVideoGenProviderugGeneric text/image-to-video over the OpenAI ``client.videos`` API. DeepInfra, OpenAI/Sora, and OpenRouter all expose the same ``POST /videos`` async-job shape (``create`` → poll → ``download_content``), so the SDK call lives here once. A concrete backend only needs to declare its identity and credentials:: class FooVideoGenProvider(OpenAICompatibleVideoGenProvider): name = "foo" _env_key = "FOO_API_KEY" _default_base_url = "https://api.foo.com/v1/openai" def list_models(self): return [...] # entries with an "id" key; default_model() uses [0] ``image_url`` routes to image-to-video; its absence routes to text-to-video. Provider-specific fields (``image_url``/``negative_prompt``/``seed``) ride in ``extra_body`` so they pass through the SDK unchanged. OPENAI_API_KEYrK_env_keyzhttps://api.openai.com/v1_default_base_urlg@float_poll_interval_sg @_poll_deadline_scrddl}|jj|jdj S)Nrr#)osenvironr*rr)rrs r_api_keyz)OpenAICompatibleVideoGenProvider._api_keys'zz~~dmmR06688rc4t|jS)N)rMrrs rrz-OpenAICompatibleVideoGenProvider.is_availablesDMMO$$rc ddl}|jjd i|}hd}|j|jz}t |dd|vr|j|k\r>t dt |dddt|jd t |ddd |j|j|jj|j}t |dd|vr|S) aCCreate the video job and poll to completion with a hard deadline. Replaces ``client.videos.create_and_poll`` (unbounded 1/s loop) with a coarse interval and a wall-clock cap. Returns the terminal video object (any status); raises :class:`TimeoutError` if the deadline passes first. rN>rfailedcanceled cancelled completed succeededstatusz video job r)rz( did not reach a terminal status within zs (last status=)r) timer^create monotonicrgetattr TimeoutErrorrsleeprretriever))rclient call_kwargsrreterminaldeadlines r_create_and_pollz1OpenAICompatibleVideoGenProvider._create_and_polls $ $$3{3Y>>#d&;&;;eXt,H<~~8+" c!: ;<%%()>)>%?$@A$$+E8T$B#EQH JJt,, -MM**5884EeXt,H< rcddl}|jj|jj ddj }|xs |j S)Nr _BASE_URLr#)rrr*rupperrr)rroverrides r _base_urlz*OpenAICompatibleVideoGenProvider._base_urlsF::>>TYY__%6$7y"A2FLLN14111rNr;c |r|jstdd|jS|js%t|jdd|jS ddl} |xs|j} | s&td |jd d |jS|||| d jDcic] \}}||| }}}| |d }|rt||d<|r||d<|r||d<| j|j|j} |j||}t!|dd}|dvrXt!|dd}t|r t|nd|d|j| ||t!|dd}t#|r|SSd}t!|ddxsgD]6}t%|t&r|j)dn t!|dd}|s4|}n |r!tt+||j }nS|j,j/|j0j3}tt5||j }t7|| ||rd$nd%||xsd|j&t!|dd}t#|r|SS#t $rtdd|jcYSwxYwcc}}w#t$rv}tjd|jdt|jd|d|j| ||cYd}~t!|dd}t#|r|SSd}~wwxYw#t$r}|r$tjd!|j||}nOt|jd"|d#|j| ||cYd}~t!|dd}t#|r|SSYd}~wd}~wwxYw#t!|dd}t#|r|wwxYw)'Nzprompt is requiredinvalid_request)rrrz is not setmissing_credentialsrz8openai Python package not installed (pip install openai)missing_dependencyzno z, video model available (live catalog empty?)no_model)rBr@r=rD)r<rFsecondssize extra_body)api_keybase_urlz%s video generation failedT)exc_infoz video generation failed: api_errorrrr)rrrzvideo job ended with status= job_faileddatar)rgz3%s: saving video locally failed (%s); returning URLz7 video job succeeded but no output could be retrieved: empty_responseimager.)rer<rFrr@r?r)rrrrropenai ImportErrorr,rrKOpenAIrr Exceptionloggerdebugrcallable isinstancedictr*rr^download_contentr)readr}r)rrFr<r=r>r?r@rArBrCrDrGrmodel_idrrrrrreexcrr job_errorritem candidate video_refrxs rrHz)OpenAICompatibleVideoGenProvider.generates+V\\^!*7HSWS\S\ }}!{30    0D..0!DII;&RS% $3 ,&  eg  1 } qD   19F&K %(]K " ",K  (2K %t}}AQRN  --fkBUHd3F77$E7D9 %,5#i.=YZ`Yc;d+!YY"!!- lFGT2ESCvt4: /9$/EDHHUO7SWY^`dKe #C     #N3tyy$I JI!--88BGGIC #$4S$K LI $$-6)!QFGT2Ec !P/  "  ,  9499t T%!YYK'A#G*!YY"!!- NFGT2EU ` LL!VX\XaXacfg #I)!% +bcfbgh#3!%&%%1 &FGT2E- 2FGT2Es!J!9KK1AOAO!O'A6M#O!!KK M A M"M #OM  O OAO(O)OOOO"O>rIrL)rrrrNrJrrP)rRrSrTrUr__annotations__rrrrrrrrYrZrHrrrrr{s&%Hc$8s8"e!#e#9 %02 $#'48"&0,)- $"MM M ! M 2 M MMM'MMMM Mrr)rJr)rwrKrgrKrhrKrJr)rxbytesrgrKrhrKrJr) rrKrgrKrrrrrJr)rerKr<rKrFrKrrKr@rKr?rrrKrzOptional[Dict[str, Any]]rJrN)rrKrrKrrKr<rKrFrKr@rKrJrN)"rU __future__rrWrnrploggingrspathlibrtypingrrrrr getLoggerrRrr rrYrrZABCrrdr{r}rrrrrrrrrs ,\#  33   8 $ )\o[&GOGy swwy B     .         & = = = =  =  =J&*         $H'      6S'7Sr