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

empathy_software_plugin/wizards/prompt_engineering_wizard.py

@@ -1,425 +0,0 @@
-"""Prompt Engineering Quality Wizard - Level 4 Anticipatory Empathy
-
-Alerts developers to prompt quality issues before they impact AI performance.
-
-In our experience developing AI Nurse Florence and the Empathy Framework,
-we learned that prompt quality degrades subtly over time. This wizard alerts
-you to drift patterns, context inefficiencies, and structural issues before
-they compound into major problems.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-import os
-import re
-import sys
-from typing import Any
-
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "..", "src"))
-
-from empathy_os.plugins import BaseWizard
-
-
-class PromptEngineeringWizard(BaseWizard):
-    """Level 4 Anticipatory: Analyzes prompt quality and alerts to degradation.
-
-    What This Wizard Learned From Experience:
-    - Prompts drift subtly as features evolve
-    - Context bloat reduces effectiveness over time
-    - Inconsistent structures across prompts create confusion
-    - Early detection prevents compounding quality issues
-    """
-
-    def __init__(self):
-        super().__init__(
-            name="Prompt Engineering Quality Wizard",
-            domain="software",
-            empathy_level=4,
-            category="ai_development",
-        )
-
-    def get_required_context(self) -> list[str]:
-        """Required context for prompt analysis"""
-        return [
-            "prompt_files",  # List of prompt template files
-            "project_path",  # Path to project
-            "ai_provider",  # openai, anthropic, etc. (optional)
-            "version_history",  # Git history (optional for drift detection)
-        ]
-
-    async def analyze(self, context: dict[str, Any]) -> dict[str, Any]:
-        """Analyze prompt quality and predict degradation patterns.
-
-        In our experience: Prompt quality issues compound quickly.
-        A small inconsistency today becomes a major refactor in weeks.
-        """
-        self.validate_context(context)
-
-        prompt_files = context["prompt_files"]
-        _project_path = context["project_path"]
-        version_history = context.get("version_history", [])
-
-        # Current issues (Levels 1-3)
-        issues = await self._analyze_prompt_quality(prompt_files)
-
-        # Level 4: Predict future problems
-        predictions = await self._predict_prompt_degradation(prompt_files, version_history, context)
-
-        # Generate recommendations
-        recommendations = self._generate_recommendations(issues, predictions)
-
-        # Extract patterns for cross-domain learning
-        patterns = self._extract_patterns(issues, predictions)
-
-        return {
-            "issues": issues,
-            "predictions": predictions,
-            "recommendations": recommendations,
-            "patterns": patterns,
-            "confidence": self._calculate_confidence(context),
-            "metadata": {
-                "wizard": self.name,
-                "empathy_level": self.empathy_level,
-                "prompts_analyzed": len(prompt_files),
-            },
-        }
-
-    async def _analyze_prompt_quality(self, prompt_files: list[str]) -> list[dict[str, Any]]:
-        """Analyze current prompt quality (Level 3 Proactive).
-
-        Checks for immediate issues that impact AI performance.
-        """
-        issues = []
-
-        for prompt_file in prompt_files:
-            # Read prompt content
-            try:
-                with open(prompt_file) as f:
-                    content = f.read()
-            except Exception as e:
-                issues.append(
-                    {
-                        "severity": "error",
-                        "type": "file_read_error",
-                        "file": prompt_file,
-                        "message": f"Could not read prompt file: {e}",
-                    },
-                )
-                continue
-
-            # Check prompt structure
-            if not self._has_clear_structure(content):
-                issues.append(
-                    {
-                        "severity": "warning",
-                        "type": "unclear_structure",
-                        "file": prompt_file,
-                        "message": (
-                            "Prompt lacks clear structure (role, task, context, constraints). "
-                            "In our experience, structured prompts perform more reliably."
-                        ),
-                        "suggestion": "Use sections: ## Role, ## Task, ## Context, ## Constraints",
-                    },
-                )
-
-            # Check for context bloat
-            if len(content) > 4000:  # Arbitrary threshold from experience
-                issues.append(
-                    {
-                        "severity": "warning",
-                        "type": "context_bloat",
-                        "file": prompt_file,
-                        "message": (
-                            f"Prompt is {len(content)} characters. "
-                            "Longer prompts often contain redundancy that reduces clarity."
-                        ),
-                        "suggestion": "Review for redundancy. Consider separating into base + context injection.",
-                    },
-                )
-
-            # Check for vague instructions
-            vague_patterns = [r"\bhelp\b", r"\btry to\b", r"\bmaybe\b", r"\bif possible\b"]
-            vague_found = []
-            for pattern in vague_patterns:
-                if re.search(pattern, content, re.IGNORECASE):
-                    vague_found.append(pattern.strip("\\b"))
-
-            if vague_found:
-                issues.append(
-                    {
-                        "severity": "info",
-                        "type": "vague_language",
-                        "file": prompt_file,
-                        "message": (
-                            f"Vague language detected: {', '.join(vague_found)}. "
-                            "Precise instructions yield more consistent results."
-                        ),
-                        "suggestion": "Use imperative verbs: 'Analyze', 'Extract', 'Generate'",
-                    },
-                )
-
-            # Check for missing examples
-            if not self._has_examples(content):
-                issues.append(
-                    {
-                        "severity": "info",
-                        "type": "missing_examples",
-                        "file": prompt_file,
-                        "message": (
-                            "No examples found. In our experience, few-shot examples "
-                            "significantly improve output quality."
-                        ),
-                        "suggestion": "Add 2-3 examples in <example> tags",
-                    },
-                )
-
-        return issues
-
-    async def _predict_prompt_degradation(
-        self,
-        prompt_files: list[str],
-        version_history: list[dict],
-        context: dict[str, Any],
-    ) -> list[dict[str, Any]]:
-        """Level 4 Anticipatory: Predict prompt quality degradation.
-
-        Experience-based insight: Prompts drift as codebases evolve.
-        Early alerts prevent compound degradation.
-        """
-        predictions = []
-
-        # Pattern 1: Prompt-code drift
-        if len(version_history) > 0:
-            prompt_changes = self._count_prompt_changes(version_history)
-            code_changes = self._count_code_changes(version_history)
-
-            if code_changes > prompt_changes * 3:
-                predictions.append(
-                    {
-                        "type": "prompt_code_drift",
-                        "alert": (
-                            "Code is evolving faster than prompts. "
-                            "In our experience, this leads to AI responses that become "
-                            "less relevant as the codebase changes. Alert: Review prompts "
-                            "to ensure they reflect current architecture."
-                        ),
-                        "probability": "high",
-                        "impact": "medium",
-                        "prevention_steps": [
-                            "Schedule quarterly prompt review",
-                            "Link prompt updates to major code refactors",
-                            "Add prompt validation tests",
-                            "Document prompt-code dependencies",
-                        ],
-                        "reasoning": (
-                            "Code evolution without corresponding prompt updates creates "
-                            "misalignment. We've seen this reduce AI effectiveness by 30-50%."
-                        ),
-                    },
-                )
-
-        # Pattern 2: Prompt sprawl
-        if len(prompt_files) > 10:
-            predictions.append(
-                {
-                    "type": "prompt_sprawl",
-                    "alert": (
-                        f"You have {len(prompt_files)} prompt files. "
-                        "In our experience, prompt count above 15 leads to maintenance burden. "
-                        "Alert: Consider consolidating with parameterized base prompts before "
-                        "this becomes unwieldy."
-                    ),
-                    "probability": "medium-high",
-                    "impact": "medium",
-                    "prevention_steps": [
-                        "Create base prompt templates",
-                        "Use variable injection for variations",
-                        "Implement prompt composition pattern",
-                        "Document prompt inheritance structure",
-                    ],
-                    "reasoning": (
-                        "Each additional prompt increases maintenance surface. "
-                        "We've found 3-5 base prompts with composition scales better than "
-                        "dozens of standalone prompts."
-                    ),
-                },
-            )
-
-        # Pattern 3: Missing version control
-        prompts_with_versions = sum(1 for f in prompt_files if self._has_version_marker(f))
-
-        if prompts_with_versions < len(prompt_files) * 0.5:
-            predictions.append(
-                {
-                    "type": "prompt_versioning_gap",
-                    "alert": (
-                        "Most prompts lack version markers. "
-                        "In our experience, unversioned prompts make debugging AI behavior "
-                        "extremely difficult. Alert: Implement versioning before issues arise."
-                    ),
-                    "probability": "high",
-                    "impact": "high",
-                    "prevention_steps": [
-                        "Add version markers to all prompts (e.g., v1.2.0)",
-                        "Log prompt version with each AI request",
-                        "Create prompt changelog",
-                        "Implement A/B testing framework for prompt changes",
-                    ],
-                    "reasoning": (
-                        "When AI behavior changes unexpectedly, version tracking is essential "
-                        "for debugging. We learned this the hard way."
-                    ),
-                },
-            )
-
-        # Pattern 4: Context window inefficiency
-        total_prompt_size = sum(self._estimate_token_count(f) for f in prompt_files)
-        avg_size = total_prompt_size / len(prompt_files) if prompt_files else 0
-
-        if avg_size > 2000:  # tokens
-            predictions.append(
-                {
-                    "type": "context_window_inefficiency",
-                    "alert": (
-                        f"Average prompt size ~{int(avg_size)} tokens. "
-                        "In our experience, prompts above 2000 tokens often contain "
-                        "redundancy that could be refactored. Alert: Review for efficiency "
-                        "before context costs compound."
-                    ),
-                    "probability": "medium",
-                    "impact": "medium",
-                    "prevention_steps": [
-                        "Extract common instructions to base template",
-                        "Use dynamic context injection (not static bloat)",
-                        "Implement prompt caching strategies",
-                        "Consider retrieval-augmented generation for large contexts",
-                    ],
-                    "reasoning": (
-                        "Token costs scale linearly with prompt size. We've reduced costs "
-                        "40-60% by refactoring bloated prompts."
-                    ),
-                },
-            )
-
-        return predictions
-
-    def _generate_recommendations(self, issues: list[dict], predictions: list[dict]) -> list[str]:
-        """Generate actionable recommendations"""
-        recommendations = []
-
-        # High-impact predictions first
-        high_impact = [p for p in predictions if p.get("impact") in ["high", "medium"]]
-        for pred in high_impact:
-            recommendations.append(f"[ALERT] {pred['alert']}")
-            recommendations.append("  Prevention steps:")
-            for step in pred["prevention_steps"][:3]:  # Top 3
-                recommendations.append(f"    - {step}")
-
-        # Critical issues
-        critical = [i for i in issues if i.get("severity") == "error"]
-        if critical:
-            recommendations.append(f"\n[CRITICAL] Fix {len(critical)} errors immediately")
-
-        # Quick wins
-        warnings = [i for i in issues if i.get("severity") == "warning"]
-        if len(warnings) > 3:
-            recommendations.append(
-                f"\n[QUICK WIN] Address {len(warnings)} warnings to improve prompt quality",
-            )
-
-        return recommendations
-
-    def _extract_patterns(
-        self,
-        issues: list[dict],
-        predictions: list[dict],
-    ) -> list[dict[str, Any]]:
-        """Extract patterns for cross-domain learning (Level 5).
-
-        Pattern: Drift detection applies to many domains.
-        """
-        patterns = []
-
-        if any(p["type"] == "prompt_code_drift" for p in predictions):
-            patterns.append(
-                {
-                    "pattern_type": "artifact_code_drift",
-                    "description": (
-                        "When artifacts (prompts, docs, configs) evolve slower than "
-                        "code, misalignment compounds over time"
-                    ),
-                    "domain_agnostic": True,
-                    "applicable_to": [
-                        "AI prompt engineering",
-                        "API documentation",
-                        "Configuration management",
-                        "Clinical protocols (healthcare)",
-                        "Compliance documentation",
-                    ],
-                    "detection": "Compare change velocity: artifacts vs code",
-                    "threshold": "Alert when code_changes > artifact_changes * 3",
-                },
-            )
-
-        return patterns
-
-    def _calculate_confidence(self, context: dict[str, Any]) -> float:
-        """Calculate analysis confidence"""
-        confidence = 0.75  # Base
-
-        if context.get("version_history"):
-            confidence += 0.15  # History improves drift detection
-
-        if len(context.get("prompt_files", [])) > 5:
-            confidence += 0.05  # More data = better patterns
-
-        return min(1.0, confidence)
-
-    # Helper methods
-
-    def _has_clear_structure(self, content: str) -> bool:
-        """Check if prompt has clear structural markers"""
-        markers = ["##", "Role:", "Task:", "Context:", "Instructions:"]
-        return any(marker in content for marker in markers)
-
-    def _has_examples(self, content: str) -> bool:
-        """Check if prompt contains examples"""
-        example_markers = ["<example>", "Example:", "For example:", "```"]
-        return any(marker in content for marker in example_markers)
-
-    def _count_prompt_changes(self, history: list[dict]) -> int:
-        """Count prompt-related changes in version history"""
-        return sum(
-            1
-            for commit in history
-            if any(
-                "prompt" in f.lower() or f.endswith(".txt") or f.endswith(".md")
-                for f in commit.get("files", [])
-            )
-        )
-
-    def _count_code_changes(self, history: list[dict]) -> int:
-        """Count code changes in version history"""
-        return sum(
-            1
-            for commit in history
-            if any(f.endswith((".py", ".js", ".ts", ".java")) for f in commit.get("files", []))
-        )
-
-    def _has_version_marker(self, filepath: str) -> bool:
-        """Check if file has version marker"""
-        try:
-            with open(filepath) as f:
-                content = f.read()
-                return bool(re.search(r"v\d+\.\d+\.\d+|version:", content, re.IGNORECASE))
-        except OSError:
-            return False
-
-    def _estimate_token_count(self, filepath: str) -> int:
-        """Rough estimate of token count (chars / 4)"""
-        try:
-            with open(filepath) as f:
-                return len(f.read()) // 4
-        except OSError:
-            return 0