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

empathy_os/workflows/seo_optimization.py

@@ -1,633 +0,0 @@
-"""SEO Optimization Workflow
-
-Cost-optimized multi-tier workflow for SEO auditing and optimization.
-
-Tier usage:
-- CHEAP (Haiku): File scanning, link validation
-- CAPABLE (Sonnet): Content analysis, suggestion generation
-- PREMIUM (Opus): Strategic recommendations, user-facing reports
-"""
-
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-from empathy_os.models import ModelTier
-from empathy_os.workflows.base import BaseWorkflow, WorkflowResult
-
-
-@dataclass
-class SEOOptimizationConfig:
-    """Configuration for SEO optimization workflow."""
-
-    docs_path: Path
-    site_url: str
-    target_keywords: list[str]
-    mode: str = "audit"  # audit, suggest, fix
-    interactive: bool = True
-
-
-class SEOOptimizationWorkflow(BaseWorkflow):
-    """Multi-tier workflow for SEO optimization.
-
-    This workflow demonstrates:
-    1. Cost-optimized tier routing (CHEAP → CAPABLE → PREMIUM)
-    2. Interactive approval workflow
-    3. Multi-agent coordination
-    4. Structured reporting
-
-    Usage:
-        workflow = SEOOptimizationWorkflow()
-        result = await workflow.execute(
-            docs_path=Path("docs"),
-            site_url="https://example.com",
-            mode="fix"
-        )
-    """
-
-    # Class attributes for workflow definition
-    name = "seo-optimization"
-    description = "Audit and optimize SEO for documentation sites"
-    stages = ["scan", "analyze", "recommend", "implement"]
-    tier_map = {
-        "scan": ModelTier.CHEAP,
-        "analyze": ModelTier.CAPABLE,
-        "recommend": ModelTier.PREMIUM,
-        "implement": ModelTier.CAPABLE,
-    }
-
-    def __init__(self):
-        """Initialize SEO optimization workflow."""
-        super().__init__(
-            enable_heartbeat_tracking=True,  # Enable dashboard visibility
-            enable_coordination=True,  # Enable coordination patterns
-        )
-
-        # Initialize workflow state
-        self._seo_config = None
-        self._mode = "audit"
-        self._interactive = True
-        self._user_goal = None
-        self._scan_result = None
-        self._analyze_result = None
-        self._recommend_result = None
-
-    async def execute(
-        self,
-        docs_path: Path | str = Path("docs"),
-        site_url: str = "https://smartaimemory.com",
-        target_keywords: list[str] | None = None,
-        mode: str = "audit",
-        interactive: bool = True,
-        user_goal: str | None = None,
-        **kwargs: Any,
-    ) -> WorkflowResult:
-        """Execute SEO optimization workflow with Socratic questioning.
-
-        Args:
-            docs_path: Path to documentation directory
-            site_url: Base URL of the site
-            target_keywords: List of target keywords for SEO
-            mode: Operation mode (audit, suggest, fix)
-            interactive: Enable interactive approval for fixes
-            user_goal: User's primary goal (launch, visibility, health, specific)
-            **kwargs: Additional workflow parameters
-
-        Returns:
-            WorkflowResult with findings, suggestions, and cost breakdown
-        """
-        # Convert to Path if string
-        docs_path = Path(docs_path) if isinstance(docs_path, str) else docs_path
-
-        # Default keywords if not provided
-        if target_keywords is None:
-            target_keywords = ["AI framework", "anticipatory AI", "multi-agent systems"]
-
-        # Initial Discovery Questions (Socratic approach)
-        if interactive and user_goal is None:
-            user_goal = await self._ask_initial_discovery()
-
-        # Create internal config for SEO-specific settings
-        seo_config = SEOOptimizationConfig(
-            docs_path=docs_path,
-            site_url=site_url,
-            target_keywords=target_keywords,
-            mode=mode,
-            interactive=interactive,
-        )
-
-        # Store user goal and config in workflow for run_stage access
-        # NOTE: Don't overwrite self._seo_config - that's the WorkflowConfig used by base class
-        self._user_goal = user_goal
-        self._seo_config = seo_config
-        self._mode = mode
-        self._interactive = interactive
-
-        # Store intermediate results for stage chaining
-        self._scan_result = None
-        self._analyze_result = None
-        self._recommend_result = None
-
-        # Let the base class handle execution by calling run_stage for each stage
-        return await super().execute(
-            docs_path=docs_path,
-            site_url=site_url,
-            target_keywords=target_keywords,
-            mode=mode,
-            interactive=interactive,
-            user_goal=user_goal,
-            **kwargs,
-        )
-
-    async def run_stage(
-        self,
-        stage_name: str,
-        tier: ModelTier,
-        input_data: Any,
-    ) -> tuple[Any, int, int]:
-        """Execute a single SEO optimization stage.
-
-        Args:
-            stage_name: Name of the stage to run
-            tier: Model tier to use
-            input_data: Input data for this stage
-
-        Returns:
-            Tuple of (output_data, input_tokens, output_tokens)
-        """
-        # Route to appropriate stage method
-        if stage_name == "scan":
-            result = await self._scan_files(self._seo_config)
-            self._scan_result = result
-            return result, 0, 0  # Minimal tokens for file scanning
-
-        elif stage_name == "analyze":
-            result = await self._analyze_seo(self._seo_config, self._scan_result)
-            self._analyze_result = result
-            # Estimate tokens for analysis stage
-            return result, 1000, 500
-
-        elif stage_name == "recommend":
-            result = await self._generate_recommendations(self._seo_config, self._analyze_result)
-            self._recommend_result = result
-            # Estimate tokens for recommendation stage
-            return result, 2000, 1500
-
-        elif stage_name == "implement":
-            if self._mode == "fix":
-                result = await self._implement_fixes(self._seo_config, self._recommend_result)
-                # Estimate tokens for implementation stage
-                return result, 1500, 800
-            else:
-                # Skip implementation if not in fix mode
-                return {"skipped": True, "reason": "Not in fix mode"}, 0, 0
-
-        else:
-            raise ValueError(f"Unknown stage: {stage_name}")
-
-    def should_skip_stage(self, stage_name: str, input_data: Any) -> tuple[bool, str | None]:
-        """Determine if a stage should be skipped based on mode.
-
-        Args:
-            stage_name: Name of the stage
-            input_data: Current workflow data
-
-        Returns:
-            Tuple of (should_skip, reason)
-        """
-        # Skip recommend stage if mode is audit
-        if stage_name == "recommend" and self._mode == "audit":
-            return True, "Audit mode - skipping recommendations"
-
-        # Skip implement stage if mode is not fix
-        if stage_name == "implement" and self._mode != "fix":
-            return True, f"Mode is {self._mode} - skipping implementation"
-
-        return False, None
-
-    async def _scan_files(self, config: SEOOptimizationConfig) -> dict[str, Any]:
-        """Scan files for SEO data (CHEAP tier - fast scanning).
-
-        This is a lightweight operation perfect for Haiku:
-        - File enumeration
-        - Basic metadata extraction
-        - Link validation
-        """
-        # Quick file scan
-        markdown_files = list(config.docs_path.rglob("*.md"))
-
-        return {
-            "file_count": len(markdown_files),
-            "files": [str(f) for f in markdown_files],
-            "docs_path": str(config.docs_path),
-            "site_url": config.site_url,
-        }
-
-    async def _analyze_seo(
-        self, config: SEOOptimizationConfig, scan_data: dict[str, Any]
-    ) -> dict[str, Any]:
-        """Analyze SEO issues (CAPABLE tier - detailed analysis).
-
-        This requires Sonnet's reasoning capabilities:
-        - Pattern detection
-        - Content quality analysis
-        - Issue categorization
-        """
-        # Mock analysis for demonstration
-        # In production, this would use LLM calls to analyze files
-        issues = []
-
-        # Check each file for basic SEO issues
-        for file_path in scan_data.get("files", []):
-            try:
-                content = Path(file_path).read_text()
-
-                # Check for missing meta description
-                if "description:" not in content and "# " in content:
-                    issues.append({
-                        "file": file_path,
-                        "element": "meta_description",
-                        "severity": "critical",
-                        "message": "Missing meta description"
-                    })
-
-                # Check for H1 count
-                h1_count = content.count("# ")
-                if h1_count == 0:
-                    issues.append({
-                        "file": file_path,
-                        "element": "h1_count",
-                        "severity": "warning",
-                        "message": "No H1 heading found"
-                    })
-                elif h1_count > 1:
-                    issues.append({
-                        "file": file_path,
-                        "element": "h1_count",
-                        "severity": "warning",
-                        "message": f"Multiple H1 headings ({h1_count})"
-                    })
-            except Exception:
-                pass  # Skip files that can't be read
-
-        return {
-            "issues": issues,
-            "total_issues": len(issues),
-            "files_analyzed": len(scan_data.get("files", [])),
-        }
-
-    async def _generate_recommendations(
-        self, config: SEOOptimizationConfig, analysis: dict[str, Any]
-    ) -> dict[str, Any]:
-        """Generate strategic recommendations with Socratic questioning (PREMIUM tier).
-
-        This requires Opus's synthesis capabilities:
-        - Prioritizing fixes by impact
-        - Calculating confidence scores
-        - Generating educational explanations
-        - Identifying when to ask questions
-        """
-        recommendations = []
-        needs_clarification = []
-
-        # Process all issues with confidence scoring
-        for issue in analysis.get("issues", []):
-            confidence = self._calculate_confidence(issue)
-            explanation = self._format_educational_explanation(issue, confidence)
-
-            recommendation = {
-                "priority": "high" if issue["severity"] == "critical" else "medium",
-                "title": f"Fix {issue['element']} in {Path(issue['file']).name}",
-                "file": issue["file"],
-                "issue": issue,
-                "confidence": confidence,
-                "explanation": explanation,
-            }
-
-            # Confidence threshold: 0.8 (80%)
-            if confidence >= 0.8:
-                # High confidence - proceed with recommendation
-                recommendations.append(recommendation)
-            else:
-                # Low confidence - flag for user clarification
-                recommendation["question"] = self._generate_clarifying_question(
-                    issue, confidence
-                )
-                needs_clarification.append(recommendation)
-
-        # Sort recommendations by priority and confidence
-        recommendations.sort(
-            key=lambda r: (r["priority"] == "high", r["confidence"]), reverse=True
-        )
-
-        return {
-            "total_recommendations": len(recommendations),
-            "high_priority": len([r for r in recommendations if r["priority"] == "high"]),
-            "needs_clarification": len(needs_clarification),
-            "recommendations": recommendations,
-            "clarification_needed": needs_clarification,
-        }
-
-    def _generate_clarifying_question(
-        self, issue: dict[str, Any], confidence: float
-    ) -> str:
-        """Generate clarifying question for low-confidence issues.
-
-        Args:
-            issue: SEO issue dictionary
-            confidence: Confidence score
-
-        Returns:
-            Question to ask the user
-        """
-        element = issue.get("element")
-        file_name = Path(issue["file"]).name
-
-        # Question templates based on issue type
-        question_templates = {
-            "keyword_density": (
-                f"The keyword density in {file_name} is low. "
-                f"Should I suggest adding target keywords to headings, "
-                f"or is the current wording intentional for your brand voice?"
-            ),
-            "meta_description": (
-                f"I can generate a meta description for {file_name}. "
-                f"What's most important to emphasize: technical details, "
-                f"benefits, or use cases?"
-            ),
-            "content_length": (
-                f"{file_name} is only 150 words. "
-                f"Should I suggest expanding it, or is brevity intentional?"
-            ),
-            "heading_structure": (
-                f"The heading structure in {file_name} could be improved. "
-                f"Should I prioritize SEO optimization or preserve your "
-                f"current content organization?"
-            ),
-        }
-
-        return question_templates.get(
-            element,
-            f"I'm {confidence * 100:.0f}% confident about fixing {element} in {file_name}. "
-            f"Would you like me to suggest a fix, or would you prefer to review it first?",
-        )
-
-    async def _implement_fixes(
-        self, config: SEOOptimizationConfig, recommendations: dict[str, Any]
-    ) -> dict[str, Any]:
-        """Implement approved fixes (CAPABLE tier - execution).
-
-        This is straightforward implementation work for Sonnet:
-        - File modifications
-        - Validation
-        - Reporting
-        """
-        # Mock implementation for demonstration
-        # In production, this would apply actual fixes to files
-        applied = []
-        skipped = []
-
-        for rec in recommendations.get("recommendations", []):
-            if config.interactive:
-                # In interactive mode, would show approval prompt
-                # For demo, we'll simulate skipping
-                skipped.append(rec)
-            else:
-                # For demo, simulate applying fixes
-                applied.append(rec)
-
-        return {
-            "applied": len(applied),
-            "skipped": len(skipped),
-            "total": len(recommendations.get("recommendations", [])),
-            "applied_fixes": applied,
-            "skipped_fixes": skipped,
-        }
-
-    async def _ask_initial_discovery(self) -> str:
-        """Ask initial discovery questions using AskUserQuestion (Socratic approach).
-
-        Returns:
-            User's primary goal (launch, visibility, health, specific)
-        """
-        # Note: This method would use the AskUserQuestion tool when called from Claude Code
-        # The actual implementation is handled by the Claude Code agent invoking this workflow
-
-        # Discovery question structure for agent to use
-        discovery_question = {
-            "question": "What's most important to you right now with your documentation SEO?",
-            "header": "Goal",
-            "multiSelect": False,
-            "options": [
-                {
-                    "label": "Launch preparation",
-                    "description": "Getting the site ready for public release - need comprehensive coverage",
-                },
-                {
-                    "label": "Search visibility",
-                    "description": "Improving rankings for specific keywords - focus on high-impact changes",
-                },
-                {
-                    "label": "Health check",
-                    "description": "Regular maintenance and catching issues - balanced approach",
-                },
-                {
-                    "label": "Specific issue",
-                    "description": "You've noticed something that needs fixing - targeted investigation",
-                },
-            ],
-        }
-
-        # When running in Claude Code, this question structure would be passed to AskUserQuestion
-        # For standalone execution, default to health check
-        return "health"
-
-    def _calculate_confidence(self, issue: dict[str, Any]) -> float:
-        """Calculate confidence score for a recommendation.
-
-        Confidence factors:
-        - Standard best practice (+0.3)
-        - Matches config patterns (+0.2)
-        - Previous similar approvals (+0.2)
-        - Low risk/reversible (+0.1)
-        - Clear data supporting (+0.2)
-
-        Args:
-            issue: SEO issue dictionary
-
-        Returns:
-            Confidence score between 0.0 and 1.0
-        """
-        confidence = 0.0
-
-        # Standard best practices (high confidence)
-        best_practices = ["meta_description", "page_title", "h1_count", "sitemap"]
-        if issue.get("element") in best_practices:
-            confidence += 0.3
-
-        # Critical severity = clear fix (high confidence)
-        if issue.get("severity") == "critical":
-            confidence += 0.3
-
-        # Technical fixes are straightforward (medium confidence)
-        technical_fixes = ["sitemap", "robots_txt", "canonical"]
-        if issue.get("element") in technical_fixes:
-            confidence += 0.2
-
-        # Content fixes require more context (lower confidence)
-        content_fixes = ["keyword_density", "heading_structure", "content_length"]
-        if issue.get("element") in content_fixes:
-            confidence -= 0.1
-
-        return min(1.0, max(0.0, confidence))
-
-    def _format_educational_explanation(
-        self, issue: dict[str, Any], confidence: float
-    ) -> dict[str, str]:
-        """Format educational explanation for an issue.
-
-        Args:
-            issue: SEO issue dictionary
-            confidence: Confidence score
-
-        Returns:
-            Dictionary with impact, time, and reasoning
-        """
-        # Map severity to impact
-        impact_map = {
-            "critical": "High - directly affects search rankings",
-            "warning": "Medium - affects user experience and rankings",
-            "info": "Low - minor improvement opportunity",
-        }
-
-        # Estimate time based on issue type
-        time_estimates = {
-            "meta_description": "2-3 minutes",
-            "page_title": "1-2 minutes",
-            "h1_count": "1 minute",
-            "sitemap": "5 minutes (one-time setup)",
-            "robots_txt": "3 minutes",
-            "broken_link": "5-10 minutes (per link)",
-        }
-
-        element = issue.get("element", "unknown")
-        severity = issue.get("severity", "info")
-
-        explanation = {
-            "impact": impact_map.get(severity, "Variable impact"),
-            "time": time_estimates.get(element, "5-15 minutes"),
-            "why": self._get_reasoning(issue),
-            "confidence": f"{confidence * 100:.0f}% confident",
-        }
-
-        return explanation
-
-    def _get_reasoning(self, issue: dict[str, Any]) -> str:
-        """Get educational reasoning for why an issue matters.
-
-        Args:
-            issue: SEO issue dictionary
-
-        Returns:
-            Explanation of why the issue matters
-        """
-        reasoning_map = {
-            "meta_description": (
-                "Search engines display this in results. "
-                "A compelling description improves click-through rate by 20-30%."
-            ),
-            "page_title": (
-                "The most important on-page SEO element. "
-                "Appears in browser tabs, search results, and social shares."
-            ),
-            "h1_count": (
-                "Pages should have exactly one H1 tag. "
-                "Multiple H1s confuse search engines about page hierarchy."
-            ),
-            "sitemap": (
-                "Helps search engines discover and index all your pages. "
-                "Critical for sites with complex navigation."
-            ),
-            "robots_txt": (
-                "Controls which pages search engines can crawl. "
-                "Prevents indexing of admin pages, duplicates, etc."
-            ),
-            "broken_link": (
-                "Broken links hurt user experience and SEO. "
-                "Search engines penalize sites with many broken links."
-            ),
-        }
-
-        element = issue.get("element", "unknown")
-        return reasoning_map.get(
-            element,
-            "This affects how search engines understand and rank your content.",
-        )
-
-    def _create_clarification_question(
-        self, recommendations: list[dict[str, Any]]
-    ) -> dict[str, Any]:
-        """Create AskUserQuestion structure for low-confidence recommendations.
-
-        This demonstrates how the workflow would use AskUserQuestion tool when
-        running in Claude Code for Socratic interaction.
-
-        Args:
-            recommendations: List of recommendations needing clarification
-
-        Returns:
-            Question structure for AskUserQuestion tool
-        """
-        if not recommendations:
-            return None
-
-        # Example: Asking about prioritization when multiple issues exist
-        if len(recommendations) > 5:
-            return {
-                "question": f"I found {len(recommendations)} SEO issues. If you could only fix ONE thing before launch, what matters most?",
-                "header": "Priority",
-                "multiSelect": False,
-                "options": [
-                    {
-                        "label": "Missing meta descriptions (Recommended)",
-                        "description": "High impact - directly affects search result click-through rates",
-                    },
-                    {
-                        "label": "Page titles optimization",
-                        "description": "Medium impact - improves relevance and rankings",
-                    },
-                    {
-                        "label": "Content structure",
-                        "description": "Medium impact - better keyword placement and readability",
-                    },
-                    {
-                        "label": "Show me details first",
-                        "description": "I want to review all issues before deciding",
-                    },
-                ],
-            }
-
-        # Example: Asking about batch operations
-        return {
-            "question": f"You have {len(recommendations)} pages without descriptions. Should I:",
-            "header": "Approach",
-            "multiSelect": False,
-            "options": [
-                {
-                    "label": "Continue asking for each one",
-                    "description": "Ensures accuracy - I'll show you each one",
-                },
-                {
-                    "label": "Auto-generate all of them (Recommended)",
-                    "description": "Faster - I'll use the same approach, you review after",
-                },
-                {
-                    "label": "Batch approve",
-                    "description": "Show me 5 at once, approve/reject in bulk",
-                },
-            ],
-        }
-
-
-# Register workflow
-WORKFLOW_CLASS = SEOOptimizationWorkflow