attune-ai 2.0.0__py3-none-any.whl

attune/discovery.py

@@ -0,0 +1,306 @@
+"""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 attune.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)

attune/emergence.py

@@ -0,0 +1,306 @@
+"""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 = {}