Inter-Module Communication
Tip
When to read this: When you need cross-module calls (RPC), service contracts, directed events, or cold-start replay. Skip if not needed, as it won't affect the usage of other features.
After reading, you will know: The selection mnemonic for the three-layer communication model (RPC / directed events / broadcast),
meta.servicesservice contracts and service directory, outbound audit configuration, lazy wake-up, and cold-start replay.This section does not cover: The registration / triggering / priority mechanism of the lifecycle event system itself (see Lifecycle Management); lazy loading configuration and
activate_ondeclaration (see Lazy Loading System).
Note
This chapter requires ErisPulse 2.8.0+.
ErisPulse's modules have a three-layer communication model, arranged from "point-to-point → directed → broadcast":
| Layer | API | Semantics | Typical Scenarios |
|---|---|---|---|
| RPC | await sdk.module.call("Chat", "get_history", ...) |
Point-to-point request-response with contract / audit / timeout | Invoking capabilities of another module (e.g., fetching history, translation, refund) |
| Directed Events | await lifecycle.emit("message_received", {...}, to="Chat") |
Distributed only to lifecycle hooks registered by the specified module | Upstream state change notification to downstream (e.g., "a new message was received") |
| Broadcast | await lifecycle.emit("config.updated", {...}) |
Framework-wide lifecycle events | Hot configuration updates, module up/down events |
{!--< tips >!--}
Selection Mnemonic: Use call when you need a return value, use emit(..., to=...) to notify a specific module's hooks, and use emit(...) to notify everyone.
{!--< /tips >!--}
RPC: module.call
result = await sdk.module.call("Chat", "get_history", session_id, n=20)
Difference from direct attribute access sdk.module.Chat.get_history(...) (unchanged):
module.call() |
Direct attribute access | |
|---|---|---|
| Target not registered / enabled | Throws ModuleNotAvailableError |
Throws AttributeError |
| Lazy-loaded module | Automatically wakes up (event-driven modules use activation lock) | Async initialization throws RuntimeError |
current_owner |
Attributed to the target module (its internal wait_reply / send / logs are correctly attributed) | Maintains caller |
| Timeout | Default 30 seconds (timeout= overrides, None means no timeout) |
None |
| Scope audit | Caller passes through outbound gate actions.<caller>.call |
None |
| Contract validation | meta.services whitelist |
None |
Exception Hierarchy
ModuleError # Base class for module system exceptions
└── ModuleCallError # Base class for cross-module calls (includes module / method attributes)
├── ModuleNotAvailableError # Target not registered / enabled / activation failed
├── ServiceNotProvidedError # Method not in services whitelist / private method / does not exist
└── ModuleCallTimeoutError # Coroutine method timeout
All are part of the ErisPulseError hierarchy, and can be caught via from ErisPulse.Core import ModuleCallError.
Service Contract: meta.services
The service provider declares the whitelist of services offered externally in get_meta() (symmetrical to the commands field):
from ErisPulse.Core.Bases import BaseModule, ModuleMeta
class ChatModule(BaseModule):
@staticmethod
def get_meta() -> ModuleMeta:
return ModuleMeta(
name="Chat",
services=[
"get_history", # Simple form
{"name": "translate", "description": "Translate text into a specified language"}, # With description
],
)
async def get_history(self, session_id, n=20): ...
async def translate(self, text, target_lang): ...
def _internal_helper(self): ... # Methods with leading underscore are always prohibited from external calls
By default, services are invisible to developers:
- If
servicesis not declared → all public methods are naturally callable viamodule.call()(consistent with direct attribute access), no declaration is required - After declaration → the scope is restricted to the whitelist, calling outside the whitelist raises
ServiceNotProvidedError—used to mark "these methods are the ones promised externally" - The main control authority lies with the user:
scope.actionsconfiguration determines "who can call whom" (see audit below), the module author'sservicesis only a service declaration, and the two layers are independent
Service Descriptions: Provide human- or AI-readable descriptions for each service—leave empty if not needed, the description is automatically taken from the first line of the method's docstring (the framework already requires docstring style):
async def translate(self, text, target_lang):
"""Translate text into a specified language""" # ← This line automatically becomes the service description
...
Parameter Hints: The caller (especially AI agents) needs to know the meaning of each parameter. Leave empty if not needed,
hints are automatically taken from the :param: lines in the method's docstring:
async def render_card(self, html, width=800, height=0):
"""Render HTML into an image file
:param html: HTML text to render ← Automatically becomes the parameter hint
:param width: Canvas width in pixels, 0 for adaptive to content
:param height: Canvas height in pixels, 0 for adaptive to content
"""
For fine-grained control (overriding docstring or multi-language support), use the dict form to declare description and parameters
(both support i18n dictionaries; parameters are merged with the docstring by parameter, explicit declaration within a single parameter takes precedence,
parameters declared that do not exist in the signature are filtered):
services=[
{"name": "translate", "description": "Translate text into a specified language"},
{"name": "summarize", "description": {"i18n": "Chat.meta.svc.summarize", "default": "Summarize conversation"}},
{
"name": "render_card",
"description": "Render HTML into an image file",
"parameters": {"html": "HTML text", "width": "Width in pixels, 0 for adaptive"},
},
]
Service Directory: services()
sdk.module.services()
# {'Chat': [{'name': 'get_history', 'signature': '(session_id, n=20)',
# 'description': 'Translate text into the specified language',
# 'parameters': {'session_id': 'Session ID', 'n': 'Number of entries to return'}}]}
sdk.module.services("Chat") # Query only a specific module
- Only modules that explicitly declare
meta.servicesare listed (modules without declaration do not appear in the directory) - Each service includes a method signature string (extracted via
inspect.signature), description text, and parameter hints - Lazily loaded modules are also included in the directory (service discovery occurs before loading) — the caller can decide whether to
call()to activate the target module - Modules are also included in the topology: each entry in
sdk.module.get_topology()contains aservicesfield
{!--< tips >!--}
MCP Roadmap: The service directory (name + signature + description + parameter hints) naturally forms the shape of an MCP tool — each service becomes {"name", "description", "parameters"}. In the future, the framework could directly expose services() as an MCP server endpoint, allowing AI to discover and invoke module capabilities; scope.actions.call auditing naturally becomes a security gate for AI calls.
{!--< /tips >!--}
Outbound Audit: Who Can Call Whom
Each module.call() passes through the scope outbound gate as the caller module:
[ErisPulse.scope.actions.CallerModule.call]
deny = ["Chat.get_history"] # Deny CallerModule from calling Chat's get_history
# allow = ["Chat.get_*"] # Or whitelist: only allow calling Chat's get-* services
nameformat is<target module>.<method name>, supporting exact / glob /re:regex- Framework-level calls (without owner context, e.g., startup scripts) are not subject to audit constraints
- Denied calls throw
ModuleCallError(TRACE logcore.module.call_denied)
See Scope (scope) for configuration details on the outbound dimension.
Directed Events: lifecycle.emit with to parameter
Lifecycle events support directed propagation: when to specifies the target owner (owner), the event is only delivered to hooks registered by that owner (modules automatically register hooks in on_load and record the owner). Other modules and wildcard * handlers do not receive the event.
from ErisPulse.Core.lifecycle import lifecycle
# Emitter: event is only delivered to hooks registered by Chat module
await lifecycle.emit("message_received", {"text": "hi", "from": "u1"}, to="Chat")
# Subscriber (inside Chat module): register same-name hook, owner is automatically recorded during registration
@lifecycle.on("message_received")
async def on_message_received(data): ...
@lifecycle.on("message") # Point prefix also works (filtered by owner)
async def on_any(data): ...
Semantic details:
- If the target owner has no registered hooks → the event is silently discarded (does not send to non-existent places), use
lifecycle.has_handlers("message_received")to probe in advance - When
datais a dict, it automatically carries_trace_id(without overriding existing values), integrating with full-chain tracing - Broadcast and directed events share the same hook registration:
emit(...)withouttobroadcasts to the entire framework, while withtothe same event is only visible to the target module emit_sync/submit_event(compatibility API) also supportto=parameter
Note
Directed events are lightweight notifications, do not perform target validation or lazy activation; for target existence validation, contract audit, or return values, switch to RPC: module.call.
Lazy Loading and Invocation
module.call() transparently activates lazy-loaded modules:
- Event-driven lazy modules (
activate_ondeclared) → Use activation lock_activate(), stub automatically unregisters after activation - Regular lazy modules → Synchronous initialization or standard loading path (idempotent)
- Activation failure →
ModuleNotAvailableError
That is: the caller does not need to care whether the target module is loaded and does not need to wait for it to be activated.
Directed events (lifecycle.emit(..., to=...)) do not perform lazy activation—target not loaded means no hooks, event silently discarded; use module.call() if you need to ensure delivery.
Cold Start Replay
A newly installed / restarted module missed some chat messages—get_load_strategy(replay=...) allows the framework to replay the most recent messages from the session inbox to the module itself after it is ready:
from ErisPulse.loaders import ModuleLoadStrategy
class MyAIModule(BaseModule):
@staticmethod
def get_load_strategy():
return ModuleLoadStrategy(
lazy_load=False,
priority=100,
replay="5m", # Replay the last 5 minutes ("1h" / "300" seconds are also valid)
)
async def on_load(self, event):
@message.on_message()
async def handle(e):
if e.get("replayed"):
# Synthetic event: only supplement context, do not trigger side effects like sending
...
Semantic details:
- The data source is the session inbox (
sdk.transcript.recent()), executed in the background after module loading, without blocking startup - Synthetic events carry the
replayed: Trueflag, along with completeplatform / detail_type / user_id / alt_message, and are only distributed to the module's own handlers—other modules are unaffected by the replay - If the inbox is not enabled / no records exist / the replay duration is invalid (
replay_invalidwarning), it is silently skipped
Event Idempotency Deduplication
After platform websocket reconnection, the same event (with the same event["id"]) is often re-sent—event distribution entry deduplicates by id (capacity 4096), so the same id event is only distributed once.
[ErisPulse.framework]
event_dedupe = true # Default on; turn off for test environments with fixed id synthetic events
The deduplication cache is automatically reset when adapters register (start of new connection lifecycle).
Related Documentation
- Interaction Session System - wait_reply / timers / multi-wait / session mutual exclusion
- Scope (scope) - complete configuration for outbound dimension audit
- Ownership (owner) System - how owner context traverses cross-module calls
- Lazy Loading System - lazy loading and event-driven lazy activation (
activate_on) - Lifecycle Management - mechanism of the broadcast layer event bus