PL j] &UdZddlmZddlZddlZddlZddlZddlZddlZddl m Z ddl m Z ddl mZmZmZejeZiddd d d d d ddddddddddddddddddd d!d"d#d$d%d&d'd(d)d*d+d,d-d.d/d0Zd1ed2<ejd3ZGd4d5eZe d67Gd8d9Zd_d<Zd`d?Zdad@ZdadAZd`dBZd`dCZ dDdEdbdJZ!dcdLZ"dcdMZ#d6dNdddQZ$dedRZ%dfdTZ&dgdVZ'dWdNdhdYZ(dWdNdid^Z)dS)ju Lazy dependency installer for opt-in Hermes Agent backends. Many Hermes features (Mistral TTS, ElevenLabs TTS, Honcho memory, Bedrock, Slack, Matrix, etc.) require Python packages that not every user needs. The historical approach was to bundle them all under ``pyproject.toml`` extras (``hermes-agent[all]``) and install them eagerly at setup time. That has two problems: 1. **Fragility.** When one extra's transitive dependency becomes unavailable on PyPI (quarantined for malware, yanked, broken upload), the *entire* ``[all]`` resolve fails and fresh installs silently fall back to a stripped tier — losing 10+ unrelated extras at once. 2. **Bloat.** A user who only ever talks to one provider pulls hundreds of packages they will never import. The lazy-install pattern fixes both. Backends call :func:`ensure` at the top of their first-import path. If the deps are missing, ``ensure`` checks the ``security.allow_lazy_installs`` config flag (default true) and runs a venv-scoped pip install. If the user has explicitly disabled lazy installs, ``ensure`` raises :class:`FeatureUnavailable` with a clear remediation hint pointing at ``hermes tools`` or the manual pip command. Security model: * **Venv-scoped only.** Installs target ``sys.executable`` in the active venv. We never touch the system Python. * **PyPI by package name only.** Specs may be ``"package>=1.0,<2"`` etc. We do NOT support ``--index-url`` overrides, ``git+https://``, file: paths, or any other input that could be hijacked by a malicious config. * **Allowlist.** Only specs that appear in :data:`LAZY_DEPS` can be installed via this path. A typo in feature name doesn't get the user install-anything semantics. * **Opt-out.** Setting ``security.allow_lazy_installs: false`` in ``config.yaml`` disables runtime installs. Users in restricted networks or strict security postures can pin themselves to whatever was installed at setup time. * **Offline detection.** If the install fails (offline, mirror down, PyPI 404 / quarantine), we surface the failure as :class:`FeatureUnavailable` with the actual pip stderr — no silent retries, no caching of bad state. Adding a new backend: 1. Add an entry to :data:`LAZY_DEPS` with the package specs. 2. At the top of the backend module's import path, call ``ensure("feature.name")`` inside a try/except that converts :class:`FeatureUnavailable` to a useful runtime error. ) annotationsN) dataclass)Path)AnyCallableOptionalzprovider.anthropic)zanthropic==0.87.0zprovider.bedrock)zboto3==1.42.89z search.exa)zexa-py==2.10.2zsearch.firecrawl)zfirecrawl-py==4.17.0zsearch.parallel)zparallel-web==0.4.2ztts.edge)zedge-tts==7.2.7ztts.elevenlabs)zelevenlabs==1.59.0zstt.faster_whisper)zfaster-whisper==1.2.1zsounddevice==0.5.5z numpy==2.4.3z image.fal)zfal-client==0.13.1z memory.honcho)zhoncho-ai==2.0.1zmemory.hindsight)zhindsight-client==0.6.1zplatform.telegram)z#python-telegram-bot[webhooks]==22.6zplatform.discord)zdiscord.py[voice]==2.7.1zbrotlicffi==1.2.0.1zplatform.slack)zslack-bolt==1.27.0zslack-sdk==3.40.1zaiohttp==3.13.4zplatform.matrix)zmautrix[encryption]==0.21.0zMarkdown==3.10.2zaiosqlite==0.22.1zasyncpg==0.31.0zaiohttp-socks==0.11.0zplatform.dingtalk)zdingtalk-stream==0.24.3zalibabacloud-dingtalk==2.2.42 qrcode==7.4.2zplatform.feishu)zlark-oapi==1.5.3r )z modal==1.3.4)zdaytona==0.155.0)z vercel==0.5.7)z!google-api-python-client==2.194.0zgoogle-auth-oauthlib==1.3.1zgoogle-auth-httplib2==0.3.1)zyoutube-transcript-api==1.2.4)zagent-client-protocol==0.9.0)zfastapi==0.133.1zuvicorn[standard]==0.41.0)zterminal.modalzterminal.daytonazterminal.vercelzskill.google_workspacez skill.youtubeztool.acpztool.dashboardzdict[str, tuple[str, ...]] LAZY_DEPSz]^[A-Za-z0-9_][A-Za-z0-9_.\-]*(?:\[[A-Za-z0-9_,\-]+\])?(?:[<>=!~]=?[A-Za-z0-9_.\-+,*<>=!~]+)?$c,eZdZdZd fd Zd d ZxZS) FeatureUnavailablezA lazily-installable feature is missing and cannot be made available. Either the deps were never installed and the user has disabled lazy installs, or the install attempt failed. featurestrmissingtuple[str, ...]reasonc||_||_||_t|dSN)r rrsuper__init___format)selfr rr __class__s 3/home/kuhnn/.hermes/hermes-agent/tools/lazy_deps.pyrzFeatureUnavailable.__init__s>    (((((returnc |dd|jD}d|jd|jd|d|d S)N c34K|]}t|VdSrrepr.0ss r z-FeatureUnavailable._format..s(;;T!WW;;;;;;rzFeature z unavailable: z%. To enable manually: uv pip install z (or: pip install z).)joinrr r)r spec_lists rrzFeatureUnavailable._formatsiHH;;dl;;;;;  .t| . .T[ . .2; . . ) . . . r)r rrrrr)rr)__name__ __module__ __qualname____doc__rr __classcell__)rs@rr r s[ ))))))         rr T)frozenc.eZdZUded<ded<ded<dS)_InstallResultboolsuccessrstdoutstderrN)r'r(r)__annotations__rrr.r.s+MMMKKKKKKKKrr.rr/c tjddkrdS ddlm}|}n#t $rYdSwxYw|dpi}|dd}t |S) aReturn the ``security.allow_lazy_installs`` config flag. Defaults to True. If config is unreadable we fail open (allow), because refusing to install would lock people out of their own backends; the decision to block is an explicit user opt-in. HERMES_DISABLE_LAZY_INSTALLS1Fr) load_configTsecurityallow_lazy_installs)osenvirongethermes_cli.configr8 Exceptionr/)r8cfgsecvals r_allow_lazy_installsrCs z~~455<<u111111kmm tt ''*   #C ''' . .C 99s8 AAspecrcrtdkrdStfddDrdSdsdvsdvrdSttS)zCReject pip specs that contain URLs, paths, or shell metacharacters.Fc3 K|]}|vV dSrr4)r"chrDs rr$z _spec_is_safe..s' R R"2: R R R R R Rr) ;|&`$   \)-/.z://@)lenany startswithr/ _SAFE_SPECmatch)rDs`r _spec_is_safer[s 3t99s??u R R R R Q R R RRRu ''5D==C4KKu    && ' ''rc^tjd|}|r|dn|S)uExtract the bare package name from a pip spec. ``"slack-bolt>=1.18.0,<2"`` → ``"slack-bolt"`` ``"mautrix[encryption]>=0.20"`` → ``"mautrix"`` z^([A-Za-z0-9_][A-Za-z0-9_.\-]*))rerZgrouprDms r_pkg_name_from_specrbs/ 3T::A $1771:::$rcltjd|}|sdS||dS)uExtract just the version-specifier portion of a pip spec. ``"honcho-ai==2.0.1"`` → ``"==2.0.1"`` ``"mautrix[encryption]>=0.20,<1"`` → ``">=0.20,<1"`` ``"package"`` → ``""`` (no version constraint) z6^[A-Za-z0-9_][A-Za-z0-9_.\-]*(?:\[[A-Za-z0-9_,\-]+\])?N)r^rZendr`s r_specifier_from_specrfs9 JDQQA r >rcbt|} ddlm}m}n#t$rYdSwxYw ||}n#|$rYdSt $rYdSwxYwt |}|sdS ddlm}m }ddl m }m } n#t$rYdSwxYw | |||vS#||t f$rYdSwxYw)a^Is ``spec`` already satisfied in the current env? Checks both presence AND version. If the package is installed at a version outside the spec's range, returns False so the caller will upgrade/downgrade to the pinned version. This is what makes ``hermes update`` propagate pin bumps in :data:`LAZY_DEPS` to already- installed backends instead of silently leaving stale versions in place. If ``packaging`` is unavailable for any reason (it's a transitive of pip so this should never happen), we fall back to a presence-only check so we err on the side of "don't churn". rPackageNotFoundErrorversionFT)InvalidSpecifier SpecifierSet)InvalidVersionVersion) rbimportlib.metadatarirj ImportErrorr?rfpackaging.specifiersrkrlpackaging.versionrmrn) rDpkgrirj installed spec_tailrkrlrmrns r _is_satisfiedrvse d # #CDDDDDDDDD uuGCLL uu uu%T**I tGGGGGGGG========= ttwy!!\\)%<%<<< ni 8ttsE (( 8A  A  A $A55 BBB B.-B.ct|} ddlm}m}n#t$rYdSwxYw ||dS#|$rYdSt $rYdSwxYw)zCheap presence-only check (package name installed at any version). Used by :func:`active_features` to detect backends the user has previously activated, regardless of whether the version pin moved. rrhFT)rbrorirjrpr?)rDrsrirjs r _is_presentrx:s d # #CDDDDDDDDD uu t uu uus! (( 9A A Ai,)timeoutspecsrryintc|stdddSttjjj}it jdt|i}tj d}|r tj |ddg|dd||}|j dkrtd|j pd|jpdStd |jn>#tjt$f$r%}td |Yd }~nd }~wwxYwtjd dg} tj |d gzddd}|j dkrt%dn#tjt$f$rk tj tjd dddgddddn>#tjtjf$r }tddd|cYd }~cYSd }~wwxYwYnwxYw tj |dg|zdd|}t|j dk|j pd|jpdS#tj$r}tddd|cYd }~Sd }~wt($r}tddd|cYd }~Sd }~wwxYw)uInstall ``specs`` into the active venv using uv → pip → ensurepip ladder. Mirrors the strategy in ``hermes_cli.tools_config._pip_install`` but kept independent here so this module has no CLI dependency. Trd VIRTUAL_ENVuvpipinstall)capture_outputtextryenvrzuv pip install failed: %szuv invocation failed: %sNz-mz --version)rrryzpip not in venv ensurepipz --upgradez --default-pipx)rrrycheckFz(pip not available and ensurepip failed: zpip install timed out: pip install failed: )r.rsys executableparentr;r<rshutilwhich subprocessrun returncoder1r2loggerdebugTimeoutExpiredFileNotFoundErrorCalledProcessErrorr?) rzry venv_rootuv_envuv_binrepip_cmdprobes r_venv_pip_installrNsi ,dB+++S^$$+2I : :M3y>> : :F\$  F 8 8 2E2#$VA|q  %dAHNAHNKKK LL4ah ? ? ? ?)+<= 8 8 8 LL3Q 7 7 7 7 7 7 7 7 8~tU+GR {m #dB     q #$566 6 !  %'8 9RRR R N{KQ#$4     -z/HI R R R!%"PQ"P"PRR R R R R R R R R R   R E N y)5) )dG   ala/RRPPP  $HHHeR)F1)F)FGGGGGGGG EEEeR)C)C)CDDDDDDDDEs-AC5 CD,D  D$6EG2(FGG6G G GGGG AH&&I95II9 I9I4.I94I9r cR|tvrtd|t|S)z=Return the registered specs for a feature, or raise KeyError.zUnknown lazy feature: )r KeyErrorr s r feature_specsrs/i;;;<<< W rcNtdt|DS)zCReturn the subset of specs for ``feature`` not currently installed.c38K|]}t||VdSr)rvr!s rr$z"feature_missing..s/KKq-:J:JKKKKKKKr)tuplerrs rfeature_missingrs' KKM'22KKK K KKrpromptrNonecx|tvrt|dd|dt|}|sdS|D]%}t|st||d|&t st||d|rt jrt jrd |} td|d |d  }n#ttf$rd }YnwxYw|r|d vrt||d tdd ||t#|}|jsD|jp|jpd }|r |dd}t||d|pd ddlm}t-|dr|n#t0$rYnwxYwt|} | rt|| dtd|dS)uMake sure all packages for ``feature`` are importable. If they're missing, attempts to install them in the active venv. Raises :class:`FeatureUnavailable` if the user has disabled lazy installs or if the install attempt fails. ``prompt``: when True (default) and stdin is a TTY, asks the user to confirm before installing. Non-interactive callers (gateway, cron, batch) get prompt=False and skip the confirmation — config flag is the gate in that case. r4zfeature z not in LAZY_DEPS allowlistNz refusing to install unsafe spec z;lazy installs disabled (security.allow_lazy_installs=false)z, z Feature z requires: z) Install into the active venv now? [Y/n] n>yyeszuser declined install at promptz!Lazy-installing %s for feature %rrrdi0rzno error outputr _cache_clearzWinstall reported success but packages still not importable (may require Python restart)z$Lazy install complete for feature %r)r r rr[rCrstdinisattyr1r%inputstriplowerEOFErrorKeyboardInterruptrinforr0r2rometadatahasattrrr?) r rrrDr&answerresultsnippet_md still_missings rensurersi RJGJJJ   g&&G T"" $;4;;   ! !  W I    #)""$$ ):):)<)< IIg&&    =7FM7R>>@@  &effoG W A7#?.? A A    (((((( 3 ' '             $G,,M  ] +    KK6@@@@@s$ :DDD*G-- G:9G:c8|tvrdSt| S)z8Return True if the feature's deps are already satisfied.F)r rrs r is_availablers#iuw'' ''r Optional[str]cv|tvrdSt|}ddd|DzS)zFReturn the ``pip install`` command a user could run manually, or None.Nzuv pip install rc34K|]}t|VdSrrr!s rr$z*feature_install_command..s('?'?AQ'?'?'?'?'?'?r)r r%)r rzs rfeature_install_commandrsBit g E sxx'?'?'?'?'??? ??r list[str]cg}tD]3\}}td|Dr||4|S)aReturn the list of features the user has ever lazy-installed. A feature counts as "active" if at least one of its declared packages is currently installed in the venv (presence check, ignoring version). Features the user has never enabled stay quiet. Used by ``hermes update`` to figure out which lazy backends need a refresh pass when pins move in :data:`LAZY_DEPS`. c34K|]}t|VdSr)rxr!s rr$z"active_features..s(--!{1~~------r)r itemsrWappend)activer rzs ractive_featuresrs]F#//++## --u--- - - # MM' " " " MrFdict[str, str]cdi}tD]}t|}|sd||< t||d||<1#t$rG}dt |vsdt |vrd|j||<n d|j||<Yd}~}d}~wt $r}d|||<Yd}~d}~wwxYw|S) ujRe-run ``ensure`` for every feature the user has previously activated. Returns a ``{feature: status}`` map where status is one of: ``"current"`` — pins already satisfied, no install run ``"refreshed"`` — pins were stale, reinstall succeeded ``"failed: "`` — install attempt failed; caller decides whether to surface it (we don't raise) ``"skipped: "`` — gated off (config flag, user decline) Intended for ``hermes update``. Never raises; lazy-install failures here must not block the rest of the update flow. currentr refreshedzlazy installs disableddeclinedz skipped: zfailed: N)rrrr rrr?)rresultsr rrs rrefresh_active_featuresr s!G"$$..!'** (GG   . 76 * * * **GG  ! 9 9 9(3q6611Z3q665I5I#9qx#9#9  #8ah#8#8  . . .-!~~GG       . Ns#A B- =B B-B((B-importerCallable[[], dict[str, Any]]target_globalsdictc t||n#ttf$rYdSwxYw |}n#t$rYdSwxYw||dS)aEnsure a feature is installed, then rebind names into the caller's globals. Combines :func:`ensure` with a post-install import step that rebinds module-level names. This eliminates the error-prone pattern of manually listing every global that needs updating after lazy-install. ``importer`` is a zero-arg callable that returns a dict of ``{name: value}`` for all symbols the caller needs rebound. It is called only after :func:`ensure` succeeds (or if the packages are already installed). Returns True on success, False if deps couldn't be installed or imported. Example usage in a platform adapter:: def check_slack_requirements() -> bool: if SLACK_AVAILABLE: return True def _import(): from slack_bolt.async_app import AsyncApp from slack_bolt.adapter.socket_mode.async_handler import AsyncSocketModeHandler from slack_sdk.web.async_client import AsyncWebClient import aiohttp return { "AsyncApp": AsyncApp, "AsyncSocketModeHandler": AsyncSocketModeHandler, "AsyncWebClient": AsyncWebClient, "aiohttp": aiohttp, "SLACK_AVAILABLE": True, } return ensure_and_bind("platform.slack", _import, globals(), prompt=False) rFT)rr r?rpupdate)r rrrbindingss rensure_and_bindr.sNwv&&&&&  *uu8:: uu(### 4s)) 8 AA)rr/)rDrrr/)rDrrr)rzrryr{rr.)r rrr)r rrr/rr)r rrr/)r rrr)rr)rr/rr) r rrrrrrr/rr/)*r* __future__rloggingr;r^rrr dataclassesrpathlibrtypingrrr getLoggerr'rr r3compilerY RuntimeErrorr r.rCr[rbrfrvrxrrrrrrrrrr4rrrs,111f#"""""  !!!!!!**********  8 $ $[)0 [) + [)%[)1[)/[).$/[)0-1[)67[)D(E[)J*K[)L4M[)RAS[)^K_[)`a[)jk[)xy[)BC[)N(-) 82o[)[)[) [[[[BRZ          , $&((((%%%%    ))))X(AD6E6E6E6E6E6E|LLLL ,0QAQAQAQAQAQAh((((@@@@"/4N 22222222r