Deploy Receipt Scanner

README.md

@@ -1,12 +1,61 @@
 ---
 title: Receipt Scanner
-emoji: 🌍
-colorFrom: blue
-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
+# Receipt Scanner
+
+## Question
+
+How do we turn a document image into structured data a program can use?
+
+## System Boundary
+
+This Space treats receipt understanding as a multimodal extraction problem: image in, schema out.
+
+## Method
+
+A vision-language model reads the uploaded receipt and produces structured fields such as merchant, date, item rows, subtotal, tax, total, and payment details. The app parses the model output into table and JSON views.
+
+## Technique
+
+This is multimodal information extraction. The model must read pixels, infer document layout, identify fields, and emit a schema that downstream software can consume.
+
+The difficult part is not only recognizing text. The difficult part is assigning text to the correct semantic field: item, price, tax, total, date, or merchant.
+
+## Output
+
+The app returns a summary, an item table, raw structured JSON, and exportable records.
+
+## Why It Matters
+
+The useful part of document AI is not OCR alone. The useful part is converting messy visual evidence into validated fields that can enter a database, review queue, or accounting workflow.
+
+## What To Notice
+
+Check whether totals reconcile with item rows and whether the model preserves uncertainty. Structured extraction should be judged at the field level, not only by a nice-looking summary.
+
+## Effect In Practice
+
+Receipt extraction is a small version of a larger document-understanding pattern used for invoices, insurance forms, procurement, and expense workflows.
+
+## Hugging Face Extension
+
+The Space can be extended with a receipt dataset, field-level accuracy metrics, and model comparisons across open vision-language models.
+
+## Limitations
+
+Receipt formats vary widely. A production system should add confidence estimates, field-level validation, human review, and evaluation on a labeled receipt dataset.
+
+## Run Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,240 @@
+"""
+Receipt Scanner
+Upload a receipt photo and extract structured data (items, prices, totals).
+"""
+
+import gradio as gr
+from huggingface_hub import InferenceClient
+from PIL import Image
+import base64
+from io import BytesIO
+import json
+import pandas as pd
+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
+
+# Initialize Hugging Face Inference Client
+client = InferenceClient()
+
+EXTRACTION_PROMPT = """Analyze this receipt image and extract ALL information in a structured format.
+
+Extract:
+1. **Merchant/Store Name**
+2. **Date** (in YYYY-MM-DD format if possible)
+3. **Time** (if visible)
+4. **Items** - List each item with its price
+5. **Subtotal** (if shown)
+6. **Tax** (if shown)
+7. **Total Amount**
+8. **Payment Method** (if visible)
+
+Format your response EXACTLY as JSON:
+```json
+{
+  "merchant": "Store Name",
+  "date": "YYYY-MM-DD",
+  "time": "HH:MM",
+  "items": [
+    {"name": "Item 1", "price": 0.00},
+    {"name": "Item 2", "price": 0.00}
+  ],
+  "subtotal": 0.00,
+  "tax": 0.00,
+  "total": 0.00,
+  "payment_method": "Card/Cash/etc"
+}
+```
+
+Be precise with numbers. If something is unclear, use null."""
+
+
+def extract_json_from_text(text):
+    """Extract JSON from markdown code blocks or raw text."""
+    # Try to find JSON in code blocks first
+    json_match = re.search(r'```(?:json)?\s*(\{.*?\})\s*```', text, re.DOTALL)
+    if json_match:
+        return json_match.group(1)
+
+    # Try to find raw JSON
+    json_match = re.search(r'\{.*\}', text, re.DOTALL)
+    if json_match:
+        return json_match.group(0)
+
+    return None
+
+
+def scan_receipt(image):
+    """Extract structured data from receipt using VLM."""
+    if image is None:
+        return "❌ Please upload a receipt first!", "", ""
+
+    try:
+        # Convert PIL Image to base64
+        buffered = BytesIO()
+        if isinstance(image, str):
+            image = Image.open(image)
+        image.save(buffered, format="PNG")
+        img_str = base64.b64encode(buffered.getvalue()).decode()
+
+        # Use Florence-2 or Qwen2-VL for OCR + understanding
+        response = client.chat_completion(
+            model="Qwen/Qwen2-VL-7B-Instruct",
+            messages=[
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{img_str}"}},
+                        {"type": "text", "text": EXTRACTION_PROMPT}
+                    ]
+                }
+            ],
+            max_tokens=1000,
+            temperature=0.1  # Low temperature for accuracy
+        )
+
+        raw_response = response.choices[0].message.content
+
+        # Extract JSON from response
+        json_str = extract_json_from_text(raw_response)
+        if not json_str:
+            return f"⚠️ Could not parse receipt data.\n\nRaw response:\n{raw_response}", "", ""
+
+        # Parse JSON
+        data = json.loads(json_str)
+
+        # Create formatted summary
+        summary = f"""# 🧾 Receipt Analysis
+
+**Merchant**: {data.get('merchant', 'N/A')}
+**Date**: {data.get('date', 'N/A')}
+**Time**: {data.get('time', 'N/A')}
+
+---
+
+## 📦 Items
+
+"""
+        # Add items table
+        if data.get('items'):
+            for item in data['items']:
+                name = item.get('name', 'Unknown')
+                price = item.get('price', 0.0)
+                summary += f"- **{name}**: ${price:.2f}\n"
+        else:
+            summary += "*No items found*\n"
+
+        summary += f"""
+---
+
+## 💰 Totals
+
+- **Subtotal**: ${data.get('subtotal', 0.0):.2f}
+- **Tax**: ${data.get('tax', 0.0):.2f}
+- **Total**: ${data.get('total', 0.0):.2f}
+
+**Payment**: {data.get('payment_method', 'N/A')}
+"""
+
+        # Create DataFrame for table view
+        if data.get('items'):
+            df = pd.DataFrame(data['items'])
+            df['price'] = df['price'].apply(lambda x: f"${x:.2f}")
+        else:
+            df = pd.DataFrame(columns=['name', 'price'])
+
+        # Format JSON for download
+        json_output = json.dumps(data, indent=2)
+
+        return summary, df, json_output
+
+    except json.JSONDecodeError as e:
+        return f"❌ Error parsing JSON: {str(e)}\n\nRaw response:\n{raw_response}", "", ""
+    except Exception as e:
+        return f"❌ Error scanning receipt: {str(e)}", "", ""
+
+
+# Gradio Interface
+with gr.Blocks(theme=gr.themes.Soft()) as demo:
+    create_premium_hero(
+        "Receipt Scanner",
+        "Extract merchant, items, totals, and payment details from receipt images with a vision-language model workflow.",
+        "🧾",
+        badge="Document Vision",
+        highlights=["Vision-language extraction", "Structured JSON", "CSV export"],
+    )
+    create_method_panel({
+        "Technique": "Image-to-structured-data extraction with schema parsing and tabular validation.",
+        "What it proves": "You can turn multimodal model output into reliable downstream data products.",
+        "HF capability": "Designed for Hub-hosted VLM inference and lightweight Space deployment.",
+    })
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            image_input = gr.Image(
+                label="📸 Upload Receipt Photo",
+                type="pil",
+                height=400
+            )
+
+            scan_btn = gr.Button("🔍 Scan Receipt", variant="primary", size="lg")
+
+            gr.Markdown("""
+            ### 💡 Tips for Best Results:
+            - Good lighting, minimal shadows
+            - Receipt should be flat and clear
+            - Include the entire receipt
+            - High contrast works best
+            """)
+
+        with gr.Column(scale=1):
+            summary_output = gr.Markdown(label="📊 Summary")
+
+    with gr.Row():
+        with gr.Column():
+            table_output = gr.Dataframe(
+                label="📋 Items Table",
+                headers=["name", "price"],
+                interactive=False
+            )
+
+        with gr.Column():
+            json_output = gr.Textbox(
+                label="📄 JSON Data (copy to download)",
+                lines=15,
+                max_lines=20
+            )
+
+    # Event handler
+    scan_btn.click(
+        fn=scan_receipt,
+        inputs=[image_input],
+        outputs=[summary_output, table_output, json_output],
+        api_name="scan"
+    )
+
+    gr.Markdown("""
+    ---
+    ### 🎓 What This App Does:
+
+    1. **OCR + Understanding**: Doesn't just read text, understands structure
+    2. **Data Extraction**: Identifies items, prices, totals, dates
+    3. **JSON Export**: Download structured data for expense tracking
+    4. **Table View**: See items in an organized format
+
+    ### 📊 Use Cases:
+
+    - **Expense Tracking**: Digitize receipts for accounting
+    - **Budget Apps**: Auto-import spending data
+    - **Tax Records**: Organize business expenses
+    - **Reimbursements**: Submit itemized claims
+    - **Personal Finance**: Track spending categories
+
+    *Note: Accuracy depends on receipt clarity and format. Complex layouts may require manual verification.*
+    """)
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,4 @@
+gradio==4.44.0
+huggingface-hub==0.25.0
+Pillow==11.0.0
+pandas==2.2.3

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)