`gjdZddlmZddlZddlZddlZddlZddlmZm Z ddl m Z m Z m Z mZmZmZmZmZej&eZeGddZeGdd Zeeeeee ffZ eGd d ZeGd d ZeGddZedGddZd'dZd(dZd)dZ Gdde!Z" d*dZ#d+dZ$ d,dZ%ejLdejNejPzZ)d-dZ* d.dZ+d/dZ,d0d Z- d1d!Z.Gd"d#Z/ddd$ d2d%Z0gd&Z1y)3u Plugin LLM facade — host-owned LLM access for trusted plugins. ============================================================== Plugins built on Hermes Agent often need to make their own LLM calls out-of-band — a hook that rewrites a tool error before the user sees it, a gateway adapter that translates inbound text, a slash command that summarises a paste, a scheduled job that scores yesterday's activity into a single line on a status board. Today the only stable plugin surfaces extend an existing Hermes subsystem: ``register_tool``, ``register_platform``, ``register_memory_provider``, etc. None of those help when the plugin's job is to make its own model call. This module is the supported lane for that case. The plugin gets ``ctx.llm`` exposed on its :class:`~hermes_cli.plugins.PluginContext`: * ``complete(messages, ...)`` — chat completion against the user's active model + auth. * ``complete_structured(instructions=..., input=[...], json_schema=...)`` — bounded structured inference with optional image inputs, JSON schema validation, and parsed JSON output. * async siblings ``acomplete()`` / ``acomplete_structured()`` for plugins running on asyncio loops (gateway adapters, hooks). Provider/model/agent_id/profile are explicit keyword arguments — no embedded slugs, no shorthands. This mirrors Hermes' main config shape (``model.provider`` + ``model.model``) so plugin authors who already understand the host config don't have to learn anything new. The host owns provider routing, auth resolution, timeouts, and fallback. The plugin never sees raw OAuth tokens or API keys. All override knobs (``provider=``, ``model=``, ``agent_id=``, ``profile=``) are gated behind explicit per-plugin trust flags in ``config.yaml``:: plugins: entries: my-plugin: llm: allow_provider_override: true allow_model_override: true allowed_providers: [openrouter, anthropic] # optional allowed_models: [openai/gpt-4o-mini] # optional allow_agent_id_override: false allow_profile_override: false Untrusted plugins still get the default surface — they just can't steer provider, model, agent, or auth-profile selection. The trust gate is fail-closed: a missing config block means "no overrides," not "anything goes." Backed by :func:`agent.auxiliary_client.call_llm`, which already handles every provider, fallback chain, and per-task override Hermes supports. ) annotationsN) dataclassfield)Any AwaitableCallableDictListOptionalSequenceUnionc*eZdZUdZded<dZded<y)PluginLlmTextInputz&Text block in a structured input list.strtexttypeN)__name__ __module__ __qualname____doc____annotations__rC/root/.hermes/venv/lib/python3.12/site-packages/agent/plugin_llm.pyrrMs0 ID#rrcXeZdZUdZdZded<dZded<dZded <d Zded <d Z ded <y)PluginLlmImageInputaImage block in a structured input list. Either ``data`` (raw bytes) or ``url`` (http(s) or data: URL) must be provided. ``mime_type`` defaults to ``image/png`` when ``data`` is used and is required for non-PNG bytes to render correctly across providers. NzOptional[bytes]data Optional[str]url image/pngr mime_type file_nameimager) rrrrrrrr!r#rrrrrrUs;!D/ C Is IsD#rrcfeZdZUdZdZded<dZded<dZded<dZded<dZ ded<d Z d ed <y ) PluginLlmUsageuToken + cost usage for a completion. All fields optional — providers differ on what they return. ``cost_usd`` is the host's best estimate.rint input_tokens output_tokens total_tokenscache_read_tokenscache_write_tokensNOptional[float]cost_usd) rrrrr(rr)r*r+r,r.rrrr&r&rsHML#M3L#s $Ho$rr&creZdZUdZded<ded<ded<ded<eeZded <eeZ d ed <y ) PluginLlmCompleteResultz%Result of :meth:`PluginLlm.complete`.rrprovidermodelagent_iddefault_factoryr&usageDict[str, Any]auditN) rrrrrrr&r6dictr8rrrr0r0s7/ IM JM!.AE>A!$7E>7rr0ceZdZUdZded<ded<ded<ded<eeZded <d Zd ed <dZ ded <ee Z ded<y )PluginLlmStructuredResulta5Result of :meth:`PluginLlm.complete_structured`. ``parsed`` is set only when ``json_mode=True`` or ``json_schema`` is provided AND the response was valid JSON. ``content_type`` is ``"json"`` in that case, ``"text"`` otherwise (e.g. the model refused or the response wasn't requested as JSON).rrr1r2r3r4r&r6N Optional[Any]parsed content_typer7r8) rrrrrrr&r6r=r>r9r8rrrr;r;sO: IM JM!.AE>A FM L#!$7E>7rr;T)frozenceZdZUdZded<dZded<dZded <dZded <dZded <dZ ded <dZ ded <dZ ded<dZ ded<y) _TrustPolicyz0Resolved trust gate for one plugin's LLM access.r plugin_idFboolallow_provider_overrideNzOptional[frozenset]allowed_providersallow_any_providerallow_model_overrideallowed_modelsallow_any_modelallow_agent_id_overrideallow_profile_override) rrrrrrDrErFrGrHrIrJrKrrrrArAsb:N$)T)-1*1$$!&$&*.N'.!OT!$)T)#(D(rrAcF|xsdjjS)z;Lower-case + strip whitespace. Used for allowlist matching.r")striplower)raws r_normalize_refrPs I2    $ $ &&rct|tsy|Dcgc]}t|tst| }}d|v}|Dchc] }|s|dk7s |}}|r|s t dfS|r t ||fSt |fScc}wcc}w)uCoerce a YAML list into ``(frozenset_or_None, allow_any)``. ``["*"]`` (or any list containing ``"*"``) → ``(frozenset(), True)``. Any other list → ``(frozenset({...}), False)``. Missing / non-list → ``(None, False)`` meaning "no allowlist." )NF*T) isinstancelistrrP frozenset)rOitem normalized allow_anycleaneds r_coerce_allowlistrZs c4 36P4*T3:O.&PJPz!I *Cdts{tCGC{D  !9,, ; !!QCsB BB BBcD|s tdS ddlm}|xsi}|j d}t |t s t|S|j d}t |t s t|S|j |}t |t s t|S|j d}t |t s t|St|j d\}}t|j d \} } t|t|j d d | | t|j d d ||t|j d d t|j dd  S#t$rt|cYSwxYw)uRead ``plugins.entries..llm`` from config.yaml. Missing config → fully restrictive policy (default deny on every override). The policy is resolved per-call rather than cached so config edits take effect without restarting the agent. r")rBr) load_configpluginsentriesllmrHrErDFrGrJrK) rBrDrErFrGrHrIrJrK) rAhermes_cli.configr\ ExceptiongetrSr9rZrC) rBr\config plugins_cfgr^entryllm_cfgrHrIrErFs r_resolve_trust_policyrgsu b))11$"**Y'K k4 (i00ooi(G gt $i00 KK "E eT "i00iiG gt $i00&7 DT8U&V#NO,= '(-))  $W[[1JE%R S+-!'++.De"LM%' $W[[1JE%R S#GKK0H%$PQ  + 1i001sFFFceZdZdZy)PluginLlmTrustErrorz  ,,%&**-.((.(8(8'9:%&  *//1 ;(:M IIrct|trd|jdSt|trRd|j|j d}|j |j |d<|jr|j|d<|St|tr|jd}|dk(r1|jd}t|ts tdd|dS|dk(rld|vr|jds td d|jd|jd|jd xsd |jd xsd dStd|tdt|j)zyCoerce a structured input block to a plain dict the message builder understands. Unknown shapes raise ``ValueError``.rrrr$)rr!r#rrrz'text input block requires 'text' stringz0image input block requires 'data' bytes or 'url'r!r r#r")rrrr!r#zUnknown input block type: zUnsupported input block: )rSrrrr!r#rrr9rbr ValueErrorrr)blockdkindrs r_normalize_input_blockrzQsa%+, 33%,-  :: ! AfI 99yyAeH%yy  6>99V$DdC( !JKK"D1 1 7?U"599U+; !STT &)yy'"YY{3B{"YY{39r  5dX>?? 0e1E1E0FG HHrc g}g}|r|j|j|s||jd|r#|jddj|dg}|j} |r| d|} | tj|dd} | d | } |jd | d |D]} t| } | d d k(r|jd | d d .| d d k(s7| jdr|jdd| didb| jdxsd} t| ttfs t dtj| jd}| jdxsd}|jddd|d|id|jd|d|S#t t f$rt|} Y?wxYw)a;Build the OpenAI-style messages list for a structured call. The instructions become the first text part of the user message, followed by an optional ``Schema name: `` hint and an optional JSON-only directive when JSON output is requested. Image inputs are encoded as ``image_url`` parts. zlRespond with a single JSON object that matches the requested shape. Do not include prose or markdown fences.systemz )rolecontentz Schema name: FT) ensure_ascii sort_keysz JSON schema: rrurr$r image_url)rrrrz image input 'data' must be bytesasciir!r zdata:z;base64,user)appendrMjoinjsondumps TypeErrorrvrrzrbrSbytes bytearraybase64 b64encodedecode) instructionsinputs json_mode json_schema schema_name system_promptmessages sys_parts user_partsheader schema_textrwnormrb64mimes r_build_structured_messagesrvs &(HI,,./K+ 7 fkk)6LMN')J    !F8,[M: +**[uPTUK8-k];vv67%e, <6 !   vtF|D E &\W $xx!!'"'e!5# xx'.3!$ (:;$%GHH&&t,33G<xx ,; !!'"'5hse)D!E#!* OOV ;< O7:& +k*K +s>F88GGz```(?:json)?\s*(.+?)```ctj|}|r|jdjS|jS)zqPull the first fenced code block out of ``text`` if any. Returns ``text`` unchanged when no fence is present.) _FENCE_REsearchgrouprM)rmatchs r_strip_code_fencesrs:   T "E {{1~##%% ::<rct|s|y|sy tjt|}| ddl}|j |||dfS|dfS#tjtf$rYywxYw#t$rtjdY|dfSj$r}t d|j|d}~wwxYw)zReturn ``(parsed, content_type)``. ``content_type`` is ``"json"`` when parsing succeeded and (when a schema was given) validation passed; ``"text"`` otherwise.N)Nrrz2jsonschema unavailable; skipping schema validationz3Plugin LLM structured output did not match schema: r) rloadsrJSONDecodeErrorrv jsonschemavalidate ImportErrorloggerdebugValidationErrormessage)rrrr=rexcs r_parse_structured_textrs 0 .t45      4 6>66>  * - O LLM N 6> )) Eckk]S  s.A A( A%$A%(B7 B7B22B7cRt}t|dd|Sd fd }|dxs|d|_|dxs|d|_|dxs|j|jz|_|d xs|d |_|d xs|d |_|S)uPull token usage out of an OpenAI-shaped response object. Tolerant of provider differences — Anthropic via the auxiliary adapter exposes ``usage.prompt_tokens`` / ``usage.completion_tokens``; direct OpenAI also exposes ``cache_read_input_tokens``.r6Nct|d}|!ttrj|} | t |SdS#t t f$rYywxYw)Nr)getattrrSr9rbr'rrv)namevrOs r_gz_extract_usage.._gs[ Ct $ 9C. A ]3q6 1 1:&  s AAAA prompt_tokensr(completion_tokensr)r*cache_read_input_tokensr+cache_creation_input_tokensr,)rrreturnr')r&rr(r)r*r+r,)responser6rrOs @r_extract_usagers  E (GT *C { O,B>0BE01HR5HEN+Y0B0BUEXEX0XE !:;VrBU?VE!"?@\BG[D\E Lrc |jdj}t|dd}t|tr|St|t rg}|D]}t|t rJ|jddk(s(t|jdtsH|j|d]t|dd}t|ts{|j|dj|S y#tttf$rYywxYw)z@Pull the assistant text out of an OpenAI-shaped response object.rr~Nrrr") choicesrrrSrrTr9rbrrAttributeError IndexErrorr)rmsgr~partsparttxts r _extract_textrs q!))#y$/ gs #N gt $!E *dD)xx'61j&AQSV6W T&\2!$5C!#s+ S) *775> ! %  J 2   s(7C/;C/6C/2C/ #C//DDc|r|}n$ ddlm}|xsdjxsd}t |dd}t |t r$|jr|j}||fS|r|}||fS ddlm}|xsdjxsd}||fS#t$rd}Y~wxYw#t$rd}Y||fSwxYw) uDecide what to record as ``result.provider`` / ``result.model``. Precedence: 1. Explicit overrides win — if the plugin asked for ``provider="x"`` or ``model="y"``, that's what we record (it's what the call actually targeted). 2. Otherwise we ask the host for the current main provider/model via :func:`_read_main_provider` / :func:`_read_main_model`, since those are what ``call_llm`` resolves to when ``provider=None`` and ``model=None`` are passed through. They reflect runtime overrides set by ``set_runtime_main()``. 3. ``response.model`` (if present) overrides the recorded model string. Providers post-resolution often return a slightly different model id than the request (e.g. ``gpt-4o`` → ``gpt-4o-2024-08-06``); the plugin's audit log should reflect what actually ran. 4. If everything above is empty, fall back to ``"auto"`` / ``"default"`` so the result object has non-empty strings. r)_read_main_providerr"autor2N)_read_main_modeldefault)agent.auxiliary_clientrrMrarrSrr)provider_overridemodel_overriderr1rresponse_modelr2rs r_resolve_attributionrs4$  B+-3::<FHXw5N.#&>+?+?+A$$& U?  U?   ?%'-2446C)E U? H  E U? s##B4#B, B)(B), B=<B=c eZdZdZdddd ddZddddddddd ddZddddddddddddd dd Zddddddddd dd Zddddddddddddd dd Ze dd Z dd  ddZ dd  ddZ y) PluginLlmuHost-owned LLM access for one trusted plugin. Instances are constructed by :class:`hermes_cli.plugins.PluginContext` and exposed as ``ctx.llm``. Plugins should not instantiate this directly — the constructor binds plugin identity for trust-gate enforcement. N) policy_loader sync_caller async_callercL||_|xst|_||_||_yN) _plugin_idrg_policy_loader _sync_caller _async_caller)selfrBrrrs r__init__zPluginLlm.__init___s)$+D/D')r)r1r2 temperature max_tokenstimeoutr3profilepurposec |j|j} t| ||||\} } } }|j|| | ||||\}}}t |}t |}t |||| xsd||j| xsd|xsdd}tjd|j||| xsd|j|S)aRun a host-owned chat completion against the user's active model. ``messages`` is the standard OpenAI shape. ``provider``, ``model``, ``agent_id``, and ``profile`` follow the same explicit shape as the host's main config (``model.provider`` + ``model.model``). Each is independently gated by ``plugins.entries..llm.allow_*_override`` (see module docstring). rlrmrnrorrrprofile_overriderrrrr"rBrrrr1r2r3r6r8zGplugin_llm.complete plugin=%s provider=%s model=%s purpose=%s tokens=%d) rrrs _invoke_syncrrr0rinfor*)rrr1r2rrrr3rrrk eff_provider eff_model eff_agent eff_profile real_provider real_modelrrr6results rcompletezPluginLlm.completens,$$T__5:J '!'% ; 7 iK/3.?.?*$(#!/@/ + z8X&x(("+)!__"=b&,"      OO]J 2      rF) rrrrr1r2rrrr3rrcf|r|js td|s td|j|j}t |||| | \}}}}t |t |||||}|j||}|j||||| | | |\}}}t|}t|}t|||\}}t||||xsd||||j|xsd |xsd |xsd d  }tjd |j|||xsd ||j|S) a?Run a bounded host-owned structured completion. ``input`` accepts text and image blocks (see :class:`PluginLlmTextInput` / :class:`PluginLlmImageInput`). When ``json_mode=True`` or ``json_schema`` is provided, the response is parsed and (if a schema is given) validated; the parsed value is returned in :attr:`PluginLlmStructuredResult.parsed`. Validation requires the optional ``jsonschema`` package. When it isn't installed, JSON mode still works but schema enforcement is skipped with a debug log. z3complete_structured requires non-empty instructionsz5complete_structured requires at least one input blockrrrrrrrrrrrrrrrr extra_bodyrrrrr"rBrrrrr1r2r3r6r=r>r8zbplugin_llm.complete_structured plugin=%s provider=%s model=%s purpose=%s content_type=%s tokens=%d)rMrvrrrsrrT_json_response_formatrrrrr;rrr*)rrinputrrrrr1r2rrrr3rrrkrrrrrrrrrrr6r=r>rs rcomplete_structuredzPluginLlm.complete_structureds}<<#5#5#7RS STU U$$T__5:J '!'% ; 7 iK.%;##'  //)Q\/] .2.?.?*$(#!!/@ / + z8X&x(5   +"+)%!__"=b&,"*0b     3 OO]J 2 %,,   rc 8K|j|j} t| ||||\} } } }|j|| | ||||d{\}}}t |}t |}t |||| xsd||j| xsd|xsddS7Iw)z"Async sibling of :meth:`complete`.rrNrr"rr)rrrs _invoke_asyncrrr0)rrr1r2rrrr3rrrkrrrrrrrrr6s r acompletezPluginLlm.acomplete s$$T__5:J '!'% ; 7 iK594F4F*$(#!5G5 / + z8X&x(&"+)!__"=b&,"  / sA BBA BcK|r|js td|s td|j|j}t |||| | \}}}}t |t |||||}|j||}|j||||| | | |d{\}}}t|}t|}t|||\}}t||||xsd ||||j|xsd |xsd |xsd d  S7aw) z-Async sibling of :meth:`complete_structured`.z4acomplete_structured requires non-empty instructionsz6acomplete_structured requires at least one input blockrrrrNrrr"rr) rMrvrrrsrrTrrrrrr;)rrrrrrrr1r2rrrr3rrrkrrrrrrrrrrr6r=r>s racomplete_structuredzPluginLlm.acomplete_structured7sX&<#5#5#7ST TUV V$$T__5:J '!'% ; 7 iK.%;##'  //)Q\/] 484F4F*$(#!!5G 5 / + z8X&x(5   )"+)%!__"=b&,"*0b    / sB$D &D'A"D c.| ddd|dddiS|rddd iiSy) zBuild the ``extra_body.response_format`` payload for the provider request. Falls back to ``json_object`` when no schema is given so providers that ignore json_schema still get a hint.Nresponse_formatrplugin_structured_outputF)rschemastrict)rrr json_objectrrs rrzPluginLlm._json_response_formatsE  "!) :"-"'$$   % '>? ?r)rc |j|j||||||||Sddlm} t|xsi} |r|| j did<| d||||||| xsd} t ||| \} } | | | fS) zInvoke the host's ``call_llm``. Lazy-imports ``agent.auxiliary_client`` to avoid circular deps at plugin discovery time.Nrr)call_llmmetadata auth_profiletaskr1r2rrrrrrrr)rrr r9 setdefaultr)rrrrrrrrrr  merged_extrarr1r2s rrzPluginLlm._invoke_syncs    ($$!"3-!1'%%%   4J,"- FVL # #J 3N C& #!#+t  //) % ((rc (K|j!|j||||||||d{Sddlm} t|xsi} |r|| j did<| d||||||| xsdd{} t ||| \} } | | | fS7b7w)Nrr)async_call_llmr r r r)rrrr9rr)rrrrrrrrrrrrr1r2s rrzPluginLlm._invoke_asyncs    )++!"3-!1'%%,    :J,"- FVL # #J 3N C'& #!#+t   //) % ((;   s")BBAB3B4BB) rBrrz'Optional[Callable[[str], _TrustPolicy]]rOptional[Callable[..., Any]]r'Optional[Callable[..., Awaitable[Any]]]rNone)rList[Dict[str, Any]]r1rr2rrr-r Optional[int]rr-r3rrrrrrr0)rrrSequence[PluginLlmInput]rr<rrCrrrrr1rr2rrr-rrrr-r3rrrrrrr;)rrCrr<rOptional[Dict[str, Any]])rrrrrrrrrr-rrrr-rrrztuple[str, str, Any]) rrrrrrrrr staticmethodrrrrrrrrVsBF48@D * *? * 2 * > *  *&#'#'+$(#'"&!%!%;&; ;  ; % ;";!; ;;; !;D&*%)'+"&#'+$(#'"&!%!%!ZZ( Z # Z  Z#Z%Z ZZ%Z"Z!Z ZZ !Z" ##ZD#'#'+$(#'"&!%!%, &,  ,  , % , ", !,  , , ,  !, f&*%)'+"&#'+$(#'"&!%!%!F F ( F # F  F #F %F  F F %F "F !F  F F !F " ##F T)6 !>04-)'-)) -) & -) ( -)%-)"-)!-)--) -)r04*)'*)) *) & *) ( *)%*)"*)!*)-*) *)rr)rrc(t|fd||S)zConstruct a :class:`PluginLlm` with an injected policy and caller. Used by unit tests that don't want to round-trip through config.yaml or hit a real provider. Not part of the public plugin API. cSrr)_pidrks rz*make_plugin_llm_for_test..s6r)rBrrr)r)rBrkrrs ` rmake_plugin_llm_for_testrs )!  r) rrrPluginLlmInputr&r0r;rir)rOrrr)rOrrz tuple[Optional[frozenset], bool])rBrrrA) rkrArlrrmrrnrrorrzAtuple[Optional[str], Optional[str], Optional[str], Optional[str]])rwr rr7)rrrrrrCrr<rrrrrr)rrrr)rrrrCrr<rztuple[Optional[Any], str])rrrr&)rrrr)rrrrrrrztuple[str, str]) rBrrkrArrrrrr)2r __future__rrrloggingre dataclassesrrtypingrrrr r r r r getLoggerrrrrrr r&r0r;rArPrZrgPermissionErrorrirsrzrcompileDOTALL IGNORECASErrrrrrrr__all__rrrr,s9v#  (RRR   8 $        )+>S#XNO  % %  % 88 8 88 8. $ ) ) )' "&,^G/GLJ LJ&LJ# LJ & LJ % LJGLJh"IJ>> %> >  >  >!>>L BJJ1299r}}3L M  !0=H8./$/"/ /  /nZ)Z)L 15<@  .  :   ( r