fix: docs

docs/external_module.md

@@ -1,49 +1,60 @@
-## Module Interface Documentation
+# Module interface
 
-The ``Module`` class provides a standardized way to create and use probe data
-modules in the ``agentic_security`` project.
+Probe data modules in `agentic_security.probe_data.modules` share the same
+constructor arguments. `apply` yields result strings; some modules implement
+it as a sync iterator and others as an async iterator.
 
-All modules in :mod:`agentic_security.probe_data.modules` share the same
-constructor signature and the same ``apply`` async generator method. See the
-concrete implementations for real-world usage:
+Built-in examples:
 
-* :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`
+- `agentic_security.probe_data.modules.garak_tool`
+- `agentic_security.probe_data.modules.fine_tuned`
+- `agentic_security.probe_data.modules.inspect_ai_tool`
+- `agentic_security.probe_data.modules.rl_model`
 
-### Interface Summary
+## Constructor
 
-Every module class accepts three constructor arguments:
+```python
+def __init__(
+    self,
+    prompt_groups: list,
+    tools_inbox: asyncio.Queue,
+    opts: dict | None = None,
+): ...
+```
 
-``def __init__(self, prompt_groups: list[Any], tools_inbox: asyncio.Queue, opts: dict = {}): ...``
+`opts` is a module-specific dictionary. An omitted `opts` is treated as `{}`.
 
-The ``apply`` method is an async generator that yields result strings:
+## Usage
 
-``async def apply(self) -> AsyncGenerator[str, None]: yield "result message"``
+```python
+import asyncio
+from agentic_security.probe_data.modules.garak_tool import Module as GarakModule
 
-### Usage Example
+tools_inbox = asyncio.Queue()
+module = GarakModule(["group_a"], tools_inbox, {"port": 8718})
 
-``import asyncio``
-``from agentic_security.probe_data.modules.garak_tool import Module as GarakModule``
-``tools_inbox = asyncio.Queue()``
-``prompt_groups = ["group_a", "group_b"]``
-``opts = {"port": 8718}``
-``module = GarakModule(prompt_groups, tools_inbox, opts)``
-``async def main(): async for result in module.apply(): print(result)``
-``asyncio.run(main())``
+async def main():
+    async for result in module.apply():
+        print(result)
 
-### Defining a Custom Module
+asyncio.run(main())
+```
 
-``import asyncio``
-``from typing import Any``
-``class MyModule:``
-``    def __init__(self, prompt_groups, tools_inbox, opts={}):``
-``        self.prompt_groups = prompt_groups``
-``        self.tools_inbox = tools_inbox``
-``        self.opts = opts``
-``    async def apply(self):``
-``        for group in self.prompt_groups:``
-``            result = "processed {0}".format(group)``
-``            await self.tools_inbox.put({"message": result})``
-``            yield result``
+## Custom module
+
+```python
+import asyncio
+
+
+class MyModule:
+    def __init__(self, prompt_groups, tools_inbox, opts=None):
+        self.prompt_groups = prompt_groups
+        self.tools_inbox = tools_inbox
+        self.opts = opts or {}
+
+    async def apply(self):
+        for group in self.prompt_groups:
+            result = f"processed {group}"
+            await self.tools_inbox.put({"message": result})
+            yield result
+```