Deploy Code Search Engine

README.md

@@ -1,12 +1,61 @@
 ---
 title: Code Search Engine
-emoji: 🐠
-colorFrom: pink
+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
+# Code Search Engine
+
+## Question
+
+Can we search code by intent instead of exact identifiers?
+
+## System Boundary
+
+This Space is a small semantic code retrieval demo. It does not attempt full repository understanding; it focuses on embedding snippets and ranking them against natural-language queries.
+
+## Method
+
+Code samples are loaded from a Hub dataset, embedded with a code-oriented transformer, and compared to the embedded user query. Results are syntax-highlighted so the returned artifact is readable.
+
+## Technique
+
+Code search uses representation learning to place code and natural language in a shared semantic space. The query "read csv and group by column" can retrieve code even if the function is not named that way.
+
+This is a retrieval problem before it is a generation problem. Good code assistants need to find the right context before they can edit or explain it.
+
+## Output
+
+The app returns ranked code snippets, similarity scores, metadata, and highlighted source text.
+
+## Why It Matters
+
+Developer tools increasingly depend on code intelligence: semantic search, repair, generation, review, and retrieval-augmented coding. This Space isolates the retrieval layer.
+
+## What To Notice
+
+Look for whether retrieved code matches intent or only shares surface words. A strong embedding model should recover functional similarity.
+
+## Effect In Practice
+
+Semantic code retrieval can power internal codebase search, example discovery, migration tools, and coding-agent context selection.
+
+## Hugging Face Extension
+
+This can grow into a code-search evaluation Space using query-snippet relevance labels and comparing CodeBERT-style embeddings against newer code embedding models.
+
+## Limitations
+
+The demo uses a sampled dataset and a single embedding model. Production code search should parse symbols, track repository context, index dependencies, and evaluate relevance with developer judgments.
+
+## Run Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,311 @@
+import gradio as gr
+from datasets import load_dataset
+from sentence_transformers import SentenceTransformer
+import numpy as np
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name, guess_lexer
+from pygments.formatters import HtmlFormatter
+import re
+import os
+import sys
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+from shared.components import create_method_panel, create_premium_hero
+
+# Load code-specific model
+embedder = SentenceTransformer('microsoft/codebert-base')
+
+# Global storage
+dataset_sample = None
+embeddings = None
+code_samples = []
+
+def load_code_dataset(progress=gr.Progress()):
+    """Load a sample of The Stack dataset."""
+    global dataset_sample, embeddings, code_samples
+
+    progress(0, desc="Loading The Stack dataset...")
+    try:
+        # Load Python subset (smaller and more accessible)
+        dataset_sample = load_dataset(
+            "bigcode/the-stack-smol",
+            data_dir="data/python",
+            split="train",
+            streaming=True
+        )
+
+        # Take first 500 samples
+        code_samples = []
+        progress(0.3, desc="Sampling code repositories...")
+        for i, item in enumerate(dataset_sample):
+            if i >= 500:
+                break
+
+            code = item.get('content', '')
+            if len(code) < 50 or len(code) > 5000:  # Filter very short/long
+                continue
+
+            code_samples.append({
+                'code': code,
+                'language': 'python',
+                'size': len(code),
+                'max_stars_repo_name': item.get('max_stars_repo_name', 'unknown'),
+                'max_stars_count': item.get('max_stars_count', 0),
+                'license': item.get('max_stars_repo_licenses', ['unknown'])[0] if item.get('max_stars_repo_licenses') else 'unknown'
+            })
+
+            if len(code_samples) >= 300:
+                break
+
+        progress(0.7, desc="Creating code embeddings...")
+        code_texts = [c['code'][:512] for c in code_samples]  # Use first 512 chars
+        embeddings = embedder.encode(code_texts, show_progress_bar=False)
+
+        progress(1.0, desc="Ready!")
+        avg_stars = np.mean([c['max_stars_count'] for c in code_samples])
+        return f"✅ Loaded {len(code_samples)} code samples (avg stars: {avg_stars:.0f})"
+
+    except Exception as e:
+        return f"❌ Error: {str(e)}\nNote: Using fallback - dataset requires internet"
+
+def extract_function_name(code):
+    """Extract main function/class name from code."""
+    # Look for function definitions
+    func_match = re.search(r'def\s+(\w+)\s*\(', code)
+    if func_match:
+        return func_match.group(1)
+
+    # Look for class definitions
+    class_match = re.search(r'class\s+(\w+)\s*[:\(]', code)
+    if class_match:
+        return class_match.group(1)
+
+    return "code snippet"
+
+def syntax_highlight_code(code, language='python'):
+    """Apply syntax highlighting to code."""
+    try:
+        lexer = get_lexer_by_name(language)
+        formatter = HtmlFormatter(style='monokai', noclasses=True)
+        highlighted = highlight(code, lexer, formatter)
+        return highlighted
+    except:
+        return f"<pre><code>{code}</code></pre>"
+
+def search_code(query, language='python', min_stars=0, top_k=5):
+    """Search for code samples."""
+    if embeddings is None or not code_samples:
+        return []
+
+    # Filter by language and stars
+    filtered_samples = [
+        (i, sample) for i, sample in enumerate(code_samples)
+        if sample['language'] == language and sample['max_stars_count'] >= min_stars
+    ]
+
+    if not filtered_samples:
+        # Fallback: remove star filter
+        filtered_samples = [(i, sample) for i, sample in enumerate(code_samples)]
+
+    indices = [i for i, _ in filtered_samples]
+    filtered_embeddings = embeddings[indices]
+
+    # Search
+    query_embedding = embedder.encode([query])
+    similarities = np.dot(filtered_embeddings, query_embedding.T).flatten()
+    top_indices = np.argsort(similarities)[-top_k:][::-1]
+
+    # Map back to original samples
+    results = []
+    for idx in top_indices:
+        original_idx = indices[idx]
+        sample = code_samples[original_idx].copy()
+        sample['similarity'] = float(similarities[idx])
+        results.append(sample)
+
+    return results
+
+def format_code_results(results, query):
+    """Format code search results."""
+    if not results:
+        return "<p>No code samples found. Try adjusting filters or query.</p>"
+
+    html = f"<h2>🔍 Code Search Results</h2>"
+    html += f"<p><strong>Query:</strong> {query}</p>"
+    html += f"<p><strong>Found:</strong> {len(results)} relevant code samples</p>"
+    html += "<hr>"
+
+    for i, result in enumerate(results, 1):
+        html += f"<div style='margin: 20px 0; padding: 15px; background: #1e1e1e; border-radius: 8px;'>"
+        html += f"<h3 style='color: #fff;'>Result {i}: {extract_function_name(result['code'])}</h3>"
+
+        # Metadata
+        html += f"<p style='color: #888;'>"
+        html += f"<strong>Repo:</strong> {result['max_stars_repo_name']} | "
+        html += f"<strong>Stars:</strong> ⭐ {result['max_stars_count']} | "
+        html += f"<strong>License:</strong> {result['license']} | "
+        html += f"<strong>Relevance:</strong> {result['similarity']:.3f}"
+        html += f"</p>"
+
+        # Code
+        code = result['code'][:1000]  # Limit display length
+        highlighted = syntax_highlight_code(code, result['language'])
+        html += highlighted
+
+        # Copy button (using JavaScript)
+        escaped_code = result['code'].replace('`', '\\`').replace('$', '\\$')
+        html += f"""
+        <button onclick="navigator.clipboard.writeText(`{escaped_code}`);
+                        this.innerText='Copied!';
+                        setTimeout(() => this.innerText='Copy Code', 2000);"
+                style="margin-top: 10px; padding: 8px 16px; background: #4CAF50; color: white;
+                       border: none; border-radius: 4px; cursor: pointer;">
+            Copy Code
+        </button>
+        """
+
+        html += "</div>"
+
+    return html
+
+def perform_code_search(query, language, min_stars, num_results, progress=gr.Progress()):
+    """Perform code search."""
+    if not query:
+        return "<p>Please enter a search query</p>", ""
+
+    if embeddings is None:
+        return "<p>Please load the dataset first</p>", ""
+
+    progress(0, desc="Searching code...")
+    results = search_code(query, language, min_stars, top_k=num_results)
+
+    progress(0.7, desc="Formatting results...")
+    formatted = format_code_results(results, query)
+
+    progress(1.0, desc="Done!")
+
+    # Stats
+    stats = f"""
+### 📊 Search Statistics
+
+- **Total samples**: {len(code_samples)}
+- **Results**: {len(results)}
+- **Language**: {language}
+- **Min stars**: {min_stars}
+- **Model**: CodeBERT (Microsoft)
+
+### 🧠 How CodeBERT Works
+
+CodeBERT is trained on code and documentation:
+- Understands programming patterns
+- Maps code to natural language
+- Trained on GitHub repos
+- Supports multiple languages
+"""
+
+    return formatted, stats
+
+# Gradio Interface
+with gr.Blocks(title="Code Search Engine", theme=gr.themes.Soft()) as demo:
+    create_premium_hero(
+        "Semantic Code Search Engine",
+        "Search code with natural language using code embeddings, dataset sampling, and syntax-highlighted retrieval results.",
+        "💻",
+        badge="Code Intelligence",
+        highlights=["CodeBERT", "The Stack sample", "Semantic retrieval"],
+    )
+    create_method_panel({
+        "Technique": "Encode code snippets into vectors and rank them against natural-language queries.",
+        "What it proves": "You can adapt embedding search beyond documents into developer tooling.",
+        "HF capability": "Combines Hub datasets with transformer embeddings in an interactive Space.",
+    })
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("### Step 1: Load Dataset")
+            load_btn = gr.Button("Load Code Dataset", variant="primary")
+            load_status = gr.Textbox(label="Status", interactive=False)
+
+            gr.Markdown("### Step 2: Search Code")
+            query_input = gr.Textbox(
+                label="What are you looking for?",
+                placeholder="e.g., binary search implementation",
+                lines=2
+            )
+
+            language = gr.Dropdown(
+                choices=['python'],
+                value='python',
+                label="Language (more coming soon)"
+            )
+
+            min_stars = gr.Slider(
+                minimum=0,
+                maximum=1000,
+                value=0,
+                step=10,
+                label="Minimum GitHub Stars"
+            )
+
+            num_results = gr.Slider(
+                minimum=3,
+                maximum=10,
+                value=5,
+                step=1,
+                label="Number of Results"
+            )
+
+            search_btn = gr.Button("Search Code", variant="primary")
+
+            gr.Markdown("""
+            ### 💡 Example Searches:
+            - "binary search tree"
+            - "web scraper with requests"
+            - "recursive fibonacci"
+            - "API client with authentication"
+            - "data validation decorator"
+            """)
+
+        with gr.Column(scale=2):
+            results_output = gr.HTML(label="Code Results")
+
+            with gr.Accordion("📊 Statistics & Info", open=False):
+                stats_output = gr.Markdown()
+
+    gr.Markdown("""
+    ### 🎯 Why Semantic Code Search?
+
+    **Traditional search** (GitHub, Google):
+    - Keyword matching only
+    - Must know exact function names
+    - Hard to find by functionality
+
+    **Semantic search** (this tool):
+    - Search by what code does, not what it's called
+    - "sort a list" finds quicksort, mergesort, etc.
+    - Understands programming concepts
+
+    ### 🔧 Features:
+
+    - **Syntax highlighting** with Pygments
+    - **Copy to clipboard** button
+    - **Filter by stars** (code quality proxy)
+    - **License information** (know before you use)
+    - **CodeBERT embeddings** (code + NL understanding)
+
+    Perfect for developers learning, debugging, or finding code examples!
+    """)
+
+    load_btn.click(
+        load_code_dataset,
+        outputs=[load_status]
+    )
+
+    search_btn.click(
+        perform_code_search,
+        inputs=[query_input, language, min_stars, num_results],
+        outputs=[results_output, stats_output]
+    )
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,5 @@
+gradio==4.44.0
+huggingface-hub==0.25.0
+datasets==3.2.0
+sentence-transformers==3.3.1
+pygments==2.18.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)