empathy-framework 3.2.3__py3-none-any.whl → 3.8.2__py3-none-any.whl

workflow_patterns/behavior.py

@@ -0,0 +1,249 @@
+"""Behavioral workflow patterns.
+
+Patterns for conditional execution and dynamic behavior.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from typing import Any
+
+from .core import CodeSection, PatternCategory, WorkflowComplexity, WorkflowPattern
+
+
+class ConditionalTierPattern(WorkflowPattern):
+    """Dynamic tier routing based on complexity or conditions.
+
+    Use for: Cost optimization by downgrading/skipping expensive stages.
+    Examples: bug-predict (skip premium if low risk), code-review (conditional architect review).
+    """
+
+    id: str = "conditional-tier"
+    name: str = "Conditional Tier Routing"
+    category: PatternCategory = PatternCategory.BEHAVIOR
+    description: str = "Dynamically adjust model tiers based on conditions"
+    complexity: WorkflowComplexity = WorkflowComplexity.MODERATE
+    use_cases: list[str] = [
+        "Cost optimization",
+        "Conditional premium tier usage",
+        "Complexity-based routing",
+    ]
+    examples: list[str] = ["bug-predict", "code-review", "pr-review"]
+    requires: list[str] = ["multi-stage"]
+    risk_weight: float = 3.0
+
+    def generate_code_sections(self, context: dict[str, Any]) -> list[CodeSection]:
+        """Generate code for conditional tier routing."""
+        threshold_param = context.get("threshold_param", "complexity_threshold")
+        threshold_default = context.get("threshold_default", "0.7")
+        metric_name = context.get("metric_name", "complexity_score")
+
+        return [
+            CodeSection(
+                location="init_method",
+                code=f"""        self.{threshold_param} = {threshold_param} if {threshold_param} is not None else {threshold_default}
+        self._{metric_name}: float = 0.0""",
+                priority=1,
+            ),
+            CodeSection(
+                location="methods",
+                code=f'''    def should_skip_stage(self, stage_name: str, input_data: Any) -> tuple[bool, str | None]:
+        """Conditionally downgrade or skip stages based on {metric_name}.
+
+        Args:
+            stage_name: Name of the stage to check
+            input_data: Current workflow data
+
+        Returns:
+            Tuple of (should_skip, reason)
+
+        """
+        # Example: Downgrade premium stage if metric below threshold
+        if stage_name == "recommend" or stage_name == "architect_review":
+            if self._{metric_name} < self.{threshold_param}:
+                # Downgrade to CAPABLE instead of skipping
+                self.tier_map[stage_name] = ModelTier.CAPABLE
+                logger.info(f"Downgraded {{stage_name}} to CAPABLE ({metric_name}: {{self._{metric_name}:.2f}})")
+                return False, None
+        return False, None''',
+                priority=2,
+            ),
+        ]
+
+
+class ConfigDrivenPattern(WorkflowPattern):
+    """Load configuration from empathy.config.yml.
+
+    Use for: Configurable thresholds, options, and behavior.
+    Examples: bug-predict (risk threshold), health-check (check toggles).
+    """
+
+    id: str = "config-driven"
+    name: str = "Configuration-Driven Workflow"
+    category: PatternCategory = PatternCategory.BEHAVIOR
+    description: str = "Loads settings from empathy.config.yml"
+    complexity: WorkflowComplexity = WorkflowComplexity.SIMPLE
+    use_cases: list[str] = [
+        "Configurable thresholds",
+        "User-customizable behavior",
+        "Environment-specific settings",
+    ]
+    examples: list[str] = ["bug-predict", "health-check", "security-audit"]
+    risk_weight: float = 1.5
+
+    def generate_code_sections(self, context: dict[str, Any]) -> list[CodeSection]:
+        """Generate code for configuration loading."""
+        workflow_name = context.get("workflow_name", "my-workflow")
+        config_key = workflow_name.replace("-", "_")
+        config_params = context.get(
+            "config_params",
+            {
+                "threshold": 0.7,
+                "enabled": True,
+            },
+        )
+
+        # Generate defaults dict
+        defaults_code = "    defaults = {\n"
+        for key, value in config_params.items():
+            if isinstance(value, str):
+                defaults_code += f'        "{key}": "{value}",\n'
+            else:
+                defaults_code += f'        "{key}": {value},\n'
+        defaults_code += "    }"
+
+        # Generate config loading
+        return [
+            CodeSection(
+                location="imports",
+                code="import yaml\nfrom pathlib import Path",
+                priority=1,
+            ),
+            CodeSection(
+                location="helper_functions",
+                code=f'''def _load_{config_key}_config() -> dict:
+    """Load {config_key} configuration from empathy.config.yml.
+
+    Returns:
+        Dict with {config_key} settings, or defaults if not found.
+
+    """
+{defaults_code}
+
+    config_paths = [
+        Path("empathy.config.yml"),
+        Path("empathy.config.yaml"),
+        Path(".empathy.yml"),
+        Path(".empathy.yaml"),
+    ]
+
+    for config_path in config_paths:
+        if config_path.exists():
+            try:
+                with open(config_path) as f:
+                    config = yaml.safe_load(f)
+                    if config and "{config_key}" in config:
+                        return {{**defaults, **config["{config_key}"]}}
+            except (yaml.YAMLError, OSError):
+                pass
+
+    return defaults''',
+                priority=1,
+            ),
+            CodeSection(
+                location="init_method",
+                code=f"""        # Load configuration
+        self._config = _load_{config_key}_config()""",
+                priority=1,
+            ),
+        ]
+
+
+class CodeScannerPattern(WorkflowPattern):
+    """File scanning and analysis capabilities.
+
+    Use for: Code analysis workflows that scan files.
+    Examples: bug-predict, security-audit, test-gen.
+    """
+
+    id: str = "code-scanner"
+    name: str = "Code Scanner"
+    category: PatternCategory = PatternCategory.BEHAVIOR
+    description: str = "Scan and analyze code files with pattern matching"
+    complexity: WorkflowComplexity = WorkflowComplexity.MODERATE
+    use_cases: list[str] = [
+        "Bug detection",
+        "Security scanning",
+        "Code analysis",
+    ]
+    examples: list[str] = ["bug-predict", "security-audit"]
+    risk_weight: float = 2.0
+
+    def generate_code_sections(self, context: dict[str, Any]) -> list[CodeSection]:
+        """Generate code for file scanning."""
+        scan_pattern = context.get("scan_pattern", "*.py")
+
+        return [
+            CodeSection(
+                location="imports",
+                code="import fnmatch\nfrom pathlib import Path",
+                priority=1,
+            ),
+            CodeSection(
+                location="helper_functions",
+                code=f'''def _should_exclude_file(file_path: str, exclude_patterns: list[str]) -> bool:
+    """Check if a file should be excluded based on glob patterns.
+
+    Args:
+        file_path: Path to the file
+        exclude_patterns: List of glob patterns (e.g., "**/test_*.py")
+
+    Returns:
+        True if the file matches any exclusion pattern.
+
+    """
+    for pattern in exclude_patterns:
+        if "**" in pattern:
+            parts = pattern.split("**")
+            if len(parts) == 2:
+                prefix, suffix = parts
+                if prefix and not file_path.startswith(prefix.rstrip("/")):
+                    continue
+                if suffix and fnmatch.fnmatch(file_path, f"*{{suffix}}"):
+                    return True
+        elif fnmatch.fnmatch(file_path, pattern) or fnmatch.fnmatch(
+            Path(file_path).name,
+            pattern,
+        ):
+            return True
+    return False
+
+
+def _scan_files(
+    root_dir: str = ".",
+    pattern: str = "{scan_pattern}",
+    exclude: list[str] | None = None,
+) -> list[Path]:
+    """Scan directory for files matching pattern.
+
+    Args:
+        root_dir: Root directory to scan
+        pattern: Glob pattern for files
+        exclude: Exclusion patterns
+
+    Returns:
+        List of matching file paths
+
+    """
+    exclude = exclude or []
+    root = Path(root_dir)
+    files = []
+
+    for file_path in root.rglob(pattern):
+        if file_path.is_file() and not _should_exclude_file(str(file_path), exclude):
+            files.append(file_path)
+
+    return files''',
+                priority=1,
+            ),
+        ]

workflow_patterns/core.py

@@ -0,0 +1,76 @@
+"""Core workflow pattern definitions.
+
+Defines Pydantic models for workflow patterns extracted from existing workflows.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class PatternCategory(Enum):
+    """Categories for workflow patterns."""
+
+    STRUCTURAL = "structural"  # How workflow is organized
+    TIER = "tier"  # Tier routing strategies
+    INTEGRATION = "integration"  # External integrations
+    OUTPUT = "output"  # Output formatting
+    BEHAVIOR = "behavior"  # Behavioral patterns
+
+
+class WorkflowComplexity(Enum):
+    """Workflow complexity levels."""
+
+    SIMPLE = "simple"  # Single stage, no conditions
+    MODERATE = "moderate"  # Multiple stages, some conditions
+    COMPLEX = "complex"  # Multiple stages, conditional routing, crews
+
+
+@dataclass
+class CodeSection:
+    """A section of code to be generated."""
+
+    location: str  # Where in the file (e.g., "imports", "class_body", "methods")
+    code: str  # The code content
+    priority: int = 0  # Higher priority sections are placed first
+
+
+class WorkflowPattern(BaseModel):
+    """Base model for workflow patterns."""
+
+    id: str = Field(..., description="Unique pattern identifier")
+    name: str = Field(..., description="Human-readable pattern name")
+    category: PatternCategory = Field(..., description="Pattern category")
+    description: str = Field(..., description="Pattern description")
+    complexity: WorkflowComplexity = Field(..., description="Pattern complexity")
+    use_cases: list[str] = Field(default_factory=list, description="When to use this pattern")
+    examples: list[str] = Field(
+        default_factory=list, description="Example workflows using this pattern"
+    )
+    conflicts_with: list[str] = Field(default_factory=list, description="Incompatible pattern IDs")
+    requires: list[str] = Field(default_factory=list, description="Required pattern IDs")
+    risk_weight: float = Field(
+        default=1.0, ge=0.0, le=5.0, description="Risk factor for testing (1=low, 5=high)"
+    )
+
+    def generate_code_sections(self, context: dict[str, Any]) -> list[CodeSection]:
+        """Generate code sections for this pattern.
+
+        Args:
+            context: Context dictionary with workflow metadata
+
+        Returns:
+            List of CodeSection objects to be merged
+
+        """
+        raise NotImplementedError("Subclasses must implement generate_code_sections")
+
+    class Config:
+        """Pydantic config."""
+
+        use_enum_values = True

workflow_patterns/output.py

@@ -0,0 +1,99 @@
+"""Output formatting patterns.
+
+Patterns for structured workflow results.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from typing import Any
+
+from .core import CodeSection, PatternCategory, WorkflowComplexity, WorkflowPattern
+
+
+class ResultDataclassPattern(WorkflowPattern):
+    """Structured output with dataclass.
+
+    Use for: Type-safe, structured workflow results.
+    Examples: health-check, release-prep.
+    """
+
+    id: str = "result-dataclass"
+    name: str = "Result Dataclass"
+    category: PatternCategory = PatternCategory.OUTPUT
+    description: str = "Structured output format with dataclass"
+    complexity: WorkflowComplexity = WorkflowComplexity.SIMPLE
+    use_cases: list[str] = [
+        "Type-safe results",
+        "Structured output",
+        "API integration",
+    ]
+    examples: list[str] = ["health-check", "release-prep"]
+    risk_weight: float = 1.0
+
+    def generate_code_sections(self, context: dict[str, Any]) -> list[CodeSection]:
+        """Generate code for result dataclass."""
+        workflow_name = context.get("workflow_name", "my-workflow")
+        class_name = context.get("class_name", "MyWorkflow")
+        result_class_name = f"{class_name}Result"
+
+        # Get custom fields from context
+        custom_fields = context.get("result_fields", [])
+
+        # Generate custom fields code
+        custom_fields_code = ""
+        if custom_fields:
+            for field in custom_fields:
+                field_name = field.get("name", "custom_field")
+                field_type = field.get("type", "Any")
+                field_desc = field.get("description", "Custom field")
+                custom_fields_code += f"    {field_name}: {field_type}  # {field_desc}\n"
+
+        return [
+            CodeSection(
+                location="imports",
+                code="from dataclasses import dataclass, field",
+                priority=1,
+            ),
+            CodeSection(
+                location="dataclasses",
+                code=f'''@dataclass
+class {result_class_name}:
+    """Result from {class_name} execution."""
+
+    success: bool
+    {custom_fields_code if custom_fields_code else "    # Add custom fields here"}duration_seconds: float
+    cost: float
+    metadata: dict = field(default_factory=dict)''',
+                priority=1,
+            ),
+            CodeSection(
+                location="methods",
+                code=f'''    def _create_result(
+        self,
+        success: bool,
+        duration: float,
+        cost: float,
+        **kwargs: Any,
+    ) -> {result_class_name}:
+        """Create structured result.
+
+        Args:
+            success: Whether workflow succeeded
+            duration: Execution duration in seconds
+            cost: Total cost in USD
+            **kwargs: Additional result fields
+
+        Returns:
+            {result_class_name} instance
+
+        """
+        return {result_class_name}(
+            success=success,
+            duration_seconds=duration,
+            cost=cost,
+            **kwargs,
+        )''',
+                priority=2,
+            ),
+        ]

workflow_patterns/registry.py

@@ -0,0 +1,255 @@
+"""Workflow Pattern Registry.
+
+Manages workflow patterns and provides pattern recommendation.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from typing import Any
+
+from .behavior import CodeScannerPattern, ConditionalTierPattern, ConfigDrivenPattern
+from .core import PatternCategory, WorkflowComplexity, WorkflowPattern
+from .output import ResultDataclassPattern
+from .structural import CrewBasedPattern, MultiStagePattern, SingleStagePattern
+
+
+class WorkflowPatternRegistry:
+    """Registry for workflow patterns."""
+
+    def __init__(self):
+        """Initialize pattern registry."""
+        self._patterns: dict[str, WorkflowPattern] = {}
+        self._register_default_patterns()
+
+    def _register_default_patterns(self) -> None:
+        """Register all default patterns."""
+        patterns = [
+            # Structural
+            SingleStagePattern(),
+            MultiStagePattern(),
+            CrewBasedPattern(),
+            # Behavioral
+            ConditionalTierPattern(),
+            ConfigDrivenPattern(),
+            CodeScannerPattern(),
+            # Output
+            ResultDataclassPattern(),
+        ]
+
+        for pattern in patterns:
+            self._patterns[pattern.id] = pattern
+
+    def register(self, pattern: WorkflowPattern) -> None:
+        """Register a new pattern.
+
+        Args:
+            pattern: Pattern to register
+
+        """
+        self._patterns[pattern.id] = pattern
+
+    def get(self, pattern_id: str) -> WorkflowPattern | None:
+        """Get pattern by ID.
+
+        Args:
+            pattern_id: Pattern identifier
+
+        Returns:
+            WorkflowPattern or None if not found
+
+        """
+        return self._patterns.get(pattern_id)
+
+    def list_all(self) -> list[WorkflowPattern]:
+        """List all registered patterns.
+
+        Returns:
+            List of all patterns
+
+        """
+        return list(self._patterns.values())
+
+    def list_by_category(self, category: PatternCategory) -> list[WorkflowPattern]:
+        """List patterns by category.
+
+        Args:
+            category: Pattern category
+
+        Returns:
+            List of patterns in category
+
+        """
+        return [p for p in self._patterns.values() if p.category == category]
+
+    def list_by_complexity(self, complexity: WorkflowComplexity) -> list[WorkflowPattern]:
+        """List patterns by complexity.
+
+        Args:
+            complexity: Complexity level
+
+        Returns:
+            List of patterns with specified complexity
+
+        """
+        return [p for p in self._patterns.values() if p.complexity == complexity]
+
+    def search(self, query: str) -> list[WorkflowPattern]:
+        """Search patterns by name or description.
+
+        Args:
+            query: Search query
+
+        Returns:
+            List of matching patterns
+
+        """
+        query_lower = query.lower()
+        results = []
+
+        for pattern in self._patterns.values():
+            if (
+                query_lower in pattern.name.lower()
+                or query_lower in pattern.description.lower()
+                or any(query_lower in uc.lower() for uc in pattern.use_cases)
+            ):
+                results.append(pattern)
+
+        return results
+
+    def recommend_for_workflow(
+        self,
+        workflow_type: str,
+        complexity: WorkflowComplexity | None = None,
+    ) -> list[WorkflowPattern]:
+        """Recommend patterns for a workflow type.
+
+        Args:
+            workflow_type: Type of workflow (e.g., "code-analysis", "multi-agent")
+            complexity: Desired complexity level
+
+        Returns:
+            List of recommended patterns
+
+        """
+        recommendations = []
+
+        # Type-based recommendations
+        type_map = {
+            "code-analysis": ["multi-stage", "code-scanner", "conditional-tier"],
+            "simple": ["single-stage"],
+            "multi-agent": ["crew-based", "result-dataclass"],
+            "configurable": ["config-driven", "multi-stage"],
+            "cost-optimized": ["conditional-tier", "multi-stage"],
+        }
+
+        pattern_ids = type_map.get(workflow_type.lower(), [])
+
+        # Get patterns
+        for pattern_id in pattern_ids:
+            pattern = self.get(pattern_id)
+            if pattern:
+                if complexity is None or pattern.complexity == complexity:
+                    recommendations.append(pattern)
+
+        # Always include progress tracking and telemetry (built-in)
+        # These are inherited from BaseWorkflow
+
+        return recommendations
+
+    def validate_pattern_combination(self, pattern_ids: list[str]) -> tuple[bool, str | None]:
+        """Validate that pattern IDs can be used together.
+
+        Args:
+            pattern_ids: List of pattern IDs to validate
+
+        Returns:
+            Tuple of (is_valid, error_message)
+
+        """
+        patterns = []
+        for pattern_id in pattern_ids:
+            pattern = self.get(pattern_id)
+            if not pattern:
+                return False, f"Unknown pattern: {pattern_id}"
+            patterns.append(pattern)
+
+        # Check for conflicts
+        for pattern in patterns:
+            for other_pattern in patterns:
+                if other_pattern.id in pattern.conflicts_with:
+                    return False, f"Conflict: {pattern.id} conflicts with {other_pattern.id}"
+
+        # Check for missing requirements
+        for pattern in patterns:
+            for required_id in pattern.requires:
+                if required_id not in pattern_ids:
+                    return False, f"{pattern.id} requires {required_id}"
+
+        return True, None
+
+    def get_total_risk_weight(self, pattern_ids: list[str]) -> float:
+        """Calculate total risk weight for pattern combination.
+
+        Args:
+            pattern_ids: List of pattern IDs
+
+        Returns:
+            Total risk weight
+
+        """
+        total = 0.0
+        for pattern_id in pattern_ids:
+            pattern = self.get(pattern_id)
+            if pattern:
+                total += pattern.risk_weight
+        return total
+
+    def generate_code_sections(
+        self,
+        pattern_ids: list[str],
+        context: dict[str, Any],
+    ) -> dict[str, list[Any]]:
+        """Generate all code sections from patterns.
+
+        Args:
+            pattern_ids: List of pattern IDs to use
+            context: Context dictionary for code generation
+
+        Returns:
+            Dict mapping location to list of CodeSection objects
+
+        """
+        from collections import defaultdict
+
+        sections_by_location = defaultdict(list)
+
+        for pattern_id in pattern_ids:
+            pattern = self.get(pattern_id)
+            if pattern:
+                sections = pattern.generate_code_sections(context)
+                for section in sections:
+                    sections_by_location[section.location].append(section)
+
+        # Sort sections by priority within each location
+        for location in sections_by_location:
+            sections_by_location[location].sort(key=lambda s: -s.priority)
+
+        return dict(sections_by_location)
+
+
+# Global registry instance
+_registry: WorkflowPatternRegistry | None = None
+
+
+def get_workflow_pattern_registry() -> WorkflowPatternRegistry:
+    """Get the global workflow pattern registry.
+
+    Returns:
+        WorkflowPatternRegistry instance
+
+    """
+    global _registry
+    if _registry is None:
+        _registry = WorkflowPatternRegistry()
+    return _registry