feat(ai): add policy gateway, agent collaboration runtime, and LLM gateway hooks

- Policy gateway: regex-based content detection, sanitization, deny/allow/sanitize/require-approval actions
  with preflight, postflight, stream, and tool-call stages
- Agent collaboration runtime: bounded multi-agent orchestration with hop limits,
  deque-based message routing, and optional policy gateway integration
- LLM gateway hooks: request_hook/response_hook seams on LlmGatewaySettings,
  threaded through sync and async complete() paths
- Policy-to-LLM bridge: build_llm_policy_hooks() integration + PolicyViolationError
- End-to-end recipe: offline demo combining all three components
- Documentation: user guides, recipes, API reference, component maturity model,
  mkdocs nav, README updates
- Tests: 21 new tests across policy gateway, agent collaboration, and LLM gateway hooks
  (164 total passing)

Author: inference-stack-llc

README.md

@@ -40,6 +40,7 @@ ElectriPy Studio is a curated collection of production-ready Python components a
 - 🤖 **AI building blocks**: Provider-agnostic LLM Gateway with sync/async clients and structured-output helpers, plus a RAG Evaluation Runner for retrieval benchmarking.
 - 📊 **AI Telemetry**: Provider-agnostic telemetry primitives and adapters (JSONL, optional OpenTelemetry) for HTTP resilience, LLM gateway, policy decisions, and RAG evaluation runs.
 - 🧠 **AI product engineering utilities**: Streaming chat primitives, deterministic agent runtime helpers, RAG quality/drift metrics, grounding checks for hallucination reduction, response robustness helpers for structured outputs, prompt templating and composition, token budget tracking and truncation, priority-based context window assembly, rule-based model routing, sliding-window conversation memory, and a declarative tool registry with JSON schema generation.
+- 🛡️ **AI policy and collaboration runtime**: Deterministic policy gateway checks for preflight/postflight/stream/tool flows, plus bounded agent-to-agent collaboration runtime for specialist orchestration patterns.
 
 ## Quick Start
 
@@ -123,8 +124,11 @@ Full documentation is available in the [docs/](docs/) directory:
 - [CLI Guide](docs/user-guide/cli.md)
 - [LLM Gateway & AI](docs/user-guide/ai-llm-gateway.md)
 - [AI Telemetry](docs/user-guide/ai-telemetry.md)
+- [AI Policy Gateway](docs/user-guide/ai-policy-gateway.md)
+- [AI Agent Collaboration Runtime](docs/user-guide/ai-agent-collaboration.md)
 - [RAG Evaluation Runner](docs/user-guide/ai-rag-eval-runner.md)
 - [AI Product Engineering Utilities](docs/user-guide/ai-product-engineering.md)
+- [Component Maturity Model](docs/user-guide/component-maturity.md)
 - [Recipes](docs/recipes/cli-tool.md)
 - [API Reference](docs/api.md)
 
@@ -153,7 +157,7 @@ electripy-studio/
 │   ├── core/               # Config, logging, errors, typing
 │   ├── concurrency/        # Retry & rate limiting
 │   ├── io/                 # JSONL utilities
-│   └── cli/                # CLI commands
+│   ├── cli/                # CLI commands
 │   └── ai/                 # AI building blocks and product-engineering utilities
 │       ├── llm_gateway/    # Provider-agnostic LLM client + structured output helpers
 │       ├── rag_eval_runner/# Dataset + eval runner + CLI benchmarking
@@ -167,11 +171,15 @@ electripy-studio/
 │       ├── context_assembly/    # Priority-based context window packing
 │       ├── model_router/        # Rule-based model selection and routing
 │       ├── conversation_memory/ # Sliding window and token-aware chat history
-│       └── tool_registry/       # Declarative tool definitions and JSON schema
+│       ├── policy_gateway/      # Deterministic pre/post/tool/stream policy decisions
+│       ├── tool_registry/       # Declarative tool definitions and JSON schema
+│       └── agent_collaboration/ # Bounded multi-agent handoff orchestration
 ├── tests/                  # Test suite
 ├── docs/                   # Documentation
 ├── recipes/                # Example recipes
-│   └── 01_cli_tool/        # CLI tool example
+│   ├── 01_cli_tool/        # CLI tool example
+│   ├── 02_llm_gateway/     # LLM gateway examples
+│   └── 03_policy_collaboration/ # End-to-end policy + multi-agent flow
 ├── packages/               # NPM packages
 │   └── electripy-cli/      # NPM CLI wrapper
 ├── pyproject.toml          # Project config

docs/api.md

@@ -141,6 +141,28 @@ Complete API reference for ElectriPy modules.
 - `ToolRegistry()`: Register, look up, and export tools.
 - `ToolRegistry.to_openai_tools() -> list[dict]`: Export in OpenAI function-calling format.
 
+### Policy Gateway
+
+- `PolicyGateway(rules=..., settings=..., telemetry=...)`: deterministic policy evaluation service.
+- `PolicyRule(rule_id, code, description, stage, pattern, ...)`: rule model.
+- `PolicyDecision`: action/result model with reason codes and optional sanitized text.
+- `PolicyAction`: `allow`, `sanitize`, `deny`, `require_approval`.
+- `build_llm_policy_hooks(gateway) -> tuple[request_hook, response_hook]`: bridge for LLM Gateway hooks.
+
+### Agent Collaboration Runtime
+
+- `CollaborationTask(task_id, objective, metadata=...)`: top-level collaboration task.
+- `AgentMessage(...)`: typed handoff envelope.
+- `AgentCollaborationRuntime(agents, settings=..., policy_gateway=...)`: bounded orchestration runtime.
+- `CollaborationRuntimeSettings(max_hops=..., fail_on_blocked_handoff=...)`: reliability controls.
+- `make_message(...) -> AgentMessage`: deterministic message factory.
+
+### LLM Gateway Policy Hooks
+
+- `LlmGatewaySettings.request_hook`: preflight request transform/block seam.
+- `LlmGatewaySettings.response_hook`: postflight response transform/block seam.
+- `PolicyViolationError(stage, reasons)`: raised by policy hooks when blocked.
+
 ---
 
 For more detailed examples, see the [User Guide](user-guide/core.md) and [Recipes](recipes/cli-tool.md).

docs/index.md

@@ -20,6 +20,8 @@ ElectriPy Studio is a curated collection of production-ready Python components a
 - **AI & LLM Gateway**: Provider-agnostic LLM clients with structured output and safety seams, plus a RAG Evaluation Runner for benchmarking retrieval quality.
 - **AI Telemetry**: Provider-agnostic telemetry primitives and adapters for HTTP resilience, LLM gateway, policy decisions, and RAG evaluation, with a safe-by-default posture.
 - **AI Product Engineering Utilities**: Streaming chat, deterministic agent runtime helpers, RAG quality/drift metrics, hallucination-risk grounding checks, response robustness helpers, prompt templating, token budget management, priority-based context assembly, rule-based model routing, conversation memory, and declarative tool registry.
+- **AI Policy Gateway**: Deterministic preflight/postflight/stream/tool policy decisions with allow/sanitize/deny/require-approval actions.
+- **AI Agent Collaboration Runtime**: Bounded specialist-agent orchestration with deterministic handoffs and optional policy checks.
 
 ## Documentation Map
 
@@ -37,7 +39,10 @@ ElectriPy Studio is a curated collection of production-ready Python components a
  - [LLM Gateway & AI](user-guide/ai-llm-gateway.md)
  - [AI Product Engineering Utilities](user-guide/ai-product-engineering.md)
  - [AI Telemetry](user-guide/ai-telemetry.md)
+ - [AI Policy Gateway](user-guide/ai-policy-gateway.md)
+ - [AI Agent Collaboration Runtime](user-guide/ai-agent-collaboration.md)
  - [RAG Evaluation Runner](user-guide/ai-rag-eval-runner.md)
+ - [Component Maturity Model](user-guide/component-maturity.md)
 
 ## Requirements
 

docs/recipes/agent-collaboration-runtime.md

@@ -0,0 +1,71 @@
+# Recipe: Specialist Agent Collaboration
+
+This recipe demonstrates a planner -> retriever -> verifier pipeline using the Agent Collaboration Runtime.
+
+## Scenario
+
+You want to run multiple specialist agents while keeping execution bounded and deterministic.
+
+## Example
+
+```python
+from electripy.ai.agent_collaboration import (
+    AgentCollaborationRuntime,
+    AgentTurnResult,
+    CollaborationTask,
+    make_message,
+)
+
+class PlannerAgent:
+    def handle(self, message, *, task):
+        return AgentTurnResult(
+            produced_messages=[
+                make_message(
+                    task_id=task.task_id,
+                    seq=1,
+                    from_agent="planner",
+                    to_agent="retriever",
+                    content=f"find evidence for: {task.objective}",
+                )
+            ]
+        )
+
+class RetrieverAgent:
+    def handle(self, message, *, task):
+        return AgentTurnResult(
+            produced_messages=[
+                make_message(
+                    task_id=task.task_id,
+                    seq=2,
+                    from_agent="retriever",
+                    to_agent="verifier",
+                    content="evidence: runbook#42",
+                )
+            ]
+        )
+
+class VerifierAgent:
+    def handle(self, message, *, task):
+        return AgentTurnResult(completed=True, outcome="verified")
+
+runtime = AgentCollaborationRuntime(
+    agents={
+        "planner": PlannerAgent(),
+        "retriever": RetrieverAgent(),
+        "verifier": VerifierAgent(),
+    }
+)
+result = runtime.run(
+    task=CollaborationTask(task_id="incident-7", objective="recover API service"),
+    entry_agent="planner",
+    input_text="start",
+)
+
+print(result.success, result.terminal_status, result.hop_count)
+```
+
+## Notes
+
+- Keep message payloads concise and structured.
+- Enforce max hops to prevent runaway loops.
+- Combine with Policy Gateway for handoff safety checks.

docs/recipes/policy-collaboration-e2e.md

@@ -0,0 +1,41 @@
+# Recipe: Policy + Collaboration End-to-End
+
+This recipe demonstrates a complete local flow that combines:
+
+- LLM Gateway request/response policy hooks
+- deterministic policy decisions
+- bounded agent collaboration
+- telemetry event capture
+
+## Scenario
+
+You want one run that proves policy, orchestration, and observability work together without network dependencies.
+
+## Run the demo script
+
+```bash
+python recipes/03_policy_collaboration/run_demo.py
+```
+
+## Expected behavior
+
+- inbound prompt content is evaluated in policy preflight
+- sensitive prompt fragments can be sanitized by request hooks
+- postflight checks run on model output before downstream usage
+- collaboration runtime executes bounded handoffs with deterministic results
+- policy decisions and outcomes are observable through telemetry
+
+## Key wiring
+
+```python
+from electripy.ai.llm_gateway import LlmGatewaySettings
+from electripy.ai.policy_gateway import PolicyGateway, build_llm_policy_hooks
+
+policy = PolicyGateway(rules=[...])
+request_hook, response_hook = build_llm_policy_hooks(policy)
+
+settings = LlmGatewaySettings(
+    request_hook=request_hook,
+    response_hook=response_hook,
+)
+```

docs/recipes/policy-gateway.md

@@ -0,0 +1,78 @@
+# Recipe: Policy-Governed LLM + Tool Flow
+
+This recipe shows how to enforce deterministic policy decisions around LLM calls and tool invocations.
+
+## Scenario
+
+You want to:
+
+- Sanitize PII from user prompts.
+- Require approval for high-risk tool calls.
+- Deny responses containing restricted markers.
+
+## Example
+
+```python
+from electripy.ai.policy_gateway import (
+    PolicyAction,
+    PolicyGateway,
+    PolicyRule,
+    PolicySeverity,
+    PolicyStage,
+    after_llm_response,
+    authorize_tool_call,
+    before_llm_request,
+)
+
+gateway = PolicyGateway(
+    rules=[
+        PolicyRule(
+            rule_id="pii-email",
+            code="PII_EMAIL",
+            description="Mask emails in inbound prompts.",
+            stage=PolicyStage.PREFLIGHT,
+            pattern=r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+",
+            action=PolicyAction.SANITIZE,
+        ),
+        PolicyRule(
+            rule_id="tool-delete",
+            code="TOOL_DELETE",
+            description="Delete operations require approval.",
+            stage=PolicyStage.TOOL_CALL,
+            pattern=r"drop|delete",
+            action=PolicyAction.REQUIRE_APPROVAL,
+            severity=PolicySeverity.HIGH,
+        ),
+        PolicyRule(
+            rule_id="secret-leak",
+            code="SECRET_LEAK",
+            description="Block secret markers in output.",
+            stage=PolicyStage.POSTFLIGHT,
+            pattern=r"SECRET_[A-Z0-9]+",
+            action=PolicyAction.DENY,
+        ),
+    ]
+)
+
+request_decision = before_llm_request(gateway, "Email me at [email protected]")
+if request_decision.action == PolicyAction.SANITIZE:
+    prompt = request_decision.sanitized_text or ""
+elif request_decision.blocked:
+    raise RuntimeError("Prompt blocked by policy")
+else:
+    prompt = "Email me at [email protected]"
+
+tool_decision = authorize_tool_call(gateway, "db.execute", {"sql": "drop table users"})
+if tool_decision.blocked:
+    raise RuntimeError("Tool call blocked or requires approval")
+
+response_decision = after_llm_response(gateway, "ok")
+if response_decision.blocked:
+    raise RuntimeError("Response blocked")
+```
+
+## Notes
+
+- Keep rules versioned and reviewable.
+- Start with redaction and explicit deny lists.
+- Integrate telemetry for audit trails.

docs/user-guide/ai-agent-collaboration.md

@@ -0,0 +1,59 @@
+# AI Agent Collaboration Runtime
+
+The Agent Collaboration Runtime orchestrates bounded, deterministic handoffs between specialist agents.
+
+## Why it exists
+
+As AI systems move from single-agent flows to specialist-agent teams, reliability depends on explicit message contracts and hop limits. This runtime coordinates those handoffs in-process and works with the Policy Gateway for safety.
+
+## Core concepts
+
+- `CollaborationTask`: top-level objective and metadata.
+- `AgentMessage`: typed message envelope between agents.
+- `CollaborationAgentPort`: handler protocol each agent implements.
+- `AgentCollaborationRuntime`: deterministic orchestration service.
+
+## Quick example
+
+```python
+from electripy.ai.agent_collaboration import (
+    AgentCollaborationRuntime,
+    AgentTurnResult,
+    CollaborationTask,
+    make_message,
+)
+
+class PlannerAgent:
+    def handle(self, message, *, task):
+        return AgentTurnResult(
+            produced_messages=[
+                make_message(
+                    task_id=task.task_id,
+                    seq=1,
+                    from_agent="planner",
+                    to_agent="verifier",
+                    content="plan ready",
+                )
+            ]
+        )
+
+class VerifierAgent:
+    def handle(self, message, *, task):
+        return AgentTurnResult(completed=True, outcome="verified")
+
+runtime = AgentCollaborationRuntime(
+    agents={"planner": PlannerAgent(), "verifier": VerifierAgent()}
+)
+result = runtime.run(
+    task=CollaborationTask(task_id="incident-1", objective="triage outage"),
+    entry_agent="planner",
+    input_text="begin",
+)
+```
+
+## Reliability guardrails
+
+- Deterministic message ordering.
+- Configurable max-hop limits.
+- Optional policy checks on inbound/outbound handoffs.
+- Full transcript output for replay and debugging.

docs/user-guide/ai-llm-gateway.md

@@ -49,6 +49,9 @@ Use the LLM Gateway when you want:
   - Observability hook: `LlmGatewaySettings.on_llm_call` – optional
     callback invoked after each successful LLM call with
     `(request, response, latency_ms)`.
+  - Policy hooks: `LlmGatewaySettings.request_hook` and
+    `LlmGatewaySettings.response_hook` for deterministic pre/post
+    request enforcement.
 
 ## Basic example: OpenAI text completion
 
@@ -218,3 +221,33 @@ client = build_llm_sync_client("openai", settings=settings)
 
 If the hook raises an exception, it is logged and ignored so that
 observability issues never break core LLM functionality.
+
+## Request/response policy hooks
+
+`LlmGatewaySettings` exposes two additional seams for enterprise policy
+enforcement:
+
+- `request_hook(request) -> request`: runs before budget and provider call.
+- `response_hook(request, response) -> response`: runs after provider call
+  and before returning to the caller.
+
+If these hooks block execution they can raise
+`PolicyViolationError(stage=..., reasons=...)`.
+
+```python
+from electripy.ai.llm_gateway import LlmGatewaySettings, PolicyViolationError
+from electripy.ai.policy_gateway import PolicyGateway, build_llm_policy_hooks
+
+policy = PolicyGateway(rules=[...])
+request_hook, response_hook = build_llm_policy_hooks(policy)
+
+settings = LlmGatewaySettings(
+  request_hook=request_hook,
+  response_hook=response_hook,
+)
+
+try:
+  response = client.complete(request)
+except PolicyViolationError as exc:
+  print(exc.stage, exc.reasons)
+```