agenthandler 0.92.0__py3-none-any.whl

agenthandler/policy.py

@@ -0,0 +1,251 @@
+"""Supervision policy — what limits to enforce and what to do when they're hit."""
+
+import fnmatch
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class Action(Enum):
+    """What to do when a limit is hit."""
+
+    RETURN_ERROR = "return_error"
+    RESPOND_WITH_BEST_EFFORT = "respond_with_best_effort"
+    KILL = "kill"
+
+    @classmethod
+    def from_str(cls, s: str) -> "Action":
+        mapping = {
+            "return_error": cls.RETURN_ERROR,
+            "respond_with_best_effort": cls.RESPOND_WITH_BEST_EFFORT,
+            "kill": cls.KILL,
+        }
+        return mapping.get(s, cls.RETURN_ERROR)
+
+
+@dataclass
+class OnFailure:
+    """What to do on failure + how many retries."""
+
+    action: Action = Action.RETURN_ERROR
+    retries: int = 0
+
+
+@dataclass
+class ScopeRule:
+    """A single scope constraint on a tool parameter."""
+
+    param: str  # parameter name to constrain
+    constraint: str  # "allow", "block", or "match"
+    values: List[str]  # patterns (glob-style for allow/block, regex for match)
+
+    def check(self, param_value: Any) -> bool:
+        """Returns True if the value is allowed by this rule."""
+        str_value = str(param_value)
+        if self.constraint == "allow":
+            return any(fnmatch.fnmatch(str_value, p) for p in self.values)
+        if self.constraint == "block":
+            return not any(fnmatch.fnmatch(str_value, p) for p in self.values)
+        if self.constraint == "match":
+            return any(re.search(p, str_value) for p in self.values)
+        return True
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "param": self.param,
+            "constraint": self.constraint,
+            "values": list(self.values),
+        }
+
+
+@dataclass
+class ToolScope:
+    """Scoped permissions for a specific tool."""
+
+    tool_name: str
+    rules: List[ScopeRule]
+    max_calls_per_minute: Optional[int] = None  # rate limit
+
+    def check_args(self, kwargs: Dict[str, Any]) -> Optional[str]:
+        """Check if kwargs satisfy all rules.
+
+        Returns None if OK, error message if violated.
+        """
+        for rule in self.rules:
+            if rule.param in kwargs:
+                if not rule.check(kwargs[rule.param]):
+                    return (
+                        f"Parameter '{rule.param}' value "
+                        f"'{kwargs[rule.param]}' blocked by scope rule"
+                    )
+        return None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "tool_name": self.tool_name,
+            "rules": [r.to_dict() for r in self.rules],
+        }
+        if self.max_calls_per_minute is not None:
+            d["max_calls_per_minute"] = self.max_calls_per_minute
+        return d
+
+
+@dataclass
+class Policy:
+    """Supervision policy for a skill or agent.
+
+    Configure limits, failure handlers, and confirmation gates.
+    """
+
+    # Tool execution limits
+    tool_timeout: float = 30.0  # seconds per tool call
+    max_iterations: int = 5  # max tool call rounds
+    token_budget: Optional[int] = None  # max tokens for the whole skill
+
+    # Request-level limits
+    request_timeout: float = 300.0  # seconds for the entire request
+    silence_timeout: Optional[float] = None  # dead man's switch (seconds)
+
+    # Circuit breaker
+    circuit_breaker_threshold: int = 5  # failures before opening
+    circuit_breaker_reset: float = 60.0  # seconds before half-open
+
+    # Failure handlers
+    on_timeout: OnFailure = field(default_factory=lambda: OnFailure(Action.RETURN_ERROR))
+    on_budget_exceeded: OnFailure = field(
+        default_factory=lambda: OnFailure(Action.RESPOND_WITH_BEST_EFFORT)
+    )
+    on_max_iterations: OnFailure = field(default_factory=lambda: OnFailure(Action.RETURN_ERROR))
+    on_circuit_open: OnFailure = field(default_factory=lambda: OnFailure(Action.RETURN_ERROR))
+    on_silence: OnFailure = field(default_factory=lambda: OnFailure(Action.RETURN_ERROR))
+
+    # Crash loop protection
+    max_resumes: int = 3  # max times a session can be resumed before marked failed
+
+    # Audit
+    audit_enabled: bool = True
+
+    # Confirmation gates (tool names that require user confirm)
+    require_confirm: List[str] = field(default_factory=list)
+
+    # Tool scopes (parameter-level permission rules)
+    tool_scopes: List[ToolScope] = field(default_factory=list)
+
+    # Privacy shielding — PII redaction categories
+    # Options: "email", "phone", "ssn", "credit_card", "api_key", "ip_address"
+    # Empty list = no redaction. None = redact all categories.
+    redact: Optional[List[str]] = field(default_factory=list)
+    redact_direction: str = "both"  # "inbound", "outbound", or "both"
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize to a plain dictionary (round-trips with from_dict)."""
+        d: Dict[str, Any] = {
+            "tool_timeout": self.tool_timeout,
+            "max_iterations": self.max_iterations,
+            "request_timeout": self.request_timeout,
+            "circuit_breaker_threshold": self.circuit_breaker_threshold,
+            "circuit_breaker_reset": self.circuit_breaker_reset,
+            "audit_enabled": self.audit_enabled,
+        }
+        if self.token_budget is not None:
+            d["token_budget"] = self.token_budget
+        if self.silence_timeout is not None:
+            d["silence_timeout"] = self.silence_timeout
+        for key in (
+            "on_timeout",
+            "on_budget_exceeded",
+            "on_max_iterations",
+            "on_circuit_open",
+            "on_silence",
+        ):
+            val: OnFailure = getattr(self, key)
+            d[key] = {"action": val.action.value, "retries": val.retries}
+        d["max_resumes"] = self.max_resumes
+        if self.require_confirm:
+            d["require_confirm"] = list(self.require_confirm)
+        if self.tool_scopes:
+            d["tool_scopes"] = [s.to_dict() for s in self.tool_scopes]
+        if self.redact is not None and self.redact:
+            d["redact"] = list(self.redact)
+        elif self.redact is None:
+            d["redact"] = None
+        d["redact_direction"] = self.redact_direction
+        return d
+
+    @classmethod
+    def from_dict(cls, d: Dict[str, Any]) -> "Policy":
+        """Create a Policy from a plain dictionary.
+
+        Recognised keys (all optional — missing keys use defaults):
+            tool_timeout, max_iterations, token_budget,
+            request_timeout, silence_timeout,
+            circuit_breaker_threshold, circuit_breaker_reset,
+            max_resumes,
+            on_timeout, on_budget_exceeded, on_max_iterations,
+            on_circuit_open, on_silence, audit_enabled, require_confirm
+        """
+        kwargs: Dict[str, Any] = {}
+        # Simple scalar fields
+        for key in (
+            "tool_timeout",
+            "max_iterations",
+            "token_budget",
+            "request_timeout",
+            "silence_timeout",
+            "circuit_breaker_threshold",
+            "circuit_breaker_reset",
+            "max_resumes",
+            "audit_enabled",
+        ):
+            if key in d:
+                kwargs[key] = d[key]
+
+        # OnFailure fields (accept string or dict with action + retries)
+        for key in (
+            "on_timeout",
+            "on_budget_exceeded",
+            "on_max_iterations",
+            "on_circuit_open",
+            "on_silence",
+        ):
+            if key in d:
+                val = d[key]
+                if isinstance(val, str):
+                    kwargs[key] = OnFailure(Action.from_str(val))
+                elif isinstance(val, dict):
+                    kwargs[key] = OnFailure(
+                        Action.from_str(val.get("action", "return_error")),
+                        retries=val.get("retries", 0),
+                    )
+
+        if "require_confirm" in d:
+            kwargs["require_confirm"] = list(d["require_confirm"])
+
+        if "tool_scopes" in d:
+            scopes = []
+            for scope_dict in d["tool_scopes"]:
+                rules = []
+                for r in scope_dict.get("rules", []):
+                    rules.append(
+                        ScopeRule(
+                            param=r["param"],
+                            constraint=r.get("constraint", "allow"),
+                            values=r.get("values", []),
+                        )
+                    )
+                scopes.append(
+                    ToolScope(
+                        tool_name=scope_dict["tool_name"],
+                        rules=rules,
+                        max_calls_per_minute=scope_dict.get("max_calls_per_minute"),
+                    )
+                )
+            kwargs["tool_scopes"] = scopes
+
+        if "redact" in d:
+            kwargs["redact"] = d["redact"]  # None or list of strings
+        if "redact_direction" in d:
+            kwargs["redact_direction"] = d["redact_direction"]
+
+        return cls(**kwargs)

agenthandler/redact.py

@@ -0,0 +1,260 @@
+"""Privacy shielding — PII detection and redaction for tool call data.
+
+Regex-based pattern matching that intercepts tool call inputs and outputs,
+replacing sensitive data with placeholders. Fast, zero dependencies,
+catches the common cases.
+
+For HIPAA/GDPR-grade redaction, use a dedicated NER service — this
+catches accidental leakage, not adversarial exfiltration.
+
+Usage:
+    from agenthandler.redact import Redactor
+
+    redactor = Redactor(categories=["email", "phone", "ssn"])
+    clean = redactor.redact("Call me at 555-123-4567 or bob@example.com")
+    # "Call me at [PHONE] or [EMAIL]"
+"""
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Set, Tuple
+
+# ---------------------------------------------------------------------------
+# Pattern registry
+# ---------------------------------------------------------------------------
+
+# Each pattern: (category_name, compiled_regex, placeholder)
+_PATTERNS: List[Tuple[str, "re.Pattern[str]", str]] = [
+    (
+        "email",
+        re.compile(r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b"),
+        "[EMAIL]",
+    ),
+    (
+        "phone",
+        re.compile(
+            r"(?<!\d)"  # not preceded by digit
+            r"(?:"
+            r"\+?1[-.\s]?"  # optional country code
+            r")?"
+            r"(?:\(?\d{3}\)?[-.\s]?)"  # area code
+            r"\d{3}[-.\s]?\d{4}"  # number
+            r"(?!\d)"  # not followed by digit
+        ),
+        "[PHONE]",
+    ),
+    (
+        "ssn",
+        re.compile(r"\b\d{3}-\d{2}-\d{4}\b"),
+        "[SSN]",
+    ),
+    (
+        "credit_card",
+        re.compile(
+            r"\b(?:"
+            r"\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}"  # 16 digits
+            r"|"
+            r"\d{4}[-\s]?\d{6}[-\s]?\d{5}"  # amex 15 digits
+            r")\b"
+        ),
+        "[CREDIT_CARD]",
+    ),
+    (
+        "api_key",
+        re.compile(
+            r"(?:"
+            r"sk-[A-Za-z0-9]{20,}"  # OpenAI-style
+            r"|"
+            r"sk-ant-[A-Za-z0-9-]{20,}"  # Anthropic-style
+            r"|"
+            r"AKIA[A-Z0-9]{16}"  # AWS access key
+            r"|"
+            r"ghp_[A-Za-z0-9]{36}"  # GitHub PAT
+            r"|"
+            r"xox[boaprs]-[A-Za-z0-9-]{10,}"  # Slack token
+            r")"
+        ),
+        "[API_KEY]",
+    ),
+    (
+        "ip_address",
+        re.compile(
+            r"\b(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}"
+            r"(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\b"
+        ),
+        "[IP_ADDR]",
+    ),
+    # -- International patterns --
+    (
+        "phone",  # international phone numbers: +XX XXXX XXXXXX etc.
+        re.compile(
+            r"(?<!\d)"
+            r"\+(?:44|49|33|61|81|86|91|7|34|39|55|82|65|852)"  # country codes
+            r"[-.\s]?\d{1,5}[-.\s]?\d{3,5}[-.\s]?\d{3,5}"
+            r"(?!\d)"
+        ),
+        "[PHONE]",
+    ),
+    (
+        "national_id",  # UK National Insurance Number
+        re.compile(r"\b[A-CEGHJ-PR-TW-Z]{2}\s?\d{2}\s?\d{2}\s?\d{2}\s?[A-D]\b"),
+        "[NATIONAL_ID]",
+    ),
+    (
+        "national_id",  # German Tax ID (Steuerliche Identifikationsnummer)
+        re.compile(r"\b\d{2}\s?\d{3}\s?\d{3}\s?\d{3}\b"),
+        "[NATIONAL_ID]",
+    ),
+    (
+        "iban",  # International Bank Account Number
+        re.compile(
+            r"\b[A-Z]{2}\d{2}[\s]?[\dA-Z]{4}[\s]?[\dA-Z]{4}[\s]?[\dA-Z]{4}(?:[\s]?[\dA-Z]{1,4}){0,5}\b"
+        ),
+        "[IBAN]",
+    ),
+    (
+        "passport",  # Common passport number patterns
+        re.compile(r"\b[A-Z]{1,2}\d{6,9}\b"),
+        "[PASSPORT]",
+    ),
+]
+
+# All known category names
+ALL_CATEGORIES: Set[str] = {name for name, _, _ in _PATTERNS}
+
+
+# ---------------------------------------------------------------------------
+# Redactor
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RedactionResult:
+    """Result of a redaction pass."""
+
+    text: str
+    redacted_count: int = 0
+    categories_found: List[str] = field(default_factory=list)
+
+
+class Redactor:
+    """PII redactor with configurable categories and optional NLP augmentation.
+
+    Args:
+        categories: Which PII types to detect. Defaults to all.
+                   Options: "email", "phone", "ssn", "credit_card",
+                   "api_key", "ip_address", "national_id", "iban", "passport"
+        use_nlp: If True, augment regex with spaCy NER for names, locations,
+                 and other context-dependent PII. Requires spacy + a model.
+                 Install with: pip install spacy && python -m spacy download en_core_web_sm
+    """
+
+    def __init__(self, categories: Optional[List[str]] = None, use_nlp: bool = False):
+        if categories is None:
+            self._patterns = _PATTERNS
+        else:
+            cats = set(categories)
+            self._patterns = [(n, p, r) for n, p, r in _PATTERNS if n in cats]
+
+        self._nlp = None
+        if use_nlp:
+            self._init_nlp()
+
+    def _init_nlp(self) -> None:
+        """Load spaCy model for NER. Fails silently if not installed."""
+        try:
+            import spacy  # type: ignore[import-not-found]
+
+            self._nlp = spacy.load("en_core_web_sm")
+        except (ImportError, OSError):
+            pass  # spaCy not installed or model not downloaded
+
+    @property
+    def categories(self) -> List[str]:
+        return [name for name, _, _ in self._patterns]
+
+    def redact(self, text: str) -> RedactionResult:
+        """Redact PII from a string.
+
+        Returns a RedactionResult with the cleaned text and metadata
+        about what was found.
+        """
+        if not isinstance(text, str):
+            return RedactionResult(text=str(text))
+
+        result_text = text
+        total_count = 0
+        found_categories: List[str] = []
+
+        for name, pattern, placeholder in self._patterns:
+            new_text, count = pattern.subn(placeholder, result_text)
+            if count > 0:
+                total_count += count
+                if name not in found_categories:
+                    found_categories.append(name)
+                result_text = new_text
+
+        # NLP augmentation — catch names, locations, orgs that regex misses
+        if self._nlp is not None:
+            nlp_text, nlp_count, nlp_cats = self._nlp_redact(result_text)
+            if nlp_count > 0:
+                result_text = nlp_text
+                total_count += nlp_count
+                for cat in nlp_cats:
+                    if cat not in found_categories:
+                        found_categories.append(cat)
+
+        return RedactionResult(
+            text=result_text,
+            redacted_count=total_count,
+            categories_found=found_categories,
+        )
+
+    # NER entity label → placeholder mapping
+    _NER_LABELS = {
+        "PERSON": "[PERSON]",
+        "GPE": "[LOCATION]",
+        "LOC": "[LOCATION]",
+        "ORG": "[ORG]",
+        "NORP": "[GROUP]",
+    }
+
+    def _nlp_redact(self, text: str) -> Tuple[str, int, List[str]]:
+        """Apply spaCy NER to catch context-dependent PII."""
+        if self._nlp is None:
+            return text, 0, []
+        doc = self._nlp(text)
+        replacements = []
+        categories: List[str] = []
+        for ent in doc.ents:
+            if ent.label_ in self._NER_LABELS:
+                replacements.append((ent.start_char, ent.end_char, self._NER_LABELS[ent.label_]))
+                cat = self._NER_LABELS[ent.label_].strip("[]").lower()
+                if cat not in categories:
+                    categories.append(cat)
+
+        if not replacements:
+            return text, 0, []
+
+        # Apply replacements in reverse order to preserve offsets
+        result = text
+        for start, end, placeholder in sorted(replacements, reverse=True):
+            result = result[:start] + placeholder + result[end:]
+
+        return result, len(replacements), categories
+
+    def redact_dict(self, d: Dict[str, Any]) -> Tuple[Dict[str, Any], int]:
+        """Redact PII from all string values in a dict (shallow).
+
+        Returns (cleaned_dict, total_redaction_count).
+        """
+        cleaned = {}
+        total = 0
+        for k, v in d.items():
+            if isinstance(v, str):
+                result = self.redact(v)
+                cleaned[k] = result.text
+                total += result.redacted_count
+            else:
+                cleaned[k] = v
+        return cleaned, total