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

agents/compliance_db.py

@@ -0,0 +1,339 @@
+"""Compliance Database with Append-Only Architecture.
+
+Provides immutable audit trail for healthcare compliance tracking.
+Supports INSERT operations only (no UPDATE/DELETE) for regulatory compliance.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import sqlite3
+from collections.abc import Generator
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+class ComplianceDatabase:
+    """SQLite database for compliance tracking with append-only operations.
+
+    Features:
+    - Immutable audit trail (INSERT only, no UPDATE/DELETE)
+    - Audit date tracking
+    - Compliance status monitoring
+    - Gap detection and recording
+    - Thread-safe operations
+
+    Regulatory Compliance:
+    - Append-only design satisfies HIPAA audit log requirements
+    - No modification of historical records
+    - Complete audit trail preservation
+    """
+
+    def __init__(self, db_path: str | None = None):
+        """Initialize compliance database.
+
+        Args:
+            db_path: Path to SQLite database file.
+                    Defaults to agents/data/compliance.db
+        """
+        if db_path is None:
+            # Default to agents/data/compliance.db
+            agents_dir = Path(__file__).parent
+            data_dir = agents_dir / "data"
+            data_dir.mkdir(exist_ok=True)
+            db_path = str(data_dir / "compliance.db")
+
+        self.db_path = db_path
+        self._init_schema()
+
+    @contextmanager
+    def _get_connection(self) -> Generator[sqlite3.Connection, None, None]:
+        """Get database connection with automatic cleanup."""
+        conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        conn.row_factory = sqlite3.Row  # Enable dict-like access
+        try:
+            yield conn
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def _init_schema(self) -> None:
+        """Initialize database schema if not exists."""
+        with self._get_connection() as conn:
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS compliance_audits (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    audit_date TIMESTAMP NOT NULL,
+                    audit_type TEXT NOT NULL,  -- 'HIPAA', 'GDPR', 'SOC2', etc.
+                    findings TEXT,             -- JSON string of findings
+                    risk_score INTEGER,        -- 0-100
+                    auditor TEXT,              -- Who performed the audit
+                    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                    -- No updated_at field (immutable records)
+                );
+
+                CREATE TABLE IF NOT EXISTS compliance_gaps (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    gap_type TEXT NOT NULL,        -- 'missing_policy', 'expired_cert', etc.
+                    severity TEXT NOT NULL,        -- 'critical', 'high', 'medium', 'low'
+                    detected_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+                    description TEXT,
+                    affected_systems TEXT,         -- JSON string of affected systems
+                    compliance_framework TEXT,     -- 'HIPAA', 'GDPR', etc.
+                    detection_source TEXT          -- 'automated_scan', 'manual_review', etc.
+                    -- No status field (can't mark as "fixed", only add new record showing fix)
+                );
+
+                CREATE TABLE IF NOT EXISTS compliance_status (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    compliance_framework TEXT NOT NULL,  -- 'HIPAA', 'GDPR', 'SOC2', etc.
+                    status TEXT NOT NULL,                -- 'compliant', 'non_compliant', 'pending'
+                    effective_date TIMESTAMP NOT NULL,
+                    notes TEXT,
+                    recorded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_audits_date ON compliance_audits(audit_date DESC);
+                CREATE INDEX IF NOT EXISTS idx_gaps_severity ON compliance_gaps(severity, detected_at DESC);
+                CREATE INDEX IF NOT EXISTS idx_status_framework ON compliance_status(compliance_framework, effective_date DESC);
+                """
+            )
+
+    def record_audit(
+        self,
+        audit_date: datetime,
+        audit_type: str,
+        findings: str | None = None,
+        risk_score: int | None = None,
+        auditor: str | None = None,
+    ) -> int:
+        """Record a compliance audit (append-only).
+
+        Args:
+            audit_date: When the audit was performed
+            audit_type: Type of audit ('HIPAA', 'GDPR', 'SOC2', etc.)
+            findings: JSON string of audit findings
+            risk_score: Risk score 0-100
+            auditor: Who performed the audit
+
+        Returns:
+            Audit record ID
+
+        Note:
+            This is an append-only operation. Cannot modify existing audits.
+        """
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                INSERT INTO compliance_audits (audit_date, audit_type, findings, risk_score, auditor)
+                VALUES (?, ?, ?, ?, ?)
+                """,
+                (audit_date, audit_type, findings, risk_score, auditor),
+            )
+            return cursor.lastrowid
+
+    def get_last_audit(self, audit_type: str | None = None) -> dict[str, Any] | None:
+        """Get most recent audit record (read-only).
+
+        Args:
+            audit_type: Optional filter by audit type
+
+        Returns:
+            Audit record dict or None if no audits found
+        """
+        with self._get_connection() as conn:
+            if audit_type:
+                cursor = conn.execute(
+                    """
+                    SELECT * FROM compliance_audits
+                    WHERE audit_type = ?
+                    ORDER BY audit_date DESC
+                    LIMIT 1
+                    """,
+                    (audit_type,),
+                )
+            else:
+                cursor = conn.execute(
+                    """
+                    SELECT * FROM compliance_audits
+                    ORDER BY audit_date DESC
+                    LIMIT 1
+                    """
+                )
+
+            row = cursor.fetchone()
+            if row is None:
+                return None
+
+            return {
+                "id": row["id"],
+                "audit_date": row["audit_date"],
+                "audit_type": row["audit_type"],
+                "findings": row["findings"],
+                "risk_score": row["risk_score"],
+                "auditor": row["auditor"],
+                "created_at": row["created_at"],
+            }
+
+    def record_gap(
+        self,
+        gap_type: str,
+        severity: str,
+        description: str | None = None,
+        affected_systems: str | None = None,
+        compliance_framework: str | None = None,
+        detection_source: str = "automated_scan",
+    ) -> int:
+        """Record a compliance gap (append-only).
+
+        Args:
+            gap_type: Type of gap ('missing_policy', 'expired_cert', etc.)
+            severity: Severity level ('critical', 'high', 'medium', 'low')
+            description: Human-readable description
+            affected_systems: JSON string of affected systems
+            compliance_framework: Related framework ('HIPAA', 'GDPR', etc.)
+            detection_source: How gap was detected
+
+        Returns:
+            Gap record ID
+
+        Note:
+            This is an append-only operation. To mark a gap as fixed,
+            add a new status record, don't modify this one.
+        """
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                INSERT INTO compliance_gaps (
+                    gap_type, severity, description, affected_systems,
+                    compliance_framework, detection_source
+                )
+                VALUES (?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    gap_type,
+                    severity,
+                    description,
+                    affected_systems,
+                    compliance_framework,
+                    detection_source,
+                ),
+            )
+            return cursor.lastrowid
+
+    def get_active_gaps(
+        self, severity: str | None = None, framework: str | None = None
+    ) -> list[dict[str, Any]]:
+        """Get all recorded gaps (read-only).
+
+        Args:
+            severity: Optional filter by severity
+            framework: Optional filter by compliance framework
+
+        Returns:
+            List of gap records
+
+        Note:
+            Returns all gaps. In append-only design, gaps are never deleted.
+            To track fixes, use separate status records.
+        """
+        with self._get_connection() as conn:
+            query = "SELECT * FROM compliance_gaps WHERE 1=1"
+            params: list[Any] = []
+
+            if severity:
+                query += " AND severity = ?"
+                params.append(severity)
+
+            if framework:
+                query += " AND compliance_framework = ?"
+                params.append(framework)
+
+            query += " ORDER BY detected_at DESC"
+
+            cursor = conn.execute(query, params)
+            rows = cursor.fetchall()
+
+            return [
+                {
+                    "id": row["id"],
+                    "gap_type": row["gap_type"],
+                    "severity": row["severity"],
+                    "detected_at": row["detected_at"],
+                    "description": row["description"],
+                    "affected_systems": row["affected_systems"],
+                    "compliance_framework": row["compliance_framework"],
+                    "detection_source": row["detection_source"],
+                }
+                for row in rows
+            ]
+
+    def record_compliance_status(
+        self,
+        compliance_framework: str,
+        status: str,
+        effective_date: datetime,
+        notes: str | None = None,
+    ) -> int:
+        """Record compliance status change (append-only).
+
+        Args:
+            compliance_framework: Framework name ('HIPAA', 'GDPR', 'SOC2', etc.)
+            status: Status ('compliant', 'non_compliant', 'pending')
+            effective_date: When this status became effective
+            notes: Additional notes
+
+        Returns:
+            Status record ID
+
+        Note:
+            This is an append-only operation. Status history is preserved.
+        """
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                INSERT INTO compliance_status (compliance_framework, status, effective_date, notes)
+                VALUES (?, ?, ?, ?)
+                """,
+                (compliance_framework, status, effective_date, notes),
+            )
+            return cursor.lastrowid
+
+    def get_current_compliance_status(self, compliance_framework: str) -> dict[str, Any] | None:
+        """Get most recent compliance status (read-only).
+
+        Args:
+            compliance_framework: Framework name
+
+        Returns:
+            Status record or None
+        """
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                SELECT * FROM compliance_status
+                WHERE compliance_framework = ?
+                ORDER BY effective_date DESC, recorded_at DESC
+                LIMIT 1
+                """,
+                (compliance_framework,),
+            )
+
+            row = cursor.fetchone()
+            if row is None:
+                return None
+
+            return {
+                "id": row["id"],
+                "compliance_framework": row["compliance_framework"],
+                "status": row["status"],
+                "effective_date": row["effective_date"],
+                "notes": row["notes"],
+                "recorded_at": row["recorded_at"],
+            }

agents/epic_integration_wizard.py

@@ -1,5 +1,4 @@
-"""
-Epic Integration Wizard - LangChain Agent
+"""Epic Integration Wizard - LangChain Agent
 Multi-step wizard for configuring and testing Epic FHIR integration
 
 Copyright 2025 Smart AI Memory, LLC
@@ -26,8 +25,7 @@ logger = logging.getLogger(__name__)
 
 
 class WizardState(TypedDict):
-    """
-    State for Epic Integration Wizard
+    """State for Epic Integration Wizard
 
     Tracks all wizard steps, user inputs, validation results, and progress.
     Microsoft-style linear progression with validation at each step.
@@ -114,8 +112,7 @@ def create_initial_state() -> WizardState:
 
 
 async def step_1_prerequisites(state: WizardState) -> WizardState:
-    """
-    Step 1: Check Prerequisites
+    """Step 1: Check Prerequisites
 
     Validates system readiness:
     - Python version
@@ -142,7 +139,7 @@ async def step_1_prerequisites(state: WizardState) -> WizardState:
         if not settings.database_url:
             missing.append("Database configuration")
     except Exception as e:
-        missing.append(f"Configuration error: {str(e)}")
+        missing.append(f"Configuration error: {e!s}")
 
     state["prerequisites_checked"] = True
     state["prerequisites_passed"] = len(missing) == 0
@@ -153,7 +150,7 @@ async def step_1_prerequisites(state: WizardState) -> WizardState:
     # Even if automated prerequisites fail, user can still configure Epic manually
     if state["prerequisites_passed"]:
         state["messages"].append(
-            AIMessage(content="✅ All prerequisites met. Ready to configure Epic integration.")
+            AIMessage(content="✅ All prerequisites met. Ready to configure Epic integration."),
         )
     else:
         # Don't block progression - just warn user
@@ -164,8 +161,7 @@ async def step_1_prerequisites(state: WizardState) -> WizardState:
 
 
 async def step_2_credentials(state: WizardState) -> WizardState:
-    """
-    Step 2: Epic Credentials Input
+    """Step 2: Epic Credentials Input
 
     Collects and validates:
     - Epic Client ID
@@ -192,15 +188,14 @@ async def step_2_credentials(state: WizardState) -> WizardState:
     state["completed_steps"].append(2)
     state["current_step"] = 3
     state["messages"].append(
-        AIMessage(content="✅ Epic credentials collected. Ready to test connection.")
+        AIMessage(content="✅ Epic credentials collected. Ready to test connection."),
     )
 
     return state
 
 
 async def step_3_connection_test(state: WizardState) -> WizardState:
-    """
-    Step 3: Test Epic FHIR Connection
+    """Step 3: Test Epic FHIR Connection
 
     Validates:
     - OAuth token can be obtained
@@ -226,13 +221,13 @@ async def step_3_connection_test(state: WizardState) -> WizardState:
             state["oauth_token_obtained"] = True
             state["connection_test_passed"] = True
             state["messages"].append(
-                AIMessage(content="✅ Successfully connected to Epic FHIR API")
+                AIMessage(content="✅ Successfully connected to Epic FHIR API"),
             )
         except Exception as e:
             state["connection_test_error"] = str(e)
             state["connection_test_passed"] = False
-            state["errors"].append(f"OAuth token request failed: {str(e)}")
-            state["messages"].append(AIMessage(content=f"❌ Connection failed: {str(e)}"))
+            state["errors"].append(f"OAuth token request failed: {e!s}")
+            state["messages"].append(AIMessage(content=f"❌ Connection failed: {e!s}"))
             return state
 
         state["completed_steps"].append(3)
@@ -242,14 +237,13 @@ async def step_3_connection_test(state: WizardState) -> WizardState:
         logger.error(f"Connection test failed: {e}", exc_info=True)
         state["connection_test_error"] = str(e)
         state["connection_test_passed"] = False
-        state["errors"].append(f"Connection test error: {str(e)}")
+        state["errors"].append(f"Connection test error: {e!s}")
 
     return state
 
 
 async def step_4_resource_permissions(state: WizardState) -> WizardState:
-    """
-    Step 4: Select FHIR Resources and Scopes
+    """Step 4: Select FHIR Resources and Scopes
 
     User selects which FHIR resources to enable:
     - Patient (demographics)
@@ -284,15 +278,14 @@ async def step_4_resource_permissions(state: WizardState) -> WizardState:
     state["completed_steps"].append(4)
     state["current_step"] = 5
     state["messages"].append(
-        AIMessage(content=f"✅ Configured {len(scopes)} resource permissions: {', '.join(scopes)}")
+        AIMessage(content=f"✅ Configured {len(scopes)} resource permissions: {', '.join(scopes)}"),
     )
 
     return state
 
 
 async def step_5_test_patient_lookup(state: WizardState) -> WizardState:
-    """
-    Step 5: Test Patient Lookup
+    """Step 5: Test Patient Lookup
 
     Validates end-to-end functionality:
     - Search patient by MRN
@@ -316,7 +309,8 @@ async def step_5_test_patient_lookup(state: WizardState) -> WizardState:
         )
 
         epic_client = EpicFHIRClient(
-            base_url=state["epic_fhir_base_url"], oauth_manager=oauth_manager
+            base_url=state["epic_fhir_base_url"],
+            oauth_manager=oauth_manager,
         )
 
         # Search for patient
@@ -332,13 +326,13 @@ async def step_5_test_patient_lookup(state: WizardState) -> WizardState:
             state["patient_data_retrieved"] = True
             state["retrieved_patient_name"] = patient_name
             state["messages"].append(
-                AIMessage(content=f"✅ Successfully retrieved patient: {patient_name}")
+                AIMessage(content=f"✅ Successfully retrieved patient: {patient_name}"),
             )
         else:
             state["patient_test_error"] = "Patient not found"
             state["errors"].append(f"Patient with MRN {state['test_mrn']} not found")
             state["messages"].append(
-                AIMessage(content=f"❌ Patient not found: MRN {state['test_mrn']}")
+                AIMessage(content=f"❌ Patient not found: MRN {state['test_mrn']}"),
             )
             return state
 
@@ -348,15 +342,14 @@ async def step_5_test_patient_lookup(state: WizardState) -> WizardState:
     except Exception as e:
         logger.error(f"Patient lookup failed: {e}", exc_info=True)
         state["patient_test_error"] = str(e)
-        state["errors"].append(f"Patient lookup error: {str(e)}")
-        state["messages"].append(AIMessage(content=f"❌ Patient lookup failed: {str(e)}"))
+        state["errors"].append(f"Patient lookup error: {e!s}")
+        state["messages"].append(AIMessage(content=f"❌ Patient lookup failed: {e!s}"))
 
     return state
 
 
 async def step_6_review_confirm(state: WizardState) -> WizardState:
-    """
-    Step 6: Review and Confirm Configuration
+    """Step 6: Review and Confirm Configuration
 
     Shows summary of all settings for final review:
     - Epic endpoint and credentials
@@ -390,15 +383,14 @@ Please confirm to activate integration.
     state["completed_steps"].append(6)
     state["current_step"] = 7
     state["messages"].append(
-        AIMessage(content="✅ Configuration confirmed. Activating integration...")
+        AIMessage(content="✅ Configuration confirmed. Activating integration..."),
     )
 
     return state
 
 
 async def step_7_complete(state: WizardState) -> WizardState:
-    """
-    Step 7: Complete Integration Setup
+    """Step 7: Complete Integration Setup
 
     Finalizes configuration:
     - Saves settings to database/config
@@ -442,14 +434,14 @@ Next steps:
 1. Train your staff on the Epic integration workflow
 2. Review HIPAA compliance documentation
 3. Monitor integration logs for any issues
-            """
-            )
+            """,
+            ),
         )
 
     except Exception as e:
         logger.error(f"Integration activation failed: {e}", exc_info=True)
-        state["errors"].append(f"Activation error: {str(e)}")
-        state["messages"].append(AIMessage(content=f"❌ Activation failed: {str(e)}"))
+        state["errors"].append(f"Activation error: {e!s}")
+        state["messages"].append(AIMessage(content=f"❌ Activation failed: {e!s}"))
 
     return state
 
@@ -460,8 +452,7 @@ Next steps:
 
 
 def should_continue(state: WizardState) -> str:
-    """
-    Determine next step based on current state
+    """Determine next step based on current state
 
     Microsoft wizard pattern: linear progression with error handling
     """
@@ -482,20 +473,19 @@ def should_continue(state: WizardState) -> str:
 
     if current_step == 1:
         return "prerequisites"
-    elif current_step == 2:
+    if current_step == 2:
         return "credentials"
-    elif current_step == 3:
+    if current_step == 3:
         return "connection_test"
-    elif current_step == 4:
+    if current_step == 4:
         return "resource_permissions"
-    elif current_step == 5:
+    if current_step == 5:
         return "test_patient_lookup"
-    elif current_step == 6:
+    if current_step == 6:
         return "review_confirm"
-    elif current_step == 7:
+    if current_step == 7:
         return "complete"
-    else:
-        return END
+    return END
 
 
 # =============================================================================
@@ -504,8 +494,7 @@ def should_continue(state: WizardState) -> str:
 
 
 def create_epic_wizard_graph():
-    """
-    Create LangGraph workflow for Epic Integration Wizard
+    """Create LangGraph workflow for Epic Integration Wizard
 
     Microsoft-style multi-step wizard:
     Prerequisites → Credentials → Connection Test → Permissions → Patient Test → Review → Complete