cortexhub 0.1.0__py3-none-any.whl

cortexhub/config.py

@@ -0,0 +1,37 @@
+"""Configuration management for CortexHub SDK.
+
+The SDK configuration is minimal by design:
+- Telemetry is ALWAYS governance mode (not configurable)
+- Guardrail behavior comes from POLICIES (not SDK config)
+- Approval behavior comes from POLICIES (not SDK config)
+
+SDK only configures:
+- Where to cache policies locally
+- Connection settings (API key, URL)
+"""
+
+import os
+
+
+class Config:
+    """SDK configuration - minimal by design.
+    
+    Most behavior is determined by POLICIES in the CortexHub cloud,
+    not SDK configuration.
+    """
+
+    def __init__(
+        self,
+        policies_dir: str = "./policies",
+    ):
+        """Initialize configuration.
+
+        Args:
+            policies_dir: Directory for local policy cache
+        """
+        self.policies_dir = policies_dir
+
+    def validate(self) -> None:
+        """Validate configuration settings."""
+        # Minimal validation - most config comes from cloud
+        pass

cortexhub/context/__init__.py

@@ -0,0 +1,5 @@
+"""Context enrichment for enhanced policy evaluation."""
+
+from cortexhub.context.enricher import ContextEnricher
+
+__all__ = ["ContextEnricher"]

cortexhub/context/enricher.py

@@ -0,0 +1,172 @@
+"""Context enrichment for policy evaluation.
+
+Adds runtime context to authorization requests:
+- Agent roles and metadata
+- Temporal constraints (time of day, business hours)
+- Regulatory flags (HIPAA, SOX, GDPR)
+- User context (when available)
+"""
+
+from datetime import datetime
+from typing import Any
+
+import structlog
+
+from cortexhub.policy.models import AuthorizationRequest
+
+logger = structlog.get_logger(__name__)
+
+
+class AgentRegistry:
+    """Registry mapping agent IDs to roles and metadata."""
+
+    def __init__(self):
+        """Initialize agent registry."""
+        self._agents: dict[str, dict[str, Any]] = {}
+
+    def register(
+        self,
+        agent_id: str,
+        role: str,
+        permissions: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Register an agent with role and permissions.
+
+        Args:
+            agent_id: Unique agent identifier
+            role: Agent role (e.g., "nurse", "refund_processor")
+            permissions: List of allowed actions
+            metadata: Additional metadata (tenure, department, etc.)
+        """
+        self._agents[agent_id] = {
+            "role": role,
+            "permissions": permissions or [],
+            "metadata": metadata or {},
+        }
+        logger.info("Agent registered", agent_id=agent_id, role=role)
+
+    def get(self, agent_id: str) -> dict[str, Any]:
+        """Get agent metadata.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            Agent metadata or empty dict if not found
+        """
+        return self._agents.get(agent_id, {})
+
+
+class ContextEnricher:
+    """Enriches authorization requests with runtime context.
+
+    Adds:
+    - Agent roles and permissions
+    - Temporal constraints (time, business hours)
+    - Regulatory flags (HIPAA, SOX compliance)
+    - User context
+    """
+
+    def __init__(self, agent_registry: AgentRegistry | None = None):
+        """Initialize context enricher.
+
+        Args:
+            agent_registry: Optional agent registry for role lookup
+        """
+        self.agent_registry = agent_registry or AgentRegistry()
+        logger.info("Context enricher initialized")
+
+    def enrich(self, request: AuthorizationRequest) -> AuthorizationRequest:
+        """Enrich authorization request with additional context.
+
+        INVARIANT: Enrichment may only ADD context keys, never MUTATE args or resource.
+        This protects policy correctness and audit integrity.
+
+        Args:
+            request: Base authorization request
+
+        Returns:
+            Enriched authorization request
+        """
+        agent_id = request.principal.id
+
+        # Get agent metadata
+        agent_metadata = self.agent_registry.get(agent_id)
+
+        if agent_metadata:
+            # Add agent role
+            request.context["agent_role"] = agent_metadata.get("role", "unknown")
+            request.context["agent_permissions"] = agent_metadata.get("permissions", [])
+
+            # Add agent metadata
+            metadata_dict = agent_metadata.get("metadata", {})
+            if metadata_dict:
+                request.context["agent_metadata"] = metadata_dict
+
+            logger.debug(
+                "Agent context enriched",
+                agent_id=agent_id,
+                role=agent_metadata.get("role"),
+                trace_id=request.trace_id,
+            )
+
+        # Add temporal context
+        now = datetime.utcnow()
+        request.context["temporal"] = {
+            "timestamp": now.isoformat(),
+            "hour": now.hour,
+            "day_of_week": now.weekday(),  # 0=Monday, 6=Sunday
+            "is_business_hours": self._is_business_hours(now),
+        }
+
+        # Add regulatory context (based on agent role)
+        if agent_metadata:
+            role = agent_metadata.get("role", "")
+            request.context["regulatory"] = self._get_regulatory_context(role)
+
+        return request
+
+    def _is_business_hours(self, dt: datetime) -> bool:
+        """Check if current time is within business hours.
+
+        Args:
+            dt: Datetime to check
+
+        Returns:
+            True if business hours (9 AM - 5 PM, Monday-Friday)
+        """
+        # Business hours: 9 AM - 5 PM, Monday-Friday
+        is_weekday = dt.weekday() < 5  # 0-4 = Monday-Friday
+        is_work_hours = 9 <= dt.hour < 17  # 9 AM - 5 PM
+        return is_weekday and is_work_hours
+
+    def _get_regulatory_context(self, role: str) -> dict[str, Any]:
+        """Get regulatory context based on agent role.
+
+        Args:
+            role: Agent role
+
+        Returns:
+            Regulatory context dict
+        """
+        context = {
+            "hipaa_applicable": False,
+            "sox_applicable": False,
+            "gdpr_applicable": False,
+            "minimum_necessary": False,
+        }
+
+        # Healthcare roles = HIPAA
+        if role in ["nurse", "doctor", "healthcare_agent", "patient_communication"]:
+            context["hipaa_applicable"] = True
+            context["minimum_necessary"] = True  # HIPAA minimum necessary rule
+
+        # Financial roles = SOX
+        if role in ["refund_processor", "billing_agent", "finance_agent"]:
+            context["sox_applicable"] = True
+
+        # All roles = GDPR (if EU)
+        context["gdpr_applicable"] = True
+
+        return context

cortexhub/errors.py

@@ -0,0 +1,123 @@
+"""Exception types for CortexHub SDK.
+
+Distinct error types for debugging without ambiguity.
+"""
+
+from typing import Any
+
+
+class CortexHubError(Exception):
+    """Base exception for all CortexHub errors."""
+
+    pass
+
+
+class ConfigurationError(CortexHubError):
+    """Raised when SDK configuration is invalid (missing API key, etc.)."""
+
+    pass
+
+
+class PolicyViolationError(CortexHubError):
+    """Raised when a policy forbids a tool invocation (effect=DENY)."""
+
+    def __init__(self, message: str, policy_id: str | None = None, reasoning: str = ""):
+        super().__init__(message)
+        self.policy_id = policy_id
+        self.reasoning = reasoning
+
+
+class GuardrailViolationError(CortexHubError):
+    """Raised when a guardrail detects a violation (PII, secrets, injection)."""
+
+    def __init__(
+        self,
+        message: str,
+        guardrail_type: str,
+        findings: list[dict] | None = None,
+    ):
+        super().__init__(message)
+        self.guardrail_type = guardrail_type
+        self.findings = findings or []
+
+
+class ApprovalRequiredError(CortexHubError):
+    """Raised when policy requires human approval before execution.
+
+    The SDK creates an approval record in CortexHub cloud. Customer's system
+    receives an approval.requested webhook and handles the approval workflow.
+    After decision, customer resumes the agent using framework-native mechanisms.
+
+    Attributes:
+        approval_id: Cloud approval record ID (apr_xxx)
+        run_id: SDK session ID for correlation
+        tool_name: Name of the tool requiring approval
+        policy_id: Policy that triggered escalation
+        policy_name: Human-readable policy name
+        reason: Policy explanation (why approval is required)
+        expires_at: When approval expires (ISO format)
+        decision_endpoint: URL to submit decision
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        approval_id: str,
+        run_id: str,
+        tool_name: str,
+        policy_id: str | None = None,
+        policy_name: str | None = None,
+        reason: str = "",
+        expires_at: str | None = None,
+        decision_endpoint: str | None = None,
+    ):
+        super().__init__(message)
+        self.approval_id = approval_id
+        self.run_id = run_id
+        self.tool_name = tool_name
+        self.policy_id = policy_id
+        self.policy_name = policy_name
+        self.reason = reason
+        self.expires_at = expires_at
+        self.decision_endpoint = decision_endpoint
+
+    def to_dict(self) -> dict[str, Any]:
+        """Deterministic outcome for customer handling."""
+        return {
+            "type": "approval_required",
+            "blocked": True,
+            "approval_id": self.approval_id,
+            "run_id": self.run_id,
+            "tool_name": self.tool_name,
+            "policy_id": self.policy_id,
+            "policy_name": self.policy_name,
+            "reason": self.reason,
+            "expires_at": self.expires_at,
+            "decision_endpoint": self.decision_endpoint,
+        }
+
+
+class ApprovalDeniedError(CortexHubError):
+    """Raised when an approval request is denied or expired."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        approval_id: str,
+        denied_by: str | None = None,
+        reason: str = "",
+    ):
+        super().__init__(message)
+        self.approval_id = approval_id
+        self.denied_by = denied_by
+        self.reason = reason
+
+
+class PolicyLoadError(CortexHubError):
+    """Raised when policy bundle cannot be loaded or is invalid."""
+
+    def __init__(self, message: str, policies_dir: str):
+        super().__init__(message)
+        self.policies_dir = policies_dir

cortexhub/frameworks.py

@@ -0,0 +1,83 @@
+"""Supported framework definitions.
+
+Users specify which framework they're using via the Framework enum.
+This avoids fragile auto-detection and makes dependencies explicit.
+
+We support AGENT frameworks only - not LLM proxies or RAG tools.
+"""
+
+from enum import Enum
+
+
+class Framework(str, Enum):
+    """Supported AI agent frameworks.
+    
+    CortexHub supports frameworks that provide agent orchestration with
+    native approval/human-in-the-loop mechanisms:
+    
+    - LangGraph: Checkpointing + interrupt()
+    - CrewAI: human_input=True
+    - OpenAI Agents SDK: needsApproval + state serialization
+    - Claude Agent SDK: Subagents + tool-based
+    
+    Usage:
+        import cortexhub
+        cortex = cortexhub.init("my_agent", cortexhub.Framework.LANGGRAPH)
+    
+    Each framework requires its corresponding optional dependency:
+        pip install cortexhub[langgraph]
+        pip install cortexhub[crewai]
+        pip install cortexhub[openai-agents]
+        pip install cortexhub[claude-agents]
+    """
+    
+    LANGGRAPH = "langgraph"
+    """LangGraph - Stateful agent orchestration.
+    
+    Features:
+    - Graph-based agent workflows
+    - Checkpointing for pause/resume
+    - interrupt() for human-in-the-loop
+    - Cycles and branches
+    
+    Install: pip install cortexhub[langgraph]
+    """
+    
+    CREWAI = "crewai"
+    """CrewAI - Multi-agent crews.
+    
+    Features:
+    - Role-based agents
+    - Sequential and hierarchical processes
+    - human_input=True for approval
+    - Task delegation
+    
+    Install: pip install cortexhub[crewai]
+    """
+    
+    OPENAI_AGENTS = "openai_agents"
+    """OpenAI Agents SDK.
+    
+    Features:
+    - Native tool calling
+    - needsApproval for human-in-the-loop
+    - State serialization for pause/resume
+    - Handoffs between agents
+    
+    Install: pip install cortexhub[openai-agents]
+    """
+    
+    CLAUDE_AGENTS = "claude_agents"
+    """Claude Agent SDK (formerly Claude Code SDK).
+    
+    Features:
+    - Computer use (bash, files, code)
+    - Subagents for parallelization
+    - MCP integration
+    - Context compaction
+    
+    Install: pip install cortexhub[claude-agents]
+    """
+    
+    def __str__(self) -> str:
+        return self.value

cortexhub/guardrails/__init__.py

@@ -0,0 +1,3 @@
+"""Guardrails for PII detection, secrets scanning, and prompt manipulation detection."""
+
+__all__ = []

cortexhub/guardrails/injection.py

@@ -0,0 +1,180 @@
+"""Prompt injection detection using pattern-based heuristics.
+
+Lightweight, fast detection without ML dependencies.
+Baseline defense against common attack patterns.
+
+Premium Features (Backend):
+- LLM Guard: ML-based injection + jailbreak detection
+- Toxicity detection
+- Advanced attack pattern recognition
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+
+@dataclass
+class ManipulationDetectionResult:
+    """Result of prompt manipulation detection scan."""
+    detected: bool
+    patterns: list[str]
+    findings: list[dict[str, Any]] = field(default_factory=list)
+    
+    @property
+    def count(self) -> int:
+        """Total matches found."""
+        return len(self.findings)
+
+
+class PromptManipulationDetector:
+    """Lightweight prompt injection detection using patterns.
+
+    Detects common attack patterns:
+    - Role switching ("ignore previous instructions")
+    - System override ("you are now admin")
+    - Delimiter abuse (excessive delimiters)
+    - Encoding tricks (base64, decode)
+    - Context escape ("end of system")
+    - Instruction injection (special tokens)
+
+    For premium ML-based detection (toxicity, advanced jailbreaks),
+    use backend LLM Guard integration.
+    """
+
+    def __init__(self, enabled: bool = True, sensitivity: float = 0.7):
+        """Initialize prompt manipulation detector.
+
+        Args:
+            enabled: Whether detection is enabled
+            sensitivity: Detection sensitivity (0.0-1.0, higher = more strict)
+        """
+        self.enabled = enabled
+        self.sensitivity = sensitivity
+        self._compile_patterns()
+        logger.info(
+            "Prompt manipulation detector initialized (pattern-based, lightweight)",
+            enabled=enabled,
+            sensitivity=sensitivity,
+        )
+
+    def _compile_patterns(self) -> None:
+        """Compile patterns for common prompt manipulation techniques."""
+        self.patterns = {
+            # Role switching / instruction negation
+            "role_switch": re.compile(
+                r"\b(ignore|disregard|forget|override|bypass)\s+"
+                r"(previous|above|prior|all|any)\s+"
+                r"(instructions?|rules?|constraints?|context|prompts?)\b",
+                re.IGNORECASE,
+            ),
+            # System override / privilege escalation
+            "system_override": re.compile(
+                r"\b(you are now|act as|pretend to be|system message|"
+                r"new instructions?|admin mode|developer mode|god mode)\b",
+                re.IGNORECASE,
+            ),
+            # Delimiter abuse
+            "delimiter_abuse": re.compile(r"(```|---|===|\*\*\*|###){3,}"),
+            # Encoding tricks
+            "encoding_tricks": re.compile(
+                r"\b(base64|rot13|hex|decode|unescape|eval|exec)\s*[([]",
+                re.IGNORECASE,
+            ),
+            # Context escape
+            "context_escape": re.compile(
+                r"\b(end of|start of|begin|finish)\s+(context|system|prompt|instructions?)\b",
+                re.IGNORECASE,
+            ),
+            # Instruction injection (special tokens)
+            "instruction_injection": re.compile(
+                r"<\|?(im_start|im_end|system|assistant|user)\|?>",
+                re.IGNORECASE,
+            ),
+        }
+
+    def scan(self, text: str | dict[str, Any]) -> list[dict[str, Any]]:
+        """Scan text for prompt manipulation patterns.
+
+        Args:
+            text: Text or dict to scan
+
+        Returns:
+            List of findings with pattern type and position
+        """
+        if not self.enabled:
+            return []
+
+        # Convert dict to JSON string for scanning
+        if isinstance(text, dict):
+            import json
+
+            text = json.dumps(text)
+
+        findings = []
+
+        for pattern_name, pattern in self.patterns.items():
+            matches = pattern.finditer(text)
+            for match in matches:
+                findings.append(
+                    {
+                        "type": pattern_name,
+                        "value": match.group(),
+                        "start": match.start(),
+                        "end": match.end(),
+                        "confidence": 0.7,  # Pattern-based has moderate confidence
+                    }
+                )
+
+        # Filter by sensitivity threshold
+        findings = [f for f in findings if f["confidence"] >= (1.0 - self.sensitivity)]
+
+        if findings:
+            logger.warning(
+                "Prompt manipulation patterns detected (lightweight)",
+                count=len(findings),
+                patterns=list(set(f["type"] for f in findings)),
+            )
+
+        return findings
+
+    def detect(self, text: str | dict[str, Any]) -> ManipulationDetectionResult:
+        """Detect prompt manipulation and return structured result.
+
+        Args:
+            text: Text or dict to scan
+
+        Returns:
+            ManipulationDetectionResult with detection details
+        """
+        findings = self.scan(text)
+        
+        if not findings:
+            return ManipulationDetectionResult(
+                detected=False,
+                patterns=[],
+                findings=[],
+            )
+        
+        patterns = list(set(f["type"] for f in findings))
+        
+        return ManipulationDetectionResult(
+            detected=True,
+            patterns=patterns,
+            findings=findings,
+        )
+
+    def has_manipulation(self, text: str | dict[str, Any]) -> bool:
+        """Check if text contains manipulation patterns.
+
+        Args:
+            text: Text or dict to check
+
+        Returns:
+            True if manipulation patterns detected
+        """
+        return len(self.scan(text)) > 0