ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

モジュール間通信

Tip

この記事を読むタイミング:RPCによるモジュール間呼び出し、サービス契約、宛先指定イベント、またはコールドスタート時のイベントリプレイが必要な場合。必要なければ飛ばしても、他の機能の使用に影響はありません。

この記事を読んだ後には:3層通信モデル(RPC / 宛先指定イベント / ブロードキャスト)の選択のコツ、meta.services によるサービス契約とサービスディレクトリ、出向き監査の設定方法、およびラグドウォーキングとコールドスタート時のイベントリプレイについて理解できます。

この記事では扱いません:ライフサイクルイベントシステム自体の登録 / 発火 / 優先度のメカニズム(ライフサイクル管理を参照);ラグドロードの設定と activate_on の宣言(ラグドロードシステムを参照)。

Note

本章の内容は ErisPulse 2.8.0+ が必要です。

ErisPulse では、モジュール間には3層の通信モデルが存在し、「点対点 → 宛先指定 → ブロードキャスト」の順序で構成されています:

層 API 意味 代表的なシナリオ
RPC await sdk.module.call("Chat", "get_history", ...) 点対点のリクエスト-レスポンス、契約 / 監査 / タイムアウト付き 他のモジュールの機能を呼び出す(履歴の取得、翻訳、返金など)
宛先指定イベント await lifecycle.emit("message_received", {...}, to="Chat") 指定されたモジュールが登録したライフサイクルフックにのみ配信 上流の状態変化を下流に通知する(「新しいメッセージを受け取りました」など)
ブロードキャスト await lifecycle.emit("config.updated", {...}) フレームワーク全体で見えるライフサイクルイベント 設定のホットアップデート、モジュールの起動 / 終了

{!--< tips >!--} 選択のコツ:返り値が必要な場合は call を使い、特定のモジュールのフックに通知したい場合は emit(..., to=...) を使い、全員に通知したい場合は emit(...) を使う。 {!--< /tips >!--}

RPC: module.call

result = await sdk.module.call("Chat", "get_history", session_id, n=20)

sdk.module.Chat.get_history(...)(変更なし)の属性アクセスとの違いは以下の通りです:

module.call() 属性アクセス
目標が登録されていない / 有効になっていない ModuleNotAvailableError をスロー AttributeError をスロー
ラグジュアリーなモジュール 自動的に起動(イベント駆動モジュールはアクティベーションロックを通過) 非同期初期化モジュールは RuntimeError をスロー
current_owner ターゲットモジュールに帰属(内部の wait_reply / 送信 / ログは正しい帰属) 呼び出し元に保持
タイムアウト 30秒(timeout= で上書き、None でタイムアウトなし) なし
scope 審査 呼び出し元が出口のゲートを通過 actions.<呼び出し元>.call なし
契約検証 meta.services のホワイトリスト なし

エラー体系

ModuleError                      # モジュールシステムのエラー基底クラス
└── ModuleCallError              # 跨モジュール呼び出しの基底クラス(module / method 属性を含む)
    ├── ModuleNotAvailableError  # 目標が登録されていない / 有効になっていない / 起動に失敗
    ├── ServiceNotProvidedError  # メソッドが services ホワイトリストにない / 私的メソッド / 存在しない
    └── ModuleCallTimeoutError   # クロージャー関数がタイムアウト

すべて ErisPulseError 体系に属し、from ErisPulse.Core import ModuleCallError でキャッチ可能です。

サービス契約: meta.services

サービス提供者は get_meta() で公開するホワイトリストを宣言します(commands と対称):

from ErisPulse.Core.Bases import BaseModule, ModuleMeta

class ChatModule(BaseModule):
    @staticmethod
    def get_meta() -> ModuleMeta:
        return ModuleMeta(
            name="チャット",
            services=[
                "get_history",                                       # 簡単な形
                {"name": "translate", "description": "テキストを指定された言語に翻訳する"},  # 説明付き
            ],
        )

    async def get_history(self, session_id, n=20): ...
    async def translate(self, text, target_lang): ...
    def _internal_helper(self): ...   # 下線付きメソッドは外部から呼び出し禁止

開発者は無感覚なデフォルト:

  • services を宣言していない → 公開メソッドはすべて module.call() で呼び出せる(属性アクセスと同様)、宣言は不要
  • 宣言後 → ホワイトリストに絞られ、越境呼び出しは ServiceNotProvidedError をスロー——「これが外部に約束したメソッド」を明示する
  • 制限の主制御権はユーザー側:scope.actions の設定が「誰が誰を呼び出せるか」を決定(後述の審査参照)、モジュール作者の services はサービス面の宣言に過ぎず、2つの層は互いに置換不可能

サービス紹介:各サービスに人間 / AI が読める説明を付ける——不要なら何も書かなくてよい、説明はメソッドの docstring 首行(フレームワークは docstring 形式を要求している)から自動取得:

async def translate(self, text, target_lang):
    """テキストを指定された言語に翻訳する"""    # ← この行がサービス紹介として自動取得される
    ...

パラメータ提示:呼び出し元(特に AI エージェント)は各パラメータの意味を知る必要がある。不要なら何も書かなくてよい、提示はメソッドの docstring の :param: 行から自動取得:

async def render_card(self, html, width=800, height=0):
    """HTMLを画像ファイルにレンダリングする

    :param html: レンダリングするHTMLテキスト          ← 自動的にパラメータ提示として取得される
    :param width: 画布の幅ピクセル、0は内容に応じて自動調整
    :param height: 画布の高さピクセル、0は内容に応じて自動調整
    """

微調整が必要な場合(docstring を上書き / 多言語対応)は dict 形式で description と parameters を宣言(両方とも i18n 辞書に対応;parameters はパラメータと docstring をマージし、docstring が優先、宣言されたが存在しないパラメータはフィルタリングされる):

services=[
    {"name": "translate", "description": "テキストを指定された言語に翻訳する"},
    {"name": "summarize", "description": {"i18n": "Chat.meta.svc.summarize", "default": "会話の要約"}},
    {
        "name": "render_card",
        "description": "HTMLを画像ファイルにレンダリングする",
        "parameters": {"html": "HTMLテキスト", "width": "幅ピクセル、0は自動調整"},
    },
]

サービスディレクトリ: services()

sdk.module.services()
# {'Chat': [{'name': 'get_history', 'signature': '(session_id, n=20)',
#            'description': 'テキストを指定された言語に翻訳する',
#            'parameters': {'session_id': 'セッションID', 'n': '返却件数'}}]}

sdk.module.services("Chat")   # 指定されたモジュールのみを照会
  • 明示的に meta.services を宣言したモジュールのみをリストアップ(宣言していないモジュールはディレクトリに表示されない)
  • 各サービスにはメソッドのシグネチャ文字列(inspect.signature から抽出)、説明文、パラメータ提示が付く
  • ラグジュアリーなモジュールもディレクトリに表示される(サービス発見はロードより先に発生)——呼び出し元はこれにより、call() でターゲットモジュールを起動するかを判断できる
  • トポロジーにも反映される:sdk.module.get_topology() の各モジュール項目に services フィールドが含まれる

{!--< tips >!--} MCP 化の道筋:サービスディレクトリ(名前 + シグネチャ + 説明 + パラメータ提示)は MCP tool の形状に相当する——各サービスは自然に {"name", "description", "parameters"} になる。将来、フレームワークは services() を直接 MCP サーバエンドポイントとして公開し、AI がモジュールの能力を発見して呼び出せるようにする。また、scope.actions.call 審査は AI 呼び出しのセキュリティゲートとして自然に機能する。 {!--< /tips >!--}

出力審査: 誰が誰を呼び出せるか

module.call() は呼び出し元モジュールの立場で scope の出力ゲートを通過する:

[ErisPulse.scope.actions.CallerModule.call]
deny = ["Chat.get_history"]        # CallerModule が Chat の get_history を呼び出すことを禁止
# allow = ["Chat.get_*"]           # またはホワイトリスト:get で始まるサービスのみを許可
  • name の形式は <ターゲットモジュール>.<メソッド名>、正確な一致 / glob / re: 正規表現が可能
  • フレームワーク層の呼び出し(owner コンテキストがない、例:起動スクリプト)は審査制約を受けない
  • 拒否された呼び出しは ModuleCallError をスロー(TRACE ログ core.module.call_denied)

設定方法は 作用域(scope) の出力側の詳細を参照。

指定イベント: lifecycle.emit の to パラメータ

ライフサイクルイベントは指定送信をサポート:to でターゲット所有者(owner)を指定すると、イベントはその owner として登録されたフックにのみ配信される(on_load 内で登録されたフックは自動的に本モジュールに帰属)、他のモジュールやワイルドカード * ハンドラは感知しない。

from ErisPulse.Core.lifecycle import lifecycle

# 投递元:イベントは Chat モジュールが登録したフックにのみ投递される
await lifecycle.emit("message_received", {"text": "hi", "from": "u1"}, to="Chat")

# 訂閱元(Chat モジュール内):同名のフックを登録し、owner は登録時に自動的に記録される
@lifecycle.on("message_received")
async def on_message_received(data): ...

@lifecycle.on("message")          # 点式の親前缀も同様に有効(owner でフィルタリング)
async def on_any(data): ...

意味の詳細:

  • ターゲット owner に登録されたフックがない → イベントは静かに破棄(存在しない場所には送らない)、lifecycle.has_handlers("message_received") で事前に検出可能
  • data が dict の場合、_trace_id が自動的に付与される(既存値を上書きしない)、全トラッキングと連携
  • ブロードキャストと指定は同じフック登録を共有:emit(...) に to を指定しないと全フレームワークにブロードキャスト、to を指定すると同一イベントはターゲットモジュールにのみ見える
  • emit_sync / submit_event(互換 API)も to= パラメータをサポート

Note

指定イベントは軽量な通知であり、ターゲットの検証やラグジュアリーな起動は行わない;ターゲットの存在性検証、契約審査、または返り値が必要な場合は、RPC: module.call を使用してください。

ラグジュアリーなモジュールと呼び出し

module.call() はラグジュアリーなモジュールに対して透明な起動を行う:

  • イベント駆動ラグジュアリーなモジュール(activate_on で宣言)→ 活性化ロック _activate() を通る、活性化後はトリガースタブが自動的に登録解除
  • 通常のラグジュアリーなモジュール → 同期初期化または通常のロード経路(冪等)
  • 起動に失敗 → ModuleNotAvailableError

つまり:呼び出し元はターゲットモジュールがロードされているかどうかを気にする必要はない、また、ターゲットを起動するために特定のイベントを待つ必要もない。

指定イベント(lifecycle.emit(..., to=...))はラグジュアリーな起動を行わない——ターゲットがロードされていないとフックが存在しない、イベントは静かに破棄される;確実に送信したい場合は module.call() を使用してください。

クールスタート時の再再生

新規インストール / 再起動のモジュールは一部のチャットを逃した——get_load_strategy(replay=...) により、フレームワークはモジュールが準備された後、会話の受信箱に含まれる最近のメッセージを再再生してモジュール自身に送る:

from ErisPulse.loaders import ModuleLoadStrategy

class MyAIModule(BaseModule):
    @staticmethod
    def get_load_strategy():
        return ModuleLoadStrategy(
            lazy_load=False,
            priority=100,
            replay="5m",        # 最近の5分間を再再生("1h" / "300"秒の形式も可)
        )

    async def on_load(self, event):
        @message.on_message()
        async def handle(e):
            if e.get("replayed"):
                # 合成イベント:コンテキストの補完のみ、送信などの副作用は発生しない
                ...

意味の詳細:

  • データソースは会話の受信箱(sdk.transcript.recent())であり、モジュールのロード完了後にバックグラウンドで実行され、起動をブロックしない
  • 合成イベントには replayed: True フラグ、platform / detail_type / user_id / alt_message が含まれ、本モジュールのハンドラにのみ分発される——他のモジュールには再再生の影響を受けない
  • 受信箱が有効 / 記録がない / 時間の宣言が不正(replay_invalid 警告)の場合は静かにスキップされる

イベントの冪等性と重複除去

プラットフォームの websocket 再接続後に同じイベントが重複送信されることがよくある(同じ event["id"])——配信エントリは id に基づいて LRU で重複除去(容量 4096)、同じ id のイベントは1回しか配信されない。

[ErisPulse.framework]
event_dedupe = true   # 既定で有効;テスト環境で固定 id の合成イベントを生成する場合は無効化可能

アダプターが登録(新接続のライフサイクルの起点)されたときに、自動的に重複除去キャッシュがリセットされる。

関連ドキュメント