governance-sdk 0.1.0__tar.gz

governance_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: governance-sdk
+Version: 0.1.0
+Summary: A plug-and-play SDK to capture and audit tool calls in Agentic AI applications
+Author-email: Sanjay Nithin <sanjaynithin220@gmail.com>
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: langchain-core>=0.1.0; extra == "dev"
+
+# Governance SDK (AI Frameworks Edition)
+
+A lightweight, non-blocking, plug-and-play Python SDK to automatically intercept, evaluate, and authorize tool calls in LangChain, LangGraph, and CrewAI agentic applications.
+
+## Features
+
+- **Multi-Framework Auto-Interception**: Automatically intercepts tool calls in **LangChain**, **LangGraph**, and **CrewAI** (by hooking base tool run/arun methods) with zero configuration.
+- **Zero-Touch Automatic Context Capture**: Walks up the Python execution stack frames to auto-resolve active context details such as `session_id`, `agent_name`, `purpose`, and `trace_id` by inspecting local variables. No manual wrapping required!
+- **Three-Tier Governance Workflow**: Evaluates risk and routes tool execution decisions:
+  - `allow`: Automatically executes the tool.
+  - `preview_and_confirmation`: Triggers an interactive CLI prompt to confirm execution.
+  - `needs_full_review`: Triggers an interactive CLI prompt indicating full review is required.
+- **Exception-Based Control**: If a developer/user denies an execution prompt, the SDK raises `PermissionDeniedError` or `ReviewRequiredError`, letting the calling application abort or handle it gracefully.
+- **Non-Blocking Asynchronous Auditing**: Completed tool logs are queued in-memory and batch-shipped to the Governance Server asynchronously by a background worker thread.
+- **Fail-safe & Resilient**: Operates with exponential backoff on server log shipment delivery failure.
+
+---
+
+## Installation
+
+Install the package in editable mode:
+```bash
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+Initialize the SDK at the entry point of your agentic application.
+
+### 1. SDK Initialization
+```python
+import governance_sdk
+
+governance_sdk.init(
+    server_url="http://127.0.0.1:8000/api/v1/tool-calls",
+    risk_check_url="http://127.0.0.1:8000/api/v1/risk-checks",
+    project_name="customer-support-agent"
+)
+```
+
+You can also use environment variables:
+```bash
+export GOVERNANCE_SERVER_URL="http://127.0.0.1:8000/api/v1/tool-calls"
+export GOVERNANCE_RISK_CHECK_URL="http://127.0.0.1:8000/api/v1/risk-checks"
+export GOVERNANCE_PROJECT_NAME="customer-support-agent"
+```
+And simply call `init()`:
+```python
+import governance_sdk
+governance_sdk.init()
+```
+
+### 2. Auto-Interception & Context Capture
+Once `init()` is called, any tool executed by your agent in LangChain, LangGraph, or CrewAI will be automatically intercepted:
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def delete_user_data(user_id: str) -> str:
+    """Deletes sensitive user information."""
+    return f"User {user_id} deleted."
+
+# In your agent logic:
+# When this tool is called, the SDK automatically walks the stack to extract:
+# - session_id (resolves from variables named session_id, sid, session, etc.)
+# - agent_name (resolves from class name or variable agent_name)
+# - purpose (resolves from variables named purpose, intent, reason, etc.)
+# Then it verifies the risk score on the server side.
+delete_user_data.run({"user_id": "usr_992"})
+```
+
+### 3. Explicit Context Override (Optional)
+If you want to manually specify context instead of relying on the auto-captured stack frames, use the `agent_context` manager:
+
+```python
+import governance_sdk
+
+with governance_sdk.agent_context(agent_name="Supervisor-Agent", session_id="session_override_123", purpose="cleanup"):
+    # All tool calls executed inside this block will prioritize these values
+    agent.run("delete temporary files")
+```
+
+---
+
+## Captured Payload Format
+
+The JSON payload sent to the governance logging server has the following structure:
+
+```json
+{
+  "project_name": "customer-support-agent",
+  "tool_calls": [
+    {
+      "tool_name": "delete_user_data",
+      "tool_description": "Deletes sensitive user information.",
+      "arguments": { "user_id": "usr_992" },
+      "output": "User usr_992 deleted.",
+      "error": null,
+      "status": "success",
+      "timestamp_start": "2026-07-30T13:30:00Z",
+      "timestamp_end": "2026-07-30T13:30:00.045Z",
+      "duration_ms": 45,
+      "context": {
+        "agent_name": "Supervisor-Agent",
+        "session_id": "session_override_123",
+        "purpose": "cleanup",
+        "caller_filename": "main.py",
+        "caller_line_number": 42,
+        "caller_function": "execute_task"
+      },
+      "risk_score": 0.90,
+      "risk_category": "high_risk",
+      "governance_decision": "allow"
+    }
+  ]
+}
+```

governance_sdk-0.1.0/README.md

@@ -0,0 +1,120 @@
+# Governance SDK (AI Frameworks Edition)
+
+A lightweight, non-blocking, plug-and-play Python SDK to automatically intercept, evaluate, and authorize tool calls in LangChain, LangGraph, and CrewAI agentic applications.
+
+## Features
+
+- **Multi-Framework Auto-Interception**: Automatically intercepts tool calls in **LangChain**, **LangGraph**, and **CrewAI** (by hooking base tool run/arun methods) with zero configuration.
+- **Zero-Touch Automatic Context Capture**: Walks up the Python execution stack frames to auto-resolve active context details such as `session_id`, `agent_name`, `purpose`, and `trace_id` by inspecting local variables. No manual wrapping required!
+- **Three-Tier Governance Workflow**: Evaluates risk and routes tool execution decisions:
+  - `allow`: Automatically executes the tool.
+  - `preview_and_confirmation`: Triggers an interactive CLI prompt to confirm execution.
+  - `needs_full_review`: Triggers an interactive CLI prompt indicating full review is required.
+- **Exception-Based Control**: If a developer/user denies an execution prompt, the SDK raises `PermissionDeniedError` or `ReviewRequiredError`, letting the calling application abort or handle it gracefully.
+- **Non-Blocking Asynchronous Auditing**: Completed tool logs are queued in-memory and batch-shipped to the Governance Server asynchronously by a background worker thread.
+- **Fail-safe & Resilient**: Operates with exponential backoff on server log shipment delivery failure.
+
+---
+
+## Installation
+
+Install the package in editable mode:
+```bash
+pip install -e .
+```
+
+---
+
+## Quickstart
+
+Initialize the SDK at the entry point of your agentic application.
+
+### 1. SDK Initialization
+```python
+import governance_sdk
+
+governance_sdk.init(
+    server_url="http://127.0.0.1:8000/api/v1/tool-calls",
+    risk_check_url="http://127.0.0.1:8000/api/v1/risk-checks",
+    project_name="customer-support-agent"
+)
+```
+
+You can also use environment variables:
+```bash
+export GOVERNANCE_SERVER_URL="http://127.0.0.1:8000/api/v1/tool-calls"
+export GOVERNANCE_RISK_CHECK_URL="http://127.0.0.1:8000/api/v1/risk-checks"
+export GOVERNANCE_PROJECT_NAME="customer-support-agent"
+```
+And simply call `init()`:
+```python
+import governance_sdk
+governance_sdk.init()
+```
+
+### 2. Auto-Interception & Context Capture
+Once `init()` is called, any tool executed by your agent in LangChain, LangGraph, or CrewAI will be automatically intercepted:
+
+```python
+from langchain_core.tools import tool
+
+@tool
+def delete_user_data(user_id: str) -> str:
+    """Deletes sensitive user information."""
+    return f"User {user_id} deleted."
+
+# In your agent logic:
+# When this tool is called, the SDK automatically walks the stack to extract:
+# - session_id (resolves from variables named session_id, sid, session, etc.)
+# - agent_name (resolves from class name or variable agent_name)
+# - purpose (resolves from variables named purpose, intent, reason, etc.)
+# Then it verifies the risk score on the server side.
+delete_user_data.run({"user_id": "usr_992"})
+```
+
+### 3. Explicit Context Override (Optional)
+If you want to manually specify context instead of relying on the auto-captured stack frames, use the `agent_context` manager:
+
+```python
+import governance_sdk
+
+with governance_sdk.agent_context(agent_name="Supervisor-Agent", session_id="session_override_123", purpose="cleanup"):
+    # All tool calls executed inside this block will prioritize these values
+    agent.run("delete temporary files")
+```
+
+---
+
+## Captured Payload Format
+
+The JSON payload sent to the governance logging server has the following structure:
+
+```json
+{
+  "project_name": "customer-support-agent",
+  "tool_calls": [
+    {
+      "tool_name": "delete_user_data",
+      "tool_description": "Deletes sensitive user information.",
+      "arguments": { "user_id": "usr_992" },
+      "output": "User usr_992 deleted.",
+      "error": null,
+      "status": "success",
+      "timestamp_start": "2026-07-30T13:30:00Z",
+      "timestamp_end": "2026-07-30T13:30:00.045Z",
+      "duration_ms": 45,
+      "context": {
+        "agent_name": "Supervisor-Agent",
+        "session_id": "session_override_123",
+        "purpose": "cleanup",
+        "caller_filename": "main.py",
+        "caller_line_number": 42,
+        "caller_function": "execute_task"
+      },
+      "risk_score": 0.90,
+      "risk_category": "high_risk",
+      "governance_decision": "allow"
+    }
+  ]
+}
+```

governance_sdk-0.1.0/governance_sdk/__init__.py

@@ -0,0 +1,81 @@
+from typing import Optional, Dict, Any
+
+from governance_sdk.config import SDKConfig
+from governance_sdk.client import GovernanceClient
+from governance_sdk.context import agent_context
+from governance_sdk.exceptions import GovernanceError, PermissionDeniedError, ReviewRequiredError
+from governance_sdk.instrumentor import patch_all
+
+_active_client: Optional[GovernanceClient] = None
+
+def init(
+    api_key: str,
+    server_url: Optional[str] = None,
+    risk_check_url: Optional[str] = None,
+    project_name: Optional[str] = None,
+    enabled: Optional[bool] = None,
+    batch_size: Optional[int] = None,
+    flush_interval: Optional[float] = None,
+    max_queue_size: Optional[int] = None,
+    fallback_policy: Optional[str] = None,
+    risk_threshold: Optional[float] = None,
+    extra_metadata: Optional[Dict[str, Any]] = None
+) -> Optional[GovernanceClient]:
+    """
+    Initializes the Governance SDK.
+    Starts the background worker queue and patches LangChain tool calling mechanisms.
+    
+    Example:
+        import governance_sdk
+        governance_sdk.init(
+            server_url="https://governance.yourorg.com/api/v1/tool-calls",
+            project_name="customer-support-agent"
+        )
+    """
+    global _active_client
+    
+    config = SDKConfig(
+        server_url=server_url,
+        risk_check_url=risk_check_url,
+        api_key=api_key,
+        project_name=project_name,
+        enabled=enabled,
+        batch_size=batch_size,
+        flush_interval=flush_interval,
+        max_queue_size=max_queue_size,
+        fallback_policy=fallback_policy,
+        risk_threshold=risk_threshold,
+        extra_metadata=extra_metadata
+    )
+    
+    if not config.enabled: # is governance server enabled or not
+        if _active_client:
+            _active_client.shutdown()
+            _active_client = None
+        return None
+        
+    if not _active_client:
+        _active_client = GovernanceClient(config)
+        _active_client.start()
+    else:
+        _active_client.config = config
+        _active_client.start()
+        
+    # Auto-patch LangChain tool calling
+    patch_all(_active_client)
+    
+    return _active_client
+
+def get_active_client() -> Optional[GovernanceClient]:
+    """Retrieves the active global governance client."""
+    return _active_client
+
+__all__ = [
+    "init",
+    "agent_context",
+    "get_active_client",
+    "GovernanceError",
+    "PermissionDeniedError",
+    "ReviewRequiredError"
+]
+

governance_sdk-0.1.0/governance_sdk/client.py

@@ -0,0 +1,331 @@
+import atexit
+import json
+import logging
+import queue
+import threading
+import time
+from typing import Dict, Any, List, Optional
+import urllib.request
+import urllib.error
+
+from governance_sdk.config import SDKConfig
+
+logger = logging.getLogger("governance_sdk")
+
+def safe_serialize(obj: Any) -> Any:
+    """Safely serializes objects that might not be JSON serializable."""
+    try:
+        json.dumps(obj)
+        return obj
+    except (TypeError, OverflowError):
+        if isinstance(obj, dict):
+            return {str(k): safe_serialize(v) for k, v in obj.items()}
+        elif isinstance(obj, (list, tuple, set)):
+            return [safe_serialize(x) for x in obj]
+        else:
+            try:
+                if hasattr(obj, "__dict__"):
+                    return safe_serialize(obj.__dict__)
+                return repr(obj)
+            except Exception:
+                return str(obj)
+
+class GovernanceClient:
+    def __init__(self, config: SDKConfig):
+        self.config = config
+        self.queue: queue.Queue = queue.Queue(maxsize=config.max_queue_size)
+        self.stop_event = threading.Event()
+        self.worker_thread: Optional[threading.Thread] = None
+        self.lock = threading.Lock()
+        
+    def start(self) -> None:
+        """Starts the background worker thread."""
+        with self.lock:
+            if self.worker_thread and self.worker_thread.is_alive():
+                return
+            self.stop_event.clear()
+            self.worker_thread = threading.Thread(
+                target=self._worker_loop, 
+                name="governance-sdk-worker", 
+                daemon=True
+            )
+            self.worker_thread.start()
+            atexit.register(self.shutdown)
+
+    def send_tool_call(self, tool_call_data: Dict[str, Any]) -> None:
+        """Enqueues a tool call payload without blocking."""
+        if not self.config.is_configured():
+            return
+            
+        if not self.worker_thread or not self.worker_thread.is_alive():
+            self.start()
+
+        sanitized = safe_serialize(tool_call_data)
+        
+        try:
+            self.queue.put_nowait(sanitized)
+        except queue.Full:
+            logger.warning("Governance SDK queue is full. Dropping tool call report.")
+
+    def check_tool_risk(
+        self,
+        tool_name: str,
+        tool_description: str,
+        arguments: Any,
+        context: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """
+        Synchronously queries the governance server to evaluate the risk score of a tool call before execution.
+        Categorizes risk and returns decision (allow, preview_and_confirmation, needs_full_review).
+        """
+        if not self.config.is_configured():
+            return {
+                "decision": "allow", 
+                "risk_score": 0.0, 
+                "risk_category": "safe", 
+                "reason": "Governance SDK is disabled or not configured"
+            }
+            
+        payload = {
+            "project_name": self.config.project_name,
+            "tool_name": tool_name,
+            "tool_description": tool_description,
+            "arguments": safe_serialize(arguments),
+            "context": safe_serialize(context)
+        }
+        
+        data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "governance-sdk-python/0.1.0"
+        }
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+            
+        try:
+            req = urllib.request.Request(
+                self.config.risk_check_url,
+                data=data,
+                headers=headers,
+                method="POST"
+            )
+            # Use a 10-second timeout for risk assessment to support multi-agent analysis
+            with urllib.request.urlopen(req, timeout=10.0) as response:
+                if 200 <= response.status < 300:
+                    resp_data = json.loads(response.read().decode("utf-8"))
+                    
+                    risk_score = float(resp_data.get("risk_score", 0.0))
+                    raw_decision = resp_data.get("decision", "allow").lower()
+                    
+                    # Categorize risk score if not provided by server
+                    if "risk_category" in resp_data:
+                        risk_category = resp_data["risk_category"].lower()
+                    else:
+                        if risk_score >= 0.80:
+                            risk_category = "high_risk"
+                        elif risk_score >= 0.60:
+                            risk_category = "medium_risk"
+                        elif risk_score >= 0.30:
+                            risk_category = "low_risk"
+                        else:
+                            risk_category = "safe"
+                            
+                    reason = resp_data.get("reason", "Approved by default policy")
+                    
+                    # Local risk override guardrail: map high risk or threshold exceedance to user prompt
+                    if raw_decision == "allow" and risk_category == "high_risk":
+                        decision = "preview_and_confirmation"
+                        reason = f"Local override: High risk score ({risk_score}) requires permission. {reason}"
+                    elif raw_decision == "allow" and risk_score > self.config.risk_threshold:
+                        decision = "preview_and_confirmation"
+                        reason = f"Local override: Threshold exceeded ({risk_score} > {self.config.risk_threshold}) requires permission. {reason}"
+                    else:
+                        # Standardize decision to the three allowed options
+                        if raw_decision in ("preview_and_confirmation", "needs_permission"):
+                            decision = "preview_and_confirmation"
+                        elif raw_decision in ("needs_full_review", "block"):
+                            decision = "needs_full_review"
+                        else:
+                            decision = "allow"
+                        
+                    return {
+                        "decision": decision,
+                        "risk_score": risk_score,
+                        "risk_category": risk_category,
+                        "reason": reason
+                    }
+        except Exception as e:
+            logger.warning(f"Governance Server risk-check failed: {e}. Falling back to '{self.config.fallback_policy}' policy.")
+            
+        # Fallback handling
+        fallback_decision = self.config.fallback_policy
+        if fallback_decision == "policy":
+            return self._evaluate_local_fallback_policy(tool_name, tool_description, arguments)
+        elif fallback_decision == "block":
+            return {
+                "decision": "needs_full_review",
+                "risk_score": 1.0,
+                "risk_category": "high_risk",
+                "reason": "Server unreachable. Applied fallback closed policy: block."
+            }
+        else:
+            return {
+                "decision": "allow",
+                "risk_score": 0.0,
+                "risk_category": "safe",
+                "reason": "Server unreachable. Applied fallback open policy: allow."
+            }
+
+    def _evaluate_local_fallback_policy(self, tool_name: str, tool_description: str, arguments: Any) -> Dict[str, Any]:
+        """
+        Evaluates a local rules-based safety policy when the Governance Server is unreachable.
+        """
+        tool_lower = tool_name.lower()
+        desc_lower = (tool_description or "").lower()
+        args_str = str(arguments).lower()
+        
+        # 1. Check for destructive commands/shell execution
+        destructive_commands = ["rm -rf", "rm -f", "mkfs", "dd if=", "reboot", "shutdown", "chmod 777", "chown"]
+        shell_keywords = ["shell", "terminal", "exec", "command", "system", "run"]
+        
+        is_shell_tool = any(kw in tool_lower for kw in shell_keywords)
+        has_destructive = any(cmd in args_str for cmd in destructive_commands)
+        
+        if is_shell_tool and has_destructive:
+            return {
+                "decision": "needs_full_review",
+                "risk_score": 0.95,
+                "risk_category": "high_risk",
+                "reason": "Server unreachable. Local policy block: Destructive command detected in shell execution."
+            }
+            
+        # 2. Check for credential leaks / sensitive reads
+        sensitive_patterns = ["akiat", "akia", "slack_token", "stripe", "github_token", "password", "private_key", ".pem", "id_rsa"]
+        has_sensitive = any(pat in args_str for pat in sensitive_patterns)
+        has_sensitive_files = any(f in args_str for f in ["/etc/passwd", "/etc/shadow", ".ssh/"])
+        
+        if has_sensitive or has_sensitive_files:
+            return {
+                "decision": "preview_and_confirmation",
+                "risk_score": 0.85,
+                "risk_category": "high_risk",
+                "reason": "Server unreachable. Local policy warning: Sensitive data or credential leak risk detected."
+            }
+            
+        # 3. Check for general database or filesystem deletion
+        delete_keywords = ["delete", "remove", "destroy", "rm", "drop", "truncate"]
+        is_delete_op = any(kw in tool_lower for kw in delete_keywords) or any(kw in desc_lower for kw in delete_keywords)
+        
+        if is_delete_op:
+            return {
+                "decision": "preview_and_confirmation",
+                "risk_score": 0.70,
+                "risk_category": "medium_risk",
+                "reason": "Server unreachable. Local policy warning: Destructive delete/remove operation detected."
+            }
+            
+        # 4. Otherwise allow
+        return {
+            "decision": "allow",
+            "risk_score": 0.15,
+            "risk_category": "safe",
+            "reason": "Server unreachable. Local policy allow: No high-risk patterns matched."
+        }
+
+
+    def _worker_loop(self) -> None:
+        """Background thread loop that batches and sends tool logs."""
+        batch_size = self.config.batch_size
+        flush_interval = self.config.flush_interval
+        
+        while not self.stop_event.is_set():
+            batch = self._gather_batch(batch_size, timeout=flush_interval)
+            if batch:
+                self._send_batch_with_retry(batch)
+                
+        self._flush_remaining()
+
+    def _gather_batch(self, batch_size: int, timeout: float) -> List[Dict[str, Any]]:
+        batch = []
+        start_time = time.time()
+        
+        while len(batch) < batch_size:
+            remaining_time = timeout - (time.time() - start_time)
+            if remaining_time <= 0:
+                break
+                
+            try:
+                item = self.queue.get(timeout=max(0.01, remaining_time))
+                batch.append(item)
+                self.queue.task_done()
+            except queue.Empty:
+                break
+                
+        return batch
+
+    def _send_batch_with_retry(self, batch: List[Dict[str, Any]]) -> None:
+        payload = {
+            "project_name": self.config.project_name,
+            "tool_calls": batch
+        }
+        
+        data = json.dumps(payload).encode("utf-8")
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": "governance-sdk-python/0.1.0"
+        }
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+
+        backoff = 1.0
+        max_backoff = 30.0
+        retries = 3
+        
+        for attempt in range(retries):
+            if self.stop_event.is_set() and attempt > 0:
+                break
+                
+            try:
+                req = urllib.request.Request(
+                    self.config.server_url,
+                    data=data,
+                    headers=headers,
+                    method="POST"
+                )
+                with urllib.request.urlopen(req, timeout=5.0) as response:
+                    if 200 <= response.status < 300:
+                        return
+            except (urllib.error.URLError, Exception) as e:
+                if attempt < retries - 1:
+                    time.sleep(backoff)
+                    backoff = min(backoff * 2, max_backoff)
+                else:
+                    logger.error(f"Governance SDK failed to send {len(batch)} tool logs: {e}")
+
+    def _flush_remaining(self) -> None:
+        while not self.queue.empty():
+            batch = []
+            while len(batch) < self.config.batch_size:
+                try:
+                    item = self.queue.get_nowait()
+                    batch.append(item)
+                    self.queue.task_done()
+                except queue.Empty:
+                    break
+            if batch:
+                self._send_batch_with_retry(batch)
+
+    def shutdown(self) -> None:
+        with self.lock:
+            if self.stop_event.is_set():
+                return
+            self.stop_event.set()
+            
+        if self.worker_thread:
+            self.worker_thread.join(timeout=3.0)
+            self.worker_thread = None
+            
+        try:
+            atexit.unregister(self.shutdown)
+        except Exception:
+            pass