empathy-framework 2.4.0__py3-none-any.whl → 3.8.2__py3-none-any.whl

empathy_os/trust_building.py

@@ -1,5 +1,4 @@
-"""
-Trust-Building Behaviors for Anticipatory AI Agents
+"""Trust-Building Behaviors for Anticipatory AI Agents
 
 Implements behaviors that build trust through anticipatory actions:
 - Pre-format data for handoffs (reduce cognitive load)
@@ -29,8 +28,7 @@ logger = logging.getLogger(__name__)
 
 @dataclass
 class TrustSignal:
-    """
-    A signal that indicates trust is building or eroding
+    """A signal that indicates trust is building or eroding
 
     Trust signals help track how trust evolves over time based on
     observable behaviors and outcomes.
@@ -44,8 +42,7 @@ class TrustSignal:
 
 
 class TrustBuildingBehaviors:
-    """
-    Level 4 Anticipatory trust-building behaviors
+    """Level 4 Anticipatory trust-building behaviors
 
     Philosophy: Trust is earned through consistent, helpful actions that
     demonstrate understanding of collaboration dynamics and proactive
@@ -76,6 +73,7 @@ class TrustBuildingBehaviors:
         ...     instruction=instruction,
         ...     ambiguities=["which system?", "what changes?"]
         ... )
+
     """
 
     def __init__(self):
@@ -83,10 +81,12 @@ class TrustBuildingBehaviors:
         self.trust_signals: list[TrustSignal] = []
 
     def pre_format_for_handoff(
-        self, data: dict[str, Any], recipient_role: str, context: str
+        self,
+        data: dict[str, Any],
+        recipient_role: str,
+        context: str,
     ) -> dict[str, Any]:
-        """
-        Pre-format data for handoff to reduce recipient's cognitive load
+        """Pre-format data for handoff to reduce recipient's cognitive load
 
         **Trust Built:**
         - "This AI understands my workflow"
@@ -109,6 +109,7 @@ class TrustBuildingBehaviors:
             ...     context="board_meeting"
             ... )
             >>> # Returns: executive summary format with key highlights
+
         """
         logger.info(f"Pre-formatting data for handoff to {recipient_role} (context: {context})")
 
@@ -148,8 +149,7 @@ class TrustBuildingBehaviors:
         detected_ambiguities: list[str],
         context: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        """
-        Clarify ambiguous instructions before execution to prevent wasted effort
+        """Clarify ambiguous instructions before execution to prevent wasted effort
 
         **Trust Built:**
         - "This AI doesn't make dangerous assumptions"
@@ -171,14 +171,16 @@ class TrustBuildingBehaviors:
             ...     instruction=instruction,
             ...     detected_ambiguities=ambiguities
             ... )
+
         """
         logger.info(f"Clarifying ambiguous instruction: {instruction}")
 
-        clarification = {
+        clarifying_questions: list[dict[str, str]] = []
+        clarification: dict[str, Any] = {
             "original_instruction": instruction,
             "status": "needs_clarification",
             "ambiguities_detected": detected_ambiguities,
-            "clarifying_questions": [],
+            "clarifying_questions": clarifying_questions,
             "reasoning": (
                 "Detected ambiguities in instruction. Clarifying before acting "
                 "to prevent wasted effort or incorrect execution."
@@ -189,7 +191,7 @@ class TrustBuildingBehaviors:
         # Generate specific clarifying questions
         for ambiguity in detected_ambiguities:
             question = self._generate_clarifying_question(instruction, ambiguity, context)
-            clarification["clarifying_questions"].append(question)
+            clarifying_questions.append(question)
 
         # Record trust signal
         self._record_trust_signal(
@@ -201,10 +203,11 @@ class TrustBuildingBehaviors:
         return clarification
 
     def volunteer_structure_during_stress(
-        self, stress_indicators: dict[str, Any], available_scaffolding: list[str]
+        self,
+        stress_indicators: dict[str, Any],
+        available_scaffolding: list[str],
     ) -> dict[str, Any]:
-        """
-        Volunteer structure/scaffolding during stressful situations
+        """Volunteer structure/scaffolding during stressful situations
 
         **Not pep talks, actual structural help:**
         - Break down overwhelming tasks
@@ -231,14 +234,16 @@ class TrustBuildingBehaviors:
             ...     stress_indicators=stress,
             ...     available_scaffolding=scaffolding
             ... )
+
         """
         logger.info("Volunteering structure during detected stress")
 
         stress_level = self._assess_stress_level(stress_indicators)
 
-        support = {
+        offered_support: list[dict[str, Any]] = []
+        support: dict[str, Any] = {
             "stress_assessment": {"level": stress_level, "indicators": stress_indicators},
-            "offered_support": [],
+            "offered_support": offered_support,
             "reasoning": (
                 f"Detected {stress_level} stress. Volunteering structural support "
                 "to reduce cognitive load and provide actionable scaffolding."
@@ -249,30 +254,30 @@ class TrustBuildingBehaviors:
         # Offer appropriate scaffolding based on stress level
         if stress_level in ["high", "critical"]:
             if "prioritization" in available_scaffolding:
-                support["offered_support"].append(
+                offered_support.append(
                     {
                         "type": "prioritization",
                         "description": "Help prioritize tasks using urgency-importance matrix",
                         "immediate": True,
-                    }
+                    },
                 )
 
             if "breakdown" in available_scaffolding:
-                support["offered_support"].append(
+                offered_support.append(
                     {
                         "type": "task_breakdown",
                         "description": "Break overwhelming tasks into smaller, manageable steps",
                         "immediate": True,
-                    }
+                    },
                 )
 
         if "templates" in available_scaffolding:
-            support["offered_support"].append(
+            offered_support.append(
                 {
                     "type": "templates",
                     "description": "Provide templates to reduce creation effort",
                     "immediate": False,
-                }
+                },
             )
 
         # Record trust signal
@@ -285,10 +290,11 @@ class TrustBuildingBehaviors:
         return support
 
     def offer_proactive_help(
-        self, struggle_indicators: dict[str, Any], available_help: list[str]
+        self,
+        struggle_indicators: dict[str, Any],
+        available_help: list[str],
     ) -> dict[str, Any]:
-        """
-        Proactively offer help when collaborator is struggling
+        """Proactively offer help when collaborator is struggling
 
         **Trust Built:**
         - "This AI notices when I'm stuck"
@@ -309,14 +315,16 @@ class TrustBuildingBehaviors:
             ...     struggle_indicators=indicators,
             ...     available_help=help_types
             ... )
+
         """
         logger.info("Offering proactive help based on struggle indicators")
 
         struggle_type = self._classify_struggle(struggle_indicators)
 
-        offer = {
+        help_offered: list[dict[str, str]] = []
+        offer: dict[str, Any] = {
             "struggle_assessment": {"type": struggle_type, "indicators": struggle_indicators},
-            "help_offered": [],
+            "help_offered": help_offered,
             "tone": "supportive_not_condescending",
             "reasoning": (
                 f"Detected {struggle_type} struggle pattern. Offering relevant help "
@@ -328,22 +336,21 @@ class TrustBuildingBehaviors:
         # Offer appropriate help based on struggle type
         if struggle_type == "comprehension":
             if "explanation" in available_help:
-                offer["help_offered"].append(
-                    {"type": "explanation", "description": "Provide clearer explanation of concept"}
+                help_offered.append(
+                    {
+                        "type": "explanation",
+                        "description": "Provide clearer explanation of concept",
+                    },
                 )
             if "examples" in available_help:
-                offer["help_offered"].append(
-                    {"type": "examples", "description": "Show concrete examples"}
-                )
+                help_offered.append({"type": "examples", "description": "Show concrete examples"})
 
         elif struggle_type == "execution":
             if "debugging" in available_help:
-                offer["help_offered"].append(
-                    {"type": "debugging", "description": "Help debug the issue"}
-                )
+                help_offered.append({"type": "debugging", "description": "Help debug the issue"})
             if "guidance" in available_help:
-                offer["help_offered"].append(
-                    {"type": "step_by_step", "description": "Provide step-by-step guidance"}
+                help_offered.append(
+                    {"type": "step_by_step", "description": "Provide step-by-step guidance"},
                 )
 
         # Record trust signal
@@ -356,11 +363,11 @@ class TrustBuildingBehaviors:
         return offer
 
     def get_trust_trajectory(self) -> dict[str, Any]:
-        """
-        Get trust trajectory based on recorded signals
+        """Get trust trajectory based on recorded signals
 
         Returns:
             Analysis of trust evolution over time
+
         """
         if not self.trust_signals:
             return {"status": "insufficient_data", "trajectory": "unknown", "signal_count": 0}
@@ -396,12 +403,11 @@ class TrustBuildingBehaviors:
         """Determine appropriate format based on role and context"""
         if role in ["executive", "manager", "director"]:
             return "executive_summary"
-        elif role in ["developer", "engineer", "analyst"]:
+        if role in ["developer", "engineer", "analyst"]:
             return "technical_detail"
-        elif role in ["team_lead", "coordinator"]:
+        if role in ["team_lead", "coordinator"]:
             return "action_oriented"
-        else:
-            return "general"
+        return "general"
 
     def _create_executive_summary(self, data: dict, context: str) -> dict:
         """Create executive summary format"""
@@ -455,20 +461,25 @@ class TrustBuildingBehaviors:
         """Extract technical notes"""
         return [f"Data structure: {type(data).__name__}"]
 
-    def _extract_immediate_actions(self, data: dict) -> list[str]:
+    def _extract_immediate_actions(self, data: dict[str, Any]) -> list[str]:
         """Extract immediate actions"""
         if "actions" in data:
-            return data["actions"][:5]
+            actions: list[str] = data["actions"][:5]
+            return actions
         return ["Review data and determine next steps"]
 
-    def _extract_priorities(self, data: dict) -> list[str]:
+    def _extract_priorities(self, data: dict[str, Any]) -> list[str]:
         """Extract priorities"""
         if "priorities" in data:
-            return data["priorities"]
+            priorities: list[str] = data["priorities"]
+            return priorities
         return []
 
     def _generate_clarifying_question(
-        self, instruction: str, ambiguity: str, context: dict | None
+        self,
+        instruction: str,
+        ambiguity: str,
+        context: dict | None,
     ) -> dict[str, str]:
         """Generate a specific clarifying question"""
         return {
@@ -484,21 +495,19 @@ class TrustBuildingBehaviors:
 
         if stress_score >= 4:
             return "critical"
-        elif stress_score >= 3:
+        if stress_score >= 3:
             return "high"
-        elif stress_score >= 2:
+        if stress_score >= 2:
             return "moderate"
-        else:
-            return "low"
+        return "low"
 
     def _classify_struggle(self, indicators: dict) -> str:
         """Classify type of struggle"""
         if "repeated_errors" in indicators:
             return "execution"
-        elif "time_on_task" in indicators:
+        if "time_on_task" in indicators:
             return "comprehension"
-        else:
-            return "general"
+        return "general"
 
     def _record_trust_signal(self, signal_type: str, behavior: str, evidence: str | None = None):
         """Record a trust signal"""

empathy_os/validation/__init__.py

@@ -0,0 +1,19 @@
+"""XML validation for XML-enhanced prompts.
+
+Provides schema validation and graceful fallbacks.
+
+Copyright 2026 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from empathy_os.validation.xml_validator import (
+                                                 ValidationResult,
+                                                 XMLValidator,
+                                                 validate_xml_response,
+)
+
+__all__ = [
+    "XMLValidator",
+    "ValidationResult",
+    "validate_xml_response",
+]

empathy_os/validation/xml_validator.py

@@ -0,0 +1,281 @@
+"""XML validation for response verification.
+
+Validates XML-structured responses with graceful fallbacks.
+
+Copyright 2026 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ValidationResult:
+    """Result of XML validation.
+
+    Attributes:
+        is_valid: Whether XML is valid
+        error_message: Error message if invalid
+        parsed_data: Parsed data if valid
+        fallback_used: Whether fallback parsing was used
+    """
+
+    is_valid: bool
+    error_message: str | None = None
+    parsed_data: dict[str, Any] | None = None
+    fallback_used: bool = False
+
+
+class XMLValidator:
+    """Validates XML responses with graceful fallbacks.
+
+    Supports:
+    - Well-formedness validation
+    - XSD schema validation (optional)
+    - Graceful fallback on validation errors
+    - Schema caching for performance
+
+    Usage:
+        validator = XMLValidator()
+        result = validator.validate("<thinking>...</thinking>")
+
+        if result.is_valid:
+            data = result.parsed_data
+        else:
+            # Use fallback parsing
+            data = fallback_parse(response)
+    """
+
+    def __init__(
+        self,
+        schema_dir: str = ".empathy/schemas",
+        strict: bool = False,
+        enable_xsd: bool = False,
+    ):
+        """Initialize validator.
+
+        Args:
+            schema_dir: Directory containing XSD schemas
+            strict: If True, fail on validation errors. If False, use fallback.
+            enable_xsd: Enable XSD schema validation (requires lxml)
+        """
+        self.schema_dir = Path(schema_dir)
+        self.strict = strict
+        self.enable_xsd = enable_xsd
+        self._schema_cache: dict[str, Any] = {}
+
+        # Try to import lxml for XSD validation
+        self._lxml_available = False
+        if enable_xsd:
+            try:
+                from lxml import etree as lxml_etree  # noqa: F401
+
+                self._lxml_available = True
+            except ImportError:
+                pass
+
+    def validate(self, xml_string: str, schema_name: str | None = None) -> ValidationResult:
+        """Validate XML string.
+
+        Args:
+            xml_string: XML content to validate
+            schema_name: Optional XSD schema name (e.g., "agent_response")
+
+        Returns:
+            ValidationResult with validation status and parsed data
+        """
+        # Step 1: Well-formedness validation
+        try:
+            root = ET.fromstring(xml_string)  # nosec B314 - parsing trusted LLM responses
+        except ET.ParseError as e:
+            if self.strict:
+                return ValidationResult(
+                    is_valid=False,
+                    error_message=f"XML parsing failed: {e}",
+                    fallback_used=False,
+                )
+            # Try fallback parsing
+            return self._fallback_parse(xml_string, str(e))
+
+        # Step 2: XSD schema validation (optional)
+        if schema_name and self.enable_xsd and self._lxml_available:
+            schema_result = self._validate_with_xsd(xml_string, schema_name)
+            if not schema_result.is_valid:
+                if self.strict:
+                    return schema_result
+                # Continue with parsed data despite schema error
+                return ValidationResult(
+                    is_valid=True,
+                    parsed_data=self._extract_data(root),
+                    fallback_used=True,
+                    error_message=f"Schema validation failed: {schema_result.error_message}",
+                )
+
+        # Step 3: Extract structured data
+        parsed_data = self._extract_data(root)
+
+        return ValidationResult(
+            is_valid=True,
+            parsed_data=parsed_data,
+            fallback_used=False,
+        )
+
+    def _validate_with_xsd(self, xml_string: str, schema_name: str) -> ValidationResult:
+        """Validate XML against XSD schema.
+
+        Args:
+            xml_string: XML content
+            schema_name: Schema file name (without .xsd extension)
+
+        Returns:
+            ValidationResult
+        """
+        if not self._lxml_available:
+            return ValidationResult(
+                is_valid=False,
+                error_message="lxml not available for XSD validation",
+            )
+
+        try:
+            from lxml import etree as lxml_etree
+        except ImportError:
+            return ValidationResult(
+                is_valid=False,
+                error_message="lxml import failed",
+            )
+
+        # Load schema
+        schema_path = self.schema_dir / f"{schema_name}.xsd"
+        if not schema_path.exists():
+            return ValidationResult(
+                is_valid=False,
+                error_message=f"Schema not found: {schema_path}",
+            )
+
+        # Check cache
+        if schema_name not in self._schema_cache:
+            try:
+                schema_doc = lxml_etree.parse(str(schema_path))
+                self._schema_cache[schema_name] = lxml_etree.XMLSchema(schema_doc)
+            except Exception as e:
+                return ValidationResult(
+                    is_valid=False,
+                    error_message=f"Schema loading failed: {e}",
+                )
+
+        schema = self._schema_cache[schema_name]
+
+        # Validate
+        try:
+            xml_doc = lxml_etree.fromstring(xml_string.encode("utf-8"))
+            is_valid = schema.validate(xml_doc)
+
+            if not is_valid:
+                error_log = schema.error_log
+                return ValidationResult(
+                    is_valid=False,
+                    error_message=f"Schema validation failed: {error_log}",
+                )
+
+            return ValidationResult(is_valid=True)
+
+        except Exception as e:
+            return ValidationResult(
+                is_valid=False,
+                error_message=f"Validation error: {e}",
+            )
+
+    def _fallback_parse(self, xml_string: str, error: str) -> ValidationResult:
+        """Attempt fallback parsing of malformed XML.
+
+        Args:
+            xml_string: XML string that failed to parse
+            error: Parse error message
+
+        Returns:
+            ValidationResult with fallback data
+        """
+        # Try to extract data using regex patterns
+        import re
+
+        data: dict[str, Any] = {}
+
+        # Extract thinking content
+        thinking_match = re.search(r"<thinking[^>]*>(.*?)</thinking>", xml_string, re.DOTALL)
+        if thinking_match:
+            data["thinking"] = thinking_match.group(1).strip()
+
+        # Extract answer content
+        answer_match = re.search(r"<answer[^>]*>(.*?)</answer>", xml_string, re.DOTALL)
+        if answer_match:
+            data["answer"] = answer_match.group(1).strip()
+
+        # If we extracted something, consider it a partial success
+        if data:
+            return ValidationResult(
+                is_valid=True,
+                parsed_data=data,
+                fallback_used=True,
+                error_message=f"XML parsing failed, used fallback: {error}",
+            )
+
+        # Complete failure
+        return ValidationResult(
+            is_valid=False,
+            error_message=f"XML parsing and fallback failed: {error}",
+            fallback_used=True,
+        )
+
+    def _extract_data(self, root: ET.Element) -> dict[str, Any]:
+        """Extract structured data from parsed XML.
+
+        Args:
+            root: Parsed XML root element
+
+        Returns:
+            Dictionary with extracted data
+        """
+        data: dict[str, Any] = {}
+
+        # Extract all child elements
+        for child in root:
+            # Handle nested elements
+            if len(child):
+                data[child.tag] = self._extract_data(child)
+            else:
+                # Leaf node - get text content
+                data[child.tag] = child.text if child.text else ""
+
+        # Also store root attributes
+        if root.attrib:
+            data["_attributes"] = dict(root.attrib)
+
+        return data
+
+
+def validate_xml_response(
+    response: str,
+    schema_name: str | None = None,
+    strict: bool = False,
+) -> ValidationResult:
+    """Convenience function to validate XML response.
+
+    Args:
+        response: XML response string
+        schema_name: Optional XSD schema name
+        strict: If True, fail on validation errors
+
+    Returns:
+        ValidationResult
+
+    Example:
+        >>> response = "<thinking>Analysis</thinking><answer>Result</answer>"
+        >>> result = validate_xml_response(response)
+        >>> if result.is_valid:
+        ...     print(result.parsed_data)
+    """
+    validator = XMLValidator(strict=strict)
+    return validator.validate(response, schema_name)