Deploy Contract Red Team

README.md

@@ -1,12 +1,61 @@
 ---
 title: Contract Red Team
-emoji: 📈
-colorFrom: red
-colorTo: gray
+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
+# Contract Red Team
+
+## Question
+
+How can an AI assistant review a contract while keeping evidence visible?
+
+## System Boundary
+
+This Space is a contract-risk triage tool. It is not legal advice. It is designed to surface clauses worth human review.
+
+## Method
+
+The app extracts text from a PDF, chunks the contract, embeds clauses, searches for risk patterns, and uses model-assisted explanation to describe potential issues such as termination, non-compete, IP assignment, liability, and arbitration.
+
+## Technique
+
+This is evidence-first document triage. The system combines deterministic risk patterns with retrieval and model explanation.
+
+The design goal is to keep the clause visible. The model should not be a magic summarizer; it should point to text that a human can inspect.
+
+## Output
+
+The app returns a risk report with clause evidence, category labels, and suggested review questions.
+
+## Why It Matters
+
+High-stakes document AI must be evidence-first. The user should see why a clause was flagged, not merely receive a summary.
+
+## What To Notice
+
+The strongest outputs are tied to exact clauses. If the evidence is vague, the finding should be treated as weak.
+
+## Effect In Practice
+
+This workflow can help users prioritize review time by surfacing clauses that deserve attention before a detailed legal review.
+
+## Hugging Face Extension
+
+The Space can be expanded with a clause-risk dataset, model explanations, and evaluation on category precision and evidence quality.
+
+## Limitations
+
+Contracts are jurisdiction-specific and context-dependent. This tool should be used for education and triage only, followed by professional legal review.
+
+## Run Locally
+
+```bash
+pip install -r requirements.txt
+python app.py
+```

app.py

@@ -0,0 +1,398 @@
+import gradio as gr
+from huggingface_hub import InferenceClient
+import PyPDF2
+import io
+from sentence_transformers import SentenceTransformer
+import faiss
+import numpy as np
+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 clients
+client = InferenceClient(token=os.getenv("HF_TOKEN"))
+embedding_model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
+
+# Known risky clause patterns
+RISKY_PATTERNS = [
+    {
+        "category": "Termination",
+        "keywords": ["at-will", "without cause", "immediate termination", "no notice"],
+        "risk_indicators": ["employer can terminate", "company may terminate", "dismiss without"]
+    },
+    {
+        "category": "Non-Compete",
+        "keywords": ["non-compete", "covenant not to compete", "shall not engage", "prohibited from working"],
+        "risk_indicators": ["any business", "similar industry", "12 months", "24 months", "geographic area"]
+    },
+    {
+        "category": "Intellectual Property",
+        "keywords": ["work product", "intellectual property", "inventions", "copyrights", "patents"],
+        "risk_indicators": ["belong to company", "assigned to employer", "waive rights", "all ideas"]
+    },
+    {
+        "category": "Confidentiality",
+        "keywords": ["confidential", "proprietary", "trade secrets", "non-disclosure"],
+        "risk_indicators": ["indefinitely", "perpetuity", "all information", "broadly defined"]
+    },
+    {
+        "category": "Liability",
+        "keywords": ["indemnify", "hold harmless", "liability", "damages"],
+        "risk_indicators": ["unlimited liability", "personal liability", "consequential damages", "punitive damages"]
+    },
+    {
+        "category": "Compensation",
+        "keywords": ["salary", "compensation", "bonus", "payment"],
+        "risk_indicators": ["discretionary", "sole discretion", "may adjust", "subject to change"]
+    },
+    {
+        "category": "Arbitration",
+        "keywords": ["arbitration", "dispute resolution", "waive right to sue"],
+        "risk_indicators": ["binding arbitration", "waive jury trial", "class action waiver"]
+    }
+]
+
+def extract_text_from_pdf(pdf_file):
+    """Extract text from uploaded PDF file"""
+    try:
+        pdf_reader = PyPDF2.PdfReader(io.BytesIO(pdf_file))
+        text = ""
+        for page in pdf_reader.pages:
+            text += page.extract_text() + "\n"
+        return text
+    except Exception as e:
+        return f"Error extracting PDF: {str(e)}"
+
+def split_into_clauses(text):
+    """Split contract into clauses"""
+    # Split by common clause separators
+    import re
+    # Split by numbered sections, or by double newlines, or by periods followed by uppercase
+    clauses = []
+
+    # First try numbered sections
+    sections = re.split(r'\n\s*\d+\.|\n\s*[A-Z]\.|Article \d+', text)
+
+    for section in sections:
+        # Further split long sections by sentences
+        sentences = section.split('. ')
+        current_clause = ""
+        for sentence in sentences:
+            current_clause += sentence + ". "
+            if len(current_clause) > 100:  # Create clause every ~100 chars
+                clauses.append(current_clause.strip())
+                current_clause = ""
+        if current_clause.strip():
+            clauses.append(current_clause.strip())
+
+    # Filter out very short clauses
+    clauses = [c for c in clauses if len(c) > 50]
+    return clauses
+
+def build_vector_db(clauses):
+    """Create FAISS vector database from clauses"""
+    embeddings = embedding_model.encode(clauses)
+    dimension = embeddings.shape[1]
+    index = faiss.IndexFlatL2(dimension)
+    index.add(np.array(embeddings).astype('float32'))
+    return index, embeddings
+
+def analyze_clause_risk(clause):
+    """Analyze a single clause for risk using pattern matching and reasoning"""
+    risks = []
+
+    clause_lower = clause.lower()
+
+    for pattern in RISKY_PATTERNS:
+        # Check if clause contains risk indicators
+        keyword_matches = sum(1 for kw in pattern["keywords"] if kw in clause_lower)
+        risk_matches = sum(1 for ri in pattern["risk_indicators"] if ri in clause_lower)
+
+        if keyword_matches > 0 and risk_matches > 0:
+            # Calculate risk score
+            if risk_matches >= 2 or "unlimited" in clause_lower or "perpetuity" in clause_lower:
+                risk_level = "HIGH"
+            elif risk_matches >= 1:
+                risk_level = "MEDIUM"
+            else:
+                risk_level = "LOW"
+
+            risks.append({
+                "category": pattern["category"],
+                "risk_level": risk_level,
+                "clause": clause[:300] + "..." if len(clause) > 300 else clause
+            })
+
+    return risks
+
+def get_ai_analysis(clause, category, risk_level):
+    """Use reasoning model to explain the risk"""
+    prompt = f"""You are a legal risk analyst. Analyze this contract clause.
+
+Category: {category}
+Risk Level: {risk_level}
+Clause: "{clause}"
+
+Provide:
+1. WHY this clause is risky (2-3 sentences, be specific)
+2. SUGGESTED REVISION (1-2 sentences on how to make it fairer)
+
+Be direct and actionable."""
+
+    try:
+        response = ""
+        for message in client.chat_completion(
+            model="Qwen/Qwen2.5-72B-Instruct",
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=300,
+            stream=True
+        ):
+            if message.choices[0].delta.content:
+                response += message.choices[0].delta.content
+
+        # Parse response
+        parts = response.split("SUGGESTED REVISION")
+        why_risky = parts[0].replace("WHY", "").replace("1.", "").strip()
+        suggested = parts[1].replace("2.", "").strip() if len(parts) > 1 else "Negotiate this clause with legal counsel."
+
+        return why_risky, suggested
+    except:
+        return "This clause may impose unfair obligations or risks on one party.", "Consider negotiating more balanced terms with legal counsel."
+
+def analyze_contract(pdf_file, progress=gr.Progress()):
+    """Main function to analyze contract"""
+    if pdf_file is None:
+        return "🔍 Please upload a contract to investigate.", ""
+
+    progress(0, desc="🔍 Investigating contract...")
+
+    # Extract text
+    text = extract_text_from_pdf(pdf_file)
+    if "Error" in text:
+        return text, ""
+
+    progress(0.2, desc="📄 Analyzing clauses...")
+
+    # Split into clauses
+    clauses = split_into_clauses(text)
+
+    if len(clauses) == 0:
+        return "⚠️ Could not extract clauses from contract. Please ensure it's a text-based PDF.", ""
+
+    progress(0.4, desc="🔎 Searching for suspicious clauses...")
+
+    # Analyze each clause
+    all_risks = []
+    for i, clause in enumerate(clauses):
+        risks = analyze_clause_risk(clause)
+        all_risks.extend(risks)
+        progress(0.4 + (0.4 * (i / len(clauses))), desc=f"🔎 Analyzing clause {i+1}/{len(clauses)}...")
+
+    if len(all_risks) == 0:
+        summary = f"""
+# ✅ Investigation Complete
+
+**Contract Status:** LOW RISK
+
+🔍 Analyzed {len(clauses)} clauses
+✓ No major red flags detected
+
+**Note:** This is an automated analysis. Always consult a licensed attorney for legal advice.
+        """
+        return summary, ""
+
+    progress(0.8, desc="🧠 Generating risk analysis...")
+
+    # Sort by risk level
+    risk_order = {"HIGH": 0, "MEDIUM": 1, "LOW": 2}
+    all_risks.sort(key=lambda x: risk_order[x["risk_level"]])
+
+    # Generate detailed analysis for top risks
+    detailed_findings = []
+    for i, risk in enumerate(all_risks[:5]):  # Limit to top 5
+        why, suggested = get_ai_analysis(risk["clause"], risk["category"], risk["risk_level"])
+        detailed_findings.append({
+            "category": risk["category"],
+            "risk_level": risk["risk_level"],
+            "clause": risk["clause"],
+            "why_risky": why,
+            "suggested": suggested
+        })
+        progress(0.8 + (0.15 * (i / min(5, len(all_risks)))), desc=f"🧠 Analyzing risk {i+1}...")
+
+    progress(0.95, desc="📊 Generating report...")
+
+    # Create summary
+    high_count = sum(1 for r in all_risks if r["risk_level"] == "HIGH")
+    medium_count = sum(1 for r in all_risks if r["risk_level"] == "MEDIUM")
+    low_count = sum(1 for r in all_risks if r["risk_level"] == "LOW")
+
+    overall_risk = "HIGH" if high_count > 0 else ("MEDIUM" if medium_count > 0 else "LOW")
+    risk_emoji = "🚨" if overall_risk == "HIGH" else ("⚠️" if overall_risk == "MEDIUM" else "✅")
+
+    summary = f"""
+# {risk_emoji} Investigation Complete
+
+**Overall Risk Assessment:** {overall_risk}
+
+## 📊 Risk Dashboard
+- 🚨 **HIGH Risk Clauses:** {high_count}
+- ⚠️ **MEDIUM Risk Clauses:** {medium_count}
+- ℹ️ **LOW Risk Clauses:** {low_count}
+
+**Total Clauses Analyzed:** {len(clauses)}
+
+---
+
+**⚠️ DISCLAIMER:** This is an automated analysis tool, NOT legal advice. Always consult a licensed attorney before signing any contract.
+    """
+
+    # Create detailed report
+    detailed = "# 🔍 Detailed Findings\n\n"
+
+    for i, finding in enumerate(detailed_findings, 1):
+        risk_color = "🚨" if finding["risk_level"] == "HIGH" else ("⚠️" if finding["risk_level"] == "MEDIUM" else "ℹ️")
+
+        detailed += f"""
+## {risk_color} Finding #{i}: {finding["category"]}
+
+**Risk Level:** {finding["risk_level"]}
+
+**Suspicious Clause:**
+> {finding["clause"]}
+
+**Why This Is Risky:**
+{finding["why_risky"]}
+
+**Suggested Revision:**
+{finding["suggested"]}
+
+---
+
+"""
+
+    progress(1.0, desc="✅ Investigation complete!")
+
+    return summary, detailed
+
+# Custom CSS for detective theme
+custom_css = """
+.gradio-container {
+    font-family: 'Courier New', monospace;
+}
+
+.risk-high {
+    background-color: #fee;
+    border-left: 4px solid #c00;
+    padding: 10px;
+}
+
+.risk-medium {
+    background-color: #ffeaa7;
+    border-left: 4px solid #fdcb6e;
+    padding: 10px;
+}
+
+.risk-low {
+    background-color: #d5f4e6;
+    border-left: 4px solid #00b894;
+    padding: 10px;
+}
+
+#component-0 {
+    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+}
+
+.title-text {
+    color: #f39c12;
+    text-shadow: 2px 2px 4px rgba(0,0,0,0.5);
+}
+
+.detective-badge {
+    background-color: #2c3e50;
+    color: #f39c12;
+    padding: 20px;
+    border-radius: 10px;
+    border: 2px solid #f39c12;
+}
+"""
+
+# Create Gradio interface
+with gr.Blocks(css=custom_css, theme=gr.themes.Monochrome()) as demo:
+    create_premium_hero(
+        "Contract Red Team",
+        "Upload a contract and inspect risky clauses with retrieval, clause patterning, and model-assisted explanation.",
+        "🔍",
+        badge="Legal AI Triage",
+        highlights=["Clause retrieval", "Risk taxonomy", "Evidence-first report"],
+    )
+    create_method_panel({
+        "Technique": "PDF parsing → clause chunking → embedding retrieval → risk-pattern scoring → explanation.",
+        "What it proves": "You can build an evidence-first AI assistant for high-stakes document review.",
+        "Safety note": "This is triage and education, not legal advice or a substitute for counsel.",
+    })
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            gr.Markdown("""
+            ### 📋 How It Works
+            1. **Upload** your contract (PDF)
+            2. **AI investigates** each clause
+            3. **Get detailed report** on risky clauses
+
+            ### ✅ Supported Contracts
+            - NDAs (Non-Disclosure Agreements)
+            - Employment Contracts
+            - Service Agreements
+            - Consulting Agreements
+            - Freelance Contracts
+
+            ### ⚠️ We Check For
+            - Unfair termination clauses
+            - Broad non-compete agreements
+            - IP rights issues
+            - Liability concerns
+            - Confidentiality overreach
+            - Compensation risks
+            - Arbitration requirements
+            """)
+
+            pdf_input = gr.File(
+                label="📄 Upload Contract (PDF)",
+                file_types=[".pdf"],
+                type="binary"
+            )
+
+            analyze_btn = gr.Button(
+                "🔍 Start Investigation",
+                variant="primary",
+                size="lg"
+            )
+
+        with gr.Column(scale=2):
+            gr.Markdown("### 📊 Investigation Summary")
+            summary_output = gr.Markdown(value="🔍 Upload a contract to begin investigation...")
+
+            gr.Markdown("### 🔍 Detailed Findings")
+            detailed_output = gr.Markdown(value="")
+
+    gr.HTML("""
+        <div style='background-color: #2c3e50; color: #ecf0f1; padding: 20px; border-radius: 10px; margin-top: 20px; text-align: center;'>
+            <h3 style='color: #e74c3c; margin-top: 0;'>⚠️ IMPORTANT DISCLAIMER</h3>
+            <p>This tool provides an automated analysis and is <strong>NOT legal advice</strong>.
+            Always consult with a licensed attorney before signing any contract.
+            The AI may miss risks or provide inaccurate information.</p>
+        </div>
+    """)
+
+    # Event handlers
+    analyze_btn.click(
+        fn=analyze_contract,
+        inputs=[pdf_input],
+        outputs=[summary_output, detailed_output]
+    )
+
+if __name__ == "__main__":
+    demo.launch()

requirements.txt

@@ -0,0 +1,5 @@
+gradio==4.44.0
+huggingface-hub==0.25.0
+PyPDF2==3.0.1
+sentence-transformers==3.3.1
+faiss-cpu==1.9.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)