empathy-framework 4.7.0__py3-none-any.whl → 4.7.1__py3-none-any.whl

patterns/README.md

@@ -0,0 +1,119 @@
+# Empathy Framework Pattern Catalog
+
+A catalog of reusable patterns extracted from the Empathy Framework codebase, organized for cross-domain transfer and Level 5 (Systems Thinking) capability development.
+
+## Purpose
+
+This catalog serves three goals:
+
+1. **Document existing patterns** - Capture what we've already built
+2. **Enable cross-domain transfer** - Apply patterns from reliability to trust, from observability to empathy
+3. **Accelerate Level 5 thinking** - Train the ability to recognize "this problem is like that solved problem"
+
+## Pattern Categories
+
+### Reliability Patterns
+*Source: `src/empathy_os/resilience/`*
+
+| Pattern | Level | Key Insight |
+|---------|-------|-------------|
+| [Circuit Breaker](reliability/circuit-breaker.md) | 4 | Predict failures, fail fast |
+| [Graceful Degradation](reliability/graceful-degradation.md) | 4 | Partial value beats total failure |
+| [Retry with Backoff](reliability/retry-with-backoff.md) | 3 | Transient failures are recoverable |
+
+### Observability Patterns
+*Source: `src/empathy_os/models/telemetry.py`, `src/empathy_os/resilience/health.py`*
+
+| Pattern | Level | Key Insight |
+|---------|-------|-------------|
+| [Health Monitoring](observability/health-monitoring.md) | 4 | Degraded predicts unhealthy |
+| [Telemetry Tracking](observability/telemetry-tracking.md) | 3-4 | Failures are learning data |
+
+### Cross-Domain Transfers
+*The Level 5 breakthrough patterns*
+
+| Transfer | From → To | Status | Key Insight |
+|----------|-----------|--------|-------------|
+| [Circuit Breaker → Trust](cross-domain/circuit-breaker-to-trust.md) | Reliability → Trust | **IMPLEMENTED** | Protect relationships like systems |
+| [Alerting → Empathy Levels](cross-domain/alerting-to-empathy-levels.md) | Observability → Empathy | Documented | Thresholds trigger level changes |
+| [Degradation → Conversation](cross-domain/graceful-degradation-to-conversation.md) | Reliability → UX | Documented | Degraded response beats failure |
+
+### Implemented Transfers
+
+| Transfer | Implementation | Guide |
+|----------|----------------|-------|
+| Circuit Breaker → Trust | [`src/empathy_os/trust/`](../src/empathy_os/trust/) | [Trust Circuit Breaker Guide](../docs/guides/trust-circuit-breaker.md) |
+
+## Capability Level Reference
+
+| Level | Name | Pattern Characteristic |
+|-------|------|----------------------|
+| 1 | Reactive | Respond to explicit requests |
+| 2 | Guided | Follow established patterns |
+| 3 | Proactive | Anticipate immediate needs |
+| 4 | Anticipatory | Predict future needs (30-90 days) |
+| 5 | Systems | Transfer patterns across domains |
+
+## How to Use This Catalog
+
+### For Developers
+1. When facing a new problem, search for similar patterns
+2. Check cross-domain transfers for non-obvious solutions
+3. Contribute new patterns following the template
+
+### For AI Systems
+1. Reference patterns when solving problems
+2. Propose cross-domain transfers when patterns match
+3. Track pattern usage for learning
+
+### For Architects
+1. Ensure new features follow established patterns
+2. Identify opportunities for pattern consolidation
+3. Propose new cross-domain transfers
+
+## Pattern Template
+
+```markdown
+# Pattern Name
+
+**Source Domain:** Where this pattern originated
+**Location in Codebase:** File paths
+**Level:** Capability level (1-5)
+
+## Overview
+What problem does this solve?
+
+## Implementation
+Code examples from actual codebase
+
+## Key Insight
+The one thing to remember
+
+## Cross-Domain Transfer Potential
+Where else could this apply?
+```
+
+## Contributing
+
+1. Identify a pattern in the codebase
+2. Document using the template above
+3. Look for cross-domain transfer opportunities
+4. Add to the appropriate category
+
+## Metrics
+
+Track pattern catalog health:
+- Patterns documented: 5
+- Cross-domain transfers: 3 (1 implemented)
+- Implementations: 1 (Trust Circuit Breaker)
+- Coverage of codebase: ~40%
+- Last updated: 2025-12-28
+
+## Documentation
+
+- [Pattern Catalog Guide](../docs/guides/pattern-catalog.md) - How to use and contribute to the catalog
+- [Trust Circuit Breaker Guide](../docs/guides/trust-circuit-breaker.md) - Detailed guide for the implemented transfer
+
+---
+
+*This catalog is a key component of reaching Level 5 (Systems Thinking) capability.*

patterns/__init__.py

@@ -0,0 +1,95 @@
+"""Wizard Factory Pattern Library.
+
+This package provides a comprehensive pattern library for creating wizards
+in the Empathy Framework. Patterns are extracted from 78 existing wizards
+and encoded as Pydantic models for type safety and code generation.
+
+**Pattern Categories:**
+- Structural: Overall wizard flow and architecture
+- Input: Data collection patterns
+- Validation: Data validation and approval patterns
+- Behavior: Wizard behavior and capabilities
+- Empathy: User experience and empathy patterns
+
+**Usage:**
+    from patterns import get_pattern_registry, LinearFlowPattern
+
+    # Get pattern registry
+    registry = get_pattern_registry()
+
+    # Search for patterns
+    patterns = registry.search("linear")
+
+    # Get pattern by ID
+    pattern = registry.get("linear_flow")
+
+    # Generate code from pattern
+    code = pattern.generate_code()
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .behavior import (
+                       AIEnhancementPattern,
+                       FixApplicationPattern,
+                       PredictionPattern,
+                       RiskAssessmentPattern,
+                       RiskLevel,
+)
+from .core import BasePattern, CodeGeneratorMixin, PatternCategory, ValidationMixin
+from .empathy import EducationalBannerPattern, EmpathyLevelPattern, UserGuidancePattern
+from .input import (
+                       CodeAnalysisPattern,
+                       ContextBasedPattern,
+                       FieldDefinition,
+                       StructuredFieldsPattern,
+)
+from .registry import PatternRegistry, get_pattern_registry, load_patterns
+from .structural import (
+                       LinearFlowPattern,
+                       PhaseConfig,
+                       PhasedProcessingPattern,
+                       SessionBasedPattern,
+                       StepConfig,
+)
+from .validation import ApprovalPattern, ConfigValidationPattern, StepValidationPattern
+
+__all__ = [
+    # Core
+    "BasePattern",
+    "PatternCategory",
+    "CodeGeneratorMixin",
+    "ValidationMixin",
+    # Structural
+    "StepConfig",
+    "LinearFlowPattern",
+    "PhaseConfig",
+    "PhasedProcessingPattern",
+    "SessionBasedPattern",
+    # Input
+    "FieldDefinition",
+    "StructuredFieldsPattern",
+    "CodeAnalysisPattern",
+    "ContextBasedPattern",
+    # Validation
+    "ConfigValidationPattern",
+    "StepValidationPattern",
+    "ApprovalPattern",
+    # Behavior
+    "RiskLevel",
+    "RiskAssessmentPattern",
+    "AIEnhancementPattern",
+    "PredictionPattern",
+    "FixApplicationPattern",
+    # Empathy
+    "EmpathyLevelPattern",
+    "EducationalBannerPattern",
+    "UserGuidancePattern",
+    # Registry
+    "PatternRegistry",
+    "get_pattern_registry",
+    "load_patterns",
+]
+
+__version__ = "1.0.0"

patterns/behavior.py

@@ -0,0 +1,298 @@
+"""Behavior patterns for wizard capabilities.
+
+Behavior patterns define what wizards can do beyond basic data collection:
+- Risk Assessment: Level 4 Anticipatory risk analysis
+- AI Enhancement: Improve user input with AI
+- Prediction: Predict future issues (Level 4)
+- Fix Application: Automatically fix detected issues
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from .core import BasePattern, CodeGeneratorMixin, PatternCategory
+
+
+class RiskLevel(BaseModel):
+    """Definition of a risk level."""
+
+    name: str = Field(..., description="Risk level name (e.g., 'critical', 'high')")
+    threshold: int = Field(..., description="Issue count threshold for this level", ge=0)
+    alert_message: str = Field(..., description="Alert message when threshold exceeded")
+
+
+class RiskAssessmentPattern(BasePattern, CodeGeneratorMixin):
+    """Level 4 Anticipatory risk assessment pattern.
+
+    **Description:**
+    Wizards that analyze issues and predict which ones will cause problems.
+    This implements Level 4 Anticipatory Empathy by forecasting future failures.
+
+    **Usage:** 16 wizards (all coach wizards)
+    **Reusability:** 0.8
+
+    **Risk Levels:**
+    - CRITICAL: Will cause production failures (>0 critical issues)
+    - HIGH: High probability of bugs (>5 high-risk issues)
+    - MEDIUM: Moderate concern (>20 medium issues)
+    - LOW: Minor issues
+
+    **Output:**
+    {
+        "alert_level": "CRITICAL",
+        "by_risk_level": {"critical": 5, "high": 12, "medium": 8},
+        "predictions": [...],
+        "recommendations": [...],
+    }
+    """
+
+    category: Literal[PatternCategory.BEHAVIOR] = PatternCategory.BEHAVIOR
+    risk_levels: list[RiskLevel] = Field(
+        default_factory=lambda: [
+            RiskLevel(
+                name="critical",
+                threshold=1,
+                alert_message="Critical issues detected - production failure likely",
+            ),
+            RiskLevel(
+                name="high",
+                threshold=5,
+                alert_message="High-risk issues accumulating - bugs probable",
+            ),
+            RiskLevel(
+                name="medium",
+                threshold=20,
+                alert_message="Medium issues detected - quality degrading",
+            ),
+        ],
+        description="Risk level definitions with thresholds",
+    )
+
+    def generate_code(self) -> str:
+        """Generate risk assessment code."""
+        return '''
+class RiskAnalyzer:
+    """Analyze issues for risk levels"""
+
+    def __init__(self):
+        self.risk_levels = ["critical", "high", "medium", "low"]
+
+    def analyze(self, issues: list) -> dict[str, Any]:
+        """Analyze issues and assess risk.
+
+        Args:
+            issues: List of issues to analyze
+
+        Returns:
+            Risk assessment with alert level and breakdown
+        """
+        # Count by risk level
+        by_level = {level: 0 for level in self.risk_levels}
+
+        for issue in issues:
+            severity = issue.get("severity", "low")
+            if severity in by_level:
+                by_level[severity] += 1
+
+        # Determine alert level
+        alert_level = self._determine_alert_level(by_level)
+
+        return {
+            "alert_level": alert_level,
+            "by_risk_level": by_level,
+            "total_issues": len(issues),
+        }
+
+    def _determine_alert_level(self, by_level: dict[str, int]) -> str:
+        """Determine overall alert level"""
+        if by_level["critical"] > 0:
+            return "CRITICAL"
+        elif by_level["high"] > 5:
+            return "HIGH"
+        elif by_level["medium"] > 20:
+            return "MEDIUM"
+        else:
+            return "LOW"
+'''
+
+
+class AIEnhancementPattern(BasePattern, CodeGeneratorMixin):
+    """AI text enhancement pattern.
+
+    **Description:**
+    Wizards that use AI to improve user-provided text. Common in healthcare
+    wizards where users provide rough notes and AI enhances them with:
+    - Professional medical terminology
+    - Proper formatting
+    - Clarity improvements
+    - Grammar/spelling fixes
+
+    **Usage:** 16 wizards (all healthcare wizards)
+    **Reusability:** 0.7
+
+    **Endpoint:**
+    POST /{wizard_id}/enhance
+    Body: {"text": "...", "field": "chief_complaint"}
+
+    **Enhancement Guidelines:**
+    - Preserve original meaning
+    - Use domain-appropriate terminology
+    - Maintain professional tone
+    - Follow documentation standards
+    """
+
+    category: Literal[PatternCategory.BEHAVIOR] = PatternCategory.BEHAVIOR
+    enhancement_guidelines: list[str] = Field(
+        default_factory=lambda: [
+            "Use appropriate clinical terminology",
+            "Clear and concise language",
+            "Maintain professional tone",
+            "Preserve all key information",
+            "Follow documentation standards",
+        ],
+        description="Guidelines for AI enhancement",
+    )
+
+    def generate_code(self) -> str:
+        """Generate AI enhancement endpoint."""
+        guidelines = "\n".join(f"- {g}" for g in self.enhancement_guidelines)
+
+        return f'''
+@router.post("/{{wizard_id}}/enhance")
+async def enhance_text(wizard_id: str, text_data: dict[str, Any]):
+    """Enhance user text with AI
+
+    Args:
+        wizard_id: Wizard session ID
+        text_data: {{"text": "...", "field": "field_name"}}
+
+    Returns:
+        Enhanced text
+    """
+    session = await _get_session(wizard_id)
+    if not session:
+        raise HTTPException(404, "Wizard session not found")
+
+    original_text = text_data.get("text", "")
+    field_name = text_data.get("field", "text")
+
+    if not original_text:
+        raise HTTPException(422, "No text provided for enhancement")
+
+    # Get chat service
+    chat_service = get_service("chat")
+
+    # Enhancement prompt
+    prompt = f"""
+You are assisting with documentation. Please enhance the following text:
+
+Field: {{field_name}}
+Original: {{original_text}}
+
+Enhancement guidelines:
+{guidelines}
+
+Enhanced text:"""
+
+    response = await chat_service.chat(
+        message=prompt,
+        conversation_id=f"enhance_{{wizard_id}}",
+        context={{"wizard_id": wizard_id, "field": field_name}},
+    )
+
+    return {{
+        "original_text": original_text,
+        "enhanced_text": response.get("response", original_text),
+        "field": field_name,
+    }}
+'''
+
+
+class PredictionPattern(BasePattern):
+    """Level 4 Anticipatory prediction pattern.
+
+    **Description:**
+    Wizards that predict future issues before they occur. This implements
+    Level 4 Anticipatory Empathy by forecasting problems.
+
+    **Usage:** 16 wizards (all coach wizards)
+    **Reusability:** 0.8
+
+    **Prediction Types:**
+    - production_failure_risk: Critical issues → runtime errors
+    - bug_density_increase: High-risk accumulation → more bugs
+    - technical_debt_accumulation: Code quality degradation
+    - test_maintenance_burden: Flaky tests → maintenance overhead
+
+    **Signature:**
+    def predict_future_issues(
+        self,
+        code: str,
+        file_path: str,
+        project_context: dict,
+        timeline_days: int = 90
+    ) -> list[WizardPrediction]
+    """
+
+    category: Literal[PatternCategory.BEHAVIOR] = PatternCategory.BEHAVIOR
+    timeline_days: int = Field(
+        default=90,
+        description="Prediction timeline in days",
+        ge=1,
+        le=365,
+    )
+    prediction_types: list[str] = Field(
+        default_factory=lambda: [
+            "production_failure_risk",
+            "bug_density_increase",
+            "technical_debt_accumulation",
+        ],
+        description="Types of predictions this wizard makes",
+    )
+
+
+class FixApplicationPattern(BasePattern):
+    """Automatic fix application pattern.
+
+    **Description:**
+    Wizards that can automatically fix detected issues. Issues are grouped
+    into auto-fixable and manual categories.
+
+    **Usage:** 8 wizards (AI wizards with code modification)
+    **Reusability:** 0.75
+
+    **Workflow:**
+    1. Detect issues
+    2. Group by fixability (auto vs manual)
+    3. Apply auto-fixes if enabled
+    4. Track success/failure per fix
+
+    **Auto-Fixable Examples:**
+    - Linting issues (ruff --fix)
+    - Import sorting (isort)
+    - Code formatting (black)
+    - Simple refactorings
+
+    **Manual-Only Examples:**
+    - Architecture changes
+    - Logic bugs
+    - Security vulnerabilities
+    """
+
+    category: Literal[PatternCategory.BEHAVIOR] = PatternCategory.BEHAVIOR
+    auto_fix_enabled: bool = Field(
+        default=False,
+        description="Whether auto-fix is enabled by default",
+    )
+    dry_run_by_default: bool = Field(
+        default=True,
+        description="Whether to dry-run fixes before applying",
+    )
+    supported_fix_types: list[str] = Field(
+        default_factory=lambda: ["lint", "format", "import", "refactor"],
+        description="Types of fixes this wizard supports",
+    )