attune-ai 2.0.0__py3-none-any.whl

attune/memory/edges.py

@@ -0,0 +1,179 @@
+"""Memory Graph Edge Types
+
+Defines edge types for connecting nodes in the knowledge graph.
+Edges represent relationships between entities discovered by workflows.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class EdgeType(Enum):
+    """Types of relationships between nodes."""
+
+    # Causal relationships
+    CAUSES = "causes"  # bug causes another bug
+    CAUSED_BY = "caused_by"  # reverse of causes
+    LEADS_TO = "leads_to"  # issue leads to another issue
+
+    # Resolution relationships
+    FIXED_BY = "fixed_by"  # bug fixed by a fix
+    FIXES = "fixes"  # fix fixes a bug
+    MITIGATES = "mitigates"  # partial fix
+
+    # Similarity relationships
+    SIMILAR_TO = "similar_to"  # similar issues
+    RELATED_TO = "related_to"  # general relation
+    DUPLICATE_OF = "duplicate_of"  # same issue
+
+    # Structural relationships
+    CONTAINS = "contains"  # file contains function
+    CONTAINED_IN = "contained_in"  # reverse
+    DEPENDS_ON = "depends_on"  # code dependency
+    IMPORTED_BY = "imported_by"  # reverse
+    AFFECTS = "affects"  # issue affects code
+    AFFECTED_BY = "affected_by"  # code affected by issue
+
+    # Testing relationships
+    TESTED_BY = "tested_by"  # code tested by test
+    TESTS = "tests"  # test tests code
+    COVERS = "covers"  # test covers code path
+
+    # Documentation relationships
+    DOCUMENTS = "documents"  # doc documents code
+    DOCUMENTED_BY = "documented_by"  # reverse
+
+    # Sequence relationships
+    PRECEDED_BY = "preceded_by"  # temporal order
+    FOLLOWED_BY = "followed_by"  # reverse
+
+    # Derivation relationships
+    DERIVED_FROM = "derived_from"  # pattern derived from code
+    REFACTORED_TO = "refactored_to"  # code refactored
+
+
+@dataclass
+class Edge:
+    """An edge connecting two nodes in the memory graph.
+
+    Represents a relationship between entities.
+    """
+
+    source_id: str
+    target_id: str
+    type: EdgeType
+
+    # Edge metadata
+    weight: float = 1.0  # Strength of relationship (0.0 - 1.0)
+    confidence: float = 1.0  # How confident we are in this edge
+
+    # Context
+    description: str = ""
+    source_workflow: str = ""
+
+    # Additional data
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    # Timestamps
+    created_at: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert edge to dictionary for JSON serialization."""
+        return {
+            "source_id": self.source_id,
+            "target_id": self.target_id,
+            "type": self.type.value,
+            "weight": self.weight,
+            "confidence": self.confidence,
+            "description": self.description,
+            "source_workflow": self.source_workflow,
+            "metadata": self.metadata,
+            "created_at": self.created_at.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Edge":
+        """Create edge from dictionary."""
+        return cls(
+            source_id=data["source_id"],
+            target_id=data["target_id"],
+            type=EdgeType(data["type"]),
+            weight=data.get("weight", 1.0),
+            confidence=data.get("confidence", 1.0),
+            description=data.get("description", ""),
+            source_workflow=data.get("source_workflow", data.get("source_wizard", "")),
+            metadata=data.get("metadata", {}),
+            created_at=(
+                datetime.fromisoformat(data["created_at"])
+                if "created_at" in data
+                else datetime.now()
+            ),
+        )
+
+    @property
+    def id(self) -> str:
+        """Generate unique edge ID."""
+        return f"{self.source_id}-{self.type.value}-{self.target_id}"
+
+
+# Common edge patterns for workflow findings
+WORKFLOW_EDGE_PATTERNS = {
+    "security-audit": [
+        (EdgeType.CAUSES, "vulnerability → vulnerability"),
+        (EdgeType.FIXED_BY, "vulnerability → fix"),
+        (EdgeType.AFFECTS, "vulnerability → file"),
+    ],
+    "bug-predict": [
+        (EdgeType.CAUSES, "bug → bug"),
+        (EdgeType.SIMILAR_TO, "bug → bug"),
+        (EdgeType.FIXED_BY, "bug → fix"),
+    ],
+    "perf-audit": [
+        (EdgeType.CAUSES, "performance_issue → performance_issue"),
+        (EdgeType.LEADS_TO, "code_smell → performance_issue"),
+        (EdgeType.MITIGATES, "refactor → performance_issue"),
+    ],
+    "code-review": [
+        (EdgeType.CONTAINS, "file → function"),
+        (EdgeType.RELATED_TO, "code_smell → pattern"),
+        (EdgeType.REFACTORED_TO, "function → function"),
+    ],
+    "test-gen": [
+        (EdgeType.TESTS, "test → function"),
+        (EdgeType.COVERS, "test → file"),
+        (EdgeType.TESTS, "test_case → bug"),
+    ],
+    "dependency-check": [
+        (EdgeType.DEPENDS_ON, "file → dependency"),
+        (EdgeType.CAUSES, "dependency → vulnerability"),
+    ],
+}
+
+
+# Reverse edge type mapping
+REVERSE_EDGE_TYPES = {
+    EdgeType.CAUSES: EdgeType.CAUSED_BY,
+    EdgeType.CAUSED_BY: EdgeType.CAUSES,
+    EdgeType.FIXED_BY: EdgeType.FIXES,
+    EdgeType.FIXES: EdgeType.FIXED_BY,
+    EdgeType.CONTAINS: EdgeType.CONTAINED_IN,
+    EdgeType.CONTAINED_IN: EdgeType.CONTAINS,
+    EdgeType.DEPENDS_ON: EdgeType.IMPORTED_BY,
+    EdgeType.IMPORTED_BY: EdgeType.DEPENDS_ON,
+    EdgeType.TESTED_BY: EdgeType.TESTS,
+    EdgeType.TESTS: EdgeType.TESTED_BY,
+    EdgeType.DOCUMENTS: EdgeType.DOCUMENTED_BY,
+    EdgeType.DOCUMENTED_BY: EdgeType.DOCUMENTS,
+    EdgeType.PRECEDED_BY: EdgeType.FOLLOWED_BY,
+    EdgeType.FOLLOWED_BY: EdgeType.PRECEDED_BY,
+    EdgeType.SIMILAR_TO: EdgeType.SIMILAR_TO,  # Symmetric
+    EdgeType.RELATED_TO: EdgeType.RELATED_TO,  # Symmetric
+    EdgeType.DUPLICATE_OF: EdgeType.DUPLICATE_OF,  # Symmetric
+    EdgeType.AFFECTS: EdgeType.AFFECTED_BY,
+    EdgeType.AFFECTED_BY: EdgeType.AFFECTS,
+}

attune/memory/encryption.py

@@ -0,0 +1,159 @@
+"""Encryption manager for long-term memory system
+
+Provides AES-256-GCM encryption/decryption for SENSITIVE patterns.
+Extracted from long_term.py for better modularity and testability.
+
+Key Features:
+- AES-256-GCM authenticated encryption
+- Master key management (environment variable, file, or generated)
+- Base64-encoded output for safe storage
+- Proper error handling and security logging
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import base64
+import binascii
+import os
+from pathlib import Path
+
+import structlog
+
+from .long_term_types import SecurityError
+
+logger = structlog.get_logger(__name__)
+
+# Check for cryptography library
+try:
+    from cryptography.exceptions import InvalidTag
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+    HAS_ENCRYPTION = True
+except ImportError:
+    HAS_ENCRYPTION = False
+    logger.warning("cryptography library not available - encryption disabled")
+
+
+class EncryptionManager:
+    """Manages encryption/decryption for SENSITIVE patterns.
+
+    Uses AES-256-GCM (Galois/Counter Mode) for authenticated encryption.
+    Keys are derived from a master key using HKDF.
+    """
+
+    def __init__(self, master_key: bytes | None = None):
+        """Initialize encryption manager.
+
+        Args:
+            master_key: 32-byte master key (or None to generate/load)
+
+        """
+        if not HAS_ENCRYPTION:
+            logger.warning("Encryption not available - install cryptography library")
+            self.enabled = False
+            return
+
+        self.enabled = True
+        self.master_key = master_key or self._load_or_generate_key()
+
+    def _load_or_generate_key(self) -> bytes:
+        """Load master key from environment or generate new one.
+
+        Production: Set EMPATHY_MASTER_KEY environment variable
+        Development: Generates ephemeral key (warning logged)
+        """
+        # Check environment variable first
+        if env_key := os.getenv("EMPATHY_MASTER_KEY"):
+            try:
+                return base64.b64decode(env_key)
+            except (binascii.Error, ValueError) as e:
+                logger.error("invalid_master_key_in_env", error=str(e))
+                raise ValueError("Invalid EMPATHY_MASTER_KEY format") from e
+
+        # Check key file
+        key_file = Path.home() / ".empathy" / "master.key"
+        if key_file.exists():
+            try:
+                return key_file.read_bytes()
+            except (OSError, PermissionError) as e:
+                logger.error("failed_to_load_key_file", error=str(e))
+
+        # Generate ephemeral key (NOT for production)
+        logger.warning(
+            "no_master_key_found",
+            message="Generating ephemeral encryption key - set EMPATHY_MASTER_KEY for production",
+        )
+        return AESGCM.generate_key(bit_length=256)
+
+    def encrypt(self, plaintext: str) -> str:
+        """Encrypt plaintext using AES-256-GCM.
+
+        Args:
+            plaintext: Content to encrypt
+
+        Returns:
+            Base64-encoded ciphertext with format: nonce||ciphertext||tag
+
+        Raises:
+            SecurityError: If encryption fails
+
+        """
+        if not self.enabled:
+            raise SecurityError("Encryption not available - install cryptography library")
+
+        try:
+            # Generate random 96-bit nonce (12 bytes)
+            nonce = os.urandom(12)
+
+            # Create AESGCM cipher
+            aesgcm = AESGCM(self.master_key)
+
+            # Encrypt and authenticate
+            ciphertext = aesgcm.encrypt(nonce, plaintext.encode("utf-8"), None)
+
+            # Combine nonce + ciphertext for storage
+            encrypted_data = nonce + ciphertext
+
+            # Return base64-encoded
+            return base64.b64encode(encrypted_data).decode("utf-8")
+
+        except (ValueError, TypeError, UnicodeEncodeError) as e:
+            logger.error("encryption_failed", error=str(e))
+            raise SecurityError(f"Encryption failed: {e}") from e
+
+    def decrypt(self, ciphertext_b64: str) -> str:
+        """Decrypt ciphertext using AES-256-GCM.
+
+        Args:
+            ciphertext_b64: Base64-encoded encrypted data
+
+        Returns:
+            Decrypted plaintext
+
+        Raises:
+            SecurityError: If decryption fails (invalid key, corrupted data, etc.)
+
+        """
+        if not self.enabled:
+            raise SecurityError("Encryption not available - install cryptography library")
+
+        try:
+            # Decode from base64
+            encrypted_data = base64.b64decode(ciphertext_b64)
+
+            # Extract nonce (first 12 bytes) and ciphertext (rest)
+            nonce = encrypted_data[:12]
+            ciphertext = encrypted_data[12:]
+
+            # Create AESGCM cipher
+            aesgcm = AESGCM(self.master_key)
+
+            # Decrypt and verify
+            plaintext_bytes = aesgcm.decrypt(nonce, ciphertext, None)
+
+            return plaintext_bytes.decode("utf-8")
+
+        except (ValueError, TypeError, UnicodeDecodeError, binascii.Error, InvalidTag) as e:
+            logger.error("decryption_failed", error=str(e))
+            raise SecurityError(f"Decryption failed: {e}") from e