Deploy GitHub Issue Triager

README.md

@@ -1,12 +1,61 @@
 ---
-title: Github Issue Triager
-emoji: 🦀
-colorFrom: green
-colorTo: gray
+title: GitHub Issue Triager
+emoji: 🎫
+colorFrom: yellow
+colorTo: blue
 sdk: gradio
-sdk_version: 6.13.0
 app_file: app.py
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# GitHub Issue Triager
+
+## Question
+
+Can an LLM turn a messy issue report into useful project-management structure?
+
+## System Boundary
+
+This Space is a triage assistant. It does not make final product decisions; it proposes labels, priority, severity, assignment hints, and next steps for human review.
+
+## Method
+
+The issue text is passed to an instruction model with a structured JSON schema. The app parses the response and presents both the classification and the reasoning.
+
+## Technique
+
+This is structured generation. Instead of asking the model for a paragraph, the app asks for a bounded object with fields that can be validated and used by another system.
+
+The schema is the interface between language understanding and workflow automation.
+
+## Output
+
+The app returns a title, labels, priority, severity, category, assignee suggestion, estimated effort, and rationale.
+
+## Why It Matters
+
+LLMs become more useful in operations when their output is constrained into a schema. This demo shows how unstructured text can become a reviewable workflow artifact.
+
+## What To Notice
+
+The rationale is important. A label without reasoning is hard to review; a label with reasoning can be corrected and used to improve future prompts or datasets.
+
+## Effect In Practice
+
+Issue triage can reduce repetitive coordination work and make human review more consistent, especially in repositories with many incoming reports.
+
+## Hugging Face Extension
+
+This can grow into a labeled issue-triage dataset and a model-comparison Space for classification accuracy, calibration, and rationale quality.
+
+## Limitations
+
+The model does not know repository history unless the text includes it. Production triage should integrate repository metadata, issue history, code ownership, and feedback loops.
+
+## Run Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,244 @@
+"""
+GitHub Issue Triager
+Agentic workflow: Analyze → Classify → Prioritize → Assign
+"""
+
+import gradio as gr
+from huggingface_hub import InferenceClient
+import json
+import os
+import sys
+import time
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+from shared.components import create_method_panel, create_premium_hero
+
+# Initialize client
+client = InferenceClient(model="meta-llama/Llama-3.3-70B-Instruct")
+
+def triage_issue(issue_text: str) -> dict:
+    """Analyze and triage a GitHub issue"""
+
+    prompt = f"""You are a GitHub issue triager. Analyze this issue and provide structured triage information.
+
+ISSUE:
+{issue_text}
+
+Provide a JSON response with:
+{{
+    "title": "Brief title extracted from issue",
+    "labels": ["bug", "feature", "question", "documentation", "enhancement", "performance"],
+    "priority": "P0/P1/P2/P3",
+    "severity": "Critical/High/Medium/Low",
+    "category": "Frontend/Backend/DevOps/Documentation/Other",
+    "estimated_effort": "Small (< 1 day)/Medium (1-3 days)/Large (> 3 days)",
+    "suggested_assignee": "Team/person based on issue type",
+    "reasoning": {{
+        "label_reasoning": "Why these labels",
+        "priority_reasoning": "Why this priority (consider: impact, urgency, user-facing)",
+        "effort_reasoning": "Why this effort estimate"
+    }},
+    "related_areas": ["area1", "area2"],
+    "next_steps": ["Step 1", "Step 2"]
+}}
+
+Priority definitions:
+- P0: Critical bug, service down, data loss
+- P1: Major bug, significant feature broken, high user impact
+- P2: Minor bug, feature request with clear value
+- P3: Nice-to-have, low impact
+
+Choose only the most relevant labels (2-4 max)."""
+
+    response = ""
+    for message in client.chat_completion(
+        messages=[{"role": "user", "content": prompt}],
+        max_tokens=1200,
+        stream=True,
+    ):
+        response += message.choices[0].delta.content or ""
+
+    # Extract JSON
+    try:
+        if "```json" in response:
+            response = response.split("```json")[1].split("```")[0].strip()
+        elif "```" in response:
+            response = response.split("```")[1].split("```")[0].strip()
+
+        data = json.loads(response)
+        return data
+    except Exception as e:
+        return {
+            "title": "Error parsing issue",
+            "labels": [],
+            "priority": "P3",
+            "severity": "Low",
+            "category": "Other",
+            "estimated_effort": "Unknown",
+            "suggested_assignee": "TBD",
+            "reasoning": {
+                "label_reasoning": "Error occurred",
+                "priority_reasoning": "Error occurred",
+                "effort_reasoning": "Error occurred"
+            },
+            "related_areas": [],
+            "next_steps": []
+        }
+
+def process_triage(issue_text: str, progress=gr.Progress()):
+    """Main issue triage workflow"""
+
+    if not issue_text.strip():
+        return "Please paste an issue description."
+
+    # Step 1: Analyze issue
+    progress(0.2, desc="Analyzing issue content...")
+    time.sleep(0.3)
+
+    # Step 2: Classify and prioritize
+    progress(0.5, desc="Classifying and prioritizing...")
+    triage = triage_issue(issue_text)
+
+    # Step 3: Generate recommendations
+    progress(0.8, desc="Generating recommendations...")
+    time.sleep(0.3)
+
+    # Format output
+    priority_emoji = {
+        "P0": "🔴",
+        "P1": "🟠",
+        "P2": "🟡",
+        "P3": "🟢"
+    }
+
+    severity_emoji = {
+        "Critical": "🚨",
+        "High": "⚠️",
+        "Medium": "📊",
+        "Low": "ℹ️"
+    }
+
+    output = f"# Issue Triage Report\n\n"
+    output += f"## {triage['title']}\n\n"
+
+    # Priority and Severity
+    output += "### 🎯 Priority & Severity\n\n"
+    p_emoji = priority_emoji.get(triage['priority'], "⚪")
+    s_emoji = severity_emoji.get(triage['severity'], "ℹ️")
+
+    output += f"- **Priority**: {p_emoji} **{triage['priority']}**\n"
+    output += f"- **Severity**: {s_emoji} {triage['severity']}\n"
+    output += f"- **Category**: {triage['category']}\n"
+    output += f"- **Estimated Effort**: {triage['estimated_effort']}\n\n"
+
+    # Labels
+    output += "### 🏷️ Suggested Labels\n\n"
+    for label in triage['labels']:
+        # Color code labels
+        label_colors = {
+            "bug": "🔴",
+            "feature": "🟦",
+            "question": "🟣",
+            "documentation": "📘",
+            "enhancement": "✨",
+            "performance": "⚡"
+        }
+        emoji = label_colors.get(label, "🔖")
+        output += f"- {emoji} `{label}`\n"
+    output += "\n"
+
+    # Assignment
+    output += "### 👤 Suggested Assignment\n\n"
+    output += f"**{triage['suggested_assignee']}**\n\n"
+
+    # Related Areas
+    if triage['related_areas']:
+        output += "### 🔗 Related Areas\n\n"
+        for area in triage['related_areas']:
+            output += f"- {area}\n"
+        output += "\n"
+
+    # Reasoning
+    output += "### 💡 Reasoning\n\n"
+    output += f"**Labels**: {triage['reasoning']['label_reasoning']}\n\n"
+    output += f"**Priority**: {triage['reasoning']['priority_reasoning']}\n\n"
+    output += f"**Effort**: {triage['reasoning']['effort_reasoning']}\n\n"
+
+    # Next Steps
+    if triage['next_steps']:
+        output += "### ✅ Recommended Next Steps\n\n"
+        for i, step in enumerate(triage['next_steps'], 1):
+            output += f"{i}. {step}\n"
+        output += "\n"
+
+    output += "---\n*Generated by Issue Triager Agent*\n"
+
+    progress(1.0, desc="Complete!")
+
+    return output
+
+# Gradio Interface
+with gr.Blocks(theme=gr.themes.Soft(), title="GitHub Issue Triager") as demo:
+    create_premium_hero(
+        "GitHub Issue Triager Agent",
+        "Convert messy issue reports into labels, severity, priority, ownership suggestions, and reasoning.",
+        "🎫",
+        badge="Developer Operations",
+        highlights=["Structured triage", "Reasoned labels", "Agent workflow"],
+    )
+    create_method_panel({
+        "Workflow": "Issue text → classification prompt → JSON parsing → priority and routing report.",
+        "What it proves": "You can turn LLM output into operational structure, not just prose.",
+        "HF capability": "Runs as a lightweight Space over Hub-hosted instruction models.",
+    })
+
+    with gr.Row():
+        with gr.Column():
+            issue_input = gr.Textbox(
+                label="GitHub Issue",
+                placeholder="Paste issue title and description...",
+                lines=12
+            )
+            triage_btn = gr.Button("🔍 Triage Issue", variant="primary", size="lg")
+
+            gr.Examples(
+                examples=[
+                    ["""Title: App crashes on startup after login
+
+When I try to log in, the app crashes immediately. This started happening after the latest update (v2.1.0). I'm on iPhone 14, iOS 17.
+
+Steps to reproduce:
+1. Open app
+2. Enter credentials
+3. Tap login
+4. App crashes
+
+Expected: Should show dashboard
+Actual: App crashes to home screen
+
+This is blocking all users from accessing the app."""],
+                    ["""Title: Add dark mode support
+
+It would be great to have a dark mode option in the settings. Many users prefer dark mode for night-time usage and it reduces eye strain.
+
+This has been requested by multiple users in our Discord community."""],
+                    ["""Title: Documentation unclear for API authentication
+
+The docs for setting up API authentication are confusing. The example code doesn't work and there's no explanation of where to find the API key.
+
+Could we update the docs with a clearer example?"""],
+                ],
+                inputs=issue_input
+            )
+
+    with gr.Row():
+        output = gr.Markdown(label="Triage Report")
+
+    triage_btn.click(
+        fn=process_triage,
+        inputs=[issue_input],
+        outputs=[output]
+    )
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,2 @@
+gradio==4.44.0
+huggingface-hub==0.25.0

shared/components.py

@@ -0,0 +1,375 @@
+"""
+HF-Master Shared Components
+Reusable Gradio components for all projects
+"""
+
+import html
+from pathlib import Path
+import gradio as gr
+from typing import List, Tuple, Optional, Dict, Any
+
+
+class SharedComponents:
+    """Shared UI components for all HF-Master projects"""
+
+    @staticmethod
+    def _esc(value: Any) -> str:
+        """Escape text before placing it inside shared HTML components."""
+        return html.escape(str(value), quote=True)
+
+    @staticmethod
+    def _style_tag() -> str:
+        """Inline the shared stylesheet for Gradio Spaces that do not pass css=."""
+        style_path = Path(__file__).with_name("styles.css")
+        try:
+            return f"<style>{style_path.read_text(encoding='utf-8')}</style>"
+        except OSError:
+            return ""
+
+    @staticmethod
+    def create_header(title: str, description: str, emoji: str = "🚀") -> gr.Markdown:
+        """Create standardized project header"""
+        return SharedComponents.create_premium_hero(
+            title=title,
+            description=description,
+            emoji=emoji,
+            badge="AI/ML Space",
+            highlights=["Interactive demo", "Explainable workflow", "HF-ready"],
+        )
+
+    @staticmethod
+    def create_footer(version: str = "1.0.0") -> gr.Markdown:
+        """Create standardized project footer"""
+        return gr.Markdown(f"""
+<div class="hf-footer">
+  <strong>{SharedComponents._esc(version)}</strong> · Built as a practical AI/ML learning Space for the Hugging Face community.
+</div>
+""")
+
+    @staticmethod
+    def create_premium_hero(
+        title: str,
+        description: str,
+        emoji: str = "🚀",
+        badge: str = "Featured Space",
+        highlights: Optional[List[str]] = None,
+    ) -> gr.HTML:
+        """Create a richer landing-page hero for Spaces."""
+        highlights = highlights or []
+        esc = SharedComponents._esc
+        chips = "".join(
+            f"""
+            <span class="hf-chip">{esc(item)}</span>
+            """
+            for item in highlights
+        )
+
+        return gr.HTML(f"""
+{SharedComponents._style_tag()}
+<div class="hf-hero">
+  <div class="hf-hero-grid">
+    <div class="hf-hero-copy">
+      <div class="hf-icon">{esc(emoji)}</div>
+      <div>
+        <div class="hf-badge">{esc(badge)}</div>
+        <h1>{esc(title)}</h1>
+        <p>{esc(description)}</p>
+      </div>
+    </div>
+  </div>
+  <div class="hf-chip-row">
+    {chips}
+  </div>
+</div>
+""")
+
+    @staticmethod
+    def create_method_panel(items: Dict[str, str]) -> gr.HTML:
+        """Create a compact method/pipeline explainer panel."""
+        esc = SharedComponents._esc
+        cards = "".join(
+            f"""
+            <div class="hf-method-card">
+              <span>{esc(label)}</span>
+              <p>{esc(text)}</p>
+            </div>
+            """
+            for label, text in items.items()
+        )
+        return gr.HTML(f"""{SharedComponents._style_tag()}<div class="hf-method-grid">{cards}</div>""")
+
+    @staticmethod
+    def create_status_badge(status: str) -> str:
+        """Create status badge"""
+        colors = {
+            "complete": "🟢",
+            "in-progress": "🟡",
+            "planned": "⚪",
+            "experimental": "🔴"
+        }
+        return colors.get(status.lower(), "⚪")
+
+    @staticmethod
+    def create_project_card(
+        title: str,
+        description: str,
+        tech_stack: List[str],
+        difficulty: str,
+        viral_potential: str
+    ) -> str:
+        """Create markdown project card"""
+        tech_badges = " ".join([f"`{t}`" for t in tech_stack])
+
+        return f"""
+## {title}
+
+{description}
+
+**Tech Stack:** {tech_badges}
+
+**Difficulty:** {difficulty} | **Viral Potential:** {viral_potential}
+"""
+
+    @staticmethod
+    def create_risk_chart(risk_factors: Dict[str, float]) -> Any:
+        """Create risk factor visualization"""
+        import plotly.graph_objects as go
+
+        factors = list(risk_factors.keys())
+        scores = [risk_factors[f] * 100 for f in factors]
+
+        fig = go.Figure(data=[
+            go.Bar(
+                x=scores,
+                y=[f.replace('_', ' ').title() for f in factors],
+                orientation='h',
+                marker=dict(
+                    color=scores,
+                    colorscale='RdYlGn_r',
+                    cmin=0,
+                    cmax=100
+                )
+            )
+        ])
+
+        fig.update_layout(
+            title="Risk Factor Breakdown",
+            xaxis_title="Risk Score",
+            yaxis_title="Factor",
+            height=400,
+            template="plotly_white"
+        )
+
+        return fig
+
+    @staticmethod
+    def create_comparison_chart(items: List[Dict], keys: List[str]) -> Any:
+        """Create comparison visualization"""
+        import plotly.graph_objects as go
+
+        fig = go.Figure()
+
+        for i, item in enumerate(items):
+            fig.add_trace(go.Bar(
+                name=item.get('name', f'Item {i+1}'),
+                x=keys,
+                y=[item.get(k, 0) for k in keys]
+            ))
+
+        fig.update_layout(
+            barmode='group',
+            height=400
+        )
+
+        return fig
+
+    @staticmethod
+    def create_metric_card(label: str, value: str, emoji: str = "📊") -> gr.Markdown:
+        """Create metric display card"""
+        return gr.Markdown(f"""
+### {emoji} {label}
+
+**{value}**
+""")
+
+    @staticmethod
+    def create_error_display(error: str) -> gr.Markdown:
+        """Create error message display"""
+        return gr.Markdown(f"""
+❌ **Error**
+
+{error}
+""")
+
+    @staticmethod
+    def create_success_display(message: str) -> gr.Markdown:
+        """Create success message display"""
+        return gr.Markdown(f"""
+✅ **Success**
+
+{message}
+""")
+
+
+class LoadingSpinner:
+    """Loading state display"""
+
+    @staticmethod
+    def create_spinner(message: str = "Loading...") -> gr.Markdown:
+        """Create loading spinner"""
+        return gr.Markdown(f"""
+⏳ **{message}**
+
+_This may take a moment..._
+""")
+
+    @staticmethod
+    def create_progress_bar(initial: float = 0) -> gr.Markdown:
+        """Create progress display"""
+        return gr.Markdown(f"""
+░░░░░░░░░ **{initial}%**
+""")
+
+
+class TableFormatter:
+    """Format data as tables"""
+
+    @staticmethod
+    def format_dict_table(data: Dict[str, Any], headers: List[str] = None) -> List:
+        """Format dictionary as table rows"""
+        if not headers:
+            headers = ["Key", "Value"]
+
+        rows = []
+        for key, value in data.items():
+            rows.append([key, str(value)])
+
+        return [headers] + rows
+
+    @staticmethod
+    def create_dataframe(data: List[Dict], columns: List[str] = None) -> List:
+        """Create dataframe-compatible data structure"""
+        if not data:
+            return []
+
+        if columns:
+            headers = columns
+        else:
+            headers = list(data[0].keys()) if data else []
+
+        rows = [[row.get(h, "") for h in headers] for row in data]
+
+        return [headers] + rows
+
+
+class CodeHighlighter:
+    """Code display and highlighting"""
+
+    @staticmethod
+    def create_code_display(code: str, language: str = "python") -> gr.Code:
+        """Create code display block"""
+        return gr.Code(
+            value=code,
+            language=language,
+            lines=20
+        )
+
+    @staticmethod
+    def create_copy_button(code: str) -> gr.Button:
+        """Create copy-to-clipboard button"""
+        return gr.Button("📋 Copy Code")
+
+    @staticmethod
+    def create_diff_view(old_code: str, new_code: str) -> Tuple[gr.Code, gr.Code]:
+        """Create side-by-side diff view"""
+        return (
+            gr.Code(value=old_code, language="python", lines=15, label="Before"),
+            gr.Code(value=new_code, language="python", lines=15, label="After")
+        )
+
+
+def create_header(title: str, description: str, emoji: str = "🚀") -> gr.Markdown:
+    return SharedComponents.create_header(title, description, emoji)
+
+
+def create_footer(version: str = "1.0.0") -> gr.Markdown:
+    return SharedComponents.create_footer(version)
+
+
+def create_premium_hero(
+    title: str,
+    description: str,
+    emoji: str = "🚀",
+    badge: str = "Featured Space",
+    highlights: Optional[List[str]] = None,
+) -> gr.HTML:
+    return SharedComponents.create_premium_hero(title, description, emoji, badge, highlights)
+
+
+def create_method_panel(items: Dict[str, str]) -> gr.HTML:
+    return SharedComponents.create_method_panel(items)
+
+
+class ProgressTracker:
+    """Track multi-step progress"""
+
+    def __init__(self, steps: List[str]):
+        self.steps = steps
+        self.current = 0
+
+    def get_status(self) -> str:
+        """Get current status"""
+        completed = "✅ " + "\n".join(self.steps[:self.current])
+        current = f"🔄 {self.steps[self.current]}" if self.current < len(self.steps) else ""
+        remaining = "\n".join([f"⬜ {s}" for s in self.steps[self.current+1:]])
+
+        return f"""
+## Progress
+
+{completed}
+{current}
+{remaining}
+"""
+
+    def advance(self) -> bool:
+        """Move to next step"""
+        if self.current < len(self.steps):
+            self.current += 1
+            return True
+        return False
+
+    def reset(self):
+        """Reset progress"""
+        self.current = 0
+
+
+def create_tabbed_interface(tabs: Dict[str, Any]) -> gr.Blocks:
+    """Create tabbed interface helper"""
+    with gr.Blocks() as demo:
+        with gr.Tabs():
+            for tab_name, tab_content in tabs.items():
+                with gr.Tab(tab_name):
+                    tab_content
+
+    return demo
+
+
+def create_side_by_side(left_content: Any, right_content: Any) -> Tuple[gr.Column, gr.Column]:
+    """Create side-by-side layout"""
+    with gr.Row():
+        with gr.Column():
+            left_content
+        with gr.Column():
+            right_content
+
+    return left_content, right_content
+
+
+def create_accordion(items: List[Tuple[str, Any]]) -> gr.Accordion:
+    """Create accordion-style expandable sections"""
+    with gr.Accordion("Click to expand") as accordion:
+        for title, content in items:
+            gr.Markdown(f"### {title}")
+            content
+
+    return accordion

shared/styles.css

@@ -0,0 +1,425 @@
+/* HF-Master Shared Styles
+   Light research-studio system inspired by MCP Video Localizer. */
+
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap');
+
+:root {
+    --peach: #ffad7a;
+    --peach-dark: #e8935c;
+    --lavender: #b8a9d9;
+    --sky-blue: #7accff;
+    --ink: #1f2937;
+    --slate: #4b5563;
+    --muted: #6b7280;
+    --bg-light: #f9fafb;
+    --surface: #ffffff;
+    --surface-soft: #fff7f1;
+    --border-default: #e5e7eb;
+    --border-subtle: #f3f4f6;
+    --accent-subtle: rgba(255, 173, 122, 0.14);
+    --shadow-sm: 0 1px 2px rgba(31, 41, 55, 0.05);
+    --shadow-md: 0 8px 24px rgba(31, 41, 55, 0.08);
+    --shadow-lg: 0 18px 48px rgba(31, 41, 55, 0.12);
+    --radius: 8px;
+}
+
+html {
+    scroll-behavior: smooth;
+}
+
+body,
+.gradio-container {
+    background:
+        radial-gradient(circle at 7% 4%, rgba(255, 173, 122, 0.22), transparent 28%),
+        radial-gradient(circle at 88% 8%, rgba(122, 204, 255, 0.20), transparent 30%),
+        linear-gradient(180deg, #ffffff 0%, var(--bg-light) 44%, #f7f2fb 100%) !important;
+    color: var(--ink) !important;
+    font-family: Inter, "Helvetica Neue", "Segoe UI", system-ui, -apple-system, sans-serif !important;
+    font-weight: 400;
+    letter-spacing: 0;
+    -webkit-font-smoothing: antialiased;
+}
+
+.gradio-container {
+    max-width: 1180px !important;
+    margin: 0 auto !important;
+}
+
+.main,
+.block-container {
+    background: transparent !important;
+}
+
+.block-container {
+    max-width: 1180px;
+    padding-top: 2rem;
+    padding-bottom: 2rem;
+}
+
+/* Shared hero used by Gradio helpers and Streamlit HTML. */
+.hf-hero,
+.hero {
+    position: relative;
+    overflow: hidden;
+    background:
+        radial-gradient(circle at 20% 8%, rgba(255, 255, 255, 0.52), transparent 26%),
+        linear-gradient(135deg, var(--peach) 0%, var(--lavender) 54%, var(--sky-blue) 100%);
+    border: 1px solid rgba(255, 255, 255, 0.72);
+    border-radius: 16px;
+    box-shadow: var(--shadow-lg), 0 0 34px rgba(255, 173, 122, 0.18);
+    color: #ffffff;
+    margin: 1rem 0 1.25rem 0;
+    padding: clamp(1.25rem, 3vw, 2.25rem);
+}
+
+.hf-hero::after,
+.hero::after {
+    content: "";
+    position: absolute;
+    inset: auto -12% -45% auto;
+    width: 360px;
+    height: 360px;
+    background: rgba(255, 255, 255, 0.22);
+    border-radius: 999px;
+    pointer-events: none;
+}
+
+.hf-hero-grid,
+.hf-hero-copy {
+    position: relative;
+    z-index: 1;
+}
+
+.hf-hero-copy {
+    display: flex;
+    align-items: flex-start;
+    gap: 1rem;
+}
+
+.hf-icon {
+    align-items: center;
+    background: rgba(255, 255, 255, 0.24);
+    border: 1px solid rgba(255, 255, 255, 0.45);
+    border-radius: 8px;
+    box-shadow: var(--shadow-sm);
+    display: inline-flex;
+    flex: 0 0 auto;
+    font-size: 1.7rem;
+    height: 3.75rem;
+    justify-content: center;
+    width: 3.75rem;
+}
+
+.hf-badge {
+    background: rgba(255, 255, 255, 0.22);
+    border: 1px solid rgba(255, 255, 255, 0.42);
+    border-radius: 999px;
+    color: rgba(255, 255, 255, 0.96);
+    display: inline-flex;
+    font-size: 0.76rem;
+    font-weight: 800;
+    letter-spacing: 0.06em;
+    margin-bottom: 0.7rem;
+    padding: 0.34rem 0.7rem;
+    text-transform: uppercase;
+}
+
+.hf-hero h1,
+.hero h1 {
+    color: #ffffff !important;
+    font-size: clamp(2rem, 4vw, 3.35rem);
+    font-weight: 800;
+    letter-spacing: 0;
+    line-height: 1.04;
+    margin: 0 0 0.45rem 0;
+    text-shadow: 0 2px 12px rgba(31, 41, 55, 0.18);
+}
+
+.hf-hero p,
+.hero p {
+    color: rgba(255, 255, 255, 0.96) !important;
+    font-size: 1.03rem;
+    line-height: 1.65;
+    margin: 0;
+    max-width: 68ch;
+}
+
+.hf-chip-row,
+.pill-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.55rem;
+    margin-top: 1.15rem;
+    position: relative;
+    z-index: 1;
+}
+
+.hf-chip,
+.badge,
+.tech-tag {
+    background: rgba(255, 255, 255, 0.24);
+    border: 1px solid rgba(255, 255, 255, 0.45);
+    border-radius: 999px;
+    color: #ffffff;
+    display: inline-flex;
+    font-size: 0.86rem;
+    font-weight: 700;
+    padding: 0.42rem 0.75rem;
+}
+
+.hf-method-grid {
+    display: grid;
+    gap: 0.9rem;
+    grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+    margin: 1rem 0;
+}
+
+.hf-method-card,
+.glass-card,
+.project-card,
+.info-card,
+.metric-card,
+.stat-box,
+.gradio-container .form,
+.gradio-container .panel {
+    background: rgba(255, 255, 255, 0.88) !important;
+    border: 1px solid var(--border-default) !important;
+    border-radius: var(--radius) !important;
+    box-shadow: var(--shadow-md) !important;
+}
+
+.hf-method-card {
+    padding: 1rem;
+}
+
+.hf-method-card span {
+    color: var(--peach-dark);
+    display: block;
+    font-size: 0.78rem;
+    font-weight: 800;
+    letter-spacing: 0.04em;
+    margin-bottom: 0.35rem;
+    text-transform: uppercase;
+}
+
+.hf-method-card p {
+    color: var(--slate);
+    line-height: 1.55;
+    margin: 0;
+}
+
+.project-card,
+.info-card,
+.metric-card,
+.stat-box {
+    padding: 1rem;
+}
+
+h1,
+h2,
+h3,
+h4,
+.markdown-text h1,
+.markdown-text h2,
+.markdown-text h3 {
+    color: var(--ink) !important;
+    font-family: Inter, "Helvetica Neue", system-ui, sans-serif !important;
+    letter-spacing: 0;
+}
+
+p,
+li,
+label,
+.markdown-text,
+.markdown-text p,
+.markdown-text span {
+    color: var(--slate) !important;
+    font-family: Inter, "Helvetica Neue", system-ui, sans-serif !important;
+}
+
+strong {
+    color: var(--ink);
+    font-weight: 700;
+}
+
+input,
+select,
+textarea,
+.gr-textbox,
+.gr-dropdown {
+    background: #ffffff !important;
+    border: 1px solid var(--border-default) !important;
+    border-radius: var(--radius) !important;
+    color: var(--ink) !important;
+    font-family: Inter, "Helvetica Neue", system-ui, sans-serif !important;
+    transition: border-color 0.15s ease, box-shadow 0.15s ease !important;
+}
+
+input:focus,
+select:focus,
+textarea:focus,
+.gr-textbox:focus {
+    border-color: var(--peach) !important;
+    box-shadow: 0 0 0 3px var(--accent-subtle) !important;
+    outline: none !important;
+}
+
+button.primary,
+button[class*="primary"],
+div[data-testid="stButton"] > button {
+    background: linear-gradient(135deg, var(--peach) 0%, var(--peach-dark) 100%) !important;
+    border: 0 !important;
+    border-radius: var(--radius) !important;
+    box-shadow: 0 8px 20px rgba(255, 173, 122, 0.28) !important;
+    color: #ffffff !important;
+    font-family: Inter, "Helvetica Neue", system-ui, sans-serif !important;
+    font-weight: 800 !important;
+    padding: 0.72rem 1.1rem !important;
+    transition: transform 0.18s ease, box-shadow 0.18s ease !important;
+}
+
+button.primary:hover,
+button[class*="primary"]:hover,
+div[data-testid="stButton"] > button:hover {
+    box-shadow: 0 12px 26px rgba(255, 173, 122, 0.36) !important;
+    transform: translateY(-1px) !important;
+}
+
+button.secondary,
+button[class*="secondary"] {
+    background: #ffffff !important;
+    border: 1px solid var(--border-default) !important;
+    border-radius: var(--radius) !important;
+    color: var(--ink) !important;
+    font-weight: 700 !important;
+}
+
+code,
+pre {
+    border-radius: var(--radius) !important;
+}
+
+code {
+    background: #fff2e8 !important;
+    color: #9a4f1f !important;
+}
+
+pre {
+    background: #111827 !important;
+    border: 1px solid #273244 !important;
+    color: #f9fafb !important;
+}
+
+table {
+    border-collapse: collapse;
+    width: 100%;
+}
+
+th {
+    background: #fff2e8;
+    color: var(--ink);
+    font-weight: 800;
+}
+
+td,
+th {
+    border-bottom: 1px solid var(--border-default);
+    padding: 0.7rem;
+}
+
+blockquote,
+.markdown-text blockquote {
+    background: #faf9fc !important;
+    border-left: 3px solid var(--lavender) !important;
+    border-radius: 0 var(--radius) var(--radius) 0 !important;
+    color: var(--slate) !important;
+    margin: 0.5rem 0 !important;
+    padding: 0.75rem 1rem !important;
+}
+
+a {
+    color: #2774a9 !important;
+    font-weight: 700;
+}
+
+.hf-footer {
+    border-top: 1px solid var(--border-default);
+    color: var(--muted);
+    font-size: 0.92rem;
+    margin-top: 1.5rem;
+    padding: 1rem 0;
+    text-align: center;
+}
+
+.hf-footer strong {
+    color: var(--ink);
+}
+
+/* Streamlit shell polish. */
+div[data-testid="stHeader"],
+div[data-testid="stToolbar"] {
+    background: transparent !important;
+}
+
+div[data-testid="stSidebar"] {
+    background: rgba(255, 255, 255, 0.82) !important;
+    border-right: 1px solid var(--border-default);
+}
+
+div[data-baseweb="input"],
+div[data-baseweb="textarea"],
+div[data-baseweb="select"] {
+    background: #ffffff !important;
+}
+
+div[data-testid="stTextInput"] input,
+div[data-testid="stTextArea"] textarea,
+div[data-testid="stSelectbox"] div {
+    border-radius: var(--radius) !important;
+    border-color: var(--border-default) !important;
+}
+
+div[data-testid="stMetric"] {
+    background: rgba(255, 255, 255, 0.9);
+    border: 1px solid var(--border-default);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow-md);
+    padding: 0.8rem 1rem;
+}
+
+.stPlotlyChart {
+    background: rgba(255, 255, 255, 0.86);
+    border: 1px solid var(--border-default);
+    border-radius: var(--radius);
+    box-shadow: var(--shadow-sm);
+    padding: 0.3rem;
+}
+
+@keyframes fadeIn {
+    from {
+        opacity: 0;
+        transform: translateY(8px);
+    }
+    to {
+        opacity: 1;
+        transform: translateY(0);
+    }
+}
+
+.hf-hero,
+.hf-method-card,
+.metric-card,
+.info-card {
+    animation: fadeIn 0.28s ease-out;
+}
+
+@media (max-width: 720px) {
+    .hf-hero-copy {
+        flex-direction: column;
+    }
+
+    .hf-icon {
+        height: 3.2rem;
+        width: 3.2rem;
+    }
+}

shared/utils.py

@@ -0,0 +1,366 @@
+"""
+HF-Master Shared Utilities
+Helper functions for all projects
+"""
+
+import os
+import re
+import json
+import hashlib
+from typing import Dict, List, Optional, Any, Union
+from datetime import datetime
+from pathlib import Path
+import sqlite3
+
+
+def load_env(var_name: str, default: Optional[str] = None) -> Optional[str]:
+    """Load environment variable with optional default"""
+    return os.getenv(var_name, default)
+
+
+def load_api_key(provider: str = "openai") -> Optional[str]:
+    """Load API key for specified provider"""
+    key_map = {
+        "openai": "OPENAI_API_KEY",
+        "anthropic": "ANTHROPIC_API_KEY",
+        "huggingface": "HF_TOKEN",
+        "cohere": "COHERE_API_KEY",
+        "together": "TOGETHER_API_KEY"
+    }
+
+    env_var = key_map.get(provider.lower())
+    if env_var:
+        return load_env(env_var)
+
+    return None
+
+
+def estimate_token_count(text: str, model: str = "gpt-4") -> int:
+    """Estimate token count for text"""
+    tokens_per_word = {
+        "gpt-4": 4,      # ~4 chars per token
+        "gpt-3.5": 4,
+        "claude": 4,
+        "llama": 3       # More efficient
+    }
+
+    chars_per_token = tokens_per_word.get(model, 4)
+    return len(text) // chars_per_token
+
+
+def estimate_tokens(text: str, model: str = "gpt-4") -> int:
+    """Backward-compatible alias used by older apps"""
+    return estimate_token_count(text, model)
+
+
+def calculate_api_cost(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    provider: str = "openai"
+) -> float:
+    """Calculate API cost for model usage"""
+
+    pricing = {
+        "openai": {
+            "gpt-4": {"input": 0.03, "output": 0.06},
+            "gpt-3.5-turbo": {"input": 0.001, "output": 0.002},
+            "gpt-4-turbo": {"input": 0.01, "output": 0.03}
+        },
+        "anthropic": {
+            "claude-3-opus": {"input": 0.015, "output": 0.075},
+            "claude-3-sonnet": {"input": 0.003, "output": 0.015}
+        }
+    }
+
+    provider_pricing = pricing.get(provider, {})
+    model_pricing = provider_pricing.get(model, {"input": 0.01, "output": 0.03})
+
+    input_cost = (input_tokens / 1000) * model_pricing["input"]
+    output_cost = (output_tokens / 1000) * model_pricing["output"]
+
+    return input_cost + output_cost
+
+
+def calculate_cost(tokens: int, model: str = "gpt-4", provider: str = "openai") -> float:
+    """Backward-compatible alias used by older apps"""
+    return calculate_api_cost(model=model, input_tokens=tokens, output_tokens=0, provider=provider)
+
+
+def sanitize_filename(name: str) -> str:
+    """Convert string to safe filename"""
+    name = name.lower().strip()
+    name = re.sub(r'[^\w\s-]', '', name)
+    name = re.sub(r'[\s]+', '-', name)
+    return name
+
+
+def create_hash(text: str, length: int = 8) -> str:
+    """Create short hash from text"""
+    return hashlib.md5(text.encode()).hexdigest()[:length]
+
+
+def format_duration(seconds: float) -> str:
+    """Format duration in human-readable form"""
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    elif seconds < 3600:
+        return f"{seconds/60:.1f}m"
+    else:
+        return f"{seconds/3600:.1f}h"
+
+
+def format_bytes(bytes: int) -> str:
+    """Format bytes in human-readable form"""
+    for unit in ['B', 'KB', 'MB', 'GB', 'TB']:
+        if bytes < 1024:
+            return f"{bytes:.1f} {unit}"
+        bytes /= 1024
+    return f"{bytes:.1f} PB"
+
+
+def truncate_text(text: str, max_length: int = 100, suffix: str = "...") -> str:
+    """Truncate text with suffix"""
+    if len(text) <= max_length:
+        return text
+    return text[:max_length - len(suffix)] + suffix
+
+
+def parse_dice_notation(notation: str) -> Dict[str, Any]:
+    """Parse dice notation like 2d6+3"""
+    match = re.match(r'(\d+)d(\d+)(kh\d+)?([+-]\d+)?', notation.upper())
+    if not match:
+        raise ValueError(f"Invalid dice notation: {notation}")
+
+    num_dice = int(match.group(1))
+    die_size = int(match.group(2))
+    keep_high = match.group(3)
+    modifier = int(match.group(4)) if match.group(4) else 0
+
+    return {
+        "num_dice": num_dice,
+        "die_size": die_size,
+        "keep_high": keep_high,
+        "modifier": modifier
+    }
+
+
+def roll_dice(notation: str) -> List[int]:
+    """Roll dice and return individual rolls"""
+    import random
+
+    parsed = parse_dice_notation(notation)
+    rolls = [random.randint(1, parsed["die_size"]) for _ in range(parsed["num_dice"])]
+
+    if parsed["keep_high"]:
+        keep = int(parsed["keep_high"][2:])
+        rolls = sorted(rolls, reverse=True)[:keep]
+
+    return rolls
+
+
+def calculate_modifier(ability_score: int) -> int:
+    """Calculate D&D ability modifier from score"""
+    return (ability_score - 10) // 2
+
+
+def validate_ethereum_address(address: str) -> bool:
+    """Validate Ethereum address format"""
+    pattern = r'^0x[a-fA-F0-9]{40}$'
+    return bool(re.match(pattern, address))
+
+
+def validate_solana_address(address: str) -> bool:
+    """Validate Solana address format"""
+    pattern = r'^[1-9A-HJ-NP-Za-km-z]{32,44}$'
+    return bool(re.match(pattern, address))
+
+
+def extract_urls(text: str) -> List[str]:
+    """Extract URLs from text"""
+    url_pattern = r'https?://[^\s<>"{}|\\^`\[\]]+'
+    return re.findall(url_pattern, text)
+
+
+def extract_code_blocks(text: str) -> List[str]:
+    """Extract code blocks from markdown text"""
+    pattern = r'```(?:\w+)?\n(.*?)```'
+    return re.findall(pattern, text, re.DOTALL)
+
+
+def parse_math_expression(expr: str) -> float:
+    """Safely evaluate simple math expressions"""
+    allowed_chars = set("0123456789+-*/.() ")
+    if all(c in allowed_chars for c in expr):
+        return eval(expr)
+    raise ValueError(f"Unsafe expression: {expr}")
+
+
+def create_timer(func):
+    """Decorator to time function execution"""
+    import time
+    from functools import wraps
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start = time.time()
+        result = func(*args, **kwargs)
+        duration = time.time() - start
+        print(f"{func.__name__} took {format_duration(duration)}")
+        return result
+
+    return wrapper
+
+
+def retry_on_failure(max_attempts: int = 3, delay: float = 1.0):
+    """Decorator to retry function on failure"""
+    from functools import wraps
+    import time
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    if attempt == max_attempts - 1:
+                        raise
+                    time.sleep(delay * (attempt + 1))
+
+        return wrapper
+
+    return decorator
+
+
+class SimpleCache:
+    """Simple in-memory cache"""
+
+    def __init__(self, max_size: int = 100):
+        self.cache: Dict[str, Any] = {}
+        self.max_size = max_size
+        self.access_times: Dict[str, datetime] = {}
+
+    def get(self, key: str) -> Optional[Any]:
+        """Get value from cache"""
+        if key in self.cache:
+            self.access_times[key] = datetime.now()
+            return self.cache[key]
+        return None
+
+    def set(self, key: str, value: Any):
+        """Set value in cache"""
+        if len(self.cache) >= self.max_size:
+            oldest = min(self.access_times.items(), key=lambda x: x[1])[0]
+            del self.cache[oldest]
+            del self.access_times[oldest]
+
+        self.cache[key] = value
+        self.access_times[key] = datetime.now()
+
+    def clear(self):
+        """Clear cache"""
+        self.cache.clear()
+        self.access_times.clear()
+
+
+class Database:
+    """Simple SQLite wrapper"""
+
+    def __init__(self, db_path: str = "data.db"):
+        self.db_path = db_path
+        Path(db_path).parent.mkdir(parents=True, exist_ok=True)
+        self.conn = None
+
+    def connect(self):
+        """Connect to database"""
+        self.conn = sqlite3.connect(self.db_path)
+        self.conn.row_factory = sqlite3.Row
+
+    def close(self):
+        """Close database connection"""
+        if self.conn:
+            self.conn.close()
+
+    def execute(self, query: str, params: tuple = ()) -> sqlite3.Cursor:
+        """Execute query"""
+        if not self.conn:
+            self.connect()
+        return self.conn.execute(query, params)
+
+    def commit(self):
+        """Commit transaction"""
+        if self.conn:
+            self.conn.commit()
+
+    def fetchall(self, query: str, params: tuple = ()) -> List[Dict]:
+        """Fetch all results"""
+        cursor = self.execute(query, params)
+        return [dict(row) for row in cursor.fetchall()]
+
+    def fetchone(self, query: str, params: tuple = ()) -> Optional[Dict]:
+        """Fetch one result"""
+        cursor = self.execute(query, params)
+        row = cursor.fetchone()
+        return dict(row) if row else None
+
+    def create_table(self, name: str, columns: Dict[str, str]):
+        """Create table with columns"""
+        cols = ", ".join([f"{k} {v}" for k, v in columns.items()])
+        self.execute(f"CREATE TABLE IF NOT EXISTS {name} ({cols})")
+        self.commit()
+
+
+def load_json_file(filepath: str) -> Dict:
+    """Load JSON file"""
+    with open(filepath, 'r') as f:
+        return json.load(f)
+
+
+def save_json_file(data: Dict, filepath: str):
+    """Save JSON file"""
+    Path(filepath).parent.mkdir(parents=True, exist_ok=True)
+    with open(filepath, 'w') as f:
+        json.dump(data, f, indent=2)
+
+
+def merge_dicts(*dicts: Dict) -> Dict:
+    """Merge multiple dictionaries"""
+    result = {}
+    for d in dicts:
+        result.update(d)
+    return result
+
+
+def flatten_list(nested: List[Any]) -> List[Any]:
+    """Flatten nested list"""
+    result = []
+    for item in nested:
+        if isinstance(item, list):
+            result.extend(flatten_list(item))
+        else:
+            result.append(item)
+    return result
+
+
+def chunk_text(text: str, chunk_size: int, overlap: int = 0) -> List[str]:
+    """Split text into overlapping chunks"""
+    chunks = []
+    start = 0
+
+    while start < len(text):
+        end = start + chunk_size
+        chunks.append(text[start:end])
+        start = end - overlap
+
+    return chunks
+
+
+def get_project_root() -> Path:
+    """Get project root directory"""
+    return Path(__file__).parent.parent
+
+
+def ensure_dir(path: str):
+    """Ensure directory exists"""
+    Path(path).mkdir(parents=True, exist_ok=True)