From 66a38574a506c8f76433da0ea5917e28cd413524 Mon Sep 17 00:00:00 2001
From: TianHengZhuang <39034691+TianHengZhuang@users.noreply.github.com>
Date: Mon, 7 Sep 2026 11:05:40 +0800
Subject: [PATCH] docs: add ModuleProtocol

---
 .../probe_data/modules/module_protocol.py     | 46 +++++++++++++++++++
 1 file changed, 46 insertions(+)
 create mode 100644 agentic_security/probe_data/modules/module_protocol.py

diff --git a/agentic_security/probe_data/modules/module_protocol.py b/agentic_security/probe_data/modules/module_protocol.py
new file mode 100644
index 0000000..30355ba
--- /dev/null
+++ b/agentic_security/probe_data/modules/module_protocol.py
@@ -0,0 +1,46 @@
+""":mod:`module_protocol` -- Base protocol for probe data modules.
+
+Defines the abstract Protocol that all probe data modules must implement,
+providing a standardized interface for module initialization and execution.
+
+See Also:
+    :mod:`agentic_security.probe_data.modules.garak_tool`
+    :mod:`agentic_security.probe_data.modules.fine_tuned`
+    :mod:`agentic_security.probe_data.modules.inspect_ai_tool`
+    :mod:`agentic_security.probe_data.modules.rl_model`
+    :doc:`/external_module`
+"""""
+
+from typing import Protocol, Any, AsyncGenerator, runtime_checkable
+
+
+@runtime_checkable
+class ModuleProtocol(Protocol):
+    """:class:`Protocol` defining the interface for probe data modules.
+
+    All modules in :mod:`agentic_security.probe_data.modules` share the same
+    constructor signature and the same async ``apply`` generator method.
+    The protocol captures these shared elements to support type checking.
+
+    Attributes:
+        prompt_groups: List of prompt groups to be processed.
+        tools_inbox: Async queue that receives tool execution results.
+        opts: Module-specific configuration dictionary.
+
+    Note:
+        Use the concrete :class:`Module` base class rather than this
+        protocol directly. This protocol exists to document the shared
+        interface and to enable runtime type checking.
+    """
+
+    prompt_groups: list[Any]
+    tools_inbox: asyncio.Queue
+    opts: dict
+
+    async def apply(self) -> AsyncGenerator[str, None]:
+        """Execute the module and yield result messages.
+
+        Yields:
+            str: Result messages generated during module execution.
+        """
+        ...
\ No newline at end of file