oq'jeZUdZddlmZddlZddlZddlZddlZddlmZm Z m Z m Z m Z ddl mZmZmZejeZdddd dd d dddd d d ddddddddddd d d dddddddddddd d d d ddd!dd"d#d$d%d&d d'd d(d)dd*dd+d,d-d.dd/d d d0 d1ddd2dd3d4dddd'd'd d5Zd6ed7<d8Zd`d=ZdadBZdbdCZdcdGZdddQZdad:edR<ejZdedSZda d:edT<da!d:edU<ejZ"dVZ#dWZ$dfdZZ%dgd[Z&Gd\d]eZ'dhd_Z(dS)iu FAL.ai video generation backend. User-facing surface: pick a **model family** (e.g. "Pixverse v6", "Veo 3.1", "Seedance 2.0", "Kling v3 4K", "LTX 2.3", "Happy Horse"). The plugin auto-routes to the family's text-to-video endpoint when called without ``image_url``, and to its image-to-video endpoint when ``image_url`` is provided. The agent never sees the routing — it just calls ``video_generate(prompt=..., image_url=...)``. Model families (each with t2v + i2v endpoints): Cheap tier: ltx-2.3 fal-ai/ltx-2.3-22b/text-to-video / fal-ai/ltx-2.3-22b/image-to-video pixverse-v6 fal-ai/pixverse/v6/text-to-video / fal-ai/pixverse/v6/image-to-video Premium tier: veo3.1 fal-ai/veo3.1 / fal-ai/veo3.1/image-to-video seedance-2.0 bytedance/seedance-2.0/text-to-video / bytedance/seedance-2.0/image-to-video kling-v3-4k fal-ai/kling-video/v3/4k/text-to-video / fal-ai/kling-video/v3/4k/image-to-video happy-horse alibaba/happy-horse/text-to-video / alibaba/happy-horse/image-to-video Selection precedence for the active family: 1. ``model=`` arg from the tool call 2. ``FAL_VIDEO_MODEL`` env var 3. ``video_gen.fal.model`` in ``config.yaml`` 4. ``video_gen.model`` in ``config.yaml`` (when it's one of our family IDs) 5. ``DEFAULT_MODEL`` Authentication via ``FAL_KEY`` or the managed Nous gateway. Output is an HTTPS URL from FAL's CDN; the gateway downloads and delivers it. ) annotationsN)AnyDictListOptionalTuple)VideoGenProvidererror_responsesuccess_responsez LTX 2.3 (22B)z~30-60scheapz322B model with native audio generation. Affordable.z fal-ai/ltx-2.3-22b/text-to-videoz!fal-ai/ltx-2.3-22b/image-to-videoT) displayspeedprice strengthstier text_endpointimage_endpoint aspect_ratios resolutions durationsaudionegativez Pixverse v6z~30-90sz.Affordable. Negative prompts. 1-15s durations.z fal-ai/pixverse/v6/text-to-videoz!fal-ai/pixverse/v6/image-to-video360p540p720p1080p)zVeo 3.1z~60-120spremiumzBGoogle DeepMind. Cinematic, native audio, strong prompt adherence.z fal-ai/veo3.1zfal-ai/veo3.1/image-to-video)16:99:16)rr4k)s) r rrrrrrrrrduration_suffixrrz Seedance 2.0z;ByteDance. Cinematic, synchronized audio + lip-sync, 4-15s.z$bytedance/seedance-2.0/text-to-videoz%bytedance/seedance-2.0/image-to-video)z21:9r!z4:31:1z3:4r")480prr)r$rFz Kling v3 4Kz ~120-300sz14K output, native audio (Chinese/English), 3-15s.z&fal-ai/kling-video/v3/4k/text-to-videoz'fal-ai/kling-video/v3/4k/image-to-videostart_image_urlr!r"r))r) r rrrrrrimage_param_keyrrrrrzHappy Horse 1.0uAAlibaba. New model, sparse public docs — conservative defaults.z!alibaba/happy-horse/text-to-videoz"alibaba/happy-horse/image-to-video)zltx-2.3 pixverse-v6zveo3.1z seedance-2.0z kling-v3-4kz happy-horsezDict[str, Dict[str, Any]] FAL_FAMILIESr/rrreturnboolct|trt|dkrdStd|DsdS|d|dz dkS)zIHeuristic: a 2-tuple of ints with a gap > 1 is treated as ``(min, max)``.Fc3@K|]}t|tVdSN) isinstanceint).0ds C/home/ubuntu/.hermes/hermes-agent/plugins/video_gen/fal/__init__.py z%_is_duration_range..s,55az!S!!555555rr)r7tuplelenall)rs r;_is_duration_rangerAse i ' '3y>>Q+>+>u 559555 5 5u Q<)A, & **r=familyDict[str, Any]duration Optional[int]c|d}|sS|dSt|r#|\}}t|t|S|vrSt|fdS)Nrrc(t|z Sr6)abs)r:rDs r;z!_clamp_duration..sAL(9(9r=)key)getrAmaxmin)rBrDrlohis ` r;_clamp_durationrPs ;''I |)$$*B2s2x(()))9 y9999 : : ::r=c ddlm}|}t|tr|dnd}t|tr|niS#t $r'}t d|icYd}~Sd}~wwxYw)Nr) load_config video_genz#Could not load video_gen config: %s)hermes_cli.configrRr7dictrK Exceptionloggerdebug)rRcfgsectionexcs r;_load_video_gen_sectionr\s111111kmm*4S$*?*?I#''+&&&T$Wd33;ww;  :C@@@ sAA B!B=BBexplicit Optional[str]Tuple[str, Dict[str, Any]]c4g}|||tjdt }t |dt r|dni}t |t r(||d|d}t |tr|||D]k}t |trT|r@|tvr%|}|t|fcSltttfS)z>Decide which FAL family to use. Returns ``(family_id, meta)``.FAL_VIDEO_MODELfalmodel) appendosenvironrKr\r7rUstrstripr0 DEFAULT_MODEL)r] candidatesrYfal_cfgtopcfids r;_resolve_familyrosT&(Jhbjnn%677888 ! # #C *3775>>4 @ @HcggennnbG'4  0'++g../// '''  C#s# ** a   *!'')) * \0I0I''))C S)) ) ) ) ,}5 55r=promptrg image_url aspect_ratio resolutionnegative_promptrOptional[bool]seedci} |r|| d<|r|dpd} || | <||| d<|dr||dvr|| d<|dr||dvr|| d <t||} | 4|d r|d d } | | | d <|dr|t|| d<|dr|r|| d<| S)zJBuild a family-specific payload, dropping keys the family doesn't declare.rpr.rqNrvrrrrrsrr(rDrgenerate_audiorrt)rKrPr2) rBrprqrDrrrsrtrrvpayloadrJclampedsuffixs r;_build_payloadr}sZ!G #"!jj*++:{    zz/""3 6/2 2 2&2GN #zz-  /  . . .$.GL !fh//Gvzz+66-r22!(2&22  zz'0u0$(KK ! zz*5/5%4!" Nr= _fal_clientcttSt5ttcdddSddlm}|atcdddS#1swxYwYdS)aoLazy-load the ``fal_client`` SDK and cache it on this module. Delegates the actual import to :func:`tools.fal_common.import_fal_client` so the ``lazy_deps`` ensure-install handling stays in one place. Thread-safe via double-checked locking: concurrent first calls import the SDK exactly once instead of each racing thread re-running the import. Nrimport_fal_client)r~_fal_client_locktools.fal_commonrrs r;_load_fal_clientr)s   " 766666''))  sAAAA_managed_fal_video_client _managed_fal_video_client_configcbddlm}m}|r |dsdSddlm}|dS)zsReturn managed fal-queue gateway config when the user prefers the gateway or direct FAL credentials are absent.r)fal_key_is_configuredprefers_gatewayrSN)resolve_managed_tool_gatewayz fal-queue)tools.tool_backend_helpersrrtools.managed_tool_gatewayr)rrrs r;"_resolve_managed_fal_video_gatewayrFsgRQQQQQQQ{'C'CtGGGGGG ' ' 4 44r=cDddlm}|jd|jf}t 5t t|krt cdddSt|t|j|ja|at cdddS#1swxYwYdS)zQReuse the managed FAL client so its internal httpx.Client is not leaked per call.r)_ManagedFalSyncClient/N)rJqueue_run_origin) rrgateway_originrstripnous_user_token_managed_fal_video_client_lockrrrr~)managed_gatewayr client_configs r;_get_managed_fal_video_clientrRs"766666 &--c22'M ( ) ) $ 05UYf5f5f, ) ) ) ) ) ) ) ) $9$9 /,;% % % ! ,9(( ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) ) )sB3BBBendpoint argumentsctdttji}t }|t |||St|} ||||S#t$r@}ddl m }||}|'d|cxkrdkrnntd|d |d |d}~wwxYw) zSubmit a FAL video request using direct credentials or the managed queue gateway. Returns a request handle whose ``.get()`` blocks until the result is ready. zx-idempotency-keyN)rheadersr)_extract_http_statusiiz-Nous Subscription gateway rejected endpoint '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` → Video Generation.) rrguuiduuid4rr~submitrrVrr ValueError)rrrequest_headersrmanaged_clientr[rstatuss r;_submit_fal_video_requestris; *C ,=,=>O8::O!!(i!YYY2?CCN$$ #%      999999%%c**  #"5"5"5"5#"5"5"5"5"5YYYYYY     s.B C;C  CcFddlm}|rdStduS)zNTrue if the FAL.ai video backend is reachable (direct key or managed gateway).rrTN)rrrrs r;_check_fal_video_availablers;@@@@@@t - / /t ;;r=c eZdZdZed#dZed#dZd$dZd%d Zd&d Z d'd Z d'dZ dddddddddd d(d"Z dS))FALVideoGenProviderzFAL.ai multi-family video generation backend. Routes between text-to-video and image-to-video endpoints automatically based on whether ``image_url`` was provided. r1rgcdS)Nrbselfs r;namezFALVideoGenProvider.nameur=cdS)NFALrrs r; display_namez FALVideoGenProvider.display_namerr=r2cB tS#t$rYdSwxYw)NF)rrVrs r; is_availablez FALVideoGenProvider.is_availables5 -// /   55 s  List[Dict[str, Any]]c g}tD]\}}g}|dr|d|dr|d|||d|d|d|d|d d |d |S) Nrtextrimager rrrrr )idr rrrr modalities)r0itemsrKrd)routrnmetars r; list_modelszFALVideoGenProvider.list_modelss$&%++--  IC$&Jxx(( *!!&)))xx()) +!!'*** JJ ?g!+.g33(     r=r^ctSr6)rirs r; default_modelz!FALVideoGenProvider.default_modelsr=rCcdddddddgdS) Nrpaidu^LTX, Pixverse, Veo 3.1, Seedance 2.0, Kling 4K, Happy Horse — text-to-video & image-to-videoFAL_KEYzFAL.ai API keyzhttps://fal.ai/dashboard/keys)rJrpurl)rbadgetagenv_varsrrs r;get_setup_schemaz$FALVideoGenProvider.get_setup_schemas4s%.:   r=c $ddggdgddddddd S) Nrrr,rrrTr)rrr max_duration min_durationsupports_audiosupports_negative_promptmax_reference_imagesrrs r; capabilitiesz FALVideoGenProvider.capabilitiess:!7+444<<<"(,$%   r=Nr!r) rcrqreference_image_urlsrDrrrsrtrrvrprcrqrOptional[List[str]]rDrErrrsrtrrurvkwargsrc  tstddd|S tn##t$rtddd|cYSwxYw|pd}t |\} } |pdpd}|r2| d}d }|std | d d d| | Sn1| d}d}|std | dd d| | S|stddd| | St| ||||||| |  } t||}|}nN#t$rA}t d| ||dtd|dd| ||cYd}~Sd}~wwxYwt|tr|pidnd}d}t|tr|d}nt|tr|}|stddd| | Sd|i}t|tr@|dr |d|d<|d r |d |d <t|| ||d!|vr|ndd"|vr4t!dd#|d"Dpd$nd%d|&S)'NuNo FAL backend available. Either set FAL_KEY (run `hermes tools` → Video Generation → FAL to configure) or sign in to Nous (`hermes setup`) for managed gateway access. auth_requiredrb)error error_typeproviderrpz@fal_client Python package not installed (pip install fal-client)missing_dependencyrxrrz FAL family us has no image-to-video endpoint. Pick a family with image-to-video support via `hermes tools` → Video Generation.modality_unsupported)rrrrcrprrzq has no text-to-video endpoint. Pass an image_url to use its image-to-video endpoint, or pick a different family.zprompt is required.missing_prompt)rprqrDrrrsrtrrvz1FAL video gen failed (family=%s, endpoint=%s): %sT)exc_infozFAL video generation failed: api_error)rrrrcrprrvideorz%FAL returned no video URL in responseempty_responser file_size content_typerrrDc3BK|]}||VdSr6)isdigit)r9rms r;r<z/FALVideoGenProvider.generate.._s/ O Oq199;; O O O O O O Or=0r)rrcrpmodalityrrrDrextra)rr r ImportErrorrhrorKr}rrVrWwarningr7rUrgr r8join)rrprcrqrrDrrrsrtrrvr family_idrBimage_url_normr modality_usedrzhandleresultr[rrrs r;generatezFALVideoGenProvider.generates-*++ !V+             !X/     ,B%%''+E22 6$/r0022:d  zz"233H#M %DiDDD 6")F zz/22H"M %PiPPP 6")F !++i  ! $%!+     .xAAFZZ\\FF    NNC8S4    ";c;;&i)        0:&$/G/GQ2""7+++T! eT " " ))E""CC s # # C !=+i  ",X 6 eT " " >yy%% 8%*;%7k"yy(( >(-n(=n%")77)B)B[eip[p[pS O OGJ,? O O OOOVSVWWWvw    s-2AA)$E F6FFF)r1rgr1r2)r1r)r1r^r1rC)rprgrcr^rqr^rrrDrErrrgrsrgrtr^rrurvrErrr1rC) __name__ __module__ __qualname____doc__propertyrrrrrrrrrr=r;rrs XX &          $#'48"&" )- $"E E E E E E E E r=rNonecH|tdS)uFPlugin entry point — wire ``FALVideoGenProvider`` into the registry.N)register_video_gen_providerr)ctxs r;registerrjs###$7$9$9:::::r=)rrr1r2)rBrCrDrEr1rEr)r]r^r1r_)rBrCrprgrqr^rDrErrrgrsrgrtr^rrurvrEr1rC)r1r)rrgrrCr)r1r))r __future__rloggingre threadingrtypingrrrrragent.video_gen_providerr r r getLoggerrrWr0__annotations__rirArPr\ror}r~Lockrrrrrrrrrrrrr=r;rs@#"""""  33333333333333  8 $ $.#J;="!E;=8   Y(8). "R?AG0"!HAC-0$%X<>ca+a+ aaaaF ++++ ; ; ; ;(    666661111p !9>##0"&%%%%(, ,,,,!/!1!1 5 5 5))).B<<<<J J J J J *J J J d;;;;;;r=