empathy-framework 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

empathy_os/trust_building.py

@@ -1,527 +0,0 @@
-"""Trust-Building Behaviors for Anticipatory AI Agents
-
-Implements behaviors that build trust through anticipatory actions:
-- Pre-format data for handoffs (reduce cognitive load)
-- Clarify ambiguous instructions before execution (prevent wasted effort)
-- Volunteer structure during stress (actual scaffolding, not pep talks)
-- Proactively offer help when collaborators are struggling
-
-These behaviors demonstrate Level 4 Anticipatory Empathy by:
-1. Predicting friction points (handoffs, confusion, stress, overload)
-2. Acting without being asked (but without overstepping)
-3. Providing structural relief (not just emotional support)
-4. Building trust through consistent, helpful actions
-
-Based on trust-building patterns from ai-nurse-florence.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-import logging
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any
-
-logger = logging.getLogger(__name__)
-
-# Role categories for O(1) lookups
-EXECUTIVE_ROLES = frozenset({"executive", "ceo", "cto", "manager", "director", "vp"})
-TECHNICAL_ROLES = frozenset({"developer", "engineer", "architect", "devops", "sre"})
-COORDINATION_ROLES = frozenset({"team_lead", "project_manager", "scrum_master", "coordinator"})
-
-# Stress level categories
-HIGH_STRESS_LEVELS = frozenset({"critical", "high", "severe"})
-
-
-@dataclass
-class TrustSignal:
-    """A signal that indicates trust is building or eroding
-
-    Trust signals help track how trust evolves over time based on
-    observable behaviors and outcomes.
-    """
-
-    signal_type: str  # "building" or "eroding"
-    behavior: str
-    timestamp: datetime = field(default_factory=datetime.now)
-    evidence: str | None = None
-    impact: float = 0.5  # 0.0-1.0, magnitude of impact
-
-
-class TrustBuildingBehaviors:
-    """Level 4 Anticipatory trust-building behaviors
-
-    Philosophy: Trust is earned through consistent, helpful actions that
-    demonstrate understanding of collaboration dynamics and proactive
-    problem-solving.
-
-    **Core Principle**: Reduce cognitive load through anticipation
-
-    **Key Behaviors:**
-    1. Pre-format data for handoffs
-    2. Clarify ambiguous instructions before acting
-    3. Volunteer structure during stress
-    4. Offer help proactively when needed
-
-    Example:
-        >>> behaviors = TrustBuildingBehaviors()
-        >>>
-        >>> # Pre-format data for handoff
-        >>> data = {"items": [...], "total": 42}
-        >>> formatted = behaviors.pre_format_for_handoff(
-        ...     data=data,
-        ...     recipient_role="manager",
-        ...     context="quarterly_review"
-        ... )
-        >>>
-        >>> # Clarify ambiguous instruction
-        >>> instruction = "Update the system"
-        >>> clarified = behaviors.clarify_before_acting(
-        ...     instruction=instruction,
-        ...     ambiguities=["which system?", "what changes?"]
-        ... )
-
-    """
-
-    def __init__(self):
-        """Initialize TrustBuildingBehaviors"""
-        self.trust_signals: list[TrustSignal] = []
-
-    def pre_format_for_handoff(
-        self,
-        data: dict[str, Any],
-        recipient_role: str,
-        context: str,
-    ) -> dict[str, Any]:
-        """Pre-format data for handoff to reduce recipient's cognitive load
-
-        **Trust Built:**
-        - "This AI understands my workflow"
-        - "I don't have to translate data myself"
-        - "My time is valued"
-
-        Args:
-            data: Raw data to be handed off
-            recipient_role: Role of the person receiving the data
-            context: Context of the handoff (e.g., "meeting_prep", "report")
-
-        Returns:
-            Formatted data optimized for recipient's workflow
-
-        Example:
-            >>> data = {"tasks": [...], "metrics": {...}}
-            >>> formatted = behaviors.pre_format_for_handoff(
-            ...     data=data,
-            ...     recipient_role="executive",
-            ...     context="board_meeting"
-            ... )
-            >>> # Returns: executive summary format with key highlights
-
-        """
-        logger.info(f"Pre-formatting data for handoff to {recipient_role} (context: {context})")
-
-        formatted = {
-            "original_data": data,
-            "format": self._determine_format(recipient_role, context),
-            "timestamp": datetime.now().isoformat(),
-            "reasoning": f"Pre-formatted for {recipient_role} workflow",
-        }
-
-        # Format based on recipient role and context (O(1) set lookups)
-        if recipient_role in EXECUTIVE_ROLES:
-            formatted["summary"] = self._create_executive_summary(data, context)
-
-        elif recipient_role in TECHNICAL_ROLES:
-            formatted["summary"] = self._create_technical_summary(data, context)
-
-        elif recipient_role in COORDINATION_ROLES:
-            formatted["summary"] = self._create_action_oriented_summary(data, context)
-
-        else:
-            # Generic format for unknown roles
-            formatted["summary"] = self._create_generic_summary(data, context)
-
-        # Record trust signal
-        self._record_trust_signal(
-            signal_type="building",
-            behavior="pre_format_handoff",
-            evidence=f"Formatted data for {recipient_role}",
-        )
-
-        return formatted
-
-    def clarify_before_acting(
-        self,
-        instruction: str,
-        detected_ambiguities: list[str],
-        context: dict[str, Any] | None = None,
-    ) -> dict[str, Any]:
-        """Clarify ambiguous instructions before execution to prevent wasted effort
-
-        **Trust Built:**
-        - "This AI doesn't make dangerous assumptions"
-        - "It asks when uncertain (intelligent caution)"
-        - "My intent is understood, not just command followed"
-
-        Args:
-            instruction: The instruction received
-            detected_ambiguities: List of ambiguous aspects
-            context: Optional additional context
-
-        Returns:
-            Clarification request with specific questions
-
-        Example:
-            >>> instruction = "Deploy the changes"
-            >>> ambiguities = ["which environment?", "which changes?", "when?"]
-            >>> clarification = behaviors.clarify_before_acting(
-            ...     instruction=instruction,
-            ...     detected_ambiguities=ambiguities
-            ... )
-
-        """
-        logger.info(f"Clarifying ambiguous instruction: {instruction}")
-
-        clarifying_questions: list[dict[str, str]] = []
-        clarification: dict[str, Any] = {
-            "original_instruction": instruction,
-            "status": "needs_clarification",
-            "ambiguities_detected": detected_ambiguities,
-            "clarifying_questions": clarifying_questions,
-            "reasoning": (
-                "Detected ambiguities in instruction. Clarifying before acting "
-                "to prevent wasted effort or incorrect execution."
-            ),
-            "timestamp": datetime.now().isoformat(),
-        }
-
-        # Generate specific clarifying questions
-        for ambiguity in detected_ambiguities:
-            question = self._generate_clarifying_question(instruction, ambiguity, context)
-            clarifying_questions.append(question)
-
-        # Record trust signal
-        self._record_trust_signal(
-            signal_type="building",
-            behavior="clarify_ambiguity",
-            evidence=f"Asked for clarification on {len(detected_ambiguities)} ambiguities",
-        )
-
-        return clarification
-
-    def volunteer_structure_during_stress(
-        self,
-        stress_indicators: dict[str, Any],
-        available_scaffolding: list[str],
-    ) -> dict[str, Any]:
-        """Volunteer structure/scaffolding during stressful situations
-
-        **Not pep talks, actual structural help:**
-        - Break down overwhelming tasks
-        - Provide templates
-        - Create checklists
-        - Suggest prioritization frameworks
-
-        **Trust Built:**
-        - "This AI provides real help, not platitudes"
-        - "It understands when I'm overwhelmed"
-        - "It offers structure, not just encouragement"
-
-        Args:
-            stress_indicators: Dict of detected stress signals
-            available_scaffolding: List of support types available
-
-        Returns:
-            Structured support offer
-
-        Example:
-            >>> stress = {"task_count": 15, "deadline_proximity": "24h"}
-            >>> scaffolding = ["prioritization", "templates", "breakdown"]
-            >>> support = behaviors.volunteer_structure_during_stress(
-            ...     stress_indicators=stress,
-            ...     available_scaffolding=scaffolding
-            ... )
-
-        """
-        logger.info("Volunteering structure during detected stress")
-
-        stress_level = self._assess_stress_level(stress_indicators)
-
-        offered_support: list[dict[str, Any]] = []
-        support: dict[str, Any] = {
-            "stress_assessment": {"level": stress_level, "indicators": stress_indicators},
-            "offered_support": offered_support,
-            "reasoning": (
-                f"Detected {stress_level} stress. Volunteering structural support "
-                "to reduce cognitive load and provide actionable scaffolding."
-            ),
-            "timestamp": datetime.now().isoformat(),
-        }
-
-        # Offer appropriate scaffolding based on stress level
-        if stress_level in HIGH_STRESS_LEVELS:
-            if "prioritization" in available_scaffolding:
-                offered_support.append(
-                    {
-                        "type": "prioritization",
-                        "description": "Help prioritize tasks using urgency-importance matrix",
-                        "immediate": True,
-                    },
-                )
-
-            if "breakdown" in available_scaffolding:
-                offered_support.append(
-                    {
-                        "type": "task_breakdown",
-                        "description": "Break overwhelming tasks into smaller, manageable steps",
-                        "immediate": True,
-                    },
-                )
-
-        if "templates" in available_scaffolding:
-            offered_support.append(
-                {
-                    "type": "templates",
-                    "description": "Provide templates to reduce creation effort",
-                    "immediate": False,
-                },
-            )
-
-        # Record trust signal
-        self._record_trust_signal(
-            signal_type="building",
-            behavior="volunteer_structure",
-            evidence=f"Offered {len(support['offered_support'])} types of structural support",
-        )
-
-        return support
-
-    def offer_proactive_help(
-        self,
-        struggle_indicators: dict[str, Any],
-        available_help: list[str],
-    ) -> dict[str, Any]:
-        """Proactively offer help when collaborator is struggling
-
-        **Trust Built:**
-        - "This AI notices when I'm stuck"
-        - "It offers help without waiting to be asked"
-        - "It doesn't overstep, but is ready to assist"
-
-        Args:
-            struggle_indicators: Signals that someone is struggling
-            available_help: Types of help available
-
-        Returns:
-            Help offer tailored to situation
-
-        Example:
-            >>> indicators = {"repeated_errors": 3, "time_on_task": 45}
-            >>> help_types = ["debugging", "explanation", "examples"]
-            >>> offer = behaviors.offer_proactive_help(
-            ...     struggle_indicators=indicators,
-            ...     available_help=help_types
-            ... )
-
-        """
-        logger.info("Offering proactive help based on struggle indicators")
-
-        struggle_type = self._classify_struggle(struggle_indicators)
-
-        help_offered: list[dict[str, str]] = []
-        offer: dict[str, Any] = {
-            "struggle_assessment": {"type": struggle_type, "indicators": struggle_indicators},
-            "help_offered": help_offered,
-            "tone": "supportive_not_condescending",
-            "reasoning": (
-                f"Detected {struggle_type} struggle pattern. Offering relevant help "
-                "proactively while respecting autonomy."
-            ),
-            "timestamp": datetime.now().isoformat(),
-        }
-
-        # Offer appropriate help based on struggle type
-        if struggle_type == "comprehension":
-            if "explanation" in available_help:
-                help_offered.append(
-                    {
-                        "type": "explanation",
-                        "description": "Provide clearer explanation of concept",
-                    },
-                )
-            if "examples" in available_help:
-                help_offered.append({"type": "examples", "description": "Show concrete examples"})
-
-        elif struggle_type == "execution":
-            if "debugging" in available_help:
-                help_offered.append({"type": "debugging", "description": "Help debug the issue"})
-            if "guidance" in available_help:
-                help_offered.append(
-                    {"type": "step_by_step", "description": "Provide step-by-step guidance"},
-                )
-
-        # Record trust signal
-        self._record_trust_signal(
-            signal_type="building",
-            behavior="proactive_help",
-            evidence=f"Offered help for {struggle_type} struggle",
-        )
-
-        return offer
-
-    def get_trust_trajectory(self) -> dict[str, Any]:
-        """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}
-
-        building_count = sum(1 for s in self.trust_signals if s.signal_type == "building")
-        eroding_count = sum(1 for s in self.trust_signals if s.signal_type == "eroding")
-
-        total = len(self.trust_signals)
-        building_ratio = building_count / total if total > 0 else 0
-
-        if building_ratio > 0.7:
-            trajectory = "strongly_building"
-        elif building_ratio > 0.5:
-            trajectory = "building"
-        elif building_ratio > 0.3:
-            trajectory = "mixed"
-        else:
-            trajectory = "eroding"
-
-        return {
-            "status": "active",
-            "trajectory": trajectory,
-            "signal_count": total,
-            "building_signals": building_count,
-            "eroding_signals": eroding_count,
-            "building_ratio": building_ratio,
-            "recent_behaviors": [s.behavior for s in self.trust_signals[-5:]],
-        }
-
-    # Helper methods
-
-    def _determine_format(self, role: str, context: str) -> str:
-        """Determine appropriate format based on role and context"""
-        if role in ["executive", "manager", "director"]:
-            return "executive_summary"
-        if role in ["developer", "engineer", "analyst"]:
-            return "technical_detail"
-        if role in ["team_lead", "coordinator"]:
-            return "action_oriented"
-        return "general"
-
-    def _create_executive_summary(self, data: dict, context: str) -> dict:
-        """Create executive summary format"""
-        return {
-            "type": "executive_summary",
-            "key_metrics": self._extract_key_metrics(data),
-            "highlights": self._extract_highlights(data),
-            "recommendations": self._extract_recommendations(data),
-            "context": context,
-        }
-
-    def _create_technical_summary(self, data: dict, context: str) -> dict:
-        """Create technical summary format"""
-        return {
-            "type": "technical_detail",
-            "details": data,
-            "technical_notes": self._extract_technical_notes(data),
-            "context": context,
-        }
-
-    def _create_action_oriented_summary(self, data: dict, context: str) -> dict:
-        """Create action-oriented summary format"""
-        return {
-            "type": "action_oriented",
-            "immediate_actions": self._extract_immediate_actions(data),
-            "priorities": self._extract_priorities(data),
-            "context": context,
-        }
-
-    def _create_generic_summary(self, data: dict, context: str) -> dict:
-        """Create generic summary format"""
-        return {"type": "general", "summary": str(data), "context": context}
-
-    def _extract_key_metrics(self, data: dict) -> list[str]:
-        """Extract key metrics from data"""
-        metrics = []
-        for key, value in data.items():
-            if isinstance(value, int | float):
-                metrics.append(f"{key}: {value}")
-        return metrics[:5]  # Top 5 metrics
-
-    def _extract_highlights(self, data: dict) -> list[str]:
-        """Extract highlights from data"""
-        return [f"Data contains {len(data)} fields"]
-
-    def _extract_recommendations(self, data: dict) -> list[str]:
-        """Extract recommendations from data"""
-        return ["Review detailed data for full context"]
-
-    def _extract_technical_notes(self, data: dict) -> list[str]:
-        """Extract technical notes"""
-        return [f"Data structure: {type(data).__name__}"]
-
-    def _extract_immediate_actions(self, data: dict[str, Any]) -> list[str]:
-        """Extract immediate actions"""
-        if "actions" in data:
-            actions: list[str] = data["actions"][:5]
-            return actions
-        return ["Review data and determine next steps"]
-
-    def _extract_priorities(self, data: dict[str, Any]) -> list[str]:
-        """Extract priorities"""
-        if "priorities" in data:
-            priorities: list[str] = data["priorities"]
-            return priorities
-        return []
-
-    def _generate_clarifying_question(
-        self,
-        instruction: str,
-        ambiguity: str,
-        context: dict | None,
-    ) -> dict[str, str]:
-        """Generate a specific clarifying question"""
-        return {
-            "ambiguity": ambiguity,
-            "question": f"Could you clarify: {ambiguity}",
-            "context": str(context) if context else "none",
-        }
-
-    def _assess_stress_level(self, indicators: dict) -> str:
-        """Assess stress level from indicators"""
-        # Simple heuristic: count stress indicators
-        stress_score = len(indicators)
-
-        if stress_score >= 4:
-            return "critical"
-        if stress_score >= 3:
-            return "high"
-        if stress_score >= 2:
-            return "moderate"
-        return "low"
-
-    def _classify_struggle(self, indicators: dict) -> str:
-        """Classify type of struggle"""
-        if "repeated_errors" in indicators:
-            return "execution"
-        if "time_on_task" in indicators:
-            return "comprehension"
-        return "general"
-
-    def _record_trust_signal(self, signal_type: str, behavior: str, evidence: str | None = None):
-        """Record a trust signal"""
-        signal = TrustSignal(signal_type=signal_type, behavior=behavior, evidence=evidence)
-        self.trust_signals.append(signal)
-
-    def reset(self):
-        """Reset trust tracking"""
-        self.trust_signals = []

empathy_os/validation/__init__.py

@@ -1,19 +0,0 @@
-"""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",
-]