governor-sdk 0.2.0__py3-none-any.whl

governor/__init__.py

@@ -0,0 +1,109 @@
+"""GovernorAI SDK - Python client for GovernorAI AI governance.
+
+Quickstart:
+    pip install governor-sdk
+    export GOVERNOR_URL=https://gateway.governorai.ai
+    export GOVERNOR_API_KEY=gov_xxx
+
+    # One-line governance for any supported framework:
+    from governor import govern
+    governed_agent = govern(your_agent)
+"""
+
+from .client import (
+    AsyncGovernorAIClient,
+    GovernorAIApprovalRequired,
+    GovernorAIClient,
+    GovernorAIDenied,
+    GovernorAIError,
+)
+from .decorator import governed, governed_tool_call
+
+__version__ = "0.2.0"
+__all__ = [
+    "AsyncGovernorAIClient",
+    "GovernorAIClient",
+    "GovernorAIError",
+    "GovernorAIDenied",
+    "GovernorAIApprovalRequired",
+    "governed",
+    "governed_tool_call",
+    "govern",
+]
+
+
+def govern(agent, *, governor_url=None, api_key=None, agent_id=None, namespace="default"):
+    """Universal one-line governance wrapper.
+
+    Auto-detects the framework and wraps the agent/executor with GovernorAI
+    governance. Supports LangChain, CrewAI, LangGraph, and LlamaIndex.
+
+    Args:
+        agent: The agent/executor/crew/engine to govern
+        governor_url: Gateway URL (falls back to GOVERNOR_URL env var)
+        api_key: API key (falls back to GOVERNOR_API_KEY env var)
+        agent_id: Agent identifier (auto-derived if omitted)
+        namespace: Namespace for policy lookup
+
+    Returns:
+        A governed wrapper that intercepts tool calls through GovernorAI.
+
+    Example:
+        from governor import govern
+        governed = govern(your_langchain_executor)
+        result = governed.invoke({"input": "query"})
+    """
+    agent_type = type(agent).__name__
+    module = type(agent).__module__ or ""
+
+    # LangChain AgentExecutor or Runnable
+    if "langchain" in module or agent_type in ("AgentExecutor", "RunnableSequence"):
+        from .integrations.langchain import wrap_agent
+        return wrap_agent(
+            agent,
+            governor_url=governor_url,
+            api_key=api_key,
+            agent_id=agent_id,
+            namespace=namespace,
+        )
+
+    # CrewAI Crew
+    if "crewai" in module or agent_type == "Crew":
+        from .integrations.crewai import GovernorAICrew
+        client = GovernorAIClient(base_url=governor_url, api_key=api_key)
+        return GovernorAICrew(
+            crew=agent,
+            governor_client=client,
+            crew_id=agent_id or "crewai-crew",
+            namespace=namespace,
+        )
+
+    # LangGraph ToolNode
+    if "langgraph" in module or agent_type == "ToolNode":
+        from .integrations.langgraph import GovernedToolNode
+        return GovernedToolNode(
+            tools=getattr(agent, "tools_by_name", {}).values() if hasattr(agent, "tools_by_name") else [],
+            governor_url=governor_url,
+            api_key=api_key,
+            agent_id=agent_id or "langgraph-agent",
+        )
+
+    # LlamaIndex QueryEngine
+    if "llama_index" in module or "llamaindex" in module or "QueryEngine" in agent_type:
+        from .integrations.llamaindex import GovernorAIQueryEngine
+        client = GovernorAIClient(base_url=governor_url, api_key=api_key)
+        return GovernorAIQueryEngine(
+            query_engine=agent,
+            governor_client=client,
+            agent_id=agent_id or "llamaindex-agent",
+            namespace=namespace,
+        )
+
+    raise TypeError(
+        f"Cannot auto-detect framework for {agent_type} from {module}. "
+        f"Use framework-specific wrappers instead:\n"
+        f"  from governor.integrations.langchain import wrap_agent\n"
+        f"  from governor.integrations.crewai import GovernorAICrew\n"
+        f"  from governor.integrations.langgraph import GovernedToolNode\n"
+        f"  from governor.integrations.llamaindex import GovernedQueryEngine"
+    )

governor/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running GovernorAI CLI as: python -m governor"""
+from .cli import main
+
+main()

governor/cli.py

@@ -0,0 +1,210 @@
+"""GovernorAI CLI — terminal-first developer experience.
+
+Usage:
+    python -m governor init       # Configure access
+    python -m governor test       # Send a test governed action
+    python -m governor status     # Check connection and policy status
+"""
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+from .client import GovernorAIClient, GovernorAIError
+
+
+CONFIG_FILE = ".governor.env"
+ENV_URL = "GOVERNOR_URL"
+ENV_KEY = "GOVERNOR_API_KEY"
+
+
+def get_client():
+    """Create a client from env vars or config file."""
+    url = os.environ.get(ENV_URL)
+    key = os.environ.get(ENV_KEY)
+
+    if not url or not key:
+        # Try .env-style config file (KEY=VALUE format, no YAML dependency)
+        config_path = Path(CONFIG_FILE)
+        if config_path.exists():
+            with open(config_path) as f:
+                for line in f:
+                    line = line.strip()
+                    if line.startswith("#") or "=" not in line:
+                        continue
+                    k, v = line.split("=", 1)
+                    k, v = k.strip(), v.strip()
+                    if k == "GOVERNOR_URL" and not url:
+                        url = v
+                    elif k == "GOVERNOR_API_KEY" and not key:
+                        key = v
+
+    if not url:
+        print(f"Error: Set {ENV_URL} or create {CONFIG_FILE}")
+        sys.exit(1)
+    if not key:
+        print(f"Error: Set {ENV_KEY} or create {CONFIG_FILE}")
+        sys.exit(1)
+
+    return GovernorAIClient(base_url=url, api_key=key)
+
+
+def cmd_init(args):
+    """Configure GovernorAI access."""
+    url = args.url or input(f"GovernorAI Gateway URL [{os.environ.get(ENV_URL, 'https://gateway.governorai.ai')}]: ").strip()
+    if not url:
+        url = os.environ.get(ENV_URL, "https://gateway.governorai.ai")
+
+    key = args.key or input("API Key: ").strip()
+    if not key:
+        print("Error: API key is required.")
+        sys.exit(1)
+
+    # Test connectivity
+    print(f"\nTesting connection to {url}...")
+    client = GovernorAIClient(base_url=url, api_key=key)
+    try:
+        # Try a simple health check or list policies
+        result = client.execute(
+            agent_id="governorai-cli-test",
+            tool="cli.init.ping",
+            args={"purpose": "connectivity_test"},
+        )
+        print(f"✓ Connected! Decision: {result.get('decision', 'ALLOW')}")
+    except GovernorAIError as e:
+        # Even a DENY is a successful connection
+        if "denied" in str(e).lower() or "blocked" in str(e).lower():
+            print(f"✓ Connected! (Policy denied test action — governance is working)")
+        else:
+            print(f"✗ Connection failed: {e}")
+            sys.exit(1)
+    except Exception as e:
+        print(f"✗ Connection failed: {e}")
+        sys.exit(1)
+
+    # Save config (.env format — no YAML dependency)
+    print(f"\nSaving to {CONFIG_FILE}...")
+    with open(CONFIG_FILE, "w") as f:
+        f.write(f"# GovernorAI configuration\n")
+        f.write(f"GOVERNOR_URL={url}\n")
+        f.write(f"GOVERNOR_API_KEY={key}\n")
+    print(f"✓ Config saved to {CONFIG_FILE}")
+    print(f"\nYou can also set environment variables:")
+    print(f"  export {ENV_URL}={url}")
+    print(f"  export {ENV_KEY}={key}")
+
+
+def cmd_test(args):
+    """Send a test governed action."""
+    client = get_client()
+    agent_id = args.agent or "cli-test-agent"
+    tool = args.tool or "cli.test.action"
+    raw_args = args.args
+
+    test_args = {}
+    if raw_args:
+        try:
+            test_args = json.loads(raw_args)
+        except json.JSONDecodeError:
+            print(f"Error: --args must be valid JSON, got: {raw_args}")
+            sys.exit(1)
+    else:
+        # Default test payload that should trigger a deny with the starter policy
+        test_args = {
+            "destination_external": True,
+            "contains_pii": True,
+            "payload_preview": "Test PII data",
+        }
+
+    print(f"Sending governed action...")
+    print(f"  Agent:  {agent_id}")
+    print(f"  Tool:   {tool}")
+    print(f"  Args:   {json.dumps(test_args, indent=2)}")
+    print()
+
+    try:
+        result = client.execute(
+            agent_id=agent_id,
+            tool=tool,
+            args=test_args,
+        )
+        decision = result.get("decision", "UNKNOWN")
+        reason = result.get("reason", "")
+        latency = result.get("latency_ms", "?")
+
+        if decision == "ALLOW":
+            print(f"  ✓ Decision: ALLOW")
+        elif decision == "DENY":
+            print(f"  ✗ Decision: DENY")
+        else:
+            print(f"  ⚡ Decision: {decision}")
+
+        if reason:
+            print(f"  Reason:  {reason}")
+        print(f"  Latency: {latency}ms")
+        print(f"\nView in dashboard → Events page")
+
+    except GovernorAIError as e:
+        print(f"  ✗ Error: {e}")
+        sys.exit(1)
+
+
+def cmd_status(args):
+    """Check connection and governance status."""
+    client = get_client()
+
+    print(f"GovernorAI Status")
+    print(f"  URL: {client.base_url}")
+    print(f"  Key: {client.api_key[:10]}..." if client.api_key else "  Key: not set")
+    print()
+
+    # Test connectivity
+    try:
+        result = client.execute(
+            agent_id="governorai-cli-status",
+            tool="cli.status.ping",
+            args={"purpose": "status_check"},
+        )
+        print(f"  Connection: ✓ OK")
+        print(f"  Decision:   {result.get('decision', 'ALLOW')}")
+    except GovernorAIError as e:
+        if "denied" in str(e).lower():
+            print(f"  Connection: ✓ OK (policy active)")
+        else:
+            print(f"  Connection: ✗ Failed ({e})")
+    except Exception as e:
+        print(f"  Connection: ✗ Failed ({e})")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="governorai",
+        description="GovernorAI CLI — AI governance from your terminal",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # init
+    init_parser = subparsers.add_parser("init", help="Configure GovernorAI access")
+    init_parser.add_argument("--url", help="Gateway URL")
+    init_parser.add_argument("--key", help="API key")
+    init_parser.set_defaults(func=cmd_init)
+
+    # test
+    test_parser = subparsers.add_parser("test", help="Send a test governed action")
+    test_parser.add_argument("--agent", help="Agent ID (default: cli-test-agent)")
+    test_parser.add_argument("--tool", help="Tool name (default: cli.test.action)")
+    test_parser.add_argument("--args", help="JSON args (default: PII test payload)")
+    test_parser.set_defaults(func=cmd_test)
+
+    # status
+    status_parser = subparsers.add_parser("status", help="Check connection status")
+    status_parser.set_defaults(func=cmd_status)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

governor/client.py

@@ -0,0 +1,369 @@
+"""GovernorAI API client."""
+
+import os
+import uuid
+from typing import Any, Optional
+
+import requests
+
+
+class GovernorAIClient:
+    """Client for interacting with GovernorAI Gateway.
+
+    Auto-configures from environment variables when explicit values are not passed:
+        GOVERNOR_URL — Gateway URL (default: http://localhost:8080)
+        GOVERNOR_API_KEY — API key for authentication
+    """
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        api_key: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        """
+        Initialize the GovernorAI client.
+
+        Args:
+            base_url: GovernorAI Gateway URL. Falls back to GOVERNOR_URL env var.
+            api_key: API key for authentication. Falls back to GOVERNOR_API_KEY env var.
+            timeout: Request timeout in seconds
+        """
+        self.base_url = (base_url or os.environ.get("GOVERNOR_URL", "http://localhost:8080")).rstrip("/")
+        self.api_key = api_key or os.environ.get("GOVERNOR_API_KEY")
+        self.timeout = timeout
+        self.session = requests.Session()
+
+    def _request_headers(self, extra: Optional[dict[str, str]] = None) -> dict[str, str]:
+        """Build per-request headers without mutating shared session state."""
+        headers: dict[str, str] = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def execute(
+        self,
+        tool: str,
+        args: dict[str, Any],
+        agent_id: str,
+        session_id: Optional[str] = None,
+        namespace: str = "default",
+        trace_id: Optional[str] = None,
+        principal_id: Optional[str] = None,
+        framework_context: Optional[dict[str, Any]] = None,
+        target_context: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a tool action through GovernorAI.
+
+        Args:
+            tool: Tool name (e.g., "erp.process_payment")
+            args: Tool arguments
+            agent_id: Agent identifier
+            session_id: Session identifier (auto-generated if not provided)
+            namespace: Namespace for policy lookup
+            trace_id: Trace ID for distributed tracing
+            principal_id: UAP principal identifier
+            framework_context: Agent framework metadata
+            target_context: Target system metadata
+
+        Returns:
+            Response from GovernorAI including decision and result
+
+        Raises:
+            GovernorAIError: If the request fails or action is denied
+        """
+        if session_id is None:
+            session_id = str(uuid.uuid4())
+
+        if trace_id is None:
+            trace_id = str(uuid.uuid4())
+
+        payload = {
+            "agent_id": agent_id,
+            "session_id": session_id,
+            "namespace": namespace,
+            "tool": tool,
+            "args": args,
+            "trace_id": trace_id,
+        }
+        if principal_id:
+            payload["principal_id"] = principal_id
+        if framework_context:
+            payload["framework_context"] = framework_context
+        if target_context:
+            payload["target_context"] = target_context
+
+        response = self.session.post(
+            f"{self.base_url}/api/v1/gateway/execute",
+            json=payload,
+            headers=self._request_headers(
+                {
+                    "X-Governor-Agent-ID": agent_id,
+                    "X-Governor-Session-ID": session_id,
+                }
+            ),
+            timeout=self.timeout,
+        )
+
+        result = response.json()
+
+        if result.get("decision") == "deny":
+            raise GovernorAIDenied(
+                result.get("reason", "Action denied"),
+                rule_id=result.get("rule_id"),
+                explain=result.get("explain"),
+                explain_code=result.get("explain_code"),
+                policy_id=result.get("policy_id"),
+            )
+
+        if result.get("decision") == "pause":
+            raise GovernorAIApprovalRequired(
+                result.get("reason", "Approval required"),
+                approval_id=result.get("approval_id"),
+                approval_url=result.get("approval_url"),
+            )
+
+        return result
+
+    def check_kill_switch(self, agent_id: str, tool: str, namespace: str) -> bool:
+        """Check if a kill switch is active."""
+        try:
+            response = self.session.get(
+                f"{self.base_url}/api/v1/killswitch/status",
+                headers=self._request_headers(),
+                timeout=self.timeout,
+            )
+            result = response.json() or {}
+        except Exception:
+            return False
+
+        for ks in result.get("kill_switches", []) or []:
+            if ks["scope"] == "agent" and ks["target"] == agent_id:
+                return True
+            if ks["scope"] == "tool" and ks["target"] == tool:
+                return True
+            if ks["scope"] == "namespace" and ks["target"] == namespace:
+                return True
+
+        return False
+
+
+class AsyncGovernorAIClient:
+    """Async client for interacting with GovernorAI Gateway.
+
+    Uses ``aiohttp`` for non-blocking HTTP calls.  Install with::
+
+        pip install aiohttp
+
+    Example::
+
+        async with AsyncGovernorAIClient(base_url="http://localhost:8080") as client:
+            result = await client.execute(
+                tool="erp.process_payment",
+                args={"amount": 100},
+                agent_id="payment-agent",
+            )
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8080",
+        api_key: Optional[str] = None,
+        timeout: int = 30,
+    ):
+        """
+        Initialize the async GovernorAI client.
+
+        Args:
+            base_url: GovernorAI Gateway URL.
+            api_key: API key for authentication.
+            timeout: Request timeout in seconds.
+
+        Raises:
+            ImportError: If ``aiohttp`` is not installed.
+        """
+        try:
+            import aiohttp  # noqa: F401
+        except ImportError:
+            raise ImportError(
+                "aiohttp is required for AsyncGovernorAIClient. "
+                "Install it with: pip install aiohttp"
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self._session: Optional[Any] = None
+
+    async def _get_session(self) -> Any:
+        """Return the shared ``aiohttp.ClientSession``, creating it lazily."""
+        if self._session is None or self._session.closed:
+            import aiohttp
+
+            headers: dict[str, str] = {}
+            if self.api_key:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            timeout = aiohttp.ClientTimeout(total=self.timeout)
+            self._session = aiohttp.ClientSession(headers=headers, timeout=timeout)
+        return self._session
+
+    async def execute(
+        self,
+        tool: str,
+        args: dict[str, Any],
+        agent_id: str,
+        session_id: Optional[str] = None,
+        namespace: str = "default",
+        trace_id: Optional[str] = None,
+        principal_id: Optional[str] = None,
+        framework_context: Optional[dict[str, Any]] = None,
+        target_context: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """
+        Execute a tool action through GovernorAI asynchronously.
+
+        Args:
+            tool: Tool name (e.g., "erp.process_payment").
+            args: Tool arguments.
+            agent_id: Agent identifier.
+            session_id: Session identifier (auto-generated if not provided).
+            namespace: Namespace for policy lookup.
+            trace_id: Trace ID for distributed tracing.
+            principal_id: UAP principal identifier.
+            framework_context: Agent framework metadata.
+            target_context: Target system metadata.
+
+        Returns:
+            Response from GovernorAI including decision and result.
+
+        Raises:
+            GovernorAIError: If the request fails or action is denied.
+        """
+        if session_id is None:
+            session_id = str(uuid.uuid4())
+
+        if trace_id is None:
+            trace_id = str(uuid.uuid4())
+
+        payload = {
+            "agent_id": agent_id,
+            "session_id": session_id,
+            "namespace": namespace,
+            "tool": tool,
+            "args": args,
+            "trace_id": trace_id,
+        }
+        if principal_id:
+            payload["principal_id"] = principal_id
+        if framework_context:
+            payload["framework_context"] = framework_context
+        if target_context:
+            payload["target_context"] = target_context
+
+        request_headers = {
+            "X-Governor-Agent-ID": agent_id,
+            "X-Governor-Session-ID": session_id,
+            "Content-Type": "application/json",
+        }
+
+        session = await self._get_session()
+        async with session.post(
+            f"{self.base_url}/api/v1/gateway/execute",
+            json=payload,
+            headers=request_headers,
+        ) as response:
+            result = await response.json()
+
+        if result.get("decision") == "deny":
+            raise GovernorAIDenied(
+                result.get("reason", "Action denied"),
+                rule_id=result.get("rule_id"),
+                explain=result.get("explain"),
+                explain_code=result.get("explain_code"),
+                policy_id=result.get("policy_id"),
+            )
+
+        if result.get("decision") == "pause":
+            raise GovernorAIApprovalRequired(
+                result.get("reason", "Approval required"),
+                approval_id=result.get("approval_id"),
+                approval_url=result.get("approval_url"),
+            )
+
+        return result
+
+    async def check_kill_switch(self, agent_id: str, tool: str, namespace: str) -> bool:
+        """Async check if a kill switch is active."""
+        try:
+            session = await self._get_session()
+            async with session.get(
+                f"{self.base_url}/api/v1/killswitch/status",
+            ) as response:
+                result = (await response.json()) or {}
+        except Exception:
+            return False
+
+        for ks in result.get("kill_switches", []) or []:
+            if ks["scope"] == "agent" and ks["target"] == agent_id:
+                return True
+            if ks["scope"] == "tool" and ks["target"] == tool:
+                return True
+            if ks["scope"] == "namespace" and ks["target"] == namespace:
+                return True
+
+        return False
+
+    async def close(self) -> None:
+        """Close the underlying HTTP session."""
+        if self._session is not None and not self._session.closed:
+            await self._session.close()
+            self._session = None
+
+    async def __aenter__(self) -> "AsyncGovernorAIClient":
+        """Enter async context manager."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit async context manager and close the session."""
+        await self.close()
+
+
+class GovernorAIError(Exception):
+    """Base exception for GovernorAI errors."""
+
+    pass
+
+
+class GovernorAIDenied(GovernorAIError):
+    """Raised when an action is denied by policy."""
+
+    def __init__(
+        self,
+        message: str,
+        rule_id: Optional[str] = None,
+        explain: Optional[str] = None,
+        explain_code: Optional[str] = None,
+        policy_id: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.rule_id = rule_id
+        self.explain = explain
+        self.explain_code = explain_code
+        self.policy_id = policy_id
+
+
+class GovernorAIApprovalRequired(GovernorAIError):
+    """Raised when an action requires approval."""
+
+    def __init__(
+        self,
+        message: str,
+        approval_id: Optional[str] = None,
+        approval_url: Optional[str] = None,
+    ):
+        super().__init__(message)
+        self.approval_id = approval_id
+        self.approval_url = approval_url