empathy-framework 4.6.6__py3-none-any.whl → 4.7.1__py3-none-any.whl

empathy_llm_toolkit/wizards/healthcare_wizard.py

@@ -1,378 +0,0 @@
-"""Healthcare Wizard - HIPAA-Compliant AI Assistant
-
-⚠️ DEPRECATED: This wizard is a basic example and is no longer actively maintained.
-For production healthcare applications, use the specialized healthcare plugin:
-    pip install empathy-healthcare-wizards
-
-Or visit: https://healthcare.smartaimemory.com/
-
-Specialized wizard for healthcare applications with enhanced PHI protection,
-mandatory encryption, comprehensive audit logging, and HIPAA compliance features.
-
-Key Features:
-- Enhanced PHI/PII detection (10+ medical patterns)
-- Automatic de-identification before LLM processing
-- Mandatory AES-256-GCM encryption for all data
-- 90-day minimum retention (HIPAA §164.528)
-- Comprehensive audit trail (HIPAA §164.312(b))
-- Access control and permission enforcement
-- Automatic classification as SENSITIVE
-
-Reference:
-- HIPAA Security Rule (45 CFR §164.312)
-- HIPAA Privacy Rule (45 CFR §164.514)
-- HITECH Act requirements
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-import logging
-import warnings
-from typing import Any
-
-from empathy_llm_toolkit import EmpathyLLM
-
-from .base_wizard import BaseWizard, WizardConfig
-
-logger = logging.getLogger(__name__)
-
-# Deprecation warning
-warnings.warn(
-    "HealthcareWizard is deprecated and will be removed in v5.0. "
-    "Use the specialized healthcare plugin instead: "
-    "pip install empathy-healthcare-wizards",
-    DeprecationWarning,
-    stacklevel=2,
-)
-
-
-# Enhanced PHI patterns for healthcare (beyond standard PII)
-HEALTHCARE_PHI_PATTERNS = [
-    # Standard PII (enabled by default)
-    "email",
-    "phone",
-    "ssn",
-    "address",
-    "credit_card",
-    "ip_address",
-    # Healthcare-specific PHI
-    "mrn",  # Medical Record Number
-    "patient_id",  # Patient identifier
-    "dob",  # Date of birth
-    "insurance_id",  # Insurance/policy numbers
-    "provider_npi",  # National Provider Identifier
-    "cpt_code",  # Medical procedure codes
-    "icd_code",  # Diagnosis codes
-    "medication_name",  # Medication names (optional, configurable)
-]
-
-
-class HealthcareWizard(BaseWizard):
-    """HIPAA-compliant healthcare AI assistant
-
-    Implements defense-in-depth security for Protected Health Information (PHI):
-    1. Enhanced PHI detection and scrubbing
-    2. Secrets detection (API keys, passwords in medical software configs)
-    3. Mandatory encryption (AES-256-GCM)
-    4. Comprehensive audit logging
-    5. 90-day minimum retention
-    6. Access control enforcement
-
-    Example:
-        >>> from empathy_llm_toolkit import EmpathyLLM
-        >>> from empathy_llm_toolkit.wizards import HealthcareWizard
-        >>>
-        >>> llm = EmpathyLLM(
-        ...     provider="anthropic",
-        ...     api_key=os.getenv("ANTHROPIC_API_KEY"),
-        ...     enable_security=True,
-        ... )
-        >>>
-        >>> wizard = HealthcareWizard(llm)
-        >>>
-        >>> result = await wizard.process(
-        ...     user_input="Patient John Doe (MRN 123456) needs follow-up",
-        ...     user_id="doctor@hospital.com"
-        ... )
-        >>>
-        >>> print(result['security_report']['phi_removed'])  # PHI was scrubbed
-
-    """
-
-    def __init__(
-        self,
-        llm: EmpathyLLM,
-        enable_medication_scrubbing: bool = False,
-        enable_diagnosis_scrubbing: bool = False,
-        custom_phi_patterns: list[str] | None = None,
-    ):
-        """Initialize HIPAA-compliant healthcare wizard
-
-        Args:
-            llm: EmpathyLLM instance (security should be enabled)
-            enable_medication_scrubbing: Scrub medication names (may reduce context)
-            enable_diagnosis_scrubbing: Scrub diagnosis codes (may reduce context)
-            custom_phi_patterns: Additional facility-specific PHI patterns
-
-        Note:
-            For maximum HIPAA compliance, llm should be initialized with
-            enable_security=True. This wizard enforces SENSITIVE classification
-            and 90-day retention regardless of LLM security settings.
-
-        """
-        # Build PHI pattern list
-        phi_patterns = HEALTHCARE_PHI_PATTERNS.copy()
-
-        if not enable_medication_scrubbing:
-            phi_patterns.remove("medication_name")
-        if not enable_diagnosis_scrubbing:
-            if "cpt_code" in phi_patterns:
-                phi_patterns.remove("cpt_code")
-            if "icd_code" in phi_patterns:
-                phi_patterns.remove("icd_code")
-
-        if custom_phi_patterns:
-            phi_patterns.extend(custom_phi_patterns)
-
-        # HIPAA-compliant configuration
-        config = WizardConfig(
-            name="Healthcare Assistant",
-            description="HIPAA-compliant AI assistant for healthcare professionals",
-            domain="healthcare",
-            # Empathy configuration
-            default_empathy_level=3,  # Proactive - anticipates needs
-            # Security configuration (HIPAA requirements)
-            enable_security=True,
-            pii_patterns=phi_patterns,
-            enable_secrets_detection=True,
-            block_on_secrets=True,  # CRITICAL: Block if secrets detected
-            # Audit configuration (HIPAA §164.312(b))
-            audit_all_access=True,  # Log every interaction
-            retention_days=90,  # HIPAA minimum for audit logs
-            # Classification (HIPAA §164.514)
-            default_classification="SENSITIVE",  # PHI is always SENSITIVE
-            auto_classify=True,
-        )
-
-        super().__init__(llm, config)
-
-        # Verify security is enabled
-        if not llm.enable_security:
-            logger.warning(
-                "HealthcareWizard initialized with security DISABLED. "
-                "HIPAA compliance requires enable_security=True in EmpathyLLM.",
-            )
-
-        logger.info(
-            f"HealthcareWizard initialized: {len(phi_patterns)} PHI patterns, "
-            f"empathy level={config.default_empathy_level}, security={llm.enable_security}",
-        )
-
-    async def process(
-        self,
-        user_input: str,
-        user_id: str,
-        empathy_level: int | None = None,
-        session_context: dict[str, Any] | None = None,
-        patient_id: str | None = None,
-    ) -> dict[str, Any]:
-        """Process healthcare request with HIPAA compliance
-
-        Args:
-            user_input: Healthcare professional's message (may contain PHI)
-            user_id: Healthcare provider identifier (email, NPI, etc.)
-            empathy_level: Override default empathy level
-            session_context: Session metadata (encounter ID, facility, etc.)
-            patient_id: Patient identifier for audit trail (optional)
-
-        Returns:
-            Dict containing:
-                - response: De-identified AI response
-                - security_report: PHI scrubbing and security scan results
-                - empathy_level: Level used
-                - hipaa_compliance: Compliance status
-                - audit_event_id: Audit trail event ID
-
-        Raises:
-            SecurityError: If secrets detected in input
-            ValueError: If invalid user_id or parameters
-
-        """
-        # Enhance session context with patient ID for audit trail
-        if patient_id:
-            if session_context is None:
-                session_context = {}
-            session_context["patient_id"] = patient_id
-
-        # Log PHI access
-        self.logger.info(
-            f"PHI access: user={user_id}, wizard={self.config.name}, "
-            f"patient={patient_id}, audit=True",
-        )
-
-        # Process through base wizard (handles security pipeline)
-        result = await super().process(
-            user_input=user_input,
-            user_id=user_id,
-            empathy_level=empathy_level,
-            session_context=session_context,
-        )
-
-        # Add HIPAA compliance metadata
-        result["hipaa_compliance"] = {
-            "phi_detected": result.get("security_report", {}).get("pii_count", 0) > 0,
-            "phi_scrubbed": True if self.llm.enable_security else False,
-            "encrypted": result.get("security_report", {}).get("encrypted", False),
-            "audit_logged": True,
-            "retention_days": self.config.retention_days,
-            "classification": "SENSITIVE",
-        }
-
-        # Log completion
-        self.logger.info(
-            f"PHI processing complete: user={user_id}, "
-            f"detected={result['hipaa_compliance']['phi_detected']}, "
-            f"scrubbed={result['hipaa_compliance']['phi_scrubbed']}",
-        )
-
-        return result
-
-    def _build_system_prompt(self, user_input: str = "") -> str:
-        """Build HIPAA-aware system prompt for healthcare domain
-
-        Includes:
-        - Healthcare domain knowledge
-        - HIPAA compliance reminders
-        - Clinical communication best practices
-        - Patient privacy emphasis
-
-        Uses XML-enhanced prompts if enabled for improved reliability
-        and reduced hallucinations (critical for HIPAA compliance).
-        """
-        # Check if XML prompts are enabled
-        if self._is_xml_enabled():
-            # Use XML-enhanced prompt for better structure and HIPAA compliance
-            return self._render_xml_prompt(
-                role="HIPAA-compliant AI healthcare assistant for clinical decision support",
-                goal="Assist healthcare professionals with evidence-based clinical guidance while maintaining strict HIPAA compliance and patient safety",
-                instructions=[
-                    "Provide clinical decision support based on current evidence-based guidelines",
-                    "Support clinical documentation following standardized formats (SBAR, SOAP, etc.)",
-                    "Help with care coordination and patient management workflows",
-                    "Use standardized medical terminology (ICD-10, CPT, SNOMED) where appropriate",
-                    "Acknowledge limitations and suggest specialist consultation when needed",
-                    "Maintain professional, empathetic communication",
-                ],
-                constraints=[
-                    "CRITICAL: All PHI is automatically de-identified - never request or display patient identifiers",
-                    "You are a decision support tool, NOT a replacement for professional clinical judgment",
-                    "NEVER diagnose or prescribe - support licensed healthcare providers who do",
-                    "In emergencies, direct to appropriate emergency services immediately",
-                    "Focus on clinical reasoning and evidence-based medicine",
-                    "Patient safety and privacy are paramount - all interactions logged for HIPAA compliance",
-                ],
-                input_type="clinical_query",
-                input_payload=user_input if user_input else "[Healthcare professional query]",
-                extra={
-                    "domain": "Healthcare / Clinical Medicine",
-                    "compliance": "HIPAA §164.312 (Security Rule), §164.514 (Privacy Rule)",
-                    "empathy_level": self.config.default_empathy_level,
-                    "phi_detection_enabled": len(self.config.pii_patterns),
-                },
-            )
-        else:
-            # Fallback to legacy plain text prompt
-            return """You are a HIPAA-compliant AI healthcare assistant.
-
-**Domain**: Healthcare / Clinical Medicine
-
-**Your Role**:
-- Assist healthcare professionals with clinical decision support
-- Provide evidence-based medical information
-- Support clinical documentation and communication
-- Help with care coordination and patient management
-
-**HIPAA Compliance**:
-- All patient data (PHI) is automatically de-identified before you see it
-- Never request or display patient identifiers in your responses
-- Focus on clinical reasoning and medical knowledge
-- Maintain patient confidentiality at all times
-
-**Clinical Guidelines**:
-- Base recommendations on current evidence-based guidelines
-- Acknowledge limitations and suggest consulting specialists when appropriate
-- Use standardized medical terminology (ICD-10, CPT, SNOMED)
-- Follow clinical communication best practices (SBAR, SOAP, etc.)
-
-**Communication Style**:
-- Professional and empathetic
-- Clear and concise
-- Evidence-based
-- Action-oriented when appropriate
-
-**Important Disclaimers**:
-- You are a clinical decision support tool, not a replacement for professional judgment
-- Always defer to licensed healthcare providers for final decisions
-- In emergencies, direct users to appropriate emergency services
-- Do not diagnose or prescribe - support healthcare professionals who do
-
-Remember: Patient safety and privacy are paramount. Interactions are logged for HIPAA compliance.
-"""
-
-    def get_phi_patterns(self) -> list[str]:
-        """Get list of PHI patterns being detected"""
-        return self.config.pii_patterns.copy()
-
-    def get_hipaa_compliance_status(self) -> dict[str, Any]:
-        """Get HIPAA compliance status for this wizard
-
-        Returns:
-            Dict with compliance checks and recommendations
-
-        """
-        status: dict[str, Any] = {
-            "compliant": True,
-            "checks": {},
-            "recommendations": [],
-        }
-
-        # Check 1: Security enabled
-        status["checks"]["security_enabled"] = self.llm.enable_security
-        if not self.llm.enable_security:
-            status["compliant"] = False
-            status["recommendations"].append(
-                "Enable security in EmpathyLLM (enable_security=True) for HIPAA compliance",
-            )
-
-        # Check 2: Encryption for SENSITIVE data
-        # Note: Encryption is handled by SecureMemDocsIntegration, not directly by EmpathyLLM
-        status["checks"]["encryption_enabled"] = self.llm.enable_security
-        if not status["checks"]["encryption_enabled"]:
-            status["recommendations"].append(
-                "Enable encryption for SENSITIVE data (HIPAA §164.312(a)(2)(iv))",
-            )
-
-        # Check 3: Audit logging
-        status["checks"]["audit_logging"] = (
-            self.llm.enable_security and self.config.audit_all_access
-        )
-        if not status["checks"]["audit_logging"]:
-            status["compliant"] = False
-            status["recommendations"].append(
-                "Enable comprehensive audit logging (HIPAA §164.312(b))",
-            )
-
-        # Check 4: PHI detection
-        status["checks"]["phi_detection"] = len(self.config.pii_patterns) >= 10
-        if not status["checks"]["phi_detection"]:
-            status["recommendations"].append("Enable comprehensive PHI detection patterns")
-
-        # Check 5: Minimum retention
-        status["checks"]["retention_policy"] = self.config.retention_days >= 90
-        if not status["checks"]["retention_policy"]:
-            status["recommendations"].append(
-                "Set minimum 90-day retention for audit logs (HIPAA §164.528)",
-            )
-
-        return status

empathy_llm_toolkit/wizards/patient_assessment_README.md

@@ -1,64 +0,0 @@
-# Patient Assessment Wizard
-
-**Domain:** healthcare
-**Type:** Wizard
-**Generated:** Pattern-Compose Methodology
-
-## Overview
-
-Auto-generated wizard using proven patterns from the Empathy Framework.
-
-## Patterns Used
-
-- **Empathy Level**: 0-4 empathy level configuration
-- **User Guidance**: Help text, examples, and prompts
-- **Linear Flow**: Step-by-step wizard with review and approval
-- **Structured Fields**: Predefined fields per step with validation
-- **Step Validation**: Ensure steps are completed in order
-- **User Approval**: Preview → Explicit Approval → Finalize
-- **Educational Banner**: Safety notices and educational content
-- **AI Enhancement**: Improve user input with AI
-- **Config Validation**: Validate wizard configuration on initialization
-- **Session-Based**: State management with session storage
-
-## Usage
-
-```python
-from wizards.patient_assessment_wizard import PatientAssessmentWizard
-
-wizard = PatientAssessmentWizard()
-result = await wizard.process(user_input="...")
-```
-
-## API Endpoints
-
-```bash
-# Process with wizard
-POST /api/wizard/patient_assessment/process
-{
-  "input": "your input here",
-  "context": {}
-}
-```
-
-## Testing
-
-```bash
-# Run unit tests
-pytest tests/unit/wizards/test_patient_assessment_wizard.py
-
-# Run with coverage
-pytest tests/unit/wizards/test_patient_assessment_wizard.py --cov
-```
-
-## Next Steps
-
-1. Customize wizard logic as needed
-2. Add domain-specific validation
-3. Extend with additional features
-4. Update tests for custom logic
-
----
-
-**Generated by:** Empathy Framework - Wizard Factory
-**Methodology:** Pattern-Compose

empathy_llm_toolkit/wizards/patient_assessment_wizard.py

@@ -1,193 +0,0 @@
-"""PatientAssessmentWizard - Generated by Pattern-Compose
-
-Domain: healthcare
-Patterns: empathy_level, user_guidance, linear_flow, structured_fields, step_validation, approval, educational_banner, ai_enhancement, config_validation, session_based
-Generated: Auto-generated by Empathy Framework
-"""
-
-from datetime import datetime
-from typing import Any
-from uuid import uuid4
-
-from fastapi import APIRouter, HTTPException
-from pydantic import BaseModel
-
-router = APIRouter(
-    prefix="/wizards/patient_assessment",
-    tags=["wizards"],
-)
-
-
-# Request/Response Models
-class WizardRequest(BaseModel):
-    """Request model for wizard."""
-
-    input: str
-    context: dict[str, Any] | None = None
-
-
-class WizardResponse(BaseModel):
-    """Response model for wizard."""
-
-    success: bool
-    output: str
-    wizard_id: str | None = None
-    error: str | None = None
-
-
-# Session storage (Redis in production, memory for development)
-_wizard_sessions: dict[str, dict[str, Any]] = {}
-
-
-@router.post("/start")
-async def start_wizard():
-    """Start patient_assessment wizard session.
-
-    Returns wizard_id and first step configuration.
-    """
-    wizard_id = str(uuid4())
-
-    session_data = {
-        "wizard_id": wizard_id,
-        "wizard_type": "patient_assessment",
-        "current_step": 1,
-        "total_steps": 5,  # TODO: Adjust based on your wizard
-        "collected_data": {},
-        "created_at": datetime.now().isoformat(),
-    }
-
-    _wizard_sessions[wizard_id] = session_data
-
-    return {
-        "wizard_id": wizard_id,
-        "current_step": 1,
-        "total_steps": 5,
-        "message": "Wizard started successfully",
-    }
-
-
-@router.post("/{wizard_id}/step")
-async def submit_step(wizard_id: str, step_data: dict[str, Any]):
-    """Submit data for current step.
-
-    Validates step sequence and stores data.
-    """
-    if wizard_id not in _wizard_sessions:
-        raise HTTPException(404, "Wizard session not found")
-
-    session = _wizard_sessions[wizard_id]
-    current_step = session["current_step"]
-    total_steps = session["total_steps"]
-
-    # Validate step number
-    submitted_step = step_data.get("step", current_step)
-    if submitted_step != current_step:
-        raise HTTPException(422, f"Expected step {current_step}, got step {submitted_step}")
-
-    # Store data
-    session["collected_data"].update(step_data.get("data", {}))
-    session["updated_at"] = datetime.now().isoformat()
-
-    # Advance to next step
-    if current_step < total_steps:
-        session["current_step"] = current_step + 1
-
-    return {
-        "wizard_id": wizard_id,
-        "current_step": session["current_step"],
-        "total_steps": total_steps,
-        "message": f"Step {current_step} completed",
-    }
-
-
-@router.post("/{wizard_id}/preview")
-async def preview_report(wizard_id: str):
-    """Generate preview without finalizing.
-
-    Allows user to review before explicit approval.
-    """
-    if wizard_id not in _wizard_sessions:
-        raise HTTPException(404, "Wizard session not found")
-
-    session = _wizard_sessions[wizard_id]
-
-    if session["current_step"] != session["total_steps"]:
-        raise HTTPException(400, "Complete all steps before preview")
-
-    # Generate preview
-    preview = _generate_report(session["collected_data"])
-    session["preview_report"] = preview
-    session["preview_generated_at"] = datetime.now().isoformat()
-
-    return {
-        "preview": preview,
-        "message": "Preview generated. Review and approve to finalize.",
-    }
-
-
-@router.post("/{wizard_id}/save")
-async def save_report(wizard_id: str, approval: dict[str, Any]):
-    """Finalize report with user approval.
-
-    Requires preview generated and explicit user approval.
-    """
-    if wizard_id not in _wizard_sessions:
-        raise HTTPException(404, "Wizard session not found")
-
-    session = _wizard_sessions[wizard_id]
-
-    # Verify preview generated
-    if "preview_report" not in session:
-        raise HTTPException(400, "Must generate preview before saving. Call /preview first.")
-
-    # Verify user approval
-    if not approval.get("user_approved", False):
-        raise HTTPException(400, "User approval required. Set 'user_approved': true")
-
-    # Mark as complete
-    session["completed"] = True
-    session["completed_at"] = datetime.now().isoformat()
-    session["final_report"] = session["preview_report"]
-
-    return {
-        "wizard_id": wizard_id,
-        "completed": True,
-        "report": session["final_report"],
-        "message": "Report finalized successfully",
-    }
-
-
-@router.get("/{wizard_id}/report")
-async def get_report(wizard_id: str):
-    """Retrieve completed report.
-
-    Only available after wizard is completed.
-    """
-    if wizard_id not in _wizard_sessions:
-        raise HTTPException(404, "Wizard session not found")
-
-    session = _wizard_sessions[wizard_id]
-
-    if not session.get("completed", False):
-        raise HTTPException(422, "Wizard not yet completed")
-
-    return {
-        "wizard_id": wizard_id,
-        "report": _generate_report(session["collected_data"]),
-    }
-
-
-def _generate_report(collected_data: dict[str, Any]) -> dict[str, Any]:
-    """Generate report from collected data.
-
-    TODO: Customize report generation for your wizard.
-    """
-    return {
-        "data": collected_data,
-        "generated_at": datetime.now().isoformat(),
-        "wizard_type": "patient_assessment",
-    }
-
-
-# Export router
-__all__ = ["router"]