agentctrl 0.1.0__py3-none-any.whl

agentctrl/__init__.py

@@ -0,0 +1,59 @@
+# Copyright 2026 Mohammad Abu Jafar
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""agentctrl — Institutional governance pipeline for AI agent actions.
+
+Usage:
+    from agentctrl import RuntimeGateway, ActionProposal
+
+    gateway = RuntimeGateway()
+    result = await gateway.validate(ActionProposal(
+        agent_id="my-agent",
+        action_type="data.read",
+        action_params={"classification": "PII"},
+        autonomy_level=2,
+    ))
+    print(result["decision"])  # ALLOW | ESCALATE | BLOCK
+"""
+
+from .types import (
+    ActionProposal,
+    PipelineStageResult,
+    PipelineHooks,
+    EscalationTarget,
+    RuntimeDecisionRecord,
+)
+from .runtime_gateway import RuntimeGateway
+from .policy_engine import PolicyEngine
+from .authority_graph import AuthorityGraphEngine
+from .risk_engine import RiskEngine, RiskScore
+from .conflict_detector import ConflictDetector
+from .decorator import governed, GovernanceBlockedError, GovernanceEscalatedError
+
+__all__ = [
+    "ActionProposal",
+    "PipelineStageResult",
+    "PipelineHooks",
+    "EscalationTarget",
+    "RuntimeDecisionRecord",
+    "RuntimeGateway",
+    "PolicyEngine",
+    "AuthorityGraphEngine",
+    "RiskEngine",
+    "RiskScore",
+    "ConflictDetector",
+    "governed",
+    "GovernanceBlockedError",
+    "GovernanceEscalatedError",
+]

agentctrl/adapters/__init__.py

@@ -0,0 +1,22 @@
+# Copyright 2026 Mohammad Abu Jafar
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Framework adapters for agentctrl.
+
+Each adapter is imported separately to avoid pulling in framework dependencies:
+
+    from agentctrl.adapters.langchain import govern_tool
+    from agentctrl.adapters.openai_agents import govern_tool
+    from agentctrl.adapters.crewai import govern_tool
+"""

agentctrl/adapters/crewai.py

@@ -0,0 +1,135 @@
+# Copyright 2026 Mohammad Abu Jafar
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""CrewAI adapter for agentctrl.
+
+Usage:
+    from agentctrl import RuntimeGateway
+    from agentctrl.adapters.crewai import govern_tool
+
+    gateway = RuntimeGateway()
+    governed = govern_tool(my_crewai_tool, gateway=gateway, agent_id="my-agent")
+
+    agent = Agent(role="analyst", tools=[governed])
+
+Requires: pip install agentctrl[crewai]
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional, Type
+
+try:
+    from crewai.tools import BaseTool as CrewBaseTool
+    from pydantic import BaseModel
+except ImportError as e:
+    raise ImportError(
+        "CrewAI adapter requires crewai. "
+        "Install with: pip install agentctrl[crewai]"
+    ) from e
+
+from ..runtime_gateway import RuntimeGateway
+from ..types import ActionProposal
+from ..decorator import GovernanceBlockedError, GovernanceEscalatedError  # noqa: F401 — re-exported
+
+
+class GovernedCrewTool(CrewBaseTool):
+    """CrewAI tool wrapper that runs governance before execution.
+
+    Wraps any existing CrewAI BaseTool. On BLOCK or ESCALATE, returns an
+    error string (CrewAI's standard pattern for tool failures — the agent
+    sees the reason and can report it).
+    """
+
+    name: str = ""
+    description: str = ""
+    args_schema: Optional[Type[BaseModel]] = None
+
+    _inner_tool: CrewBaseTool
+    _gateway: RuntimeGateway
+    _agent_id: str
+    _autonomy_level: int
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(
+        self,
+        tool: CrewBaseTool,
+        gateway: RuntimeGateway,
+        agent_id: str,
+        autonomy_level: int = 2,
+        **kwargs: Any,
+    ):
+        super().__init__(
+            name=tool.name,
+            description=tool.description,
+            args_schema=getattr(tool, "args_schema", None),
+            **kwargs,
+        )
+        self._inner_tool = tool
+        self._gateway = gateway
+        self._agent_id = agent_id
+        self._autonomy_level = autonomy_level
+
+    def _run(self, **kwargs: Any) -> str:
+        proposal = ActionProposal(
+            agent_id=self._agent_id,
+            action_type=self._inner_tool.name,
+            action_params=kwargs,
+            autonomy_level=self._autonomy_level,
+        )
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            loop = None
+
+        if loop and loop.is_running():
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor() as pool:
+                result = pool.submit(
+                    asyncio.run, self._gateway.validate(proposal)
+                ).result()
+        else:
+            result = asyncio.run(self._gateway.validate(proposal))
+
+        decision = result.get("decision", "BLOCK")
+
+        if decision == "BLOCK":
+            return f"[GOVERNANCE BLOCKED] {result.get('reason', 'Action not permitted.')}"
+        if decision == "ESCALATE":
+            return f"[GOVERNANCE ESCALATED] {result.get('reason', 'Human approval required.')}"
+
+        return self._inner_tool._run(**kwargs)
+
+
+def govern_tool(
+    tool: CrewBaseTool,
+    gateway: RuntimeGateway,
+    agent_id: str,
+    autonomy_level: int = 2,
+) -> GovernedCrewTool:
+    """Wrap a CrewAI tool with governance.
+
+    Returns a new tool that runs the governance pipeline before every invocation.
+    Drop-in replacement — same name, same schema, same interface.
+    """
+    return GovernedCrewTool(
+        tool=tool,
+        gateway=gateway,
+        agent_id=agent_id,
+        autonomy_level=autonomy_level,
+    )

agentctrl/adapters/langchain.py

@@ -0,0 +1,145 @@
+# Copyright 2026 Mohammad Abu Jafar
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""LangChain / LangGraph adapter for agentctrl.
+
+Usage:
+    from agentctrl import RuntimeGateway
+    from agentctrl.adapters.langchain import govern_tool
+
+    gateway = RuntimeGateway()
+    governed = govern_tool(my_langchain_tool, gateway=gateway, agent_id="my-agent")
+
+    # Use governed tool in any LangChain agent as usual
+    agent = create_react_agent(llm, [governed])
+
+Requires: pip install agentctrl[langchain]
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Type
+
+try:
+    from langchain_core.tools import BaseTool, ToolException
+    from langchain_core.callbacks import CallbackManagerForToolRun, AsyncCallbackManagerForToolRun
+    from pydantic import BaseModel
+except ImportError as e:
+    raise ImportError(
+        "LangChain adapter requires langchain-core. "
+        "Install with: pip install agentctrl[langchain]"
+    ) from e
+
+from ..runtime_gateway import RuntimeGateway
+from ..types import ActionProposal
+from ..decorator import GovernanceBlockedError, GovernanceEscalatedError  # noqa: F401 — re-exported
+
+
+class GovernedTool(BaseTool):
+    """LangChain tool wrapper that runs governance before execution.
+
+    Wraps any existing BaseTool. On BLOCK, raises ToolException (LangChain's
+    standard error path). On ESCALATE, raises ToolException with the escalation
+    reason so the agent can communicate it to the user.
+    """
+
+    name: str = ""
+    description: str = ""
+    args_schema: Optional[Type[BaseModel]] = None
+
+    _inner_tool: BaseTool
+    _gateway: RuntimeGateway
+    _agent_id: str
+    _autonomy_level: int
+
+    class Config:
+        arbitrary_types_allowed = True
+
+    def __init__(
+        self,
+        tool: BaseTool,
+        gateway: RuntimeGateway,
+        agent_id: str,
+        autonomy_level: int = 2,
+        **kwargs: Any,
+    ):
+        super().__init__(
+            name=tool.name,
+            description=tool.description,
+            args_schema=tool.args_schema,
+            **kwargs,
+        )
+        self._inner_tool = tool
+        self._gateway = gateway
+        self._agent_id = agent_id
+        self._autonomy_level = autonomy_level
+
+    def _run(
+        self,
+        *args: Any,
+        run_manager: Optional[CallbackManagerForToolRun] = None,
+        **kwargs: Any,
+    ) -> Any:
+        raise ToolException(
+            "GovernedTool requires async execution. Use ainvoke() or an async agent."
+        )
+
+    async def _arun(
+        self,
+        *args: Any,
+        run_manager: Optional[AsyncCallbackManagerForToolRun] = None,
+        **kwargs: Any,
+    ) -> Any:
+        proposal = ActionProposal(
+            agent_id=self._agent_id,
+            action_type=self._inner_tool.name,
+            action_params=kwargs if kwargs else {"input": args[0] if args else ""},
+            autonomy_level=self._autonomy_level,
+        )
+
+        result = await self._gateway.validate(proposal)
+        decision = result.get("decision", "BLOCK")
+
+        if decision == "BLOCK":
+            raise ToolException(
+                f"Governance blocked: {result.get('reason', 'Action not permitted.')}"
+            )
+        if decision == "ESCALATE":
+            raise ToolException(
+                f"Governance escalated: {result.get('reason', 'Human approval required.')}"
+            )
+
+        return await self._inner_tool.ainvoke(
+            kwargs if kwargs else (args[0] if args else ""),
+            config={"callbacks": run_manager.get_child() if run_manager else None},
+        )
+
+
+def govern_tool(
+    tool: BaseTool,
+    gateway: RuntimeGateway,
+    agent_id: str,
+    autonomy_level: int = 2,
+) -> GovernedTool:
+    """Wrap a LangChain tool with governance.
+
+    Returns a new tool that runs the governance pipeline before every invocation.
+    Drop-in replacement — same name, same schema, same interface.
+    """
+    return GovernedTool(
+        tool=tool,
+        gateway=gateway,
+        agent_id=agent_id,
+        autonomy_level=autonomy_level,
+    )

agentctrl/adapters/openai_agents.py

@@ -0,0 +1,141 @@
+# Copyright 2026 Mohammad Abu Jafar
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""OpenAI Agents SDK adapter for agentctrl.
+
+Usage:
+    from agentctrl import RuntimeGateway
+    from agentctrl.adapters.openai_agents import govern_tool
+
+    gateway = RuntimeGateway()
+    governed = govern_tool(my_function_tool, gateway=gateway, agent_id="my-agent")
+
+    agent = Agent(name="my-agent", tools=[governed])
+    result = Runner.run(agent, "do the thing")
+
+Requires: pip install agentctrl[openai-agents]
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable
+
+try:
+    from agents import FunctionTool, RunContext
+except ImportError as e:
+    raise ImportError(
+        "OpenAI Agents SDK adapter requires the agents package. "
+        "Install with: pip install agentctrl[openai-agents]"
+    ) from e
+
+from ..runtime_gateway import RuntimeGateway
+from ..types import ActionProposal
+from ..decorator import GovernanceBlockedError, GovernanceEscalatedError
+
+
+def govern_tool(
+    tool: FunctionTool,
+    gateway: RuntimeGateway,
+    agent_id: str,
+    autonomy_level: int = 2,
+) -> FunctionTool:
+    """Wrap an OpenAI Agents SDK FunctionTool with governance.
+
+    Returns a new FunctionTool that runs the governance pipeline before
+    every invocation. On BLOCK or ESCALATE, raises an exception that the
+    agent framework surfaces as a tool error.
+    """
+    original_fn = tool.on_invoke_tool
+
+    @functools.wraps(original_fn)
+    async def governed_invoke(ctx: RunContext, input_str: str) -> str:
+        proposal = ActionProposal(
+            agent_id=agent_id,
+            action_type=tool.name,
+            action_params={"input": input_str},
+            autonomy_level=autonomy_level,
+        )
+
+        result = await gateway.validate(proposal)
+        decision = result.get("decision", "BLOCK")
+
+        if decision == "BLOCK":
+            raise GovernanceBlockedError(
+                result.get("reason", "Action not permitted."), result
+            )
+        if decision == "ESCALATE":
+            raise GovernanceEscalatedError(
+                result.get("reason", "Human approval required."), result
+            )
+
+        return await original_fn(ctx, input_str)
+
+    governed = FunctionTool(
+        name=tool.name,
+        description=tool.description,
+        params_json_schema=tool.params_json_schema,
+        on_invoke_tool=governed_invoke,
+    )
+    return governed
+
+
+def governed_function(
+    gateway: RuntimeGateway,
+    agent_id: str,
+    autonomy_level: int = 2,
+    action_type: str | None = None,
+):
+    """Decorator for plain functions used as OpenAI agent tools.
+
+    Usage:
+        @governed_function(gateway=gateway, agent_id="my-agent")
+        async def send_email(to: str, subject: str, body: str) -> str:
+            ...
+    """
+    def decorator(fn: Callable) -> Callable:
+        resolved_action_type = action_type or fn.__name__
+
+        @functools.wraps(fn)
+        async def wrapper(*args: Any, **kwargs: Any) -> Any:
+            sig = inspect.signature(fn)
+            bound = sig.bind(*args, **kwargs)
+            bound.apply_defaults()
+            action_params = dict(bound.arguments)
+            action_params.pop("ctx", None)
+
+            proposal = ActionProposal(
+                agent_id=agent_id,
+                action_type=resolved_action_type,
+                action_params=action_params,
+                autonomy_level=autonomy_level,
+            )
+
+            result = await gateway.validate(proposal)
+            decision = result.get("decision", "BLOCK")
+
+            if decision == "BLOCK":
+                raise GovernanceBlockedError(
+                    result.get("reason", "Action not permitted."), result
+                )
+            if decision == "ESCALATE":
+                raise GovernanceEscalatedError(
+                    result.get("reason", "Human approval required."), result
+                )
+
+            return await fn(*args, **kwargs)
+
+        return wrapper
+    return decorator