attune-ai 2.1.5__py3-none-any.whl → 2.2.0__py3-none-any.whl

attune/memory/short_term/security.py

@@ -0,0 +1,300 @@
+"""Data sanitization - PII scrubbing and secrets detection.
+
+This module handles security-sensitive data processing:
+- PII (Personally Identifiable Information) scrubbing
+- Secrets detection (API keys, passwords, tokens)
+- Data sanitization before storage
+
+Classes:
+    DataSanitizer: Handles PII and secrets scrubbing
+
+Dependencies:
+    PIIScrubber: External PII detection/removal
+    SecretsDetector: External secrets detection
+
+Example:
+    >>> from attune.memory.short_term.security import DataSanitizer
+    >>> from attune.memory.types import RedisMetrics
+    >>> sanitizer = DataSanitizer(
+    ...     pii_scrub_enabled=True,
+    ...     secrets_detection_enabled=True,
+    ...     metrics=RedisMetrics()
+    ... )
+    >>> clean_data, pii_count = sanitizer.sanitize({"email": "user@example.com"})
+    >>> print(f"Scrubbed {pii_count} PII items")
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from attune.memory.security.pii_scrubber import PIIScrubber
+from attune.memory.security.secrets_detector import SecretsDetector
+from attune.memory.security.secrets_detector import Severity as SecretSeverity
+from attune.memory.types import RedisMetrics, SecurityError
+
+if TYPE_CHECKING:
+    pass
+
+logger = structlog.get_logger(__name__)
+
+
+class DataSanitizer:
+    """Handles data sanitization for short-term memory.
+
+    Provides PII scrubbing and secrets detection to protect
+    sensitive information from being stored in Redis.
+
+    PII Detection:
+        - Email addresses
+        - Social Security Numbers (SSN)
+        - Phone numbers
+        - Credit card numbers
+
+    Secrets Detection:
+        - API keys
+        - Passwords
+        - Tokens
+        - Private keys
+
+    Attributes:
+        pii_enabled: Whether PII scrubbing is active
+        secrets_enabled: Whether secrets detection is active
+        metrics: RedisMetrics instance for tracking
+
+    Example:
+        >>> sanitizer = DataSanitizer(
+        ...     pii_scrub_enabled=True,
+        ...     secrets_detection_enabled=True,
+        ...     metrics=RedisMetrics()
+        ... )
+        >>> data = {"user": "john", "email": "john@example.com"}
+        >>> clean, count = sanitizer.sanitize(data)
+        >>> print(clean)  # Email will be redacted
+        {'user': 'john', 'email': '[EMAIL]'}
+    """
+
+    def __init__(
+        self,
+        pii_scrub_enabled: bool = False,
+        secrets_detection_enabled: bool = False,
+        metrics: RedisMetrics | None = None,
+    ) -> None:
+        """Initialize data sanitizer.
+
+        Args:
+            pii_scrub_enabled: Enable PII scrubbing (emails, SSN, etc.)
+            secrets_detection_enabled: Enable secrets detection (API keys, etc.)
+            metrics: Optional RedisMetrics for tracking scrub operations
+        """
+        self.pii_enabled = pii_scrub_enabled
+        self.secrets_enabled = secrets_detection_enabled
+        self._metrics = metrics or RedisMetrics()
+
+        # Initialize scrubbers
+        self._pii_scrubber: PIIScrubber | None = None
+        self._secrets_detector: SecretsDetector | None = None
+
+        if pii_scrub_enabled:
+            self._pii_scrubber = PIIScrubber(enable_name_detection=False)
+            logger.debug(
+                "pii_scrubber_enabled",
+                message="PII scrubbing active for data sanitizer",
+            )
+
+        if secrets_detection_enabled:
+            self._secrets_detector = SecretsDetector()
+            logger.debug(
+                "secrets_detector_enabled",
+                message="Secrets detection active for data sanitizer",
+            )
+
+    @property
+    def metrics(self) -> RedisMetrics:
+        """Get metrics instance."""
+        return self._metrics
+
+    def sanitize(self, data: Any) -> tuple[Any, int]:
+        """Sanitize data by scrubbing PII and checking for secrets.
+
+        Performs two-step sanitization:
+        1. Checks for secrets (API keys, passwords) - blocks if found
+        2. Scrubs PII (emails, SSN, phone numbers) - redacts in place
+
+        Args:
+            data: Data to sanitize (dict, list, or str)
+
+        Returns:
+            Tuple of (sanitized_data, pii_count)
+            - sanitized_data: Data with PII redacted
+            - pii_count: Number of PII items found and scrubbed
+
+        Raises:
+            SecurityError: If critical/high severity secrets are detected
+
+        Example:
+            >>> sanitizer = DataSanitizer(pii_scrub_enabled=True)
+            >>> data = {"contact": "user@example.com"}
+            >>> clean, count = sanitizer.sanitize(data)
+            >>> count
+            1
+        """
+        pii_count = 0
+
+        if data is None:
+            return data, 0
+
+        # Convert data to string for scanning
+        if isinstance(data, dict):
+            data_str = json.dumps(data)
+        elif isinstance(data, list):
+            data_str = json.dumps(data)
+        elif isinstance(data, str):
+            data_str = data
+        else:
+            # For other types, convert to string
+            data_str = str(data)
+
+        # Check for secrets first (before modifying data)
+        if self._secrets_detector is not None:
+            detections = self._secrets_detector.detect(data_str)
+            # Block critical and high severity secrets
+            critical_secrets = [
+                d
+                for d in detections
+                if d.severity in (SecretSeverity.CRITICAL, SecretSeverity.HIGH)
+            ]
+            if critical_secrets:
+                self._metrics.secrets_blocked_total += len(critical_secrets)
+                secret_types = [d.secret_type.value for d in critical_secrets]
+                logger.warning(
+                    "secrets_detected_blocked",
+                    secret_types=secret_types,
+                    count=len(critical_secrets),
+                )
+                raise SecurityError(
+                    f"Cannot store data containing secrets: {secret_types}. "
+                    "Remove sensitive credentials before storing."
+                )
+
+        # Scrub PII
+        if self._pii_scrubber is not None:
+            sanitized_str, pii_detections = self._pii_scrubber.scrub(data_str)
+            pii_count = len(pii_detections)
+
+            if pii_count > 0:
+                self._metrics.pii_scrubbed_total += pii_count
+                self._metrics.pii_scrub_operations += 1
+                logger.debug(
+                    "pii_scrubbed",
+                    pii_count=pii_count,
+                    pii_types=[d.pii_type for d in pii_detections],
+                )
+
+                # Convert back to original type
+                if isinstance(data, dict):
+                    try:
+                        return json.loads(sanitized_str), pii_count
+                    except json.JSONDecodeError:
+                        # If PII scrubbing broke JSON structure, return original
+                        # This can happen if regex matches part of JSON syntax
+                        logger.warning("pii_scrubbing_broke_json_returning_original")
+                        return data, 0
+                elif isinstance(data, list):
+                    try:
+                        return json.loads(sanitized_str), pii_count
+                    except json.JSONDecodeError:
+                        logger.warning("pii_scrubbing_broke_json_returning_original")
+                        return data, 0
+                else:
+                    return sanitized_str, pii_count
+
+        return data, pii_count
+
+    def check_secrets(self, data: Any) -> list[str]:
+        """Check data for secrets without blocking.
+
+        Args:
+            data: Data to check (dict, list, or str)
+
+        Returns:
+            List of detected secret types (empty if none found)
+
+        Example:
+            >>> sanitizer = DataSanitizer(secrets_detection_enabled=True)
+            >>> secrets = sanitizer.check_secrets({"key": "sk-abc123..."})
+            >>> if secrets:
+            ...     print(f"Found secrets: {secrets}")
+        """
+        if self._secrets_detector is None or data is None:
+            return []
+
+        # Convert data to string for scanning
+        if isinstance(data, dict):
+            data_str = json.dumps(data)
+        elif isinstance(data, list):
+            data_str = json.dumps(data)
+        elif isinstance(data, str):
+            data_str = data
+        else:
+            data_str = str(data)
+
+        detections = self._secrets_detector.detect(data_str)
+        return [d.secret_type.value for d in detections]
+
+    def scrub_pii_only(self, data: Any) -> tuple[Any, int]:
+        """Scrub only PII from data (no secrets blocking).
+
+        Args:
+            data: Data to scrub (dict, list, or str)
+
+        Returns:
+            Tuple of (scrubbed_data, pii_count)
+
+        Example:
+            >>> sanitizer = DataSanitizer(pii_scrub_enabled=True)
+            >>> clean, count = sanitizer.scrub_pii_only("Email: user@example.com")
+            >>> print(clean)  # "Email: [EMAIL]"
+        """
+        if self._pii_scrubber is None or data is None:
+            return data, 0
+
+        # Convert data to string
+        if isinstance(data, dict):
+            data_str = json.dumps(data)
+        elif isinstance(data, list):
+            data_str = json.dumps(data)
+        elif isinstance(data, str):
+            data_str = data
+        else:
+            data_str = str(data)
+
+        sanitized_str, pii_detections = self._pii_scrubber.scrub(data_str)
+        pii_count = len(pii_detections)
+
+        if pii_count == 0:
+            return data, 0
+
+        # Update metrics
+        self._metrics.pii_scrubbed_total += pii_count
+        self._metrics.pii_scrub_operations += 1
+
+        # Convert back to original type
+        if isinstance(data, dict):
+            try:
+                return json.loads(sanitized_str), pii_count
+            except json.JSONDecodeError:
+                return data, 0
+        elif isinstance(data, list):
+            try:
+                return json.loads(sanitized_str), pii_count
+            except json.JSONDecodeError:
+                return data, 0
+        else:
+            return sanitized_str, pii_count

attune/memory/short_term/sessions.py

@@ -0,0 +1,250 @@
+"""Collaboration session management.
+
+This module manages multi-agent collaboration sessions:
+- Create: Start a new collaboration session
+- Join: Add agents to existing session
+- Get: Retrieve session information
+
+Key Prefix: PREFIX_SESSION = "empathy:session:"
+
+Classes:
+    SessionManager: Collaboration session operations
+
+Example:
+    >>> from attune.memory.short_term.sessions import SessionManager
+    >>> from attune.memory.types import AgentCredentials, AccessTier
+    >>> sessions = SessionManager(base_ops)
+    >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+    >>> sessions.create_session("session_1", creds, {"topic": "refactoring"})
+    >>> sessions.join_session("session_1", other_agent_creds)
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from attune.memory.types import (
+    AgentCredentials,
+    TTLStrategy,
+)
+
+if TYPE_CHECKING:
+    from attune.memory.short_term.base import BaseOperations
+
+logger = structlog.get_logger(__name__)
+
+
+class SessionManager:
+    """Collaboration session operations.
+
+    Manages multi-agent collaboration sessions including creation,
+    joining, and retrieval. Sessions track participants and metadata.
+
+    The class is designed to be composed with BaseOperations
+    for dependency injection.
+
+    Attributes:
+        PREFIX_SESSION: Key prefix for session namespace
+
+    Example:
+        >>> sessions = SessionManager(base_ops)
+        >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+        >>> sessions.create_session("session_1", creds)
+        True
+        >>> info = sessions.get_session("session_1", creds)
+    """
+
+    PREFIX_SESSION = "empathy:session:"
+
+    def __init__(self, base: BaseOperations) -> None:
+        """Initialize session manager.
+
+        Args:
+            base: BaseOperations instance for storage access
+        """
+        self._base = base
+
+    def create_session(
+        self,
+        session_id: str,
+        credentials: AgentCredentials,
+        metadata: dict | None = None,
+    ) -> bool:
+        """Create a collaboration session.
+
+        Args:
+            session_id: Unique session identifier
+            credentials: Session creator
+            metadata: Optional session metadata
+
+        Returns:
+            True if created
+
+        Raises:
+            ValueError: If session_id is empty
+            TypeError: If metadata is not dict
+
+        Example:
+            >>> sessions.create_session(
+            ...     "session_1",
+            ...     creds,
+            ...     metadata={"topic": "code review"},
+            ... )
+            True
+        """
+        # Pattern 1: String ID validation
+        if not session_id or not session_id.strip():
+            raise ValueError(f"session_id cannot be empty. Got: {session_id!r}")
+
+        # Pattern 5: Type validation
+        if metadata is not None and not isinstance(metadata, dict):
+            raise TypeError(f"metadata must be dict, got {type(metadata).__name__}")
+
+        key = f"{self.PREFIX_SESSION}{session_id}"
+        payload = {
+            "session_id": session_id,
+            "created_by": credentials.agent_id,
+            "created_at": datetime.now().isoformat(),
+            "participants": [credentials.agent_id],
+            "metadata": metadata or {},
+        }
+
+        success = self._base._set(key, json.dumps(payload), TTLStrategy.SESSION.value)
+
+        if success:
+            logger.info(
+                "session_created",
+                session_id=session_id,
+                created_by=credentials.agent_id,
+            )
+
+        return success
+
+    def join_session(
+        self,
+        session_id: str,
+        credentials: AgentCredentials,
+    ) -> bool:
+        """Join an existing session.
+
+        Args:
+            session_id: Session to join
+            credentials: Joining agent
+
+        Returns:
+            True if joined
+
+        Raises:
+            ValueError: If session_id is empty
+
+        Example:
+            >>> sessions.join_session("session_1", agent2_creds)
+            True
+        """
+        # Pattern 1: String ID validation
+        if not session_id or not session_id.strip():
+            raise ValueError(f"session_id cannot be empty. Got: {session_id!r}")
+
+        key = f"{self.PREFIX_SESSION}{session_id}"
+        raw = self._base._get(key)
+
+        if raw is None:
+            return False
+
+        payload = json.loads(raw)
+        if credentials.agent_id not in payload["participants"]:
+            payload["participants"].append(credentials.agent_id)
+            logger.info(
+                "session_joined",
+                session_id=session_id,
+                agent_id=credentials.agent_id,
+            )
+
+        return self._base._set(key, json.dumps(payload), TTLStrategy.SESSION.value)
+
+    def get_session(
+        self,
+        session_id: str,
+        credentials: AgentCredentials,
+    ) -> dict[str, Any] | None:
+        """Get session information.
+
+        Args:
+            session_id: Session identifier
+            credentials: Any participant can read
+
+        Returns:
+            Session data or None if not found
+
+        Example:
+            >>> info = sessions.get_session("session_1", creds)
+            >>> if info:
+            ...     print(f"Participants: {info['participants']}")
+        """
+        key = f"{self.PREFIX_SESSION}{session_id}"
+        raw = self._base._get(key)
+
+        if raw is None:
+            return None
+
+        result: dict[str, Any] = json.loads(raw)
+        return result
+
+    def leave_session(
+        self,
+        session_id: str,
+        credentials: AgentCredentials,
+    ) -> bool:
+        """Leave a session.
+
+        Args:
+            session_id: Session to leave
+            credentials: Leaving agent
+
+        Returns:
+            True if left successfully
+        """
+        if not session_id or not session_id.strip():
+            raise ValueError(f"session_id cannot be empty. Got: {session_id!r}")
+
+        key = f"{self.PREFIX_SESSION}{session_id}"
+        raw = self._base._get(key)
+
+        if raw is None:
+            return False
+
+        payload = json.loads(raw)
+        if credentials.agent_id in payload["participants"]:
+            payload["participants"].remove(credentials.agent_id)
+            logger.info(
+                "session_left",
+                session_id=session_id,
+                agent_id=credentials.agent_id,
+            )
+            return self._base._set(key, json.dumps(payload), TTLStrategy.SESSION.value)
+
+        return False
+
+    def list_sessions(self) -> list[dict[str, Any]]:
+        """List all active sessions.
+
+        Returns:
+            List of session data dicts
+        """
+        pattern = f"{self.PREFIX_SESSION}*"
+        keys = self._base._keys(pattern)
+        sessions = []
+
+        for key in keys:
+            raw = self._base._get(key)
+            if raw:
+                sessions.append(json.loads(raw))
+
+        return sessions