RmjIdZddlmZddlmZddlmZmZmZm Z ddl m Z m Z m Z mZmZmZmZmZddlmZmZmZmZmZmZmZmZmZmZmZmZm Z m!Z!m"Z"ddl#m$Z%ddl#m&Z'dd l#m(Z)dd l#m*Z+dd l#m,Z-dd l#m.Z/dd l#m0Z1ddl#m2Z3ddl#m4Z5e r ddl6m7Z7ddlm8Z8GddeZ9Gdde9dZ:GddeZ;edZ< GddeZ=GddeZ>Gdd eZ?dd!dPd(Z@dQd*ZAdQd+ZBed,-Gd.d/ZCed,-Gd0d1ZDed,-Gd2d3ZEed,-Gd4d5ZFGd6d7ZGdRd:ZHdRd;ZIdSd>Z.dTd@ZJed,dAdUdDZKdVdFZLdWdHZMdXdLZNdYdMZOgdNZPdOS)ZaGeneric plugin configuration and registration helpers. This module exposes the top-level plugin system used to validate and activate adaptive and custom plugin components. Component registration names are scoped per component by the runtime, so end users do not provide instance ids. ) annotations)asynccontextmanager) dataclassfieldfields is_dataclass) TYPE_CHECKING AsyncIteratorCallableLiteralProtocolSelf TypedDictcast)EventSanitizeGuardrailJson JsonObject LlmConditionalExecutionGuardrailLlmExecutionInterceptLlmRequestInterceptLlmSanitizeRequestGuardrailLlmSanitizeResponseGuardrailLlmStreamExecutionIntercept!ToolConditionalExecutionGuardrailToolExecutionInterceptToolRequestInterceptToolSanitizeGuardrailUnsupportedBehavior subscribers)_PluginHostActivation)active_plugin_report)clear_plugin_configuration)deregister_plugin)initialize_plugins)initialize_with_dynamic_plugins)list_plugin_kinds)register_plugin)validate_plugin_config) TracebackType)Eventc.eZdZUded<ded<ded<dS)_ConfigDiagnosticRequiredzLiteral['warning', 'error']levelstrcodemessageN)__name__ __module__ __qualname____annotations__Y/home/thesage/.hermes/hermes-agent/venv/lib/python3.11/site-packages/nemo_relay/plugin.pyr,r,Bs.&&&& IIILLLLLr6r,c(eZdZUdZded<ded<dS)ConfigDiagnosticz!One plugin validation diagnostic.r. componentrNr1r2r3__doc__r4r5r6r7r9r9Hs(++NNNJJJJJr6r9F)totalceZdZUdZded<dS) ConfigReportz4Validation or activation report for a plugin config.zlist[ConfigDiagnostic] diagnosticsNr;r5r6r7r?r?Os$>>''''''r6r?) rust_dynamicworkerceZdZdZd'dZd(d Zd(d Zd(dZd)dZd)dZ d*dZ d+dZ d,dZ d-dZ d.dZd/dZd0d!Zd1d#Zd2d%Zd&S)3 PluginContextzGComponent-scoped registration context passed to custom plugin handlers.namer.callbackCallable[[Event], None]returnNonecdS)z;Register an infallible event subscriber for this component.Nr5)selfrErFs r7register_subscriberz!PluginContext.register_subscriber\ r6priorityintrcdS)z3Register a mark event sanitizer for this component.Nr5rKrErNrFs r7 register_mark_sanitize_guardrailz.PluginContext.register_mark_sanitize_guardrail`rMr6cdS)z:Register a scope-start event sanitizer for this component.Nr5rQs r7'register_scope_sanitize_start_guardrailz5PluginContext.register_scope_sanitize_start_guardraild  r6cdS)z8Register a scope-end event sanitizer for this component.Nr5rQs r7%register_scope_sanitize_end_guardrailz3PluginContext.register_scope_sanitize_end_guardrailjrMr6rcdS)z>Register a tool sanitize-request guardrail for this component.Nr5rQs r7(register_tool_sanitize_request_guardrailz6PluginContext.register_tool_sanitize_request_guardrailnrUr6cdS)z?Register a tool sanitize-response guardrail for this component.Nr5rQs r7)register_tool_sanitize_response_guardrailz7PluginContext.register_tool_sanitize_response_guardrailtrUr6rcdS)zCRegister a tool conditional-execution guardrail for this component.Nr5rQs r7-register_tool_conditional_execution_guardrailz;PluginContext.register_tool_conditional_execution_guardrailzrUr6rcdS)z>Register an LLM sanitize-request guardrail for this component.Nr5rQs r7'register_llm_sanitize_request_guardrailz5PluginContext.register_llm_sanitize_request_guardrailrUr6rcdS)z?Register an LLM sanitize-response guardrail for this component.Nr5rQs r7(register_llm_sanitize_response_guardrailz6PluginContext.register_llm_sanitize_response_guardrailrUr6rcdS)zCRegister an LLM conditional-execution guardrail for this component.Nr5rQs r7,register_llm_conditional_execution_guardrailz:PluginContext.register_llm_conditional_execution_guardrailrUr6 break_chainboolrcdS)z5Register an LLM request intercept for this component.Nr5rKrErNrdrFs r7register_llm_request_interceptz,PluginContext.register_llm_request_interceptrUr6rcdS)z7Register an LLM execution intercept for this component.Nr5rQs r7 register_llm_execution_interceptz.PluginContext.register_llm_execution_interceptrMr6rcdS)zARegister an LLM streaming execution intercept for this component.Nr5rQs r7'register_llm_stream_execution_interceptz5PluginContext.register_llm_stream_execution_interceptrUr6rcdS)z5Register a tool request intercept for this component.Nr5rgs r7register_tool_request_interceptz-PluginContext.register_tool_request_interceptrUr6rcdS)z7Register a tool execution intercept for this component.Nr5rQs r7!register_tool_execution_interceptz/PluginContext.register_tool_execution_interceptrMr6N)rEr.rFrGrHrI)rEr.rNrOrFrrHrI)rEr.rNrOrFrrHrI)rEr.rNrOrFrrHrI)rEr.rNrOrFrrHrI)rEr.rNrOrFrrHrI)rEr.rNrOrFrrHrI) rEr.rNrOrdrerFrrHrI)rEr.rNrOrFrrHrI)rEr.rNrOrFrrHrI) rEr.rNrOrdrerFrrHrI)rEr.rNrOrFrrHrI)r1r2r3r<rLrRrTrWrYr[r]r_rarcrhrjrlrnrpr5r6r7rDrDYsFQQ                                                              r6rDc"eZdZdZd dZd d Zd S)Pluginz Custom plugin callback contract. plugin_configrrHlist[ConfigDiagnostic] | NonecdS)a(Validate one component-local config object. Args: plugin_config: The `config` object from a single component. Returns: A list of diagnostics, or `None` for no diagnostics. Behavior: Error diagnostics block `initialize(...)`. Nr5)rKrss r7validatezPlugin.validates  r6contextrDrIcdS)aInstall middleware and subscribers for one component instance. Args: plugin_config: The `config` object from a single component. context: Component-scoped registration context used to install middleware and subscribers. Returns: `None`. Behavior: Any exception aborts the current initialization and triggers rollback of partial registrations. Nr5)rKrsrws r7registerzPlugin.registers  r6N)rsrrHrt)rsrrwrDrHrI)r1r2r3r<rvryr5r6r7rrrrsB**           r6rrceZdZddZdS)_SupportsToDictrHrcdSNr5rKs r7to_dictz_SupportsToDict.to_dictsr6NrHr)r1r2r3rr5r6r7r{r{s((((((r6r{preserve_nullsvalueobjectrrerHrctdr'ttSt r1t t sfdtDSt trfdDSt tr fd DSttS)Nrcpi|]2}t|j}s||jt|3S)Nr)getattrrE _normalize).0 field_info field_valuerrs r7 z_normalize..sW    'z ? ?   "-!8 OZ NSSS"9!8!8r6c2g|]}t|S)rr)ritemrs r7 z_normalize..s&RRRD 4???RRRr6cti|]4\}}s| tt|t|p|dk5S)Nconfigr)rr.r)rkeyvalrs r7rz_normalize..sU   S "% cNNJs>;\ST\_]]]!0r6) hasattrrr{rr isinstancetyperlistdictitemsr)rrs``r7rrsui  6OU++33555E :eT#:#:      $Umm    %SRRRRERRRR%     !KKMM    e  r6rcFttt|Sr}rrrrs r7_normalize_objectrs  Ju-- . ..r6cJttt|dS)NTrrrs r7_normalize_component_configrs  JuTBBB C CCr6T)slotscFeZdZUdZdZded<dZded<dZded<d d Zd S) ConfigPolicyaPolicy for unsupported plugin configuration. Args: unknown_component: How to handle unknown component kinds. unknown_field: How to handle unknown fields inside known components. unsupported_value: How to handle known fields with unsupported values. Behavior: `"warn"` emits a warning diagnostic, `"error"` emits an error diagnostic that blocks initialization, and `"ignore"` suppresses the diagnostic entirely. warnrunknown_component unknown_fielderrorunsupported_valuerHrc,|j|j|jdS)z9Serialize this policy to the canonical JSON object shape.rrrrr~s r7rzConfigPolicy.to_dicts%"&!7!/!%!7   r6Nr) r1r2r3r<rr4rrrr5r6r7rrsk  .43333)/M////-44444      r6rcVeZdZUdZded<dZded<eeZded <d d Z d S) ComponentSpecaCOne top-level custom plugin component. Args: kind: Registered plugin kind string. enabled: Whether the component should be activated. config: Component-local JSON config object. Behavior: Disabled components are still validated but skipped during runtime registration. r.kindTreenableddefault_factoryrrrHcF|j|jt|jdS)z>   r6Nr) r1r2r3r<r4rrrrrr5r6r7rr sn  IIIGt444F4444      r6rcneZdZUdZdZded<eeZded<ee Z ded <dd Z d S) PluginConfiga|Canonical plugin configuration document. Args: version: Plugin config schema version. components: Ordered list of top-level components. This may mix `plugin.ComponentSpec(...)` and `adaptive.ComponentSpec(...)`. policy: Plugin-level unsupported-config policy. Behavior: Component order is preserved during initialization. rOversionrz list[object] componentsrpolicyrHrcd|jd|jD|jdS)z;Serialize this config to the canonical JSON document shape.c,g|]}t|Sr5r)rr:s r7rz(PluginConfig.to_dict..>s RRRY:i00RRRr6)rrr)rrrrr~s r7rzPluginConfig.to_dict:s<|RR$/RRRk))++   r6Nr) r1r2r3r<rr4rrrrrrr5r6r7rr(s  G$uT:::J:::: 5>>>F>>>>      r6rcjeZdZUdZded<ded<ded<dZded <ee Zd ed <ddZ dS)DynamicPluginActivationSpecaOne dynamic plugin component to load and activate. Args: plugin_id: Expected plugin identifier from the authored manifest. kind: Dynamic plugin execution lane. manifest_ref: Path to the authored ``relay-plugin.toml``. environment_ref: Optional lifecycle-managed environment path. Python workers require the path created by Relay's plugin lifecycle. config: Component-local JSON configuration. r. plugin_idDynamicPluginKindr manifest_refNz str | Noneenvironment_refrrrrHcx|j|j|jt|jd}|j |j|d<|S)zDSerialize this activation specification to its canonical JSON shape.)rrrrNr)rrrrrr)rKrs r7rz#DynamicPluginActivationSpec.to_dictVsKI -1$+>>      +'+';E# $ r6r) r1r2r3r<r4rrrrrr5r6r7rrCs  NNN"&O&&&&t444F4444      r6rcfeZdZdZdZddZedd Zedd Zdd Z ddZ ddZ dS)PluginHostActivationa$Owned lifetime for one process-wide dynamic plugin host. Keep this object alive while agent code may invoke callbacks from the loaded plugins. Prefer ``async with`` or call :meth:`close` explicitly. Native finalization performs best-effort cleanup when an object is dropped. _nativenative_NativePluginHostActivationrHrIc||_dSr}r)rKrs r7__init__zPluginHostActivation.__init__ms  r6r?c@tt|jjS)z8Return the validation report captured during activation.)rr?rreportr~s r7rzPluginHostActivation.reportpsL$,"5666r6rec|jjS)zReturn whether this activation handle has not begun teardown. ``False`` does not guarantee another process-wide activation can start; failed teardown may intentionally retain the activation owner. )r is_activer~s r7rzPluginHostActivation.is_activeus|%%r6cHK|jd{VdS)z.s!NNNd+D11NNNr6N) _initialize_with_dynamic_pluginsrr)rrnormalized_pluginsrs r7r%r%sV,ONoNNN34Ef4M4MOabb b b b b b bF  ' ''r6rIc"tdS)zClear the active plugin configuration. Returns: `None`. Behavior: This removes active component registrations but leaves the plugin kind registry intact for future validation or initialization. N)_clear_plugin_configurationr5r6r7clearrs !!!!!r6) clear_on_exitrAsyncIterator[ConfigReport]cKt|d{V} |WVtj|rtdSdS#tj|rtwwxYw)aContext manager for plugin initialization and cleanup. Args: config: `PluginConfig` or an equivalent JSON object. clear_on_exit: Whether to clear the plugin configuration on exit. Yields: The `ConfigReport` for the initialized configuration. Behavior: This context manager initializes the plugin configuration on entry and clears it on exit. N)rrflushr)rrreport_s r7pluginrsv&&&&&&&&G    GGGGG      GGGG s A&A+ConfigReport | NonecJttdztS)aMReturn the last successful plugin report. Returns: The active `ConfigReport`, or `None` when no plugin configuration is currently active. Behavior: This reports the last successfully activated configuration snapshot. It does not revalidate plugin state or inspect pending registrations. N)rr?_active_plugin_reportr5r6r7rrs   t#%:%<%< = ==r6 list[str]ctS)zList registered custom plugin kinds. Returns: A sorted list of plugin kind strings known to the plugin registry. Behavior: This reports available plugin kinds, not the currently active component set. )_list_plugin_kindsr5r6r7 list_kindsrs   r6 plugin_kindr.rc&t||dS)a Register a custom plugin implementation. Args: plugin_kind: Unique top-level component kind string. plugin: Custom plugin implementation. Returns: `None`. Behavior: Registering the same kind twice raises an error. N)_register_plugin)rrs r7ryry s[&)))))r6c t|S)a{Deregister a custom plugin kind. Args: plugin_kind: Kind string to remove from the plugin registry. Returns: `True` if a plugin was removed, otherwise `False`. Behavior: This affects future validation and initialization only. Active runtime registrations remain until `clear()` or the next successful `initialize(...)`. )_deregister_plugin)rs r7 deregisterrs k * **r6)rr9rr?rrrrDrrrr%rrrrryrrvN)rrrrerHr)rrrHr)rrrHr?)rrrrrHrr)rrrrerHr)rHr)rHr)rr.rrrrHrI)rr.rHre)Qr< __future__r contextlibr dataclassesrrrrtypingr r r r r rrr nemo_relayrrrrrrrrrrrrrrrnemo_relay._nativer rr!rr"rr#rr$rr%rr&rr'rr(rtypesr)r*r,r9r?rrDrrr{rrrrrrrrrvrrrrrryr__all__r5r6r7rs#"""""******>>>>>>>>>>>>cccccccccccccccccccc"TSSSSS!######        0(((((9((( 455Q Q Q Q Q HQ Q Q h      X    F)))))h)))9>*////DDDD         6         4         4 >++++++++\ R R R R TTTT"((((6 " " " "MQ, > > > >      * * * * ++++"   r6