Upload agents.yaml

config/agents.yaml

@@ -0,0 +1,547 @@
+# Agent Personas & Configuration
+# Design System Extractor v2
+
+# =============================================================================
+# MODEL CONFIGURATION
+# =============================================================================
+# Model assignments for each agent based on task complexity
+# =============================================================================
+
+models:
+  # Agent 1: Crawler & Extractor — NO LLM NEEDED (Rule-based)
+  agent_crawler:
+    requires_llm: false
+    notes: "Pure rule-based extraction using Playwright + CSS parsing"
+  
+  # Agent 2: Normalizer — LIGHT MODEL
+  agent_normalizer:
+    requires_llm: true
+    primary_model: "Qwen/Qwen2.5-7B-Instruct"
+    fallback_model: "microsoft/Phi-3-mini-4k-instruct"
+    tasks:
+      - "Suggest semantic token names from values"
+      - "Explain duplicate detection rationale"
+      - "Infer naming conventions from class names"
+    temperature: 0.2  # Low temp for consistent naming
+    max_tokens: 1024
+    why_this_model: |
+      7B model is sufficient because:
+      - Tasks are mostly pattern matching and naming
+      - Doesn't require complex reasoning
+      - Fast inference, good for iterative workflows
+  
+  # Agent 3: Advisor — STRONG MODEL (Key agent)
+  agent_advisor:
+    requires_llm: true
+    primary_model: "Qwen/Qwen2.5-72B-Instruct"
+    fallback_model: "mistralai/Mixtral-8x7B-Instruct-v0.1"
+    budget_model: "Qwen/Qwen2.5-7B-Instruct"  # If quota constrained
+    tasks:
+      - "Analyze extracted system for patterns and anti-patterns"
+      - "Research and recommend type scales with rationale"
+      - "Suggest spacing systems based on detected patterns"
+      - "Identify accessibility issues and fixes"
+      - "Compare against industry design systems"
+    temperature: 0.4  # Moderate temp for creative recommendations
+    max_tokens: 4096
+    why_this_model: |
+      72B model is critical because:
+      - Needs deep understanding of design systems
+      - Must reason about trade-offs (pros/cons)
+      - Should know Material, Polaris, Carbon, etc.
+      - Quality of recommendations is user-facing
+  
+  # Agent 4: Generator — LIGHT MODEL
+  agent_generator:
+    requires_llm: true
+    primary_model: "Qwen/Qwen2.5-7B-Instruct"
+    fallback_model: "mistralai/Mistral-7B-Instruct-v0.3"
+    tasks:
+      - "Format tokens into Tokens Studio JSON"
+      - "Generate CSS custom properties"
+      - "Structure metadata correctly"
+    temperature: 0.1  # Very low temp for consistent formatting
+    max_tokens: 8192  # Larger for full JSON output
+    why_this_model: |
+      7B model is sufficient because:
+      - Structured output generation is formulaic
+      - JSON schema is well-defined
+      - Speed matters for export flow
+
+# =============================================================================
+# FREE TIER vs PRO RECOMMENDATIONS
+# =============================================================================
+
+tier_recommendations:
+  free_tier:
+    description: "For users without HF Pro subscription"
+    agent2: "Qwen/Qwen2.5-7B-Instruct"
+    agent3: "mistralai/Mixtral-8x7B-Instruct-v0.1"  # Best free option for reasoning
+    agent4: "Qwen/Qwen2.5-7B-Instruct"
+    notes: "Quality will be slightly lower for Agent 3 recommendations"
+  
+  pro_tier:
+    description: "For users with HF Pro subscription"
+    agent2: "Qwen/Qwen2.5-7B-Instruct"
+    agent3: "Qwen/Qwen2.5-72B-Instruct"  # Full quality
+    agent4: "Qwen/Qwen2.5-7B-Instruct"
+    notes: "Best quality, especially for design system recommendations"
+
+# =============================================================================
+# AGENT 1: Website Crawler & Extractor
+# =============================================================================
+agent_crawler:
+  name: "Design Archaeologist"
+  persona: |
+    You are a meticulous Design Archaeologist. Your job is to carefully excavate 
+    design decisions buried in website code. You approach each site with curiosity 
+    and systematic precision, documenting everything you find without judgment.
+    
+    You understand that live websites are often messy — accumulated decisions from 
+    multiple designers over years. Your role is to faithfully extract what exists, 
+    not to fix or improve it yet.
+  
+  responsibilities:
+    - Auto-discover pages from base URL (minimum 10)
+    - Include key templates: homepage, listing, detail, form, marketing, auth
+    - Scroll pages fully (above + below fold)
+    - Extract separately for Desktop (1440px) and Mobile (375px)
+  
+  extraction_targets:
+    colors:
+      - hex values
+      - rgb/rgba values
+      - usage frequency
+      - context (background, text, border, etc.)
+    typography:
+      - font families
+      - font sizes (px, rem, em)
+      - line heights
+      - font weights
+      - letter spacing
+    spacing:
+      - margin values
+      - padding values
+      - gap values
+      - infer base system (4px, 8px)
+    other:
+      - border radius
+      - box shadows
+      - layout signals (containers, grids)
+  
+  tools:
+    - playwright (crawling, scrolling, computed styles)
+    - css parsing (CSSOM)
+  
+  output_format:
+    - raw extracted tokens
+    - confidence score per token
+    - desktop/mobile separated
+    - errors and warnings logged
+
+  guardrails:
+    - Never modify or "fix" extracted values
+    - Always preserve original CSS values
+    - Log anomalies, don't hide them
+    - Respect robots.txt (configurable)
+
+# =============================================================================
+# AGENT 2: Token Normalizer & Structurer
+# =============================================================================
+agent_normalizer:
+  name: "Design System Librarian"
+  persona: |
+    You are a methodical Design System Librarian. Your expertise is in organizing 
+    chaotic information into structured, meaningful categories. You see patterns 
+    where others see noise.
+    
+    You are careful to distinguish between what you KNOW (detected) and what you 
+    THINK (inferred). You never overwrite the truth — you annotate it.
+  
+  responsibilities:
+    - Clean noisy extraction data
+    - Group and merge duplicates (with threshold tolerance)
+    - Infer naming patterns from class names
+    - Propose initial token names
+    - Tag confidence levels
+  
+  naming_conventions:
+    colors:
+      pattern: "color.{role}.{shade}"
+      example: "color.primary.500"
+      roles: 
+        - primary
+        - secondary
+        - neutral
+        - success
+        - warning
+        - error
+      shades:
+        - 50
+        - 100
+        - 200
+        - 300
+        - 400
+        - 500
+        - 600
+        - 700
+        - 800
+        - 900
+    typography:
+      pattern: "font.{category}.{size}"
+      example: "font.heading.lg"
+      categories:
+        - heading
+        - body
+        - label
+        - caption
+      sizes:
+        - xs
+        - sm
+        - md
+        - lg
+        - xl
+        - 2xl
+    spacing:
+      pattern: "space.{size}"
+      example: "space.4, space.8"
+      note: "based on pixel value / 4"
+  
+  tagging:
+    detected: "Directly found in CSS, high confidence"
+    inferred: "Derived from patterns, medium confidence"
+    low_confidence: "Appears rarely or inconsistently"
+  
+  duplicate_threshold:
+    colors: 3  # hex values within 3 steps are potential duplicates
+    spacing: 2  # pixel values within 2px are potential duplicates
+  
+  guardrails:
+    - Never overwrite extracted truth
+    - Always mark inferred vs detected
+    - Preserve original values alongside normalized
+    - Flag conflicts, don't resolve them silently
+
+# =============================================================================
+# AGENT 3: Design System Best Practices Advisor
+# =============================================================================
+agent_advisor:
+  name: "Senior Staff Design Systems Architect"
+  persona: |
+    You are a Senior Staff Design Systems Architect with 15+ years of experience 
+    building and scaling design systems at major tech companies. You've seen what 
+    works and what doesn't.
+    
+    Your role is to ADVISE, not DECIDE. You present options with clear rationale, 
+    letting humans make the final call. You respect existing decisions while 
+    offering paths to improvement.
+  
+  responsibilities:
+    - Analyze extracted system for patterns and anti-patterns
+    - Research modern design system best practices
+    - Propose upgrade OPTIONS (never auto-apply)
+    - Ensure accessibility compliance (AA minimum)
+  
+  research_sources:
+    - Material Design (Google)
+    - Polaris (Shopify)
+    - Carbon (IBM)
+    - Fluent (Microsoft)
+    - Primer (GitHub)
+    - Radix
+    - Tailwind CSS
+  
+  upgrade_categories:
+    typography_scales:
+      - name: "Minor Third"
+        ratio: 1.2
+        description: "Subtle progression, good for dense UIs"
+      - name: "Major Third"
+        ratio: 1.25
+        description: "Balanced, most popular choice"
+      - name: "Perfect Fourth"
+        ratio: 1.333
+        description: "Strong hierarchy, good for marketing"
+      - name: "Golden Ratio"
+        ratio: 1.618
+        description: "Dramatic, use sparingly"
+    
+    spacing_systems:
+      - name: "4px base"
+        scale: [4, 8, 12, 16, 20, 24, 32, 40, 48, 64]
+        description: "Fine-grained control"
+      - name: "8px base"
+        scale: [4, 8, 16, 24, 32, 48, 64, 80, 96]
+        description: "Industry standard, recommended"
+      - name: "Tailwind"
+        scale: [4, 8, 12, 16, 20, 24, 32, 40, 48, 56, 64, 80, 96]
+        description: "Utility-first, comprehensive"
+    
+    naming_conventions:
+      - name: "T-shirt sizes"
+        example: "xs, sm, md, lg, xl, 2xl"
+        pros: "Intuitive, easy to remember"
+        cons: "Limited granularity"
+      - name: "Numeric"
+        example: "100, 200, 300, 400, 500"
+        pros: "Extensible, precise"
+        cons: "Less intuitive"
+      - name: "Semantic"
+        example: "caption, body, subhead, title, display"
+        pros: "Meaningful, self-documenting"
+        cons: "Harder to extend"
+    
+    color_ramps:
+      shades: [50, 100, 200, 300, 400, 500, 600, 700, 800, 900]
+      aa_contrast_minimum: 4.5
+      aaa_contrast_minimum: 7.0
+  
+  output_format:
+    - option sets (never single recommendations)
+    - rationale for each option
+    - pros and cons
+    - accessibility impact
+    - migration effort estimate
+  
+  guardrails:
+    - Never auto-apply changes
+    - Always provide multiple options
+    - Respect existing system, suggest improvements
+    - Flag accessibility issues prominently
+
+# =============================================================================
+# AGENT 4: Plugin & JSON Generator
+# =============================================================================
+agent_generator:
+  name: "Automation Engineer"
+  persona: |
+    You are a precise Automation Engineer. Your job is to transform design 
+    decisions into machine-readable formats that tools can consume. You care 
+    deeply about compatibility, versioning, and clean output.
+    
+    You understand that your output will be used by Figma plugins, CSS 
+    preprocessors, and design tools — so format matters.
+  
+  responsibilities:
+    - Convert finalized tokens to standard formats
+    - Generate color ramps with AA compliance
+    - Maintain viewport separation (Desktop/Mobile)
+    - Version all outputs
+  
+  output_formats:
+    tokens_studio:
+      description: "Compatible with Tokens Studio Figma plugin"
+      extension: ".json"
+    figma_variables:
+      description: "Direct Figma Variables format"
+      extension: ".json"
+    css_variables:
+      description: "CSS custom properties"
+      extension: ".css"
+    tailwind_config:
+      description: "Tailwind CSS configuration"
+      extension: ".js"
+  
+  token_structure:
+    colors:
+      include_ramps: true
+      ramp_shades: [50, 100, 200, 300, 400, 500, 600, 700, 800, 900]
+      include_contrast: true
+    typography:
+      include_composite: true  # font-family + size + weight + line-height
+      include_individual: true
+    spacing:
+      base: 8
+      include_negative: false
+  
+  metadata_fields:
+    - source_url
+    - extracted_at
+    - version
+    - viewport
+    - token_source (detected/inferred/upgraded)
+  
+  guardrails:
+    - Always include metadata
+    - Validate JSON before output
+    - Preserve source attribution on each token
+    - Warn on potential conflicts
+
+# =============================================================================
+# LANGGRAPH WORKFLOW CONFIGURATION
+# =============================================================================
+workflow:
+  name: "design_system_extraction"
+  
+  checkpoints:
+    - id: "confirm_pages"
+      description: "Human confirms discovered pages before crawling"
+      required: true
+    - id: "review_extraction"
+      description: "Human reviews extracted tokens (Stage 1 UI)"
+      required: true
+    - id: "select_upgrades"
+      description: "Human selects upgrade options (Stage 2 UI)"
+      required: true
+    - id: "approve_export"
+      description: "Human approves final output (Stage 3 UI)"
+      required: true
+  
+  parallel_nodes:
+    - name: "viewport_extraction"
+      description: "Extract Desktop and Mobile in parallel"
+      agents: ["agent_crawler"]
+    - name: "research_and_advise"
+      description: "Agent 3 can research while human reviews Stage 1"
+      agents: ["agent_advisor"]
+  
+  error_handling:
+    retry_attempts: 3
+    retry_delay_seconds: 5
+    log_errors: true
+    show_in_ui: true
+
+# =============================================================================
+# UI CONFIGURATION
+# =============================================================================
+ui:
+  layout: "single_scroll"
+  
+  stages:
+    stage1:
+      name: "Extraction Review"
+      purpose: "Trust building — see what was found"
+      components:
+        - token_tables
+        - color_swatches
+        - typography_samples
+        - viewport_toggle
+        - confidence_indicators
+        - accept_reject_controls
+    
+    stage2:
+      name: "Upgrade Playground"
+      purpose: "Decision making through live visuals"
+      components:
+        - option_selector
+        - live_preview_iframe
+        - side_by_side_comparison
+        - existing_vs_upgraded_toggle
+    
+    stage3:
+      name: "Final Review & Export"
+      purpose: "Confidence before export"
+      components:
+        - token_preview_readonly
+        - json_tree_view
+        - diff_view
+        - viewport_tabs
+        - download_buttons
+        - version_labeling
+  
+  preview:
+    type: "iframe"
+    template: "specimen.html"
+    update_trigger: "on_selection"
+
+# =============================================================================
+# 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
+    respect_robots_txt: true
+  
+  page_templates:
+    required:
+      - homepage
+      - listing
+      - detail
+    optional:
+      - form
+      - marketing
+      - auth
+      - checkout
+      - about
+      - contact
+
+# =============================================================================
+# COLOR PROCESSING
+# =============================================================================
+color_processing:
+  ramp_generation:
+    enabled: true
+    shades: [50, 100, 200, 300, 400, 500, 600, 700, 800, 900]
+    method: "oklch"  # or "hsl" or "lab"
+  
+  accessibility:
+    check_contrast: true
+    minimum_standard: "AA"  # or "AAA"
+    contrast_pairs:
+      - ["text", "background"]
+      - ["button-text", "button-background"]
+  
+  duplicate_detection:
+    enabled: true
+    threshold_delta_e: 3  # CIE Delta E threshold
+
+# =============================================================================
+# TYPOGRAPHY PROCESSING
+# =============================================================================
+typography_processing:
+  scale_options:
+    - name: "Minor Third"
+      ratio: 1.2
+    - name: "Major Third"
+      ratio: 1.25
+    - name: "Perfect Fourth"
+      ratio: 1.333
+  
+  base_size: 16  # px
+  
+  text_styles:
+    - display
+    - heading-xl
+    - heading-lg
+    - heading-md
+    - heading-sm
+    - body-lg
+    - body-md
+    - body-sm
+    - caption
+    - label
+
+# =============================================================================
+# SPACING PROCESSING
+# =============================================================================
+spacing_processing:
+  base: 8  # px
+  scale: [0, 4, 8, 12, 16, 24, 32, 48, 64, 80, 96]
+  
+  names:
+    0: "none"
+    4: "xs"
+    8: "sm"
+    12: "sm-md"
+    16: "md"
+    24: "lg"
+    32: "xl"
+    48: "2xl"
+    64: "3xl"
+    80: "4xl"
+    96: "5xl"