config/agents.yaml

# =============================================================================
# DESIGN SYSTEM AUTOMATION - AGENT CONFIGURATIONS
# =============================================================================
# 
# This file defines the personas and configurations for each agent in the
# design system extraction pipeline.
#
# Model Provider Options (via HuggingFace Inference Providers):
#   - novita (default, good balance of cost/quality)
#   - groq (fastest, good for Llama/Qwen)
#   - cerebras (ultra-fast)
#   - sambanova (good for Llama)
#   - together (wide model selection)
#   - fireworks-ai (good for code models)
#
# =============================================================================

# =============================================================================
# INFERENCE PROVIDER CONFIGURATION
# =============================================================================
inference:
  # Default provider for all LLM calls
  default_provider: "novita"
  
  # Fallback chain if primary fails
  fallback_providers:
    - "together"
    - "sambanova"
    - "groq"
  
  # HuggingFace account tiers
  billing:
    free_tier_credits: 0.10  # USD per month
    pro_tier_credits: 2.00   # USD per month ($9/mo subscription)
    warning_threshold: 0.80  # Warn at 80% usage
    
  # Show cost tracking in logs
  show_cost_tracking: true

# =============================================================================
# STAGE 1: EXTRACTION (No LLM needed)
# =============================================================================

agent1_crawler:
  name: "Website Crawler"
  persona: "Meticulous Design Archaeologist"
  description: |
    Discovers and crawls website pages to extract design tokens.
    Uses Playwright for browser automation.
  model: null  # Rule-based, no LLM needed
  
agent1_extractor:
  name: "Token Extractor"
  persona: "Meticulous Design Archaeologist"
  description: |
    Extracts colors, typography, spacing, radius, and shadows from pages.
    Pure CSS/computed style extraction.
  model: null  # Rule-based, no LLM needed

# =============================================================================
# STAGE 1: NORMALIZATION
# =============================================================================

agent2_normalizer:
  name: "Token Normalizer"
  persona: "Design System Librarian"
  description: |
    Cleans, deduplicates, and structures extracted tokens.
    Infers naming patterns and semantic roles.
  model: "microsoft/Phi-3.5-mini-instruct"
  provider: "novita"
  max_tokens: 1000
  temperature: 0.3
  tasks:
    - Clean noisy extraction data
    - Deduplicate similar tokens
    - Infer semantic naming (primary, secondary, etc.)
    - Tag confidence levels

# =============================================================================
# STAGE 2: MULTI-AGENT ANALYSIS (LangGraph Parallel)
# =============================================================================
# 
# Architecture:
#   LLM 1 ─┐
#          ├──> HEAD ──> Final Recommendations
#   LLM 2 ─┘
#   
# LLM 1 and LLM 2 run in PARALLEL via LangGraph
# HEAD compiles results and resolves conflicts
#
# =============================================================================

stage2_llm1:
  name: "Design Analyst 1"
  persona: "Senior Design Systems Architect (Global Perspective)"
  description: |
    Analyzes design tokens against industry best practices.
    Focuses on global/Asian design systems (Ant Design, etc.)
  model: "Qwen/Qwen2.5-72B-Instruct"
  provider: "novita"
  max_tokens: 1500
  temperature: 0.4
  # Cost tracking (per million tokens)
  cost_per_million_input: 0.29
  cost_per_million_output: 0.59
  tasks:
    - Analyze typography patterns and scale consistency
    - Evaluate color system and semantic usage
    - Check AA/WCAG accessibility compliance
    - Assess spacing consistency and grid alignment
    - Compare against competitor design systems
  expertise:
    - Typography best practices and type scales
    - Color theory and accessibility standards
    - Spacing systems (4px, 8px grids)
    - International design standards
    - Ant Design, Chakra UI patterns

stage2_llm2:
  name: "Design Analyst 2"
  persona: "Senior Design Systems Architect (Western Perspective)"
  description: |
    Analyzes design tokens against industry best practices.
    Focuses on Western/US design systems (Material, Apple, etc.)
  model: "meta-llama/Llama-3.3-70B-Instruct"
  provider: "novita"
  max_tokens: 1500
  temperature: 0.4
  # Cost tracking (per million tokens)
  cost_per_million_input: 0.59
  cost_per_million_output: 0.79
  tasks:
    - Analyze typography patterns and scale consistency
    - Evaluate color system and semantic usage
    - Check AA/WCAG accessibility compliance
    - Assess spacing consistency and grid alignment
    - Compare against competitor design systems
  expertise:
    - Material Design 3 patterns
    - Apple Human Interface Guidelines
    - Shopify Polaris conventions
    - IBM Carbon design standards
    - Atlassian Design System

stage2_head:
  name: "Head Compiler"
  persona: "Principal Design Systems Architect"
  description: |
    Compiles analyses from both LLM analysts.
    Resolves conflicts and synthesizes final recommendations.
  model: "meta-llama/Llama-3.3-70B-Instruct"
  provider: "novita"
  max_tokens: 2000
  temperature: 0.3
  # Cost tracking (per million tokens)
  cost_per_million_input: 0.59
  cost_per_million_output: 0.79
  tasks:
    - Compare both analyst perspectives
    - Identify agreements and disagreements
    - Resolve conflicts with clear reasoning
    - Synthesize final recommendations
    - Provide confidence scores
  expertise:
    - Cross-cultural design synthesis
    - Conflict resolution and arbitration
    - Best practice prioritization

stage2_rules:
  name: "Rule Engine"
  persona: "Calculation Engine"
  description: |
    Performs deterministic calculations.
    No LLM needed - pure math/logic.
  model: null  # No LLM - FREE
  tasks:
    - Generate type scale options (1.2, 1.25, 1.333)
    - Calculate spacing grid alignments (4px, 8px)
    - Generate color ramps (50-950 shades)
    - Compute contrast ratios for accessibility

# =============================================================================
# STAGE 3: GENERATION
# =============================================================================

agent4_generator:
  name: "JSON Generator"
  persona: "Automation Engineer"
  description: |
    Converts finalized tokens to production-ready JSON.
    Generates Figma-compatible token files.
  model: "mistralai/Codestral-22B-v0.1"
  provider: "novita"
  max_tokens: 2000
  temperature: 0.2
  tasks:
    - Generate final JSON structure
    - Apply selected upgrades
    - Format for Figma Tokens Studio
    - Include metadata and versioning

# =============================================================================
# COMPETITOR DESIGN SYSTEMS
# =============================================================================

competitors:
  # Default list (shown in UI, user can edit)
  default:
    - "Material Design 3"
    - "Apple Human Interface Guidelines"
    - "Shopify Polaris"
    - "IBM Carbon"
    - "Atlassian Design System"
  
  # Suggestions for user to add
  suggestions:
    - "Ant Design"
    - "Chakra UI"
    - "Tailwind CSS"
    - "Bootstrap"
    - "Salesforce Lightning"
    - "Adobe Spectrum"
    - "GitHub Primer"
    - "Microsoft Fluent"
    - "Radix UI"
    - "MUI (Material UI)"

# =============================================================================
# LLM PROMPT TEMPLATES
# =============================================================================

prompts:
  # Prompt for LLM 1 and LLM 2 (same structure, different perspective)
  analyst: |
    You are a {persona}.
    
    ## YOUR TASK
    Analyze these design tokens extracted from a website and compare against industry best practices.
    
    ## EXTRACTED TOKENS
    {tokens_summary}
    
    ## COMPETITOR DESIGN SYSTEMS TO RESEARCH
    {competitors}
    
    ## ANALYZE THE FOLLOWING:
    
    ### 1. Typography
    - Is the type scale consistent? Does it follow a mathematical ratio?
    - What is the detected base size?
    - Compare to competitors: what ratios do they use?
    - Score (1-10) and specific recommendations
    
    ### 2. Colors
    - Is the color palette cohesive?
    - Are semantic colors properly defined (primary, secondary, etc.)?
    - Compare to competitors: how do they structure colors?
    - Score (1-10) and specific recommendations
    
    ### 3. Accessibility (AA Compliance)
    - What contrast issues exist?
    - Which color combinations fail WCAG AA (4.5:1 for text)?
    - Specific fixes needed
    - Score (1-10)
    
    ### 4. Spacing
    - Is spacing consistent? Does it follow a grid (4px, 8px)?
    - What base unit is detected?
    - Compare to competitors: what spacing systems do they use?
    - Score (1-10) and specific recommendations
    
    ### 5. Overall Assessment
    - Top 3 priorities for improvement
    - What works well (keep these)
    - What needs immediate attention
    
    ## RESPOND IN JSON FORMAT:
    ```json
    {{
      "typography": {{
        "analysis": "...",
        "detected_ratio": 1.2,
        "detected_base": 16,
        "score": 7,
        "recommendations": ["...", "..."]
      }},
      "colors": {{
        "analysis": "...",
        "score": 6,
        "recommendations": ["...", "..."]
      }},
      "accessibility": {{
        "issues": ["...", "..."],
        "score": 5,
        "fixes": ["...", "..."]
      }},
      "spacing": {{
        "analysis": "...",
        "detected_base": 8,
        "score": 7,
        "recommendations": ["...", "..."]
      }},
      "overall_assessment": "...",
      "top_3_priorities": ["...", "...", "..."],
      "confidence": 85
    }}
    ```

  # Prompt for HEAD compiler
  head_compiler: |
    You are a Principal Design Systems Architect compiling analyses from two expert analysts.
    
    ## ANALYST 1 (Global/Asian Perspective) FINDINGS:
    {llm1_analysis}
    
    ## ANALYST 2 (Western/US Perspective) FINDINGS:
    {llm2_analysis}
    
    ## RULE-BASED CALCULATIONS:
    {rule_calculations}
    
    ## YOUR TASK:
    1. Compare both analyst perspectives
    2. Identify where they AGREE (high confidence)
    3. Identify where they DISAGREE (need resolution)
    4. Resolve disagreements with clear reasoning
    5. Synthesize final recommendations
    
    ## RESPOND IN JSON FORMAT:
    ```json
    {{
      "agreements": [
        {{"topic": "typography", "finding": "...", "confidence": 95}},
        ...
      ],
      "disagreements": [
        {{"topic": "spacing", "llm1_view": "...", "llm2_view": "...", "resolution": "...", "reasoning": "..."}}
      ],
      "final_recommendations": {{
        "type_scale": "1.25",
        "type_scale_rationale": "Both analysts agree 1.25 (Major Third) balances readability and hierarchy",
        "spacing_base": "8px",
        "spacing_rationale": "8px grid provides better alignment with industry standards",
        "color_improvements": ["Generate full ramps", "Fix contrast on secondary"],
        "accessibility_fixes": ["Increase body text contrast to 4.5:1"]
      }},
      "overall_confidence": 88,
      "summary": "The extracted design system shows strong typography foundations but needs spacing normalization and color accessibility improvements."
    }}
    ```

# =============================================================================
# EXTRACTION SETTINGS
# =============================================================================

extraction:
  viewports:
    desktop:
      width: 1440
      height: 900
      name: "Desktop"
    mobile:
      width: 375
      height: 812
      name: "Mobile"
  
  crawling:
    max_pages: 20
    min_pages: 10
    scroll_behavior: "smooth"
    wait_for_network_idle: true
    network_idle_timeout_ms: 5000
    skip_infinite_scroll: true

# =============================================================================
# TYPE SCALE OPTIONS
# =============================================================================

type_scales:
  minor_second:
    ratio: 1.067
    name: "Minor Second"
    description: "Very subtle, good for dense data UIs"
  major_second:
    ratio: 1.125
    name: "Major Second"
    description: "Subtle progression"
  minor_third:
    ratio: 1.2
    name: "Minor Third"
    description: "Balanced, widely used"
  major_third:
    ratio: 1.25
    name: "Major Third"
    description: "Classic, recommended for most UIs"
    recommended: true
  perfect_fourth:
    ratio: 1.333
    name: "Perfect Fourth"
    description: "Strong hierarchy, good for marketing"
  golden_ratio:
    ratio: 1.618
    name: "Golden Ratio"
    description: "Dramatic, use sparingly"

# =============================================================================
# SPACING SYSTEMS
# =============================================================================

spacing_systems:
  4px_grid:
    base: 4
    name: "4px Grid"
    description: "Fine-grained control, good for dense UIs"
    scale: [0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64]
  8px_grid:
    base: 8
    name: "8px Grid"
    description: "Industry standard, recommended"
    recommended: true
    scale: [0, 8, 16, 24, 32, 48, 64, 80, 96, 128]

# =============================================================================
# COLOR RAMP GENERATION
# =============================================================================

color_ramps:
  shades: [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
  method: "oklch"  # Modern perceptually uniform
  
  accessibility:
    aa_minimum: 4.5
    aaa_minimum: 7.0
    large_text_aa: 3.0