empathy-framework 3.7.0__py3-none-any.whl → 3.8.0__py3-none-any.whl

empathy_llm_toolkit/security/secure_memdocs_example.py

@@ -0,0 +1,278 @@
+"""Secure MemDocs Integration - Example Usage
+
+Demonstrates Phase 2 enterprise privacy integration with:
+- PII scrubbing
+- Secrets detection
+- Three-tier classification
+- Encryption for SENSITIVE patterns
+- Audit logging
+
+Author: Empathy Framework Team
+Version: 1.8.0-beta
+"""
+
+import sys
+from pathlib import Path
+
+# Add parent directory to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from empathy_llm_toolkit.security import SecureMemDocsIntegration, SecurityError
+
+
+def example_basic_usage():
+    """Example 1: Basic pattern storage with auto-classification"""
+    print("\n=== Example 1: Basic Pattern Storage ===\n")
+
+    # Initialize secure integration
+    integration = SecureMemDocsIntegration(
+        storage_dir="./example_memdocs",
+        audit_log_dir="./example_logs",
+    )
+
+    # Store a simple pattern
+    content = """
+    Standard Python sorting algorithm implementation:
+
+    def quick_sort(arr):
+        if len(arr) <= 1:
+            return arr
+        pivot = arr[len(arr) // 2]
+        left = [x for x in arr if x < pivot]
+        middle = [x for x in arr if x == pivot]
+        right = [x for x in arr if x > pivot]
+        return quick_sort(left) + middle + quick_sort(right)
+    """
+
+    result = integration.store_pattern(
+        content=content,
+        pattern_type="algorithm",
+        user_id="developer@company.com",
+    )
+
+    print("Pattern stored successfully!")
+    print(f"  Pattern ID: {result['pattern_id']}")
+    print(f"  Classification: {result['classification']}")
+    print(f"  PII removed: {result['sanitization_report']['pii_count']}")
+    print(f"  Encrypted: {result['metadata']['encrypted']}")
+    print(f"  Retention: {result['metadata']['retention_days']} days")
+
+    return result["pattern_id"]
+
+
+def example_pii_scrubbing():
+    """Example 2: PII scrubbing in action"""
+    print("\n=== Example 2: PII Scrubbing ===\n")
+
+    integration = SecureMemDocsIntegration(
+        storage_dir="./example_memdocs",
+        audit_log_dir="./example_logs",
+    )
+
+    # Content with PII
+    content = """
+    Contact Information:
+    - Email: john.doe@example.com
+    - Phone: 555-123-4567
+    - SSN: 123-45-6789
+
+    For support, call our team at support@company.com
+    """
+
+    result = integration.store_pattern(
+        content=content,
+        pattern_type="contact_info",
+        user_id="hr@company.com",
+    )
+
+    print("Pattern stored with PII scrubbing:")
+    print(f"  Pattern ID: {result['pattern_id']}")
+    print(f"  PII removed: {result['sanitization_report']['pii_count']} items")
+    for pii_item in result["sanitization_report"]["pii_removed"]:
+        print(f"    - {pii_item['type']}")
+
+    # Retrieve to see scrubbed content
+    pattern = integration.retrieve_pattern(
+        pattern_id=result["pattern_id"],
+        user_id="hr@company.com",
+    )
+
+    print("\nRetrieved content (PII scrubbed):")
+    print(pattern["content"][:200] + "...")
+
+    return result["pattern_id"]
+
+
+def example_secrets_blocking():
+    """Example 3: Secrets detection blocks storage"""
+    print("\n=== Example 3: Secrets Detection ===\n")
+
+    integration = SecureMemDocsIntegration(
+        storage_dir="./example_memdocs",
+        audit_log_dir="./example_logs",
+    )
+
+    # Content with secrets (WILL BE BLOCKED)
+    content = """
+    # Configuration
+    ANTHROPIC_API_KEY = "sk-ant-api03-abc123xyz789..."
+    OPENAI_API_KEY = "sk-proj-abc123xyz789..."
+    DATABASE_URL = "postgres://user:password@localhost:5432/db"
+    """
+
+    try:
+        integration.store_pattern(
+            content=content,
+            pattern_type="config",
+            user_id="developer@company.com",
+        )
+        print("ERROR: Secrets should have been blocked!")
+    except SecurityError as e:
+        print("Storage blocked (as expected):")
+        print(f"  Reason: {e!s}")
+        print("  Action: Secrets detected and storage prevented")
+        print("  Audit: Security violation logged")
+
+
+def example_healthcare_sensitive():
+    """Example 4: Healthcare pattern with SENSITIVE classification"""
+    print("\n=== Example 4: Healthcare Pattern (SENSITIVE) ===\n")
+
+    integration = SecureMemDocsIntegration(
+        storage_dir="./example_memdocs",
+        audit_log_dir="./example_logs",
+    )
+
+    # Healthcare content (auto-classified as SENSITIVE)
+    content = """
+    # Patient Vital Signs Monitoring Protocol
+
+    Normal ranges:
+    - Heart rate: 60-100 bpm
+    - Blood pressure: 90/60 to 120/80 mmHg
+    - Respiratory rate: 12-20 breaths/min
+    - Temperature: 97-99°F (36.1-37.2°C)
+    - Oxygen saturation: 95-100%
+
+    Alert thresholds:
+    - Heart rate < 50 or > 120 bpm
+    - Systolic BP < 90 or > 180 mmHg
+    - Oxygen saturation < 92%
+    """
+
+    result = integration.store_pattern(
+        content=content,
+        pattern_type="clinical_protocol",
+        user_id="nurse@hospital.com",
+    )
+
+    print("Healthcare pattern stored:")
+    print(f"  Pattern ID: {result['pattern_id']}")
+    print(f"  Classification: {result['classification']} (auto-detected)")
+    print(f"  Encrypted: {result['metadata']['encrypted']} (HIPAA compliance)")
+    print(f"  Retention: {result['metadata']['retention_days']} days (HIPAA minimum)")
+    print("  Access: Creator only (explicit permission required)")
+
+    # Retrieve (only creator can access)
+    pattern = integration.retrieve_pattern(
+        pattern_id=result["pattern_id"],
+        user_id="nurse@hospital.com",
+    )
+
+    print("\nPattern retrieved and decrypted successfully")
+    print(f"  Content length: {len(pattern['content'])} chars")
+
+    # Try to retrieve as different user (will be blocked)
+    try:
+        pattern = integration.retrieve_pattern(
+            pattern_id=result["pattern_id"],
+            user_id="other_user@hospital.com",
+        )
+        print("ERROR: Access should have been denied!")
+    except Exception:
+        print("\nAccess denied for different user (as expected):")
+        print("  Reason: SENSITIVE patterns require explicit permission")
+
+    return result["pattern_id"]
+
+
+def example_list_patterns():
+    """Example 5: List accessible patterns"""
+    print("\n=== Example 5: List Patterns ===\n")
+
+    integration = SecureMemDocsIntegration(
+        storage_dir="./example_memdocs",
+        audit_log_dir="./example_logs",
+    )
+
+    # List patterns for user
+    patterns = integration.list_patterns(user_id="developer@company.com")
+
+    print(f"Accessible patterns: {len(patterns)}")
+    for pattern in patterns:
+        print(f"\n  Pattern: {pattern['pattern_id']}")
+        print(f"    Type: {pattern['pattern_type']}")
+        print(f"    Classification: {pattern['classification']}")
+        print(f"    Created: {pattern['created_at']}")
+        print(f"    Encrypted: {pattern['encrypted']}")
+
+
+def example_statistics():
+    """Example 6: Get storage statistics"""
+    print("\n=== Example 6: Storage Statistics ===\n")
+
+    integration = SecureMemDocsIntegration(
+        storage_dir="./example_memdocs",
+        audit_log_dir="./example_logs",
+    )
+
+    stats = integration.get_statistics()
+
+    print("MemDocs Statistics:")
+    print(f"  Total patterns: {stats['total_patterns']}")
+    print("  By classification:")
+    for classification, count in stats["by_classification"].items():
+        print(f"    - {classification}: {count}")
+    print(f"  Encrypted patterns: {stats['encrypted_count']}")
+    print(f"  With PII scrubbed: {stats['with_pii_scrubbed']}")
+
+
+def main():
+    """Run all examples"""
+    print("=" * 70)
+    print("Secure MemDocs Integration - Example Usage")
+    print("Phase 2: Enterprise Privacy Integration")
+    print("=" * 70)
+
+    try:
+        # Example 1: Basic usage
+        example_basic_usage()
+
+        # Example 2: PII scrubbing
+        example_pii_scrubbing()
+
+        # Example 3: Secrets blocking
+        example_secrets_blocking()
+
+        # Example 4: Healthcare (SENSITIVE)
+        example_healthcare_sensitive()
+
+        # Example 5: List patterns
+        example_list_patterns()
+
+        # Example 6: Statistics
+        example_statistics()
+
+        print("\n" + "=" * 70)
+        print("All examples completed successfully!")
+        print("=" * 70)
+
+    except Exception as e:
+        print(f"\n\nError running examples: {e}")
+        import traceback
+
+        traceback.print_exc()
+
+
+if __name__ == "__main__":
+    main()

empathy_llm_toolkit/wizards/__init__.py

@@ -0,0 +1,38 @@
+"""Empathy LLM Wizards - Canonical Examples
+
+Core wizard base class and canonical domain examples demonstrating
+the Empathy Framework's capabilities across different use cases.
+
+Included Wizards (3 canonical examples):
+1. HealthcareWizard - HIPAA-compliant medical assistant
+2. CustomerSupportWizard - Customer service and help desk
+3. TechnologyWizard - IT and software development operations
+
+Additional Wizards Available:
+For specialized domain wizards, install separate packages:
+- Healthcare (23 wizards): pip install empathy-healthcare-wizards
+- Tech & AI (16 wizards): pip install empathy-software-wizards
+- Business (12+ wizards): pip install empathy-business-wizards
+
+Or try the live dashboards:
+- Healthcare: https://healthcare.smartaimemory.com/static/dashboard.html
+- Tech & AI: https://wizards.smartaimemory.com/
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .base_wizard import BaseWizard, WizardConfig
+from .customer_support_wizard import CustomerSupportWizard
+from .healthcare_wizard import HealthcareWizard
+from .technology_wizard import TechnologyWizard
+
+__all__ = [
+    # Base classes
+    "BaseWizard",
+    # Canonical domain examples
+    "CustomerSupportWizard",
+    "HealthcareWizard",
+    "TechnologyWizard",
+    "WizardConfig",
+]

empathy_llm_toolkit/wizards/base_wizard.py

@@ -0,0 +1,364 @@
+"""Base Wizard - Foundation for all EmpathyLLM wizards
+
+Provides common functionality for security-aware AI assistants with domain-specific
+configurations and integrated privacy controls.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from empathy_llm_toolkit import EmpathyLLM
+from empathy_llm_toolkit.claude_memory import ClaudeMemoryConfig
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class WizardConfig:
+    """Configuration for an Empathy wizard"""
+
+    # Wizard identity
+    name: str
+    description: str
+    domain: str  # healthcare, finance, legal, general, etc.
+
+    # Empathy level (0-4)
+    default_empathy_level: int = 2
+
+    # Security configuration
+    enable_security: bool = False
+    pii_patterns: list[str] = field(default_factory=list)
+    enable_secrets_detection: bool = False
+    block_on_secrets: bool = True
+
+    # Audit configuration
+    audit_all_access: bool = False
+    retention_days: int = 180
+
+    # Classification
+    default_classification: str = "INTERNAL"  # PUBLIC, INTERNAL, SENSITIVE
+    auto_classify: bool = True
+
+    # Memory configuration
+    enable_memory: bool = False
+    memory_config: ClaudeMemoryConfig | None = None
+
+    # XML-enhanced prompts (Phase 4)
+    xml_prompts_enabled: bool = True  # Enable by default for better Claude API performance
+    xml_schema_version: str = "1.0"
+    enforce_xml_response: bool = False  # Require XML-structured responses
+
+
+class BaseWizard:
+    """Base class for all Empathy LLM wizards
+
+    Provides:
+    - Integration with EmpathyLLM
+    - Security pipeline configuration
+    - Domain-specific prompting
+    - Audit logging
+    - Session management
+    """
+
+    def __init__(
+        self,
+        llm: EmpathyLLM,
+        config: WizardConfig,
+    ):
+        """Initialize wizard with LLM and configuration
+
+        Args:
+            llm: EmpathyLLM instance (with or without security enabled)
+            config: Wizard configuration
+
+        """
+        self.llm = llm
+        self.config = config
+        self.logger = logging.getLogger(f"wizard.{config.name}")
+
+        # Validate configuration
+        self._validate_config()
+
+    def _validate_config(self):
+        """Validate wizard configuration"""
+        if not 0 <= self.config.default_empathy_level <= 4:
+            raise ValueError(f"Empathy level must be 0-4, got {self.config.default_empathy_level}")
+
+        if self.config.default_classification not in ["PUBLIC", "INTERNAL", "SENSITIVE"]:
+            raise ValueError(f"Invalid classification: {self.config.default_classification}")
+
+    async def process(
+        self,
+        user_input: str,
+        user_id: str,
+        empathy_level: int | None = None,
+        session_context: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Process user input through the wizard
+
+        Args:
+            user_input: User's message or request
+            user_id: Identifier for the user
+            empathy_level: Override default empathy level (optional)
+            session_context: Additional context for the conversation
+
+        Returns:
+            Dictionary containing:
+                - response: AI response
+                - empathy_level: Level used
+                - security_report: Security scan results (if enabled)
+                - metadata: Additional wizard metadata
+
+        """
+        level = empathy_level if empathy_level is not None else self.config.default_empathy_level
+
+        self.logger.info(
+            "processing_request: wizard=%s user_id=%s empathy_level=%s",
+            self.config.name,
+            user_id,
+            level,
+        )
+
+        # Build system prompt with domain knowledge
+        system_prompt = self._build_system_prompt()
+
+        # Add session context if provided
+        if session_context:
+            context_str = self._format_context(session_context)
+            user_input = f"{context_str}\n\n{user_input}"
+
+        # Process through EmpathyLLM (with security if enabled)
+        # Note: EmpathyLLM uses 'force_level' and 'context' parameters
+        context_dict = session_context.copy() if session_context else {}
+        context_dict["system_prompt"] = system_prompt
+
+        result = await self.llm.interact(
+            user_id=user_id,
+            user_input=user_input,
+            force_level=level,
+            context=context_dict,
+        )
+
+        # Enhance result with wizard metadata
+        result["wizard"] = {
+            "name": self.config.name,
+            "domain": self.config.domain,
+            "empathy_level": level,
+        }
+
+        return result
+
+    def _build_system_prompt(self) -> str:
+        """Build domain-specific system prompt
+
+        Override in subclasses to add domain knowledge
+        """
+        return f"""You are an AI assistant specialized in {self.config.domain}.
+
+Description: {self.config.description}
+
+Guidelines:
+- Provide accurate, helpful responses
+- Be empathetic and understanding
+- Follow domain best practices
+- Maintain user privacy and confidentiality
+"""
+
+    def _format_context(self, context: dict[str, Any]) -> str:
+        """Format session context for inclusion in prompt"""
+        lines = ["Context:"]
+        for key, value in context.items():
+            lines.append(f"- {key}: {value}")
+        return "\n".join(lines)
+
+    # =========================================================================
+    # XML-Enhanced Prompt Support (Phase 4)
+    # =========================================================================
+
+    def _is_xml_enabled(self) -> bool:
+        """Check if XML prompts are enabled for this wizard."""
+        return self.config.xml_prompts_enabled
+
+    def _render_xml_prompt(
+        self,
+        role: str,
+        goal: str,
+        instructions: list[str],
+        constraints: list[str],
+        input_type: str,
+        input_payload: str,
+        extra: dict[str, Any] | None = None,
+    ) -> str:
+        """Render a wizard prompt using XML structure.
+
+        This method follows Claude API best practices for XML-enhanced prompts,
+        providing clearer structure and better performance.
+
+        Args:
+            role: The role/expertise for the AI (e.g., "registered nurse")
+            goal: The primary objective of the task
+            instructions: Step-by-step instructions list
+            constraints: Guidelines and boundaries list
+            input_type: Type of input data (e.g., "patient_data", "code", "document")
+            input_payload: The actual input content
+            extra: Additional context fields (optional)
+
+        Returns:
+            XML-formatted prompt string
+
+        Example:
+            prompt = self._render_xml_prompt(
+                role="HIPAA compliance specialist",
+                goal="Review patient handoff for completeness",
+                instructions=[
+                    "Check for required SBAR elements",
+                    "Verify patient identifiers present",
+                    "Confirm allergies documented",
+                ],
+                constraints=[
+                    "Follow Joint Commission standards",
+                    "Maintain professional medical terminology",
+                ],
+                input_type="shift_handoff",
+                input_payload=json.dumps(handoff_data),
+            )
+
+        """
+        if not self._is_xml_enabled():
+            # Fallback to plain text if XML disabled
+            return self._render_plain_prompt(
+                role,
+                goal,
+                instructions,
+                constraints,
+                input_payload,
+            )
+
+        parts = [f'<task role="{role}" version="{self.config.xml_schema_version}">']
+        parts.append(f"  <goal>{goal}</goal>")
+        parts.append("")
+
+        if instructions:
+            parts.append("  <instructions>")
+            for i, inst in enumerate(instructions, 1):
+                parts.append(f"    {i}. {inst}")
+            parts.append("  </instructions>")
+            parts.append("")
+
+        if constraints:
+            parts.append("  <constraints>")
+            for constraint in constraints:
+                parts.append(f"    - {constraint}")
+            parts.append("  </constraints>")
+            parts.append("")
+
+        # Add extra context if provided
+        if extra:
+            parts.append("  <context>")
+            for key, value in extra.items():
+                parts.append(f"    <{key}>{value}</{key}>")
+            parts.append("  </context>")
+            parts.append("")
+
+        parts.append(f'  <input type="{input_type}">')
+        parts.append(f"    {input_payload}")
+        parts.append("  </input>")
+        parts.append("</task>")
+
+        return "\n".join(parts)
+
+    def _render_plain_prompt(
+        self,
+        role: str,
+        goal: str,
+        instructions: list[str],
+        constraints: list[str],
+        input_payload: str,
+    ) -> str:
+        """Render plain text prompt (fallback for non-XML mode).
+
+        Args:
+            role: The role/expertise for the AI
+            goal: The primary objective
+            instructions: Step-by-step instructions
+            constraints: Guidelines and boundaries
+            input_payload: The input content
+
+        Returns:
+            Plain text formatted prompt
+
+        """
+        parts = [f"Role: {role}"]
+        parts.append(f"Goal: {goal}")
+        parts.append("")
+
+        if instructions:
+            parts.append("Instructions:")
+            for i, inst in enumerate(instructions, 1):
+                parts.append(f"{i}. {inst}")
+            parts.append("")
+
+        if constraints:
+            parts.append("Guidelines:")
+            for constraint in constraints:
+                parts.append(f"- {constraint}")
+            parts.append("")
+
+        parts.append("Input:")
+        parts.append(input_payload)
+
+        return "\n".join(parts)
+
+    def _parse_xml_response(self, response: str) -> dict[str, Any]:
+        """Parse XML-structured response if enforcement is enabled.
+
+        Args:
+            response: The LLM response text
+
+        Returns:
+            Dictionary with parsed fields or raw response
+
+        Note:
+            This is a basic parser. For production use, consider
+            using the full XmlResponseParser from empathy_os.prompts.
+
+        """
+        if not self.config.enforce_xml_response:
+            return {"xml_parsed": False, "content": response}
+
+        # Basic XML parsing - extract common tags
+        import re
+
+        result: dict[str, Any] = {"xml_parsed": True}
+
+        # Extract <summary> tag
+        summary_match = re.search(r"<summary>(.*?)</summary>", response, re.DOTALL)
+        if summary_match:
+            result["summary"] = summary_match.group(1).strip()
+
+        # Extract <recommendation> tags
+        recommendations = re.findall(r"<recommendation>(.*?)</recommendation>", response, re.DOTALL)
+        if recommendations:
+            result["recommendations"] = [r.strip() for r in recommendations]
+
+        # Extract <finding> tags
+        findings = re.findall(r"<finding>(.*?)</finding>", response, re.DOTALL)
+        if findings:
+            result["findings"] = [f.strip() for f in findings]
+
+        # Always include raw content
+        result["content"] = response
+
+        return result
+
+    def get_config(self) -> WizardConfig:
+        """Get wizard configuration"""
+        return self.config
+
+    def get_name(self) -> str:
+        """Get wizard name"""
+        return self.config.name