cortexhub 0.1.0__py3-none-any.whl

cortexhub/adapters/openai_agents.py

@@ -0,0 +1,192 @@
+"""OpenAI Agents SDK adapter for tool interception.
+
+Intercepts tool execution by wrapping the function_tool decorator.
+
+Architectural rules:
+- Adapter is DUMB plumbing
+- Adapter calls ONE SDK entrypoint: govern_execution()
+- SDK orchestrates everything
+- No governance logic in adapter
+"""
+
+import json
+from functools import wraps
+from typing import TYPE_CHECKING, Any, Callable
+
+import structlog
+
+from cortexhub.adapters.base import ToolAdapter
+from cortexhub.pipeline import govern_execution
+
+if TYPE_CHECKING:
+    from cortexhub.client import CortexHub
+
+logger = structlog.get_logger(__name__)
+
+# Attribute names for storing originals
+_ORIGINAL_FUNCTION_TOOL_ATTR = "__cortexhub_original_function_tool__"
+_PATCHED_ATTR = "__cortexhub_patched__"
+
+
+class OpenAIAgentsAdapter(ToolAdapter):
+    """Adapter for OpenAI Agents SDK.
+    
+    Wraps the function_tool decorator to intercept tool creation
+    and wrap the on_invoke_tool method for governance.
+    
+    Key properties:
+    - Adapter is dumb plumbing
+    - Calls SDK entrypoint, doesn't implement governance
+    - Wraps decorator to intercept all tools
+    - Async-safe via SDK
+    """
+    
+    @property
+    def framework_name(self) -> str:
+        return "openai_agents"
+    
+    def _get_framework_modules(self) -> list[str]:
+        return ["agents", "openai_agents"]
+    
+    def patch(self) -> None:
+        """Patch OpenAI Agents by wrapping the function_tool decorator."""
+        try:
+            import agents
+            import agents.tool as tool_module
+            
+            # Check if already patched
+            if getattr(tool_module, _PATCHED_ATTR, False):
+                logger.info("OpenAI Agents already patched")
+                return
+
+            cortex_hub = self.cortex_hub
+            tools = self._discover_tools()
+            if tools:
+                cortex_hub.backend.register_tool_inventory(
+                    agent_id=cortex_hub.agent_id,
+                    framework=self.framework_name,
+                    tools=tools,
+                )
+            
+            # Store original function_tool decorator
+            if not hasattr(tool_module, _ORIGINAL_FUNCTION_TOOL_ATTR):
+                setattr(tool_module, _ORIGINAL_FUNCTION_TOOL_ATTR, tool_module.function_tool)
+            
+            original_function_tool = getattr(tool_module, _ORIGINAL_FUNCTION_TOOL_ATTR)
+
+            def patched_function_tool(
+                func: Callable | None = None,
+                *,
+                name_override: str | None = None,
+                description_override: str | None = None,
+                use_docstring_info: bool = True,
+                failure_error_function: Callable | None = None,
+                strict_mode: bool = True,
+                is_enabled: bool | Callable = True,
+            ):
+                """Wrapped function_tool that adds CortexHub governance."""
+                
+                def decorator(fn: Callable) -> Any:
+                    # Create the original FunctionTool
+                    tool = original_function_tool(
+                        fn,
+                        name_override=name_override,
+                        description_override=description_override,
+                        use_docstring_info=use_docstring_info,
+                        failure_error_function=failure_error_function,
+                        strict_mode=strict_mode,
+                        is_enabled=is_enabled,
+                    )
+                    
+                    # Wrap on_invoke_tool with governance
+                    original_invoke = tool.on_invoke_tool
+                    tool_name = tool.name
+                    tool_description = tool.description
+                    
+                    async def governed_invoke(ctx, input_json: str) -> Any:
+                        """Governed tool invocation."""
+                        try:
+                            args = json.loads(input_json) if input_json else {}
+                        except json.JSONDecodeError:
+                            args = {"_raw": input_json}
+                        
+                        tool_metadata = {
+                            "name": tool_name,
+                            "description": tool_description,
+                            "framework": "openai_agents",
+                        }
+                        
+                        # Create governed function
+                        governed_fn = govern_execution(
+                            tool_fn=lambda **kw: original_invoke(ctx, input_json),
+                            tool_metadata=tool_metadata,
+                            cortex_hub=cortex_hub,
+                        )
+                        
+                        # Execute with governance
+                        result = governed_fn(**args)
+                        # Handle async
+                        if hasattr(result, '__await__'):
+                            result = await result
+                        return result
+                    
+                    # Replace on_invoke_tool with governed version
+                    # FunctionTool is a dataclass, so we need to create a new instance
+                    from agents.tool import FunctionTool
+                    
+                    governed_tool = FunctionTool(
+                        name=tool.name,
+                        description=tool.description,
+                        params_json_schema=tool.params_json_schema,
+                        on_invoke_tool=governed_invoke,
+                        strict_json_schema=tool.strict_json_schema,
+                        is_enabled=tool.is_enabled,
+                        tool_input_guardrails=tool.tool_input_guardrails,
+                        tool_output_guardrails=tool.tool_output_guardrails,
+                    )
+                    
+                    return governed_tool
+                
+                # Handle @function_tool vs @function_tool()
+                if func is not None:
+                    return decorator(func)
+                return decorator
+
+            # Apply patch
+            tool_module.function_tool = patched_function_tool
+            agents.function_tool = patched_function_tool
+            setattr(tool_module, _PATCHED_ATTR, True)
+
+            logger.info("OpenAI Agents adapter patched successfully")
+            
+        except ImportError:
+            logger.debug("OpenAI Agents SDK not installed, skipping")
+        except Exception as e:
+            logger.error("Failed to patch OpenAI Agents", error=str(e))
+    
+    def unpatch(self) -> None:
+        """Restore original function_tool decorator."""
+        try:
+            import agents
+            import agents.tool as tool_module
+            
+            if not hasattr(tool_module, _ORIGINAL_FUNCTION_TOOL_ATTR):
+                logger.debug("OpenAI Agents not patched, nothing to restore")
+                return
+            
+            original = getattr(tool_module, _ORIGINAL_FUNCTION_TOOL_ATTR)
+            tool_module.function_tool = original
+            agents.function_tool = original
+            setattr(tool_module, _PATCHED_ATTR, False)
+            
+            logger.info("OpenAI Agents adapter unpatched")
+        except ImportError:
+            pass
+    
+    def intercept(self, tool_fn, tool_name, args, **kwargs):
+        """Not used - governance happens via wrapped decorator."""
+        raise NotImplementedError("Use govern_execution via wrapped decorator")
+
+    def _discover_tools(self) -> list[dict[str, Any]]:
+        """Discover tools from OpenAI Agents SDK (best-effort)."""
+        return []

cortexhub/audit/__init__.py

@@ -0,0 +1,25 @@
+"""Audit trail schemas for enforcement and compliance."""
+
+from cortexhub.audit.events import (
+    AgentDecisionEvent,
+    ApprovalRequestEvent,
+    BaseEvent,
+    ComplianceEvent,
+    GuardrailViolationEvent,
+    LLMCallEvent,
+    PolicyDecisionEvent,
+    ToolExecutionEvent,
+    ToolInvocationEvent,
+)
+
+__all__ = [
+    "BaseEvent",
+    "ToolInvocationEvent",
+    "PolicyDecisionEvent",
+    "GuardrailViolationEvent",
+    "ApprovalRequestEvent",
+    "ToolExecutionEvent",
+    "LLMCallEvent",
+    "AgentDecisionEvent",
+    "ComplianceEvent",
+]

cortexhub/audit/events.py

@@ -0,0 +1,165 @@
+"""Audit event schemas for governance telemetry.
+
+All events include trace_id for traceability across spans and debugging.
+Uses Pydantic for type-safe, structured events.
+"""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class BaseEvent(BaseModel):
+    """Base event with common fields for all audit events."""
+
+    event_type: str
+    trace_id: str
+    session_id: str | None
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    sequence: int  # Monotonic sequence number per session for replay ordering
+
+
+class ToolInvocationEvent(BaseEvent):
+    """Event logged when a tool is invoked.
+    
+    SDK is DUMB - just sends metadata, no classifications or counts.
+    Backend aggregates and uses LLM for analysis.
+    
+    NOTE: No guardrail findings here - tools NEED the sensitive data to work.
+    NOTE: Argument VALUES only sent when privacy=False (for dev/testing).
+    """
+
+    event_type: str = "tool.invocation"
+    tool_name: str
+    tool_description: str | None = None  # Human-readable description from framework
+    arg_names: list[str] = Field(default_factory=list)  # Argument names only (NOT values)
+    framework: str  # "langchain", "openai_agents", etc.
+    agent_id: str | None = None  # Agent identifier (from cortexhub.init)
+    
+    # Only populated when privacy=False (for testing policies in dev/staging)
+    args: dict[str, Any] | None = None  # Raw argument values (NEVER in production!)
+
+
+class PolicyDecisionEvent(BaseEvent):
+    """Event logged for policy evaluation results."""
+
+    event_type: str = "policy.decision"
+    effect: str  # "allow", "deny", "escalate"
+    policy_id: str | None
+    reasoning: str
+    latency_ms: float  # Time taken to evaluate policy
+    agent_id: str | None = None  # Agent identifier
+    tool_name: str | None = None  # Tool being evaluated
+
+
+class GuardrailViolationEvent(BaseEvent):
+    """Event logged when a guardrail detects a violation."""
+
+    event_type: str = "guardrail.violation"
+    guardrail_type: str  # "pii", "secrets", "injection"
+    findings: list[dict[str, Any]]  # Detailed findings (entities, locations, scores)
+    blocked: bool  # Whether execution was blocked
+
+
+class ApprovalRequestEvent(BaseEvent):
+    """Event logged for approval requests (ESCALATE flow)."""
+
+    event_type: str = "approval.request"
+    tool_name: str
+    args: dict[str, Any]
+    approved: bool | None  # None if pending, True/False after decision
+    approver: str | None  # Who approved/denied (None for auto-approve/deny)
+    approval_mode: str  # "auto-approve", "auto-deny", "cli-prompt"
+
+
+class ToolExecutionEvent(BaseEvent):
+    """Event logged after tool execution completes."""
+
+    event_type: str = "tool.execution"
+    tool_name: str
+    success: bool
+    error: str | None  # Error message if execution failed
+    latency_ms: float  # Time taken to execute tool
+    agent_id: str | None = None  # Agent identifier
+    
+    # Only populated when privacy=False (for testing policies in dev/staging)
+    result: Any | None = None  # Raw result (NEVER in production!)
+
+
+class LLMGuardrailFindings(BaseModel):
+    """Guardrail findings for LLM calls.
+    
+    THIS is where guardrails matter - sensitive data should NOT go to LLMs.
+    """
+    pii_in_prompt: dict[str, Any] = Field(default_factory=lambda: {
+        "detected": False,
+        "count": 0,
+        "types": [],  # ["email_address", "person", "ssn"]
+        "findings": [],  # [{"type": "email", "score": 0.95}]
+    })
+    secrets_in_prompt: dict[str, Any] = Field(default_factory=lambda: {
+        "detected": False,
+        "count": 0,
+        "types": [],  # ["api_key", "password"]
+        "findings": [],
+    })
+    pii_in_response: dict[str, Any] = Field(default_factory=lambda: {
+        "detected": False,
+        "count": 0,
+        "types": [],
+        "findings": [],
+    })
+    prompt_manipulation: dict[str, Any] = Field(default_factory=lambda: {
+        "detected": False,
+        "count": 0,
+        "patterns": [],  # ["ignore_instructions", "jailbreak"]
+        "findings": [],
+    })
+
+
+class LLMCallEvent(BaseEvent):
+    """Event logged for LLM API calls.
+    
+    Guardrails ARE relevant here - sensitive data flowing to LLMs is a risk.
+    """
+
+    event_type: str = "llm.call"
+    model: str  # "gpt-4", "claude-3", etc.
+    prompt_tokens: int | None = None
+    completion_tokens: int | None = None
+    latency_ms: float = 0.0
+    cost_estimate: float | None = None
+    agent_id: str | None = None  # Agent identifier (same as tool calls)
+    
+    # Rich guardrail findings - THIS is where guardrails matter
+    guardrail_findings: LLMGuardrailFindings = Field(default_factory=LLMGuardrailFindings)
+    
+    # Only populated when privacy=False (for testing policies in dev/staging)
+    prompt: str | None = None  # Raw prompt content (NEVER in production!)
+    response: str | None = None  # Raw response content (NEVER in production!)
+
+
+class AgentDecisionEvent(BaseEvent):
+    """Event logged for agent decision-making."""
+
+    event_type: str = "agent.decision"
+    agent_id: str
+    agent_role: str | None
+    decision: str  # What the agent decided to do
+    reasoning: str | None  # Why the agent made this decision (from LLM output)
+    alternatives_considered: list[str] | None  # Other options the agent considered
+    confidence: float | None  # Confidence score (0-1)
+    context_used: dict[str, Any]  # What context the agent had
+
+
+class ComplianceEvent(BaseEvent):
+    """Event logged for regulatory compliance tracking."""
+
+    event_type: str = "compliance.audit"
+    regulation: str  # "HIPAA", "SOX", "GDPR"
+    regulation_section: str | None  # e.g., "164.312(a)(1)"
+    access_justification: str  # Why data was accessed (HIPAA minimum necessary)
+    data_classification: str | None  # "PHI", "PII", "confidential"
+    compliant: bool  # Whether action was compliant
+    violations: list[str] | None  # Any violations detected

cortexhub/auto_protect.py

@@ -0,0 +1,128 @@
+"""Framework auto-detection and automatic protection.
+
+Detects imported frameworks and applies appropriate adapters automatically.
+"""
+
+import sys
+from typing import TYPE_CHECKING
+
+import structlog
+
+if TYPE_CHECKING:
+    from cortexhub.client import CortexHub
+
+logger = structlog.get_logger(__name__)
+
+
+def auto_protect_frameworks(
+    cortex_hub: "CortexHub",
+    *,
+    enable_llm: bool = True,
+    enable_tools: bool = True,
+) -> None:
+    """Auto-detect and patch supported frameworks.
+
+    Checks sys.modules to see which frameworks are loaded, then applies
+    appropriate adapters.
+
+    Args:
+        cortex_hub: CortexHub instance
+    """
+    protected_count = 0
+
+    # Check for LangChain
+    if enable_tools and _is_langchain_available():
+        logger.info("LangChain detected - applying adapter")
+        try:
+            from cortexhub.adapters.langchain import LangChainAdapter
+
+            adapter = LangChainAdapter(cortex_hub)
+            adapter.patch()
+            protected_count += 1
+        except Exception as e:
+            logger.error("Failed to apply LangChain adapter", error=str(e))
+
+    # Check for OpenAI Agents
+    if enable_tools and _is_openai_agents_available():
+        logger.info("OpenAI Agents detected - applying adapter")
+        try:
+            from cortexhub.adapters.openai_agents import OpenAIAgentsAdapter
+
+            adapter = OpenAIAgentsAdapter(cortex_hub)
+            adapter.patch()
+            protected_count += 1
+        except Exception as e:
+            logger.error("Failed to apply OpenAI Agents adapter", error=str(e))
+
+    # Check for CrewAI
+    if enable_tools and _is_crewai_available():
+        logger.info("CrewAI detected - applying adapter")
+        try:
+            from cortexhub.adapters.crewai import CrewAIAdapter
+
+            adapter = CrewAIAdapter(cortex_hub)
+            adapter.patch()
+            protected_count += 1
+        except Exception as e:
+            logger.error("Failed to apply CrewAI adapter", error=str(e))
+
+    # Check for LlamaIndex
+    if enable_tools and _is_llamaindex_available():
+        logger.info("LlamaIndex detected - applying adapter")
+        try:
+            from cortexhub.adapters.llamaindex import LlamaIndexAdapter
+
+            adapter = LlamaIndexAdapter(cortex_hub)
+            adapter.patch()
+            protected_count += 1
+        except Exception as e:
+            logger.error("Failed to apply LlamaIndex adapter", error=str(e))
+
+    if enable_llm and _is_litellm_available():
+        logger.info("LiteLLM detected - applying adapter")
+        try:
+            from cortexhub.adapters.litellm import LiteLLMAdapter
+
+            adapter = LiteLLMAdapter(cortex_hub)
+            adapter.patch()
+            protected_count += 1
+        except Exception as e:
+            logger.error("Failed to apply LiteLLM adapter", error=str(e))
+
+    if protected_count == 0:
+        logger.warning(
+            "No supported frameworks detected. "
+            "Make sure you import your framework before calling auto_protect()"
+        )
+    else:
+        logger.info(f"Auto-protection enabled for {protected_count} framework(s)")
+
+
+def _is_langchain_available() -> bool:
+    """Check if LangChain is available."""
+    langchain_modules = [
+        "langchain",
+        "langchain_core",
+        "langchain.tools",
+    ]
+    return any(mod in sys.modules for mod in langchain_modules)
+
+
+def _is_openai_agents_available() -> bool:
+    """Check if OpenAI Agents is available."""
+    return "openai_agents" in sys.modules or "agents" in sys.modules
+
+
+def _is_crewai_available() -> bool:
+    """Check if CrewAI is available."""
+    return "crewai" in sys.modules
+
+
+def _is_llamaindex_available() -> bool:
+    """Check if LlamaIndex is available."""
+    return any(mod in sys.modules for mod in ["llama_index", "llama_index.core"])
+
+
+def _is_litellm_available() -> bool:
+    """Check if LiteLLM is available."""
+    return "litellm" in sys.modules

cortexhub/backend/__init__.py

@@ -0,0 +1,5 @@
+"""Backend communication for API key validation."""
+
+from cortexhub.backend.client import BackendClient
+
+__all__ = ["BackendClient"]