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

empathy_os/discovery.py

@@ -1,306 +0,0 @@
-"""Progressive Feature Discovery for Empathy Framework
-
-Surface tips and suggestions at the right time based on usage patterns.
-Helps users discover power-user features without overwhelming them upfront.
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-import json
-from datetime import datetime
-from pathlib import Path
-
-from empathy_os.config import _validate_file_path
-
-# Discovery tips with conditions
-DISCOVERY_TIPS = {
-    # After first commands
-    "after_first_inspect": {
-        "tip": "Try 'empathy ship' before commits for automated pre-flight checks",
-        "trigger": "inspect",
-        "min_uses": 1,
-        "priority": 2,
-        "shown": False,
-    },
-    "after_first_health": {
-        "tip": "Use 'empathy fix-all' to auto-fix lint and format issues",
-        "trigger": "health",
-        "min_uses": 1,
-        "priority": 2,
-        "shown": False,
-    },
-    # After accumulating usage
-    "after_10_inspects": {
-        "tip": "You've got patterns! Run 'empathy sync-claude' to share them with Claude Code",
-        "trigger": "inspect",
-        "min_uses": 10,
-        "priority": 1,
-        "shown": False,
-    },
-    "after_5_ships": {
-        "tip": "Start your day with 'empathy morning' for a productivity briefing",
-        "trigger": "ship",
-        "min_uses": 5,
-        "priority": 1,
-        "shown": False,
-    },
-    # Context-based tips
-    "high_tech_debt": {
-        "tip": "Tech debt is trending up. Try 'empathy status' for priority focus areas",
-        "condition": lambda stats: stats.get("tech_debt_trend") == "increasing",
-        "priority": 1,
-        "shown": False,
-    },
-    "no_patterns": {
-        "tip": "Run 'empathy learn' to extract patterns from your git history",
-        "condition": lambda stats: stats.get("patterns_learned", 0) == 0
-        and stats.get("total_commands", 0) > 5,
-        "priority": 1,
-        "shown": False,
-    },
-    "cost_savings": {
-        "tip": "Check your API savings with 'empathy costs' - model routing can save 80%!",
-        "condition": lambda stats: stats.get("api_requests", 0) > 10,
-        "priority": 2,
-        "shown": False,
-    },
-    # Weekly reminders
-    "weekly_sync": {
-        "tip": "Weekly reminder: Run 'empathy sync-claude' to keep Claude Code patterns current",
-        "condition": lambda stats: _days_since_sync(stats) >= 7,
-        "priority": 2,
-        "shown": False,
-    },
-}
-
-
-def _days_since_sync(stats: dict) -> int:
-    """Calculate days since last Claude sync."""
-    last_sync = stats.get("last_claude_sync")
-    if not last_sync:
-        return 999
-    try:
-        sync_date = datetime.fromisoformat(last_sync)
-        return (datetime.now() - sync_date).days
-    except (ValueError, TypeError):
-        return 999
-
-
-class DiscoveryEngine:
-    """Tracks usage and surfaces contextual tips.
-
-    Usage:
-        engine = DiscoveryEngine()
-        engine.record_command("inspect")
-        tips = engine.get_pending_tips()
-        engine.mark_shown("after_first_inspect")
-    """
-
-    def __init__(self, storage_dir: str = ".empathy"):
-        """Initialize discovery engine."""
-        self.storage_dir = Path(storage_dir)
-        self.storage_dir.mkdir(parents=True, exist_ok=True)
-        self.stats_file = self.storage_dir / "discovery_stats.json"
-        self._load()
-
-    def _load(self) -> None:
-        """Load discovery state from storage."""
-        if self.stats_file.exists():
-            try:
-                with open(self.stats_file) as f:
-                    self.state = json.load(f)
-            except (OSError, json.JSONDecodeError):
-                self.state = self._default_state()
-        else:
-            self.state = self._default_state()
-
-    def _default_state(self) -> dict:
-        """Return default state structure."""
-        return {
-            "command_counts": {},
-            "tips_shown": [],
-            "total_commands": 0,
-            "patterns_learned": 0,
-            "api_requests": 0,
-            "tech_debt_trend": "unknown",
-            "last_claude_sync": None,
-            "first_run": datetime.now().isoformat(),
-            "last_updated": datetime.now().isoformat(),
-        }
-
-    def _save(self) -> None:
-        """Save state to storage."""
-        self.state["last_updated"] = datetime.now().isoformat()
-        validated_path = _validate_file_path(str(self.stats_file))
-        with open(validated_path, "w") as f:
-            json.dump(self.state, f, indent=2)
-
-    def record_command(self, command: str) -> list:
-        """Record a command execution and return any triggered tips.
-
-        Args:
-            command: The command that was executed
-
-        Returns:
-            List of tip messages to show
-
-        """
-        # Update counts
-        counts = self.state.get("command_counts", {})
-        counts[command] = counts.get(command, 0) + 1
-        self.state["command_counts"] = counts
-        self.state["total_commands"] = self.state.get("total_commands", 0) + 1
-
-        self._save()
-
-        # Check for triggered tips
-        return self.get_pending_tips(trigger=command)
-
-    def record_patterns_learned(self, count: int) -> None:
-        """Record patterns learned."""
-        self.state["patterns_learned"] = self.state.get("patterns_learned", 0) + count
-        self._save()
-
-    def record_api_request(self) -> None:
-        """Record an API request."""
-        self.state["api_requests"] = self.state.get("api_requests", 0) + 1
-        self._save()
-
-    def record_claude_sync(self) -> None:
-        """Record a Claude sync."""
-        self.state["last_claude_sync"] = datetime.now().isoformat()
-        self._save()
-
-    def set_tech_debt_trend(self, trend: str) -> None:
-        """Set tech debt trend (increasing/decreasing/stable)."""
-        self.state["tech_debt_trend"] = trend
-        self._save()
-
-    def get_pending_tips(self, trigger: str | None = None, max_tips: int = 2) -> list:
-        """Get pending tips based on current state.
-
-        Args:
-            trigger: Command that triggered this check (optional)
-            max_tips: Maximum number of tips to return
-
-        Returns:
-            List of tip messages
-
-        """
-        tips_to_show = []
-        shown_tips = set(self.state.get("tips_shown", []))
-
-        for tip_id, tip_config in DISCOVERY_TIPS.items():
-            # Skip if already shown
-            if tip_id in shown_tips:
-                continue
-
-            should_show = False
-
-            # Check trigger-based tips
-            if "trigger" in tip_config:
-                if trigger == tip_config["trigger"]:
-                    count = self.state.get("command_counts", {}).get(trigger, 0)
-                    if count >= tip_config.get("min_uses", 1):
-                        should_show = True
-
-            # Check condition-based tips
-            elif "condition" in tip_config:
-                try:
-                    condition = tip_config["condition"]
-                    if callable(condition) and condition(self.state):
-                        should_show = True
-                except Exception:
-                    pass
-
-            if should_show:
-                tips_to_show.append(
-                    {
-                        "id": tip_id,
-                        "tip": tip_config["tip"],
-                        "priority": tip_config.get("priority", 3),
-                    },
-                )
-
-        # Sort by priority and limit - ensure we get an int for sorting
-        def get_priority(x: dict) -> int:
-            p = x.get("priority", 3)
-            return int(p) if isinstance(p, int | float | str) else 3
-
-        tips_to_show.sort(key=get_priority)
-        return tips_to_show[:max_tips]
-
-    def mark_shown(self, tip_id: str) -> None:
-        """Mark a tip as shown so it won't be repeated."""
-        shown = self.state.get("tips_shown", [])
-        if tip_id not in shown:
-            shown.append(tip_id)
-            self.state["tips_shown"] = shown
-            self._save()
-
-    def get_stats(self) -> dict:
-        """Get current discovery statistics."""
-        return {
-            "total_commands": self.state.get("total_commands", 0),
-            "command_counts": self.state.get("command_counts", {}),
-            "patterns_learned": self.state.get("patterns_learned", 0),
-            "tips_shown": len(self.state.get("tips_shown", [])),
-            "tips_remaining": len(DISCOVERY_TIPS) - len(self.state.get("tips_shown", [])),
-            "days_active": self._days_active(),
-        }
-
-    def _days_active(self) -> int:
-        """Calculate days since first run."""
-        first_run = self.state.get("first_run")
-        if not first_run:
-            return 0
-        try:
-            first = datetime.fromisoformat(first_run)
-            return (datetime.now() - first).days
-        except (ValueError, TypeError):
-            return 0
-
-
-# Singleton instance
-_engine: DiscoveryEngine | None = None
-
-
-def get_engine(storage_dir: str = ".empathy") -> DiscoveryEngine:
-    """Get or create the global discovery engine."""
-    global _engine
-    if _engine is None:
-        _engine = DiscoveryEngine(storage_dir)
-    return _engine
-
-
-def show_tip_if_available(command: str, quiet: bool = False) -> None:
-    """Check for tips after a command and display them.
-
-    Args:
-        command: The command that was just executed
-        quiet: If True, don't print anything
-
-    """
-    engine = get_engine()
-    tips = engine.record_command(command)
-
-    if tips and not quiet:
-        print()
-        for tip_data in tips:
-            print(f"  TIP: {tip_data['tip']}")
-            engine.mark_shown(tip_data["id"])
-        print()
-
-
-def format_tips_for_cli(tips: list) -> str:
-    """Format tips for CLI output."""
-    if not tips:
-        return ""
-
-    lines = ["\n  TIPS", "  " + "-" * 38]
-    for tip_data in tips:
-        lines.append(f"  {tip_data['tip']}")
-    lines.append("")
-
-    return "\n".join(lines)

empathy_os/emergence.py

@@ -1,306 +0,0 @@
-"""Emergence Detection for AI-Human Collaboration
-
-Detects emergent properties in AI-human collaboration - system-level behaviors
-that arise from component interactions but aren't properties of components.
-
-Based on systems thinking principles from Donella Meadows and Peter Senge.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any
-
-
-@dataclass
-class EmergentProperty:
-    """An emergent property discovered in the system
-
-    Emergent properties are behaviors or patterns that arise from the
-    interactions of system components but cannot be predicted from
-    the components alone.
-    """
-
-    property_type: str  # "norm", "pattern", "behavior", "capability"
-    description: str
-    first_observed: datetime = field(default_factory=datetime.now)
-    confidence: float = 0.0  # 0.0-1.0
-    evidence: list[dict[str, Any]] = field(default_factory=list)
-    components_involved: list[str] = field(default_factory=list)
-
-
-class EmergenceDetector:
-    """Detects emergent properties in AI-human collaboration
-
-    Emergent properties are system-level behaviors that arise from
-    component interactions but aren't properties of the components themselves.
-
-    Examples:
-    - Team norms that developed organically (not prescribed)
-    - Collaboration patterns that emerged from repeated interactions
-    - Shared understanding that goes beyond individual knowledge
-    - Trust dynamics that affect system behavior
-
-    Based on systems thinking:
-    - Whole is greater than sum of parts
-    - Properties emerge at system level
-    - Cannot reduce to component analysis
-
-    Example:
-        >>> detector = EmergenceDetector()
-        >>> baseline = {"trust": 0.3, "interactions": 10}
-        >>> current = {"trust": 0.8, "interactions": 50, "shared_patterns": 5}
-        >>> score = detector.measure_emergence(baseline, current)
-        >>> print(f"Emergence score: {score:.2f}")
-
-    """
-
-    def __init__(self):
-        """Initialize EmergenceDetector with tracking structures"""
-        self.detected_properties: list[EmergentProperty] = []
-        self.baseline_metrics: dict[str, Any] = {}
-
-    def detect_emergent_norms(
-        self,
-        team_interactions: list[dict[str, Any]],
-    ) -> list[EmergentProperty]:
-        """Detect team norms that emerged organically
-
-        Analyzes interaction history to identify behavioral patterns that:
-        1. Were not explicitly programmed or prescribed
-        2. Emerged from repeated interactions
-        3. Are now consistently followed by team members
-
-        Args:
-            team_interactions: List of interaction records with metadata
-
-        Returns:
-            List of detected emergent norms
-
-        Example:
-            >>> interactions = [
-            ...     {"type": "help_request", "response_time": 5},
-            ...     {"type": "help_request", "response_time": 3},
-            ...     {"type": "help_request", "response_time": 4}
-            ... ]
-            >>> norms = detector.detect_emergent_norms(interactions)
-
-        """
-        norms: list[EmergentProperty] = []
-
-        if not team_interactions:
-            return norms
-
-        # Detect response time norms
-        response_times = [
-            i.get("response_time", 0) for i in team_interactions if "response_time" in i
-        ]
-
-        if len(response_times) >= 3:
-            avg_response = sum(response_times) / len(response_times)
-            consistency = self._calculate_consistency(response_times)
-
-            if consistency > 0.7:  # High consistency indicates norm
-                norm = EmergentProperty(
-                    property_type="norm",
-                    description=f"Response time norm emerged: ~{avg_response:.1f} minutes",
-                    confidence=consistency,
-                    evidence=[{"response_times": response_times}],
-                    components_involved=["ai_agent", "human_user"],
-                )
-                norms.append(norm)
-
-        # Detect communication style norms
-        communication_patterns = self._analyze_communication_patterns(team_interactions)
-        if communication_patterns:
-            for pattern_name, pattern_data in communication_patterns.items():
-                if pattern_data["frequency"] > 0.6:  # Appears in >60% of interactions
-                    norm = EmergentProperty(
-                        property_type="norm",
-                        description=f"Communication pattern emerged: {pattern_name}",
-                        confidence=pattern_data["frequency"],
-                        evidence=[pattern_data],
-                        components_involved=["communication_style"],
-                    )
-                    norms.append(norm)
-
-        self.detected_properties.extend(norms)
-        return norms
-
-    def measure_emergence(self, baseline: dict[str, Any], current: dict[str, Any]) -> float:
-        """Quantify emergence by comparing baseline to current state
-
-        Measures how much new system-level properties have emerged that
-        weren't present in the baseline state.
-
-        Args:
-            baseline: Initial system state metrics
-            current: Current system state metrics
-
-        Returns:
-            Emergence score (0.0-1.0), where:
-            - 0.0: No emergence (system unchanged)
-            - 0.5: Moderate emergence (some new properties)
-            - 1.0: High emergence (significant new system capabilities)
-
-        Example:
-            >>> baseline = {"trust": 0.3, "interactions": 10}
-            >>> current = {"trust": 0.8, "interactions": 50, "patterns": 5}
-            >>> score = detector.measure_emergence(baseline, current)
-
-        """
-        emergence_score = 0.0
-        max_score = 0.0
-
-        # Measure growth in key metrics
-        if "trust" in baseline and "trust" in current:
-            trust_growth = (current["trust"] - baseline["trust"]) / max(baseline["trust"], 0.1)
-            emergence_score += min(trust_growth, 1.0) * 0.3
-            max_score += 0.3
-
-        # Measure new capabilities
-        baseline_keys = set(baseline.keys())
-        current_keys = set(current.keys())
-        new_capabilities = current_keys - baseline_keys
-
-        if new_capabilities:
-            capability_score = len(new_capabilities) / max(len(baseline_keys), 1)
-            emergence_score += min(capability_score, 1.0) * 0.3
-            max_score += 0.3
-
-        # Measure interaction complexity growth
-        if "interactions" in baseline and "interactions" in current:
-            if baseline["interactions"] > 0:
-                interaction_ratio = current["interactions"] / baseline["interactions"]
-                complexity_score = min((interaction_ratio - 1.0) / 4.0, 1.0)  # Normalize
-                emergence_score += complexity_score * 0.2
-                max_score += 0.2
-
-        # Measure pattern development
-        if "shared_patterns" in current:
-            pattern_score = min(current["shared_patterns"] / 10.0, 1.0)
-            emergence_score += pattern_score * 0.2
-            max_score += 0.2
-
-        # Normalize to 0-1 range
-        if max_score > 0:
-            return min(emergence_score / max_score, 1.0)
-        return 0.0
-
-    def detect_emergent_capabilities(
-        self,
-        historical_states: list[dict[str, Any]],
-    ) -> list[EmergentProperty]:
-        """Detect new capabilities that emerged over time
-
-        Analyzes historical system states to identify capabilities that:
-        1. Weren't present initially
-        2. Emerged through system evolution
-        3. Enable new behaviors
-
-        Args:
-            historical_states: List of system states over time
-
-        Returns:
-            List of emergent capabilities detected
-
-        """
-        if len(historical_states) < 2:
-            return []
-
-        capabilities: list[EmergentProperty] = []
-        initial_state = historical_states[0]
-
-        # Track capability development
-        for state in historical_states[1:]:
-            new_keys = set(state.keys()) - set(initial_state.keys())
-
-            for key in new_keys:
-                capability = EmergentProperty(
-                    property_type="capability",
-                    description=f"New capability emerged: {key}",
-                    confidence=0.8,
-                    evidence=[{"state": state, "timestamp": state.get("timestamp")}],
-                    components_involved=["system"],
-                )
-                capabilities.append(capability)
-
-        self.detected_properties.extend(capabilities)
-        return capabilities
-
-    def _calculate_consistency(self, values: list[float]) -> float:
-        """Calculate consistency of a set of values (0.0-1.0)
-
-        Uses coefficient of variation: lower variation = higher consistency
-        """
-        if not values or len(values) < 2:
-            return 0.0
-
-        mean = sum(values) / len(values)
-        if mean == 0:
-            return 0.0
-
-        variance = sum((x - mean) ** 2 for x in values) / len(values)
-        std_dev = variance**0.5
-        cv = std_dev / mean  # Coefficient of variation
-
-        # Convert to consistency score (inverse of variation)
-        consistency: float = max(0.0, 1.0 - min(cv, 1.0))
-        return consistency
-
-    def _analyze_communication_patterns(
-        self,
-        interactions: list[dict[str, Any]],
-    ) -> dict[str, dict[str, Any]]:
-        """Analyze communication patterns in interactions
-
-        Returns dict of pattern_name -> {frequency, examples}
-        """
-        patterns: dict[str, dict[str, Any]] = {}
-        total_interactions = len(interactions)
-
-        if total_interactions == 0:
-            return patterns
-
-        # Detect clarifying questions pattern
-        clarifying_count = sum(1 for i in interactions if i.get("type") == "clarifying_question")
-        if clarifying_count > 0:
-            patterns["clarifying_questions"] = {
-                "frequency": clarifying_count / total_interactions,
-                "count": clarifying_count,
-                "examples": [i for i in interactions if i.get("type") == "clarifying_question"][:3],
-            }
-
-        # Detect proactive suggestions pattern
-        proactive_count = sum(1 for i in interactions if i.get("type") == "proactive_suggestion")
-        if proactive_count > 0:
-            patterns["proactive_suggestions"] = {
-                "frequency": proactive_count / total_interactions,
-                "count": proactive_count,
-                "examples": [i for i in interactions if i.get("type") == "proactive_suggestion"][
-                    :3
-                ],
-            }
-
-        return patterns
-
-    def get_detected_properties(self, property_type: str | None = None) -> list[EmergentProperty]:
-        """Get all detected emergent properties, optionally filtered by type
-
-        Args:
-            property_type: Optional filter ("norm", "pattern", "behavior", "capability")
-
-        Returns:
-            List of emergent properties
-
-        """
-        if property_type:
-            return [p for p in self.detected_properties if p.property_type == property_type]
-        return self.detected_properties
-
-    def reset(self):
-        """Reset detector state"""
-        self.detected_properties = []
-        self.baseline_metrics = {}