lockstock-integrations 1.0.0__py3-none-any.whl

lockstock_openai/guardrails.py

@@ -0,0 +1,193 @@
+"""
+LockStock OpenAI Agents SDK Guardrails
+---------------------------------------
+Guardrail implementations for OpenAI Agents SDK.
+
+Usage:
+    from agents import Agent
+    from lockstock_openai import LockStockGuardrail
+
+    guardrail = LockStockGuardrail(agent_id="agent_abc123")
+
+    agent = Agent(
+        name="my-agent",
+        instructions="You are a helpful assistant.",
+        guardrails=[guardrail]
+    )
+"""
+
+from typing import Any, Dict, Optional, List
+from dataclasses import dataclass
+
+from lockstock_core import LockStockClient
+from lockstock_core.types import map_tool_to_capability, VerifyStatus
+
+
+@dataclass
+class GuardrailResult:
+    """Result of a guardrail check."""
+    passed: bool
+    reason: Optional[str] = None
+    modified_content: Optional[Any] = None
+
+
+class LockStockGuardrail:
+    """
+    Base guardrail for OpenAI Agents SDK.
+
+    Validates that the agent has permission to perform requested actions.
+    """
+
+    name = "lockstock"
+    description = "LockStock capability authorization guardrail"
+
+    def __init__(
+        self,
+        agent_id: str,
+        secret: Optional[str] = None,
+        api_key: Optional[str] = None,
+        endpoint: str = "https://lockstock-api-i9kp.onrender.com",
+        block_on_failure: bool = True
+    ):
+        """
+        Initialize LockStock guardrail.
+
+        Args:
+            agent_id: The agent's unique identifier
+            secret: The agent's HMAC secret
+            api_key: Admin API key
+            endpoint: LockStock API endpoint
+            block_on_failure: If True, block execution on auth failure
+        """
+        self.client = LockStockClient(
+            agent_id=agent_id,
+            secret=secret,
+            api_key=api_key,
+            endpoint=endpoint
+        )
+        self.agent_id = agent_id
+        self.block_on_failure = block_on_failure
+
+    async def validate(
+        self,
+        agent: Any,
+        message: Dict[str, Any]
+    ) -> GuardrailResult:
+        """
+        Validate a message before it's processed or sent.
+
+        This method is called by the OpenAI Agents SDK.
+
+        Args:
+            agent: The agent instance
+            message: The message to validate
+
+        Returns:
+            GuardrailResult indicating if validation passed
+        """
+        # Check for tool calls in assistant messages
+        if message.get("role") == "assistant" and "tool_calls" in message:
+            for tool_call in message.get("tool_calls", []):
+                if "function" in tool_call:
+                    function_name = tool_call["function"].get("name", "")
+
+                    # Map to capability
+                    capability = map_tool_to_capability(function_name)
+
+                    # Verify with LockStock
+                    result = await self.client.verify(
+                        task=capability,
+                        tool_name=function_name
+                    )
+
+                    if not result.authorized:
+                        if self.block_on_failure:
+                            return GuardrailResult(
+                                passed=False,
+                                reason=f"LockStock DENIED: {function_name} requires {capability}. "
+                                       f"Agent {self.agent_id} lacks this capability."
+                            )
+
+        return GuardrailResult(passed=True)
+
+    async def close(self):
+        """Close the underlying client."""
+        await self.client.close()
+
+
+class LockStockInputGuardrail(LockStockGuardrail):
+    """
+    Input guardrail for OpenAI Agents SDK.
+
+    Validates incoming messages/requests before processing.
+    """
+
+    name = "lockstock_input"
+    description = "LockStock input validation guardrail"
+
+    async def validate_input(
+        self,
+        agent: Any,
+        user_input: str,
+        context: Optional[Dict[str, Any]] = None
+    ) -> GuardrailResult:
+        """
+        Validate user input before processing.
+
+        Args:
+            agent: The agent instance
+            user_input: The user's input string
+            context: Optional context dictionary
+
+        Returns:
+            GuardrailResult indicating if validation passed
+        """
+        # Input validation can check for:
+        # - Sensitive data patterns
+        # - Rate limiting
+        # - Input size limits
+
+        # For now, pass through - capability checks happen at tool use
+        return GuardrailResult(passed=True)
+
+
+class LockStockOutputGuardrail(LockStockGuardrail):
+    """
+    Output guardrail for OpenAI Agents SDK.
+
+    Validates agent outputs before returning to user.
+    """
+
+    name = "lockstock_output"
+    description = "LockStock output validation guardrail"
+
+    async def validate_output(
+        self,
+        agent: Any,
+        output: str,
+        context: Optional[Dict[str, Any]] = None
+    ) -> GuardrailResult:
+        """
+        Validate agent output before returning.
+
+        Args:
+            agent: The agent instance
+            output: The agent's output string
+            context: Optional context dictionary
+
+        Returns:
+            GuardrailResult indicating if validation passed
+        """
+        # Output validation can check for:
+        # - Sensitive data leakage
+        # - Compliance requirements
+        # - Output format requirements
+
+        # Log the output to audit trail
+        await self.client.log_audit(
+            action="output",
+            status="COMPLETED",
+            metadata={"output_length": len(output)}
+        )
+
+        return GuardrailResult(passed=True)

lockstock_openai/tracing.py

@@ -0,0 +1,220 @@
+"""
+LockStock OpenAI Agents SDK Tracing
+------------------------------------
+Tracing integration for audit trail logging.
+
+The OpenAI Agents SDK supports extensible tracing. This module
+integrates LockStock's hash chain audit trail with the SDK's
+tracing infrastructure.
+"""
+
+from typing import Dict, Any, Optional
+from dataclasses import dataclass, field
+import time
+
+from lockstock_core import LockStockClient
+
+
+@dataclass
+class TraceSpan:
+    """A span in the trace."""
+    name: str
+    start_time: float
+    end_time: Optional[float] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    parent_span_id: Optional[str] = None
+    span_id: Optional[str] = None
+    status: str = "running"
+
+
+class LockStockTracer:
+    """
+    Tracer that logs agent activity to LockStock's audit trail.
+
+    Integrates with OpenAI Agents SDK's tracing infrastructure
+    while maintaining cryptographic audit guarantees.
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        secret: Optional[str] = None,
+        api_key: Optional[str] = None,
+        endpoint: str = "https://lockstock-api-i9kp.onrender.com"
+    ):
+        """
+        Initialize LockStock tracer.
+
+        Args:
+            agent_id: The agent's unique identifier
+            secret: The agent's HMAC secret
+            api_key: Admin API key
+            endpoint: LockStock API endpoint
+        """
+        self.client = LockStockClient(
+            agent_id=agent_id,
+            secret=secret,
+            api_key=api_key,
+            endpoint=endpoint
+        )
+        self.agent_id = agent_id
+        self._spans: Dict[str, TraceSpan] = {}
+        self._span_counter = 0
+
+    async def start_span(
+        self,
+        name: str,
+        parent_span_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ) -> str:
+        """
+        Start a new trace span.
+
+        Args:
+            name: Name of the span
+            parent_span_id: Optional parent span ID
+            metadata: Optional metadata
+
+        Returns:
+            The span ID
+        """
+        self._span_counter += 1
+        span_id = f"{self.agent_id}:span:{self._span_counter}"
+
+        span = TraceSpan(
+            name=name,
+            start_time=time.time(),
+            metadata=metadata or {},
+            parent_span_id=parent_span_id,
+            span_id=span_id
+        )
+
+        self._spans[span_id] = span
+
+        # Log to audit trail
+        await self.client.log_audit(
+            action=f"span_start:{name}",
+            status="STARTED",
+            metadata={
+                "span_id": span_id,
+                "parent_span_id": parent_span_id
+            }
+        )
+
+        return span_id
+
+    async def end_span(
+        self,
+        span_id: str,
+        status: str = "success",
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        """
+        End a trace span.
+
+        Args:
+            span_id: The span ID to end
+            status: Final status of the span
+            metadata: Optional additional metadata
+        """
+        if span_id not in self._spans:
+            return
+
+        span = self._spans[span_id]
+        span.end_time = time.time()
+        span.status = status
+
+        if metadata:
+            span.metadata.update(metadata)
+
+        # Log to audit trail
+        await self.client.log_audit(
+            action=f"span_end:{span.name}",
+            status=status.upper(),
+            metadata={
+                "span_id": span_id,
+                "duration_ms": (span.end_time - span.start_time) * 1000
+            }
+        )
+
+    async def log_event(
+        self,
+        name: str,
+        span_id: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None
+    ):
+        """
+        Log an event within a span.
+
+        Args:
+            name: Event name
+            span_id: Optional span ID
+            metadata: Optional metadata
+        """
+        await self.client.log_audit(
+            action=f"event:{name}",
+            status="LOGGED",
+            metadata={
+                "span_id": span_id,
+                **(metadata or {})
+            }
+        )
+
+    async def log_tool_call(
+        self,
+        tool_name: str,
+        tool_input: Dict[str, Any],
+        tool_output: Optional[Any] = None,
+        span_id: Optional[str] = None,
+        authorized: bool = True
+    ):
+        """
+        Log a tool call with its input and output.
+
+        Args:
+            tool_name: Name of the tool
+            tool_input: Tool input parameters
+            tool_output: Tool output (optional)
+            span_id: Optional span ID
+            authorized: Whether the call was authorized
+        """
+        await self.client.log_audit(
+            action=f"tool:{tool_name}",
+            status="AUTHORIZED" if authorized else "DENIED",
+            metadata={
+                "span_id": span_id,
+                "tool_name": tool_name,
+                "input_keys": list(tool_input.keys()),
+                "has_output": tool_output is not None
+            }
+        )
+
+    def get_trace_summary(self) -> Dict[str, Any]:
+        """
+        Get a summary of all traced spans.
+
+        Returns:
+            Dictionary with trace summary
+        """
+        completed = [s for s in self._spans.values() if s.end_time is not None]
+        running = [s for s in self._spans.values() if s.end_time is None]
+
+        return {
+            "agent_id": self.agent_id,
+            "total_spans": len(self._spans),
+            "completed_spans": len(completed),
+            "running_spans": len(running),
+            "spans": [
+                {
+                    "span_id": s.span_id,
+                    "name": s.name,
+                    "status": s.status,
+                    "duration_ms": (s.end_time - s.start_time) * 1000 if s.end_time else None
+                }
+                for s in self._spans.values()
+            ]
+        }
+
+    async def close(self):
+        """Close the underlying client."""
+        await self.client.close()