Upload advisor.py

agents/advisor.py

@@ -0,0 +1,681 @@
+"""
+Agent 3: Design System Best Practices Advisor
+Design System Extractor v2
+
+Persona: Senior Staff Design Systems Architect
+
+Responsibilities:
+- Analyze extracted tokens against best practices (Material, Polaris, Carbon)
+- Propose upgrade OPTIONS with rationale (LLM-powered reasoning)
+- Generate type scales, color ramps, spacing grids (Rule-based calculation)
+- Never change: font families, primary/secondary base colors
+
+Hybrid Approach:
+- LLM: Analyzes patterns, recommends options, explains rationale
+- Rules: Calculates actual values (math-based)
+"""
+
+import os
+import json
+from typing import Optional, Callable
+from dataclasses import dataclass, field
+from enum import Enum
+
+from core.token_schema import (
+    NormalizedTokens,
+    ColorToken,
+    TypographyToken,
+    SpacingToken,
+    UpgradeOption,
+    UpgradeRecommendations,
+)
+from core.color_utils import (
+    parse_color,
+    generate_color_ramp,
+    get_contrast_ratio,
+)
+
+
+# =============================================================================
+# TYPE SCALE CALCULATIONS (Rule-Based)
+# =============================================================================
+
+class TypeScaleRatio(Enum):
+    """Common type scale ratios."""
+    MINOR_SECOND = 1.067
+    MAJOR_SECOND = 1.125
+    MINOR_THIRD = 1.200
+    MAJOR_THIRD = 1.250
+    PERFECT_FOURTH = 1.333
+    AUGMENTED_FOURTH = 1.414
+    PERFECT_FIFTH = 1.500
+
+
+def generate_type_scale(base_size: float, ratio: float, steps_up: int = 5, steps_down: int = 2) -> dict:
+    """
+    Generate a type scale from a base size.
+    
+    Args:
+        base_size: Base font size in pixels (e.g., 16)
+        ratio: Scale ratio (e.g., 1.25)
+        steps_up: Number of sizes larger than base
+        steps_down: Number of sizes smaller than base
+    
+    Returns:
+        Dict with size names and values
+    """
+    scale = {}
+    
+    # Generate sizes below base
+    for i in range(steps_down, 0, -1):
+        size = base_size / (ratio ** i)
+        name = f"text.{['xs', 'sm'][steps_down - i] if i <= 2 else f'xs-{i}'}"
+        scale[name] = round(size)
+    
+    # Base size
+    scale["text.base"] = round(base_size)
+    
+    # Generate sizes above base
+    size_names = ["text.lg", "text.xl", "heading.sm", "heading.md", "heading.lg", "heading.xl", "heading.2xl", "display"]
+    for i in range(1, steps_up + 1):
+        size = base_size * (ratio ** i)
+        name = size_names[i - 1] if i <= len(size_names) else f"heading.{i}xl"
+        scale[name] = round(size)
+    
+    return scale
+
+
+# =============================================================================
+# SPACING GRID CALCULATIONS (Rule-Based)
+# =============================================================================
+
+def snap_to_grid(value: float, base: int = 8) -> int:
+    """Snap a value to the nearest grid unit."""
+    return round(value / base) * base
+
+
+def generate_spacing_scale(base: int = 8, max_value: int = 96) -> dict:
+    """
+    Generate a spacing scale based on a base unit.
+    
+    Args:
+        base: Base unit (4 or 8)
+        max_value: Maximum spacing value
+    
+    Returns:
+        Dict with spacing names and values
+    """
+    scale = {}
+    multipliers = [0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24]
+    names = ["0.5", "1", "1.5", "2", "2.5", "3", "4", "5", "6", "8", "10", "12", "16", "20", "24"]
+    
+    for mult, name in zip(multipliers, names):
+        value = int(base * mult)
+        if value <= max_value:
+            scale[f"space.{name}"] = f"{value}px"
+    
+    return scale
+
+
+def analyze_spacing_fit(detected_values: list[int], base: int = 8) -> dict:
+    """
+    Analyze how well detected spacing values fit a grid.
+    
+    Returns:
+        Dict with fit percentage and adjustments needed
+    """
+    fits = 0
+    adjustments = []
+    
+    for value in detected_values:
+        snapped = snap_to_grid(value, base)
+        if value == snapped:
+            fits += 1
+        else:
+            adjustments.append({
+                "original": value,
+                "snapped": snapped,
+                "delta": snapped - value
+            })
+    
+    return {
+        "base": base,
+        "fit_percentage": (fits / len(detected_values) * 100) if detected_values else 0,
+        "adjustments": adjustments,
+        "already_aligned": fits,
+        "needs_adjustment": len(adjustments)
+    }
+
+
+# =============================================================================
+# COLOR RAMP GENERATION (Rule-Based)
+# =============================================================================
+
+def generate_semantic_color_ramp(base_color: str, role: str = "primary") -> dict:
+    """
+    Generate a full color ramp from a base color.
+    
+    Args:
+        base_color: Hex color (e.g., "#373737")
+        role: Semantic role (primary, secondary, neutral, etc.)
+    
+    Returns:
+        Dict with shade names (50-900) and hex values
+    """
+    ramp = generate_color_ramp(base_color)
+    
+    result = {}
+    shades = ["50", "100", "200", "300", "400", "500", "600", "700", "800", "900"]
+    
+    for shade, color in zip(shades, ramp):
+        result[f"{role}.{shade}"] = color
+    
+    return result
+
+
+# =============================================================================
+# LLM-POWERED ANALYSIS (Agent 3 Brain)
+# =============================================================================
+
+class DesignSystemAdvisor:
+    """
+    Agent 3: Analyzes tokens and proposes upgrades.
+    
+    Uses LLM for reasoning and recommendations.
+    Uses rules for calculating actual values.
+    """
+    
+    def __init__(self, log_callback: Optional[Callable[[str], None]] = None):
+        self.log = log_callback or print
+        self.hf_token = os.getenv("HF_TOKEN", "")
+        self.model = os.getenv("AGENT3_MODEL", "meta-llama/Llama-3.1-70B-Instruct")
+    
+    async def analyze(
+        self, 
+        desktop_tokens: NormalizedTokens,
+        mobile_tokens: NormalizedTokens,
+    ) -> UpgradeRecommendations:
+        """
+        Analyze tokens and generate upgrade recommendations.
+        
+        Args:
+            desktop_tokens: Normalized desktop tokens
+            mobile_tokens: Normalized mobile tokens
+        
+        Returns:
+            UpgradeRecommendations with options for each category
+        """
+        self.log("🤖 Agent 3: Starting design system analysis...")
+        
+        # Gather token statistics
+        stats = self._gather_statistics(desktop_tokens, mobile_tokens)
+        self.log(f"📊 Gathered statistics: {len(stats['colors'])} colors, {len(stats['typography'])} typography, {len(stats['spacing'])} spacing")
+        
+        # Generate rule-based options first
+        self.log("🔧 Generating rule-based options...")
+        type_scale_options = self._generate_type_scale_options(stats)
+        spacing_options = self._generate_spacing_options(stats)
+        color_ramp_options = self._generate_color_ramp_options(stats)
+        
+        # Get LLM analysis and recommendations
+        self.log(f"🤖 Calling LLM ({self.model}) for analysis...")
+        llm_analysis = await self._get_llm_analysis(stats, type_scale_options, spacing_options)
+        
+        # Apply LLM recommendations to options
+        self._apply_llm_recommendations(type_scale_options, spacing_options, color_ramp_options, llm_analysis)
+        
+        self.log("✅ Analysis complete!")
+        
+        return UpgradeRecommendations(
+            typography_scales=type_scale_options,
+            spacing_systems=spacing_options,
+            color_ramps=color_ramp_options,
+            naming_conventions=[],  # TODO: Add naming convention options
+            llm_rationale=llm_analysis.get("rationale", ""),
+            detected_patterns=llm_analysis.get("patterns", []),
+            accessibility_issues=llm_analysis.get("accessibility", []),
+        )
+    
+    def _gather_statistics(self, desktop: NormalizedTokens, mobile: NormalizedTokens) -> dict:
+        """Gather statistics from tokens for analysis."""
+        
+        # Combine colors (colors are viewport-agnostic)
+        colors = {}
+        for name, token in desktop.colors.items():
+            colors[token.value] = {
+                "value": token.value,
+                "frequency": token.frequency,
+                "contexts": token.contexts,
+                "suggested_name": token.suggested_name,
+            }
+        
+        # Typography (viewport-specific)
+        typography = {
+            "desktop": [],
+            "mobile": [],
+        }
+        for name, token in desktop.typography.items():
+            typography["desktop"].append({
+                "font_family": token.font_family,
+                "font_size": token.font_size,
+                "font_weight": token.font_weight,
+                "frequency": token.frequency,
+            })
+        for name, token in mobile.typography.items():
+            typography["mobile"].append({
+                "font_family": token.font_family,
+                "font_size": token.font_size,
+                "font_weight": token.font_weight,
+                "frequency": token.frequency,
+            })
+        
+        # Spacing
+        spacing = {
+            "desktop": [],
+            "mobile": [],
+        }
+        for name, token in desktop.spacing.items():
+            spacing["desktop"].append(token.value_px)
+        for name, token in mobile.spacing.items():
+            spacing["mobile"].append(token.value_px)
+        
+        # Find most used font family
+        font_families = {}
+        for t in typography["desktop"]:
+            family = t["font_family"]
+            font_families[family] = font_families.get(family, 0) + t["frequency"]
+        
+        primary_font = max(font_families.items(), key=lambda x: x[1])[0] if font_families else "sans-serif"
+        
+        # Find base font size (most frequent in body context)
+        font_sizes = [self._parse_size(t["font_size"]) for t in typography["desktop"]]
+        base_font_size = 16  # Default
+        if font_sizes:
+            # Find most common size between 14-18px (typical body text)
+            body_sizes = [s for s in font_sizes if 14 <= s <= 18]
+            if body_sizes:
+                base_font_size = max(set(body_sizes), key=body_sizes.count)
+        
+        return {
+            "colors": colors,
+            "typography": typography,
+            "spacing": spacing,
+            "primary_font": primary_font,
+            "base_font_size": base_font_size,
+            "all_font_sizes": list(set(font_sizes)),
+        }
+    
+    def _parse_size(self, size_str: str) -> float:
+        """Parse a size string to pixels."""
+        if not size_str:
+            return 16
+        size_str = str(size_str).lower().strip()
+        if "px" in size_str:
+            return float(size_str.replace("px", ""))
+        if "rem" in size_str:
+            return float(size_str.replace("rem", "")) * 16
+        if "em" in size_str:
+            return float(size_str.replace("em", "")) * 16
+        try:
+            return float(size_str)
+        except:
+            return 16
+    
+    def _generate_type_scale_options(self, stats: dict) -> list[UpgradeOption]:
+        """Generate type scale options."""
+        base = stats["base_font_size"]
+        options = []
+        
+        ratios = [
+            ("minor_third", 1.200, "Conservative — subtle size differences"),
+            ("major_third", 1.250, "Balanced — clear hierarchy without extremes"),
+            ("perfect_fourth", 1.333, "Bold — strong visual hierarchy"),
+        ]
+        
+        for id_name, ratio, desc in ratios:
+            scale = generate_type_scale(base, ratio)
+            options.append(UpgradeOption(
+                id=f"type_scale_{id_name}",
+                name=f"Type Scale {ratio}",
+                description=desc,
+                category="typography",
+                values={
+                    "ratio": ratio,
+                    "base": base,
+                    "scale": scale,
+                },
+                pros=[
+                    f"Based on {base}px base (detected)",
+                    f"Ratio {ratio} is industry standard",
+                ],
+                cons=[],
+                effort="low",
+                recommended=False,
+            ))
+        
+        # Add "keep original" option
+        options.append(UpgradeOption(
+            id="type_scale_keep",
+            name="Keep Original",
+            description="Preserve detected font sizes without scaling",
+            category="typography",
+            values={
+                "ratio": None,
+                "base": base,
+                "scale": {f"size_{i}": s for i, s in enumerate(stats["all_font_sizes"])},
+            },
+            pros=["No changes needed", "Preserves original design"],
+            cons=["May have inconsistent scale"],
+            effort="none",
+            recommended=False,
+        ))
+        
+        return options
+    
+    def _generate_spacing_options(self, stats: dict) -> list[UpgradeOption]:
+        """Generate spacing system options."""
+        desktop_spacing = stats["spacing"]["desktop"]
+        
+        options = []
+        
+        for base in [8, 4]:
+            fit_analysis = analyze_spacing_fit(desktop_spacing, base)
+            scale = generate_spacing_scale(base)
+            
+            options.append(UpgradeOption(
+                id=f"spacing_{base}px",
+                name=f"{base}px Base Grid",
+                description=f"{'Modern standard' if base == 8 else 'Finer control'} — {fit_analysis['fit_percentage']:.0f}% of your values already fit",
+                category="spacing",
+                values={
+                    "base": base,
+                    "scale": scale,
+                    "fit_analysis": fit_analysis,
+                },
+                pros=[
+                    f"{fit_analysis['already_aligned']} values already aligned",
+                    "Consistent visual rhythm" if base == 8 else "More granular control",
+                ],
+                cons=[
+                    f"{fit_analysis['needs_adjustment']} values need adjustment" if fit_analysis['needs_adjustment'] > 0 else None,
+                ],
+                effort="low" if fit_analysis['fit_percentage'] > 70 else "medium",
+                recommended=False,
+            ))
+        
+        # Add "keep original" option
+        options.append(UpgradeOption(
+            id="spacing_keep",
+            name="Keep Original",
+            description="Preserve detected spacing values",
+            category="spacing",
+            values={
+                "base": None,
+                "scale": {f"space_{v}": f"{v}px" for v in desktop_spacing},
+            },
+            pros=["No changes needed"],
+            cons=["May have irregular spacing"],
+            effort="none",
+            recommended=False,
+        ))
+        
+        return options
+    
+    def _generate_color_ramp_options(self, stats: dict) -> list[UpgradeOption]:
+        """Generate color ramp options."""
+        options = []
+        
+        # Find primary colors (high frequency, used in text/background)
+        primary_candidates = []
+        for hex_val, data in stats["colors"].items():
+            if data["frequency"] > 10:
+                primary_candidates.append((hex_val, data))
+        
+        # Sort by frequency
+        primary_candidates.sort(key=lambda x: -x[1]["frequency"])
+        
+        # Generate ramps for top colors
+        for hex_val, data in primary_candidates[:5]:
+            role = self._infer_color_role(data)
+            ramp = generate_semantic_color_ramp(hex_val, role)
+            
+            options.append(UpgradeOption(
+                id=f"color_ramp_{role}",
+                name=f"{role.title()} Ramp",
+                description=f"Generate 50-900 shades from {hex_val}",
+                category="colors",
+                values={
+                    "base_color": hex_val,
+                    "role": role,
+                    "ramp": ramp,
+                    "preserve_base": True,
+                },
+                pros=[
+                    f"Base color {hex_val} preserved",
+                    "Full shade range for UI states",
+                    "AA contrast compliant",
+                ],
+                cons=[],
+                effort="low",
+                recommended=True,
+            ))
+        
+        return options
+    
+    def _infer_color_role(self, color_data: dict) -> str:
+        """Infer semantic role from color context."""
+        contexts = " ".join(color_data.get("contexts", [])).lower()
+        
+        if "primary" in contexts or "brand" in contexts:
+            return "primary"
+        if "secondary" in contexts or "accent" in contexts:
+            return "secondary"
+        if "background" in contexts or "surface" in contexts:
+            return "surface"
+        if "text" in contexts or "foreground" in contexts:
+            return "text"
+        if "border" in contexts or "divider" in contexts:
+            return "border"
+        if "success" in contexts or "green" in contexts:
+            return "success"
+        if "error" in contexts or "red" in contexts:
+            return "error"
+        if "warning" in contexts or "yellow" in contexts:
+            return "warning"
+        
+        return "neutral"
+    
+    async def _get_llm_analysis(self, stats: dict, type_options: list, spacing_options: list) -> dict:
+        """Get LLM analysis and recommendations."""
+        
+        if not self.hf_token:
+            self.log("⚠️ No HF token, using default recommendations")
+            return self._get_default_recommendations(stats, type_options, spacing_options)
+        
+        try:
+            from core.hf_inference import HFInferenceClient
+            
+            # HFInferenceClient gets token from settings/env
+            client = HFInferenceClient()
+            
+            # Build prompt
+            prompt = self._build_analysis_prompt(stats, type_options, spacing_options)
+            
+            self.log("📤 Sending analysis request to LLM...")
+            
+            # Use the agent-specific complete method
+            response = await client.complete_async(
+                agent_name="advisor",
+                system_prompt="You are a Senior Design Systems Architect analyzing design tokens.",
+                user_message=prompt,
+                max_tokens=1500,
+            )
+            
+            self.log("📥 Received LLM response")
+            
+            # Parse LLM response
+            return self._parse_llm_response(response)
+            
+        except Exception as e:
+            self.log(f"⚠️ LLM error: {str(e)}, using default recommendations")
+            return self._get_default_recommendations(stats, type_options, spacing_options)
+    
+    def _build_analysis_prompt(self, stats: dict, type_options: list, spacing_options: list) -> str:
+        """Build the prompt for LLM analysis."""
+        
+        # Format colors
+        colors_str = "\n".join([
+            f"  - {data['value']}: frequency={data['frequency']}, contexts={data['contexts'][:3]}"
+            for hex_val, data in list(stats['colors'].items())[:10]
+        ])
+        
+        # Format typography
+        typo_str = "\n".join([
+            f"  - {t['font_family']} {t['font_size']} (weight: {t['font_weight']}, freq: {t['frequency']})"
+            for t in stats['typography']['desktop'][:10]
+        ])
+        
+        # Format spacing
+        spacing_str = f"Desktop: {sorted(stats['spacing']['desktop'])[:15]}"
+        
+        # Format options
+        type_opts = "\n".join([
+            f"  {i+1}. {opt.name} ({opt.values.get('ratio', 'N/A')}) - {opt.description}"
+            for i, opt in enumerate(type_options[:3])
+        ])
+        
+        spacing_opts = "\n".join([
+            f"  {i+1}. {opt.name} - {opt.description}"
+            for i, opt in enumerate(spacing_options[:2])
+        ])
+        
+        return f"""You are a Senior Design Systems Architect. Analyze these extracted design tokens and provide recommendations.
+
+## EXTRACTED TOKENS
+
+### Colors (top 10 by frequency):
+{colors_str}
+
+### Typography:
+Primary font: {stats['primary_font']}
+Base size: {stats['base_font_size']}px
+{typo_str}
+
+### Spacing:
+{spacing_str}
+
+## OPTIONS TO EVALUATE
+
+### Type Scale Options:
+{type_opts}
+
+### Spacing Options:
+{spacing_opts}
+
+## YOUR TASK
+
+Based on best practices from Material Design, Shopify Polaris, and IBM Carbon Design System:
+
+1. Which TYPE SCALE ratio would you recommend and why?
+2. Which SPACING BASE (4px or 8px) fits better and why?
+3. What ACCESSIBILITY concerns do you see?
+4. What PATTERNS do you notice in this design system?
+
+Respond in this JSON format:
+{{
+  "recommended_type_scale": "minor_third|major_third|perfect_fourth|keep",
+  "recommended_spacing": "8px|4px|keep",
+  "rationale": "Your detailed explanation...",
+  "patterns": ["pattern 1", "pattern 2"],
+  "accessibility": ["issue 1", "issue 2"]
+}}"""
+    
+    def _parse_llm_response(self, response: str) -> dict:
+        """Parse LLM response into structured recommendations."""
+        try:
+            # Try to extract JSON from response
+            import re
+            json_match = re.search(r'\{[\s\S]*\}', response)
+            if json_match:
+                return json.loads(json_match.group())
+        except:
+            pass
+        
+        # Default if parsing fails
+        return {
+            "recommended_type_scale": "major_third",
+            "recommended_spacing": "8px",
+            "rationale": response[:500] if response else "Analysis complete.",
+            "patterns": [],
+            "accessibility": [],
+        }
+    
+    def _get_default_recommendations(self, stats: dict, type_options: list, spacing_options: list) -> dict:
+        """Get default recommendations without LLM."""
+        
+        # Recommend based on fit analysis
+        spacing_8_fit = 0
+        spacing_4_fit = 0
+        for opt in spacing_options:
+            if opt.id == "spacing_8px":
+                spacing_8_fit = opt.values.get("fit_analysis", {}).get("fit_percentage", 0)
+            elif opt.id == "spacing_4px":
+                spacing_4_fit = opt.values.get("fit_analysis", {}).get("fit_percentage", 0)
+        
+        return {
+            "recommended_type_scale": "major_third",  # Most common default
+            "recommended_spacing": "8px" if spacing_8_fit >= spacing_4_fit else "4px",
+            "rationale": "Based on industry best practices: Major Third (1.25) type scale provides clear hierarchy. 8px spacing grid is the modern standard used by Material Design and most design systems.",
+            "patterns": [
+                f"Primary font: {stats['primary_font']}",
+                f"Base font size: {stats['base_font_size']}px",
+            ],
+            "accessibility": [],
+        }
+    
+    def _apply_llm_recommendations(
+        self, 
+        type_options: list[UpgradeOption],
+        spacing_options: list[UpgradeOption],
+        color_options: list[UpgradeOption],
+        llm_analysis: dict
+    ):
+        """Apply LLM recommendations to options."""
+        
+        # Mark recommended type scale
+        rec_type = llm_analysis.get("recommended_type_scale", "major_third")
+        for opt in type_options:
+            if rec_type in opt.id:
+                opt.recommended = True
+                opt.description += " ⭐ LLM Recommended"
+        
+        # Mark recommended spacing
+        rec_spacing = llm_analysis.get("recommended_spacing", "8px")
+        for opt in spacing_options:
+            if rec_spacing.replace("px", "") in opt.id:
+                opt.recommended = True
+                opt.description += " ⭐ LLM Recommended"
+
+
+# =============================================================================
+# CONVENIENCE FUNCTIONS
+# =============================================================================
+
+async def analyze_design_system(
+    desktop_tokens: NormalizedTokens,
+    mobile_tokens: NormalizedTokens,
+    log_callback: Optional[Callable[[str], None]] = None
+) -> UpgradeRecommendations:
+    """
+    Convenience function to analyze a design system.
+    
+    Args:
+        desktop_tokens: Normalized desktop tokens
+        mobile_tokens: Normalized mobile tokens
+        log_callback: Optional callback for logging
+    
+    Returns:
+        UpgradeRecommendations
+    """
+    advisor = DesignSystemAdvisor(log_callback=log_callback)
+    return await advisor.analyze(desktop_tokens, mobile_tokens)