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

empathy_os/redis_memory.py

@@ -1,5 +1,4 @@
-"""
-Redis Short-Term Memory for Empathy Framework
+"""Redis Short-Term Memory for Empathy Framework
 
 Per EMPATHY_PHILOSOPHY.md v1.1.0:
 - Implements fast, TTL-based working memory for agent coordination
@@ -30,8 +29,7 @@ from .memory.short_term import AccessTier
 
 
 class TTLStrategy(Enum):
-    """
-    TTL strategies for different memory types
+    """TTL strategies for different memory types
 
     Per EMPATHY_PHILOSOPHY.md Section 9.3:
     - Working results: 1 hour
@@ -120,8 +118,7 @@ class StagedPattern:
 
 @dataclass
 class ConflictContext:
-    """
-    Context for principled negotiation
+    """Context for principled negotiation
 
     Per Getting to Yes framework:
     - Positions: What each party says they want
@@ -162,8 +159,7 @@ class ConflictContext:
 
 
 class RedisShortTermMemory:
-    """
-    Redis-backed short-term memory for agent coordination
+    """Redis-backed short-term memory for agent coordination
 
     Features:
     - Fast read/write with automatic TTL expiration
@@ -177,6 +173,7 @@ class RedisShortTermMemory:
         >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
         >>> memory.stash("analysis_results", {"issues": 3}, creds)
         >>> data = memory.retrieve("analysis_results", creds)
+
     """
 
     # Key prefixes for namespacing
@@ -194,8 +191,7 @@ class RedisShortTermMemory:
         password: str | None = None,
         use_mock: bool = False,
     ):
-        """
-        Initialize Redis connection
+        """Initialize Redis connection
 
         Args:
             host: Redis host
@@ -203,6 +199,7 @@ class RedisShortTermMemory:
             db: Redis database number
             password: Redis password (optional)
             use_mock: Use in-memory mock for testing
+
         """
         self.use_mock = use_mock or not REDIS_AVAILABLE
 
@@ -277,8 +274,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         ttl: TTLStrategy = TTLStrategy.WORKING_RESULTS,
     ) -> bool:
-        """
-        Stash data in short-term memory
+        """Stash data in short-term memory
 
         Args:
             key: Unique key for the data
@@ -291,11 +287,12 @@ class RedisShortTermMemory:
 
         Example:
             >>> memory.stash("analysis_v1", {"findings": [...]}, creds)
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} (Tier {credentials.tier.name}) "
-                "cannot write to memory. Requires CONTRIBUTOR or higher."
+                "cannot write to memory. Requires CONTRIBUTOR or higher.",
             )
 
         full_key = f"{self.PREFIX_WORKING}{credentials.agent_id}:{key}"
@@ -312,8 +309,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         agent_id: str | None = None,
     ) -> Any | None:
-        """
-        Retrieve data from short-term memory
+        """Retrieve data from short-term memory
 
         Args:
             key: Key to retrieve
@@ -325,6 +321,7 @@ class RedisShortTermMemory:
 
         Example:
             >>> data = memory.retrieve("analysis_v1", creds)
+
         """
         owner = agent_id or credentials.agent_id
         full_key = f"{self.PREFIX_WORKING}{owner}:{key}"
@@ -337,14 +334,14 @@ class RedisShortTermMemory:
         return payload.get("data")
 
     def clear_working_memory(self, credentials: AgentCredentials) -> int:
-        """
-        Clear all working memory for an agent
+        """Clear all working memory for an agent
 
         Args:
             credentials: Agent credentials (must own the memory or be Steward)
 
         Returns:
             Number of keys deleted
+
         """
         pattern = f"{self.PREFIX_WORKING}{credentials.agent_id}:*"
         keys = self._keys(pattern)
@@ -361,8 +358,7 @@ class RedisShortTermMemory:
         pattern: StagedPattern,
         credentials: AgentCredentials,
     ) -> bool:
-        """
-        Stage a pattern for validation
+        """Stage a pattern for validation
 
         Per EMPATHY_PHILOSOPHY.md: Patterns must be staged before
         being promoted to the active library.
@@ -373,11 +369,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if staged successfully
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot stage patterns. "
-                "Requires CONTRIBUTOR tier or higher."
+                "Requires CONTRIBUTOR tier or higher.",
             )
 
         key = f"{self.PREFIX_STAGED}{pattern.pattern_id}"
@@ -392,8 +389,7 @@ class RedisShortTermMemory:
         pattern_id: str,
         credentials: AgentCredentials,
     ) -> StagedPattern | None:
-        """
-        Retrieve a staged pattern
+        """Retrieve a staged pattern
 
         Args:
             pattern_id: Pattern ID
@@ -401,6 +397,7 @@ class RedisShortTermMemory:
 
         Returns:
             StagedPattern or None
+
         """
         key = f"{self.PREFIX_STAGED}{pattern_id}"
         raw = self._get(key)
@@ -414,14 +411,14 @@ class RedisShortTermMemory:
         self,
         credentials: AgentCredentials,
     ) -> list[StagedPattern]:
-        """
-        List all staged patterns awaiting validation
+        """List all staged patterns awaiting validation
 
         Args:
             credentials: Any tier can read
 
         Returns:
             List of staged patterns
+
         """
         pattern = f"{self.PREFIX_STAGED}*"
         keys = self._keys(pattern)
@@ -439,8 +436,7 @@ class RedisShortTermMemory:
         pattern_id: str,
         credentials: AgentCredentials,
     ) -> StagedPattern | None:
-        """
-        Promote staged pattern (remove from staging for library add)
+        """Promote staged pattern (remove from staging for library add)
 
         Args:
             pattern_id: Pattern to promote
@@ -448,11 +444,12 @@ class RedisShortTermMemory:
 
         Returns:
             The promoted pattern (for adding to PatternLibrary)
+
         """
         if not credentials.can_validate():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot promote patterns. "
-                "Requires VALIDATOR tier or higher."
+                "Requires VALIDATOR tier or higher.",
             )
 
         pattern = self.get_staged_pattern(pattern_id, credentials)
@@ -467,8 +464,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         reason: str = "",
     ) -> bool:
-        """
-        Reject a staged pattern
+        """Reject a staged pattern
 
         Args:
             pattern_id: Pattern to reject
@@ -477,11 +473,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if rejected
+
         """
         if not credentials.can_validate():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot reject patterns. "
-                "Requires VALIDATOR tier or higher."
+                "Requires VALIDATOR tier or higher.",
             )
 
         key = f"{self.PREFIX_STAGED}{pattern_id}"
@@ -497,8 +494,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         batna: str | None = None,
     ) -> ConflictContext:
-        """
-        Create context for principled negotiation
+        """Create context for principled negotiation
 
         Per Getting to Yes framework:
         - Separate positions from interests
@@ -513,11 +509,12 @@ class RedisShortTermMemory:
 
         Returns:
             ConflictContext for resolution
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot create conflict context. "
-                "Requires CONTRIBUTOR tier or higher."
+                "Requires CONTRIBUTOR tier or higher.",
             )
 
         context = ConflictContext(
@@ -541,8 +538,7 @@ class RedisShortTermMemory:
         conflict_id: str,
         credentials: AgentCredentials,
     ) -> ConflictContext | None:
-        """
-        Retrieve conflict context
+        """Retrieve conflict context
 
         Args:
             conflict_id: Conflict identifier
@@ -550,6 +546,7 @@ class RedisShortTermMemory:
 
         Returns:
             ConflictContext or None
+
         """
         key = f"{self.PREFIX_CONFLICT}{conflict_id}"
         raw = self._get(key)
@@ -565,8 +562,7 @@ class RedisShortTermMemory:
         resolution: str,
         credentials: AgentCredentials,
     ) -> bool:
-        """
-        Mark conflict as resolved
+        """Mark conflict as resolved
 
         Args:
             conflict_id: Conflict to resolve
@@ -575,11 +571,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if resolved
+
         """
         if not credentials.can_validate():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot resolve conflicts. "
-                "Requires VALIDATOR tier or higher."
+                "Requires VALIDATOR tier or higher.",
             )
 
         context = self.get_conflict_context(conflict_id, credentials)
@@ -603,8 +600,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         target_agent: str | None = None,
     ) -> bool:
-        """
-        Send coordination signal to other agents
+        """Send coordination signal to other agents
 
         Args:
             signal_type: Type of signal (e.g., "ready", "blocking", "complete")
@@ -614,11 +610,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if sent
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot send signals. "
-                "Requires CONTRIBUTOR tier or higher."
+                "Requires CONTRIBUTOR tier or higher.",
             )
 
         target = target_agent or "broadcast"
@@ -637,8 +634,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         signal_type: str | None = None,
     ) -> list[dict]:
-        """
-        Receive coordination signals
+        """Receive coordination signals
 
         Args:
             credentials: Agent receiving signals
@@ -646,6 +642,7 @@ class RedisShortTermMemory:
 
         Returns:
             List of signals
+
         """
         if signal_type:
             pattern = f"{self.PREFIX_COORDINATION}{signal_type}:*:{credentials.agent_id}"
@@ -673,8 +670,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         metadata: dict | None = None,
     ) -> bool:
-        """
-        Create a collaboration session
+        """Create a collaboration session
 
         Args:
             session_id: Unique session identifier
@@ -683,6 +679,7 @@ class RedisShortTermMemory:
 
         Returns:
             True if created
+
         """
         key = f"{self.PREFIX_SESSION}{session_id}"
         payload = {
@@ -699,8 +696,7 @@ class RedisShortTermMemory:
         session_id: str,
         credentials: AgentCredentials,
     ) -> bool:
-        """
-        Join an existing session
+        """Join an existing session
 
         Args:
             session_id: Session to join
@@ -708,6 +704,7 @@ class RedisShortTermMemory:
 
         Returns:
             True if joined
+
         """
         key = f"{self.PREFIX_SESSION}{session_id}"
         raw = self._get(key)
@@ -726,8 +723,7 @@ class RedisShortTermMemory:
         session_id: str,
         credentials: AgentCredentials,
     ) -> dict | None:
-        """
-        Get session information
+        """Get session information
 
         Args:
             session_id: Session identifier
@@ -735,6 +731,7 @@ class RedisShortTermMemory:
 
         Returns:
             Session data or None
+
         """
         key = f"{self.PREFIX_SESSION}{session_id}"
         raw = self._get(key)
@@ -748,11 +745,11 @@ class RedisShortTermMemory:
     # === Health Check ===
 
     def ping(self) -> bool:
-        """
-        Check Redis connection health
+        """Check Redis connection health
 
         Returns:
             True if connected and responsive
+
         """
         if self.use_mock:
             return True
@@ -764,24 +761,24 @@ class RedisShortTermMemory:
             return False
 
     def get_stats(self) -> dict:
-        """
-        Get memory statistics
+        """Get memory statistics
 
         Returns:
             Dict with memory stats
+
         """
         if self.use_mock:
             return {
                 "mode": "mock",
                 "total_keys": len(self._mock_storage),
                 "working_keys": len(
-                    [k for k in self._mock_storage if k.startswith(self.PREFIX_WORKING)]
+                    [k for k in self._mock_storage if k.startswith(self.PREFIX_WORKING)],
                 ),
                 "staged_keys": len(
-                    [k for k in self._mock_storage if k.startswith(self.PREFIX_STAGED)]
+                    [k for k in self._mock_storage if k.startswith(self.PREFIX_STAGED)],
                 ),
                 "conflict_keys": len(
-                    [k for k in self._mock_storage if k.startswith(self.PREFIX_CONFLICT)]
+                    [k for k in self._mock_storage if k.startswith(self.PREFIX_CONFLICT)],
                 ),
             }
 

empathy_os/templates.py

@@ -1,5 +1,4 @@
-"""
-Template Starters for Empathy Framework
+"""Template Starters for Empathy Framework
 
 Scaffold new projects with Empathy pre-configured for different use cases.
 
@@ -619,10 +618,12 @@ def list_templates() -> list:
 
 
 def scaffold_project(
-    template_name: str, project_name: str, target_dir: str | None = None, force: bool = False
+    template_name: str,
+    project_name: str,
+    target_dir: str | None = None,
+    force: bool = False,
 ) -> dict:
-    """
-    Create a new project from a template.
+    """Create a new project from a template.
 
     Args:
         template_name: Template ID (minimal, python-cli, python-fastapi, python-agent)
@@ -632,6 +633,7 @@ def scaffold_project(
 
     Returns:
         Dict with created files and status
+
     """
     if template_name not in TEMPLATES:
         return {
@@ -742,9 +744,8 @@ def cmd_new(args):
             print(f"    $ {step}")
         print()
         return 0
-    else:
-        print(f"\n  Error: {result['error']}")
-        if "available" in result:
-            print(f"  Available templates: {', '.join(result['available'])}")
-        print()
-        return 1
+    print(f"\n  Error: {result['error']}")
+    if "available" in result:
+        print(f"  Available templates: {', '.join(result['available'])}")
+    print()
+    return 1

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,6 +171,7 @@ class TrustBuildingBehaviors:
             ...     instruction=instruction,
             ...     detected_ambiguities=ambiguities
             ... )
+
         """
         logger.info(f"Clarifying ambiguous instruction: {instruction}")
 
@@ -202,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
@@ -232,6 +234,7 @@ class TrustBuildingBehaviors:
             ...     stress_indicators=stress,
             ...     available_scaffolding=scaffolding
             ... )
+
         """
         logger.info("Volunteering structure during detected stress")
 
@@ -256,7 +259,7 @@ class TrustBuildingBehaviors:
                         "type": "prioritization",
                         "description": "Help prioritize tasks using urgency-importance matrix",
                         "immediate": True,
-                    }
+                    },
                 )
 
             if "breakdown" in available_scaffolding:
@@ -265,7 +268,7 @@ class TrustBuildingBehaviors:
                         "type": "task_breakdown",
                         "description": "Break overwhelming tasks into smaller, manageable steps",
                         "immediate": True,
-                    }
+                    },
                 )
 
         if "templates" in available_scaffolding:
@@ -274,7 +277,7 @@ class TrustBuildingBehaviors:
                     "type": "templates",
                     "description": "Provide templates to reduce creation effort",
                     "immediate": False,
-                }
+                },
             )
 
         # Record trust signal
@@ -287,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"
@@ -311,6 +315,7 @@ class TrustBuildingBehaviors:
             ...     struggle_indicators=indicators,
             ...     available_help=help_types
             ... )
+
         """
         logger.info("Offering proactive help based on struggle indicators")
 
@@ -332,7 +337,10 @@ class TrustBuildingBehaviors:
         if struggle_type == "comprehension":
             if "explanation" in available_help:
                 help_offered.append(
-                    {"type": "explanation", "description": "Provide clearer explanation of concept"}
+                    {
+                        "type": "explanation",
+                        "description": "Provide clearer explanation of concept",
+                    },
                 )
             if "examples" in available_help:
                 help_offered.append({"type": "examples", "description": "Show concrete examples"})
@@ -342,7 +350,7 @@ class TrustBuildingBehaviors:
                 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"}
+                    {"type": "step_by_step", "description": "Provide step-by-step guidance"},
                 )
 
         # Record trust signal
@@ -355,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}
@@ -395,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"""
@@ -469,7 +476,10 @@ class TrustBuildingBehaviors:
         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 {
@@ -485,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"""