Deploy Benchmark Builder

README.md

@@ -1,12 +1,61 @@
 ---
 title: Benchmark Builder
-emoji: 🚀
-colorFrom: green
-colorTo: yellow
+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
+# Benchmark Builder
+
+## Question
+
+How do we create small evaluation datasets without filling them with weak distractors?
+
+## System Boundary
+
+This Space is an evaluation-data workbench for multiple-choice questions. It helps author questions, generate distractors, audit answer quality, and export the result.
+
+## Method
+
+The app accepts a question, correct answer, subject, difficulty, and rationale. It uses Hugging Face inference when `HF_TOKEN` is available and a deterministic fallback otherwise. It then audits duplicate choices, answer leakage, length balance, and question-stem quality.
+
+## Technique
+
+This is evaluation-set construction. The system treats each question as a data object with a correct answer, distractors, rationale, and quality checks.
+
+The distractor audit is important because weak distractors inflate model scores and make a benchmark look easier than it is.
+
+## Output
+
+The app returns a benchmark item preview, quality-check table, JSON, JSONL, or a Hugging Face Dataset push script.
+
+## Why It Matters
+
+Evaluation quality is a bottleneck in LLM work. Small, inspectable benchmarks are often more useful than large opaque ones.
+
+## What To Notice
+
+Good distractors should be plausible but wrong. If one option is obviously different in length, style, or vocabulary, the benchmark is leaking hints.
+
+## Effect In Practice
+
+This workflow can help teams build focused evals for retrieval, domain knowledge, safety, or product-specific behavior before running model comparisons.
+
+## Hugging Face Extension
+
+The generated examples can become a Hub Dataset with splits, dataset card, baseline model scores, and a Space leaderboard.
+
+## Limitations
+
+Generated distractors still need human review. Real benchmarks should include calibration, held-out validation, model baselines, and documentation of dataset scope.
+
+## Run Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,308 @@
+"""
+Benchmark Builder
+Create small, auditable multiple-choice evaluation datasets for LLMs.
+"""
+
+import json
+import os
+import re
+import sys
+from typing import Dict, List, Tuple
+
+import gradio as gr
+
+sys.path.append(os.path.join(os.path.dirname(__file__), ".."))
+from shared.components import create_footer, create_method_panel, create_premium_hero
+
+
+try:
+    from huggingface_hub import InferenceClient
+except Exception:  # pragma: no cover - optional on local machines
+    InferenceClient = None
+
+
+SEED_QUESTIONS = [
+    {
+        "question": "Which retrieval signal is strongest when a user query uses rare exact terms?",
+        "correct_answer": "BM25 lexical matching",
+        "distractors": [
+            "Random negative sampling",
+            "Temperature scaling",
+            "Decoder-only attention masking",
+        ],
+        "subject": "Information Retrieval",
+        "difficulty": "Medium",
+        "rationale": "BM25 rewards rare exact terms through inverse document frequency.",
+    }
+]
+
+DOMAIN_DISTRACTORS = {
+    "Machine Learning": [
+        "dropout regularization",
+        "batch normalization",
+        "cosine learning-rate decay",
+        "gradient clipping",
+        "early stopping",
+        "teacher forcing",
+    ],
+    "Information Retrieval": [
+        "dense vector search",
+        "query expansion",
+        "reciprocal rank fusion",
+        "cross-encoder reranking",
+        "metadata filtering",
+        "semantic chunking",
+    ],
+    "AI Safety": [
+        "output filtering",
+        "least-privilege tool access",
+        "prompt isolation",
+        "red-team evaluation",
+        "policy classification",
+        "adversarial testing",
+    ],
+    "Data Engineering": [
+        "schema validation",
+        "deduplication",
+        "entity resolution",
+        "partition pruning",
+        "incremental backfills",
+        "lineage tracking",
+    ],
+}
+
+
+def _hf_generate(prompt: str) -> List[str]:
+    """Use HF Inference when configured; otherwise return an empty list."""
+    token = os.getenv("HF_TOKEN") or os.getenv("HUGGINGFACEHUB_API_TOKEN")
+    if not token or InferenceClient is None:
+        return []
+
+    client = InferenceClient(model="mistralai/Mistral-7B-Instruct-v0.3", token=token)
+    response = client.text_generation(prompt, max_new_tokens=220, temperature=0.35)
+    match = re.search(r"\[[\s\S]*\]", response)
+    if not match:
+        return []
+    try:
+        parsed = json.loads(match.group(0))
+    except json.JSONDecodeError:
+        return []
+    return [str(item).strip() for item in parsed if str(item).strip()][:3]
+
+
+def _fallback_distractors(question: str, correct_answer: str, subject: str) -> List[str]:
+    pool = DOMAIN_DISTRACTORS.get(subject, DOMAIN_DISTRACTORS["Machine Learning"])
+    answer_terms = {term.lower() for term in re.findall(r"[A-Za-z][A-Za-z\-]+", correct_answer)}
+    chosen = []
+    for candidate in pool:
+        candidate_terms = {term.lower() for term in re.findall(r"[A-Za-z][A-Za-z\-]+", candidate)}
+        if candidate.lower() != correct_answer.lower() and not answer_terms.intersection(candidate_terms):
+            chosen.append(candidate)
+        if len(chosen) == 3:
+            break
+
+    if len(chosen) < 3:
+        chosen.extend(["a plausible baseline method", "a purely random heuristic", "a manual review process"])
+
+    if re.search(r"\bwhich\b|\bwhat\b", question.lower()):
+        return [item[:1].upper() + item[1:] for item in chosen[:3]]
+    return chosen[:3]
+
+
+def generate_distractors(question: str, correct_answer: str, subject: str, difficulty: str) -> Tuple[List[str], str]:
+    prompt = f"""
+You create benchmark-quality multiple-choice distractors.
+Return only a JSON array of exactly 3 short wrong answers.
+Subject: {subject}
+Difficulty: {difficulty}
+Question: {question}
+Correct answer: {correct_answer}
+Distractors must be plausible, mutually distinct, and not reveal the answer.
+"""
+    generated = _hf_generate(prompt)
+    source = "HF Inference model" if len(generated) == 3 else "deterministic local heuristic"
+    distractors = generated if len(generated) == 3 else _fallback_distractors(question, correct_answer, subject)
+    return distractors, source
+
+
+def audit_question(question: str, correct_answer: str, distractors: List[str]) -> List[Dict[str, str]]:
+    options = [correct_answer] + distractors
+    lower_options = [option.strip().lower() for option in options]
+    checks = []
+
+    checks.append({
+        "check": "Duplicate options",
+        "result": "pass" if len(set(lower_options)) == len(lower_options) else "review",
+        "detail": "All answer choices are unique." if len(set(lower_options)) == len(lower_options) else "At least two choices are identical.",
+    })
+
+    answer_words = set(re.findall(r"[a-zA-Z]{4,}", correct_answer.lower()))
+    leaked = any(answer_words.intersection(set(re.findall(r"[a-zA-Z]{4,}", d.lower()))) for d in distractors)
+    checks.append({
+        "check": "Answer leakage",
+        "result": "review" if leaked else "pass",
+        "detail": "A distractor shares key answer terms." if leaked else "Distractors avoid obvious answer words.",
+    })
+
+    lengths = [len(option) for option in options]
+    balanced = max(lengths) - min(lengths) <= max(18, len(correct_answer))
+    checks.append({
+        "check": "Length balance",
+        "result": "pass" if balanced else "review",
+        "detail": "Choices have comparable length." if balanced else "One option is much longer or shorter than the rest.",
+    })
+
+    stem_ok = len(question.strip()) >= 24 and question.strip().endswith("?")
+    checks.append({
+        "check": "Question stem",
+        "result": "pass" if stem_ok else "review",
+        "detail": "Stem is specific and phrased as a question." if stem_ok else "Make the stem more specific and end it with a question mark.",
+    })
+    return checks
+
+
+def render_question(question_data: Dict[str, object]) -> str:
+    letters = "ABCD"
+    options = [question_data["correct_answer"]] + question_data["distractors"]
+    option_html = ""
+    for idx, option in enumerate(options):
+        is_answer = option == question_data["correct_answer"]
+        option_html += f"""
+        <div class="info-card" style="margin:0.55rem 0; border-left:4px solid {'#22c55e' if is_answer else '#e5e7eb'} !important;">
+          <strong>{letters[idx]}.</strong> {option}
+          {'<span style="float:right; color:#15803d; font-weight:800;">answer</span>' if is_answer else ''}
+        </div>
+        """
+
+    return f"""
+    <div class="info-card">
+      <p style="margin:0 0 0.4rem 0; color:#e8935c; font-weight:800;">{question_data['subject']} · {question_data['difficulty']}</p>
+      <h3 style="margin-top:0;">{question_data['question']}</h3>
+      {option_html}
+      <p><strong>Rationale:</strong> {question_data['rationale']}</p>
+      <p><strong>Distractor source:</strong> {question_data['source']}</p>
+    </div>
+    """
+
+
+def render_audit(checks: List[Dict[str, str]]) -> str:
+    lines = ["| Check | Result | Detail |", "|---|---|---|"]
+    for check in checks:
+        badge = "Pass" if check["result"] == "pass" else "Review"
+        lines.append(f"| {check['check']} | {badge} | {check['detail']} |")
+    return "\n".join(lines)
+
+
+def add_question(
+    question: str,
+    correct_answer: str,
+    subject: str,
+    difficulty: str,
+    rationale: str,
+    state: List[Dict[str, object]],
+):
+    if not question or not correct_answer:
+        return state, "Add a question and correct answer first.", "", ""
+
+    distractors, source = generate_distractors(question, correct_answer, subject, difficulty)
+    item = {
+        "question": question.strip(),
+        "correct_answer": correct_answer.strip(),
+        "distractors": distractors,
+        "subject": subject,
+        "difficulty": difficulty,
+        "rationale": rationale.strip() or "Add a short rationale before publishing this benchmark.",
+        "source": source,
+    }
+    next_state = [*state, item]
+    checks = audit_question(item["question"], item["correct_answer"], item["distractors"])
+    status = f"Dataset now has {len(next_state)} questions. Review flags before publishing."
+    return next_state, status, render_question(item), render_audit(checks)
+
+
+def export_benchmark(benchmark_name: str, state: List[Dict[str, object]], export_format: str) -> str:
+    safe_name = re.sub(r"[^a-zA-Z0-9_\-/]", "-", benchmark_name.strip() or "my-eval-benchmark")
+    rows = state or SEED_QUESTIONS
+
+    if export_format == "JSONL":
+        return "\n".join(json.dumps(row, ensure_ascii=False) for row in rows)
+
+    if export_format == "HF Dataset Script":
+        return f"""from datasets import Dataset
+
+rows = {json.dumps(rows, indent=2)}
+dataset = Dataset.from_list(rows)
+dataset.push_to_hub("{safe_name}")
+"""
+
+    return json.dumps({"name": safe_name, "questions": rows, "total": len(rows)}, indent=2)
+
+
+with gr.Blocks(title="Benchmark Builder", theme=gr.themes.Soft()) as app:
+    state = gr.State(SEED_QUESTIONS)
+    create_premium_hero(
+        "Benchmark Builder",
+        "Design small, inspectable evaluation sets with plausible distractors, quality checks, and Hugging Face Dataset export.",
+        "📊",
+        badge="Evaluation Engineering",
+        highlights=["Optional HF inference", "Distractor audit", "Dataset push script"],
+    )
+    create_method_panel({
+        "Technique": "LLM-assisted benchmark authoring with deterministic guardrails.",
+        "What it proves": "You understand evaluation data quality, not just prompt generation.",
+        "HF capability": "Ready to publish as a Dataset and evaluate models on the Hub.",
+    })
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            question_input = gr.Textbox(
+                label="Question",
+                value="Which retrieval signal is strongest when a user query uses rare exact terms?",
+                lines=3,
+            )
+            answer_input = gr.Textbox(label="Correct answer", value="BM25 lexical matching")
+            subject = gr.Dropdown(
+                choices=list(DOMAIN_DISTRACTORS.keys()),
+                value="Information Retrieval",
+                label="Subject",
+            )
+            difficulty = gr.Radio(["Easy", "Medium", "Hard"], value="Medium", label="Difficulty")
+            rationale = gr.Textbox(
+                label="Rationale",
+                value="BM25 rewards rare exact terms through inverse document frequency.",
+                lines=2,
+            )
+            add_btn = gr.Button("Generate Distractors + Audit", variant="primary")
+        with gr.Column(scale=1):
+            status_output = gr.Markdown("Add a question to generate a benchmark-ready item.")
+            preview_output = gr.HTML(render_question({**SEED_QUESTIONS[0], "source": "seed example"}))
+            audit_output = gr.Markdown(render_audit(audit_question(
+                SEED_QUESTIONS[0]["question"],
+                SEED_QUESTIONS[0]["correct_answer"],
+                SEED_QUESTIONS[0]["distractors"],
+            )))
+
+    add_btn.click(
+        add_question,
+        inputs=[question_input, answer_input, subject, difficulty, rationale, state],
+        outputs=[state, status_output, preview_output, audit_output],
+    )
+
+    gr.Markdown("## Export")
+    with gr.Row():
+        benchmark_name = gr.Textbox(label="Hub dataset name", value="username/retrieval-mini-eval")
+        export_format = gr.Dropdown(["JSON", "JSONL", "HF Dataset Script"], value="JSON", label="Format")
+    export_btn = gr.Button("Generate Export", variant="secondary")
+    export_output = gr.Code(label="Benchmark artifact", language="python", lines=16)
+    export_btn.click(export_benchmark, inputs=[benchmark_name, state, export_format], outputs=export_output)
+
+    gr.Markdown("""
+## Why This Is Useful
+
+Evaluation sets fail quietly when distractors are weak, duplicated, or reveal the answer. This Space teaches a better workflow: generate candidates, audit them, keep rationales, and publish the result as a versioned Hugging Face Dataset.
+""")
+    create_footer("Benchmark Builder")
+
+
+if __name__ == "__main__":
+    app.launch(server_name="0.0.0.0", server_port=7860)

requirements.txt

@@ -0,0 +1,2 @@
+gradio>=4.0.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)