Upload folder using huggingface_hub

.ruff_cache/.gitignore

@@ -0,0 +1,2 @@
+# Automatically created by ruff.
+*

.ruff_cache/CACHEDIR.TAG

@@ -0,0 +1 @@
+Signature: 8a477f597d28d172789f06886806bc55

README.md

@@ -1,15 +1,84 @@
 ---
 title: Vessel Studio
-emoji: 🐢
-colorFrom: green
+emoji: 🏺
+colorFrom: blue
 colorTo: gray
 sdk: gradio
-sdk_version: 6.16.0
-python_version: '3.12'
+sdk_version: 4.44.0
 app_file: app.py
 pinned: false
 license: mit
-short_description: A local-first Creative Studio and Agentic Assistant for arti
+short_description: Local-first agentic studio for artisans using Gemma 4 12B.
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Vessel: A Local-First Agentic Studio for Craft Creators
+
+`Vessel` is a local-first creative workspace designed specifically for local artisans and craft creators (e.g., Etsy sellers, local market vendors, hobbyist potters) to manage and automate their creative businesses. By combining local multimodal image analysis, brand-voice copy generation, and a code-executing local agent, Vessel turns raw product photos and simple text instructions into professional product listings, customized social marketing campaigns, invoice databases, and customer emails.
+
+This project is built for **Track 1: Backyard AI**, specifically targeting a local artisan ("Clara," a pottery maker) who spends too much time on business admin and copywriting.
+
+---
+
+## 🚀 Key Highlights & Merit Badges
+
+* **Off the Grid:** Runs entirely offline inside the Space (using local GPU/MPS inference). No external paid APIs are called.
+* **Off-Brand:** Custom glassmorphic dark-mode dashboard using custom CSS/JS.
+* **Sharing is Caring:** Employs Hugging Face’s `smolagents` library, pushing detailed agent execution traces directly to the Hub.
+* **Field Notes:** A detailed Hugging Face blog post documenting our experience being among the first to deploy and build an agentic, multimodal workspace with the new Gemma 4 12B model.
+
+---
+
+## 🛠️ Tech Stack & Model Configuration
+
+* **LLM Engine:** `google/gemma-4-12B-it` (quantized to Q4_K_M GGUF locally, loaded in full precision on Space ZeroGPU).
+* **Frameworks:** Hugging Face `transformers` and `smolagents` (code-writing agent).
+* **Database:** SQLite (`vessel_studio.db`) representing inventory, orders, and customer lists.
+* **Aesthetics:** Custom vanilla CSS/JS injected directly into Gradio 6.0 layout.
+
+---
+
+## 📦 Project Layout
+
+```
+.
+├── app.py                # Main Gradio application interface
+├── agent.py              # smolagents CodeAgent and tool definitions
+├── models.py             # Gemma 4 model loader and inference helper
+├── database.py           # SQLite connection and seed data
+├── style.css             # Glassmorphic dark-mode CSS override rules
+├── script.js             # Javascript helper for clipboard and notifications
+├── verify_code.py        # Code quality validation script ( Ruff + Pyright )
+├── pyrightconfig.json    # Exclusion rules for type checker
+├── requirements.txt      # Dependency lists
+└── run.sh                # Executable shell script with venv auto-activation
+```
+
+---
+
+## 🔧 Local Installation & Execution
+
+### 1. Prerequisite: Gemma 4 gated model approval
+Visit [https://huggingface.co/google/gemma-4-12B-it](https://huggingface.co/google/gemma-4-12B-it) and accept the license terms.
+
+### 2. Set Up Environment Variables
+Create a `.env` file in the root directory:
+```env
+HF_TOKEN=your_huggingface_write_token_here
+SPACE_ID=your_username/your_space_name  # Required to share agent traces to the Hub
+```
+
+### 3. Run using the auto-activating wrapper script:
+The `./run.sh` script automatically detects, activates, and configures the python virtual environment:
+
+* **To initialize the SQLite Database:**
+  ```bash
+  ./run.sh db
+  ```
+* **To launch the local web server:**
+  ```bash
+  ./run.sh
+  ```
+* **To run formatting, lints, and static type checking:**
+  ```bash
+  ./run.sh verify
+  ```

agent.py

@@ -0,0 +1,400 @@
+# Import os paths, serialization tools, and datetime metadata
+import json
+import os
+from datetime import datetime
+
+# Import deep learning acceleration libraries
+import torch
+
+# Import Hugging Face API connections and agent frameworks
+from huggingface_hub import HfApi
+from smolagents import CodeAgent, Model, tool
+
+# Import query functions from database module
+from database import db_query, db_execute
+
+
+# Import model loaders and device mapping tools
+from models import load_gemma_model, get_device
+
+
+# Custom Response Wrapper class matching smolagents Model return contract
+class ChatResponse:
+    # Initialize response object with generated text content
+    def __init__(self, content):
+        self.content = content
+
+
+# Custom Model Subclass to reuse our warm, preloaded Gemma 4 model instance
+class GemmaLocalModel(Model):
+    # Initialize the custom model wrapper
+    def __init__(self, model_id="google/gemma-4-12B-it", **kwargs):
+        super().__init__(model_id=model_id, **kwargs)
+
+    # Implement generate to run inference inside agent execution loops
+    def generate(self, messages, stop_sequences=None, **kwargs):
+        # Retrieve the preloaded model and processor from cache
+        model, processor = load_gemma_model()
+        # Resolve target device mapping
+        device = get_device()
+
+        # Format prompt messages into the model's native chat syntax
+        text_prompt = processor.apply_chat_template(
+            messages, add_generation_prompt=True
+        )
+        # Process and transfer text inputs to the hardware device
+        inputs = processor(text=text_prompt, return_tensors="pt").to(device)
+
+        # Ensure correct datatypes are mapped for visual/multimodal layers
+        if "pixel_values" in inputs:
+            inputs["pixel_values"] = inputs["pixel_values"].to(model.dtype)
+
+        # Run text generation under no-gradient constraints
+        with torch.no_grad():
+            generated_ids = model.generate(
+                **inputs, max_new_tokens=1024, temperature=0.2, do_sample=True
+            )
+
+        # Isolate the input token count
+        input_len = inputs["input_ids"].shape[1]
+        # Decode the output token IDs, skipping prompt tokens
+        response_ids = generated_ids[0][input_len:]
+        # Convert token IDs back to a string
+        response_text = processor.decode(response_ids, skip_special_tokens=True).strip()
+
+        # Truncate response text if the model outputs any defined stop sequence
+        if stop_sequences:
+            for stop_seq in stop_sequences:
+                if stop_seq in response_text:
+                    response_text = response_text.split(stop_seq)[0]
+
+        # Return response wrapped in our ChatResponse object
+        return ChatResponse(content=response_text)
+
+
+# --- Define Agent Tools ---
+
+
+@tool
+def query_inventory_database(sql_query: str) -> str:
+    """
+    Executes a read-only SQL SELECT query against the local database and returns results.
+    Use this to look up inventory items, orders, or customers.
+
+    Args:
+        sql_query: A valid SQL SELECT query string.
+    """
+    # Enforce SELECT constraint to block malicious write commands in this tool
+    if not sql_query.strip().lower().startswith("select"):
+        return "Error: This tool only allows SELECT queries. Use execute_database_command for database modifications."
+    # Run the read query against SQLite
+    results = db_query(sql_query)
+    # Format database rows into a readable JSON string
+    return json.dumps(results, indent=2)
+
+
+@tool
+def execute_database_command(sql_command: str) -> str:
+    """
+    Executes an INSERT, UPDATE, or DELETE SQL statement against the local database to modify records.
+    Use this to record new orders, update stock levels, or update customer shipping addresses.
+
+    Args:
+        sql_command: A valid SQL write command string.
+    """
+    # Block SELECT statements to ensure clean usage mapping
+    if sql_command.strip().lower().startswith("select"):
+        return "Error: Use query_inventory_database for SELECT queries."
+    # Run database write modification command
+    result = db_execute(sql_command)
+    return result
+
+
+@tool
+def generate_invoice_pdf(order_id: int) -> str:
+    """
+    Generates a professional PDF invoice for a given order ID and saves it locally.
+    Returns the file path of the generated PDF.
+
+    Args:
+        order_id: The ID of the order to generate an invoice for.
+    """
+    # Import ReportLab page sizing utilities
+    from reportlab.lib.pagesizes import letter
+
+    # Import flowable element classes for layout building
+    from reportlab.platypus import (
+        SimpleDocTemplate,
+        Paragraph,
+        Spacer,
+        Table,
+        TableStyle,
+    )
+
+    # Import text style registries
+    from reportlab.lib.styles import getSampleStyleSheet, ParagraphStyle
+
+    # Import color palettes
+    from reportlab.lib import colors
+
+    # Query order details from database
+    order_rows = db_query("SELECT * FROM orders WHERE id = ?", (order_id,))
+    # Validate order existence
+    if not order_rows or "error" in order_rows[0]:
+        return f"Error: Order ID {order_id} not found."
+    # Reference target order dictionary
+    order = order_rows[0]
+
+    # Query matching customer details
+    customer_rows = db_query(
+        "SELECT * FROM customers WHERE id = ?", (order["customer_id"],)
+    )
+    # Map customer dict, fallback to placeholders if missing
+    customer = (
+        customer_rows[0]
+        if customer_rows
+        else {"name": "Unknown", "email": "N/A", "shipping_address": "N/A"}
+    )
+
+    # Query all item rows related to this order
+    items = db_query(
+        "SELECT order_items.*, inventory.name AS item_name FROM order_items JOIN inventory ON order_items.product_id = inventory.id WHERE order_id = ?",
+        (order_id,),
+    )
+
+    # Compile the target PDF filename
+    pdf_filename = f"invoice_order_{order_id}.pdf"
+    # Resolve absolute path for PDF generation
+    pdf_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), pdf_filename)
+
+    try:
+        # Instantiate ReportLab page layout with standard letter sizing
+        doc = SimpleDocTemplate(pdf_path, pagesize=letter)
+        # Initialize empty document story flow list
+        story = []
+        # Load sample style dictionary
+        styles = getSampleStyleSheet()
+
+        # Design custom brand-aligned header style
+        title_style = ParagraphStyle(
+            "InvoiceTitle",
+            parent=styles["Heading1"],
+            fontName="Helvetica-Bold",
+            fontSize=24,
+            leading=28,
+            textColor=colors.HexColor("#0d9488"),  # Teal branding color
+        )
+
+        # Reference normal text style
+        normal_style = styles["Normal"]
+
+        # Append Title to document flow
+        story.append(Paragraph("INVOICE", title_style))
+        # Append spacing under Title
+        story.append(Spacer(1, 15))
+
+        # Format customer billing info block
+        details_text = f"""
+        <b>Order ID:</b> {order_id}<br/>
+        <b>Date:</b> {order["order_date"]}<br/>
+        <b>Status:</b> {order["status"]}<br/>
+        <br/>
+        <b>Billed To:</b><br/>
+        {customer["name"]}<br/>
+        Email: {customer["email"]}<br/>
+        Address: {customer["shipping_address"]}<br/>
+        """
+        # Append customer billing details to document flow
+        story.append(Paragraph(details_text, normal_style))
+        # Append spacing under details
+        story.append(Spacer(1, 20))
+
+        # Setup items list header
+        data = [["Item", "Quantity", "Price", "Total"]]
+        # Format line items into the grid list
+        for item in items:
+            qty = item["quantity"]
+            price = item["price"]
+            total = qty * price
+            data.append([item["item_name"], str(qty), f"${price:.2f}", f"${total:.2f}"])
+
+        # Append final sum indicator row
+        data.append(["", "", "Total Due:", f"${order['total_price']:.2f}"])
+
+        # Create table mapping columns widths
+        table = Table(data, colWidths=[250, 70, 90, 90])
+        # Apply custom table grids, colors, padding, and font stylings
+        table.setStyle(
+            TableStyle(
+                [
+                    ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#f3f4f6")),
+                    ("TEXTCOLOR", (0, 0), (-1, 0), colors.HexColor("#111827")),
+                    ("ALIGN", (0, 0), (-1, -1), "LEFT"),
+                    ("BOTTOMPADDING", (0, 0), (-1, 0), 8),
+                    ("GRID", (0, 0), (-1, -2), 0.5, colors.HexColor("#e5e7eb")),
+                    ("LINEBELOW", (0, -1), (-1, -1), 1.5, colors.HexColor("#0d9488")),
+                    ("TOPPADDING", (0, -1), (-1, -1), 8),
+                    ("FONTNAME", (0, 0), (-1, 0), "Helvetica-Bold"),
+                ]
+            )
+        )
+
+        # Append table grid to document flow
+        story.append(table)
+        # Build the final PDF document on disk
+        doc.build(story)
+        return f"Success: Invoice PDF generated successfully at {pdf_path}"
+    except Exception as e:
+        # Catch and report any formatting errors during generation
+        return f"Error building PDF: {str(e)}"
+
+
+@tool
+def draft_customer_email(to_email: str, subject: str, body_content: str) -> str:
+    """
+    Drafts an email to a customer and saves it locally in a structured text file.
+    Returns the file path of the draft email.
+
+    Args:
+        to_email: The customer's email address.
+        subject: The subject line of the email.
+        body_content: The formatted body content of the email.
+    """
+    # Create the target email filename
+    draft_filename = f"email_draft_{to_email.replace('@', '_at_')}.txt"
+    # Resolve absolute path for email generation
+    draft_path = os.path.join(
+        os.path.dirname(os.path.abspath(__file__)), draft_filename
+    )
+
+    try:
+        # Write email text blocks to draft file
+        with open(draft_path, "w", encoding="utf-8") as f:
+            f.write(f"To: {to_email}\n")
+            f.write(f"Subject: {subject}\n")
+            f.write(f"Date: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
+            f.write("=" * 40 + "\n\n")
+            f.write(body_content)
+            f.write("\n\n" + "=" * 40 + "\n")
+            f.write("Draft auto-generated by Vessel Studio Client.\n")
+
+        return f"Success: Email draft saved successfully at {draft_path}"
+    except Exception as e:
+        # Return error if file write fails
+        return f"Error writing email file: {str(e)}"
+
+
+# --- Trace Pushing Mechanism ---
+
+
+def share_trace_on_hub(task_id: str, steps: list) -> bool:
+    """Serializes the agent execution steps to JSON and pushes it to the Hugging Face Space."""
+    # Load Hugging Face authorization credentials from environment
+    token = os.getenv("HF_TOKEN")
+    # Load Space repository identifier from environment
+    repo_id = os.getenv("SPACE_ID")
+
+    # Resolve trace logging directory path
+    trace_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "agent_traces")
+    # Create directory if it is absent
+    os.makedirs(trace_dir, exist_ok=True)
+
+    # Format trace log dictionary
+    trace_data = {
+        "task_id": task_id,
+        "timestamp": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        "steps": [str(step) for step in steps],
+    }
+
+    # Format trace filename
+    filename = f"trace_{task_id}.json"
+    # Resolve target file path
+    local_path = os.path.join(trace_dir, filename)
+
+    # Save structured trace log into a JSON file locally
+    with open(local_path, "w", encoding="utf-8") as f:
+        json.dump(trace_data, f, indent=2)
+
+    # Push file to Space Hub if credentials and Space target are configured
+    if token and token != "hf_YOUR_WRITE_TOKEN_HERE" and repo_id:
+        try:
+            # Instantiate Hugging Face API client
+            api = HfApi(token=token)
+            # Upload file directly to the Space repository
+            api.upload_file(
+                path_or_fileobj=local_path,
+                path_in_repo=f"agent_traces/{filename}",
+                repo_id=repo_id,
+                repo_type="space",
+            )
+            print(f"Trace pushed to Space repo: {repo_id}/agent_traces/{filename}")
+            return True
+        except Exception as e:
+            # Log failure if upload is blocked
+            print(f"Failed to push trace to Hub: {e}")
+            return False
+
+    # Log local fallback
+    print("Trace saved locally (SPACE_ID or HF_TOKEN config not found).")
+    return False
+
+
+# --- Core Run Agent Loop ---
+
+
+def run_agent(task_prompt: str, task_id: str | None = None) -> dict:
+    """Instantiates a CodeAgent with our Gemma 4 model and runs the task."""
+    # Fallback to dynamic timestamp-based ID if none is supplied
+    if task_id is None:
+        task_id = f"task_{int(datetime.now().timestamp())}"
+
+    # Initialize our custom model wrapper
+    model_wrapper = GemmaLocalModel()
+
+    # Define tools list for agent capability mapping
+    tools = [
+        query_inventory_database,
+        execute_database_command,
+        generate_invoice_pdf,
+        draft_customer_email,
+    ]
+
+    # Instantiate CodeAgent
+    agent = CodeAgent(tools=tools, model=model_wrapper, max_steps=5)
+
+    # Execute target task instruction
+    result = agent.run(task_prompt)
+
+    # Fetch intermediate execution steps from agent memory
+    steps = agent.memory.get_full_steps() if hasattr(agent, "memory") else []
+
+    # Upload logs file to the Hub (Sharing is Caring badge)
+    shared = share_trace_on_hub(task_id, steps)
+
+    return {
+        "task_id": task_id,
+        "result": result,
+        "trace_shared": shared,
+        "local_trace_path": os.path.join("agent_traces", f"trace_{task_id}.json"),
+    }
+
+
+# Execute test runs on direct execution
+if __name__ == "__main__":
+    # Import database initializer
+    import database
+
+    # Set tables schemas and seed data
+    database.initialize_database()
+
+    # Test query instruction
+    test_prompt = "Query the inventory to find all items that have 'rustic' style, and count them."
+    try:
+        print("Running agent test task...")
+        # Run test execution
+        agent_out = run_agent(test_prompt, "test_run_01")
+        print("\nAgent Output:", agent_out["result"])
+        print("Trace Path:", agent_out["local_trace_path"])
+    except Exception as e:
+        # Log failure
+        print("Agent failed to run:", e)

app.py

@@ -0,0 +1,371 @@
+# Import directory and path utilities
+import os
+import sys
+
+# Import Gradio web components
+import gradio as gr
+
+# Ensure workspace paths are resolved correctly for package imports
+sys.path.append(os.path.dirname(os.path.abspath(__file__)))
+
+# Import database, model, and agent modules
+import agent
+import database
+import models
+
+# Initialize SQLite schemas and seed baseline mock records
+database.initialize_database()
+
+# Resolve absolute paths to CSS and JS static assets
+CSS_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "style.css")
+JS_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "script.js")
+
+# Read CSS override styles
+with open(CSS_PATH, "r", encoding="utf-8") as f:
+    custom_css = f.read()
+
+# Read Javascript clipboard hooks
+with open(JS_PATH, "r", encoding="utf-8") as f:
+    custom_js = f.read()
+
+# --- Backend Ingestion Endpoints ---
+
+
+def analyze_and_draft_copy(image, custom_notes):
+    """Processes product image + custom notes via Gemma 4 to output copy blocks."""
+    # Ensure image has been uploaded
+    if image is None:
+        return ("Please upload an image of the craft item first.", "", "", "", "")
+
+    # Define system instructions prompting Gemma 4 for structured outputs
+    prompt = f"""
+You are the creative coordinator for Clara's artisan design studio.
+Analyze the uploaded image of this hand-made craft product.
+
+Custom artisan notes about the item:
+"{custom_notes if custom_notes else "No additional notes provided."}"
+
+Based on the image details and notes, generate the following content in a single structured response.
+Format each section exactly as labeled with headings:
+
+---SECTION 1: STRUCTURED ATTRIBUTES---
+Category: [Extracted category, e.g., Mug, Vase, Planter]
+Materials: [List materials, e.g., stoneware clay, blue glaze]
+Colors: [Dominant colors]
+Style: [Esthetic style, e.g., rustic, modern, whimsical]
+
+---SECTION 2: SEO LISTING COPY---
+Title: [A SEO-friendly title under 140 characters]
+Description: [A warm, narrative, story-driven product description detailing the handmade feel. Do NOT use buzzwords like "unmatched", "perfect addition", or "elevate your space".]
+Tags: [13 keywords separated by commas]
+
+---SECTION 3: SOCIAL MARKETING---
+Instagram: [Engaging Instagram caption with calls to action and relevant craft hashtags]
+Pinterest: [SEO-optimized Pinterest description detailing the visuals]
+"""
+
+    try:
+        # Load Gemma 4 from cache and run multimodal inference
+        response = models.generate_response(prompt, image=image, max_new_tokens=1536)
+
+        # Initialize fallback values for parsed segments
+        attributes = "Not extracted"
+        listing_copy = "Not extracted"
+        social_copy = "Not extracted"
+
+        # Split output text blocks using separators
+        sections = response.split("---")
+        # Extract individual section strings
+        for section in sections:
+            if "SECTION 1" in section:
+                attributes = section.replace(
+                    "SECTION 1: STRUCTURED ATTRIBUTES---", ""
+                ).strip()
+            elif "SECTION 2" in section:
+                listing_copy = section.replace(
+                    "SECTION 2: SEO LISTING COPY---", ""
+                ).strip()
+            elif "SECTION 3" in section:
+                social_copy = section.replace(
+                    "SECTION 3: SOCIAL MARKETING---", ""
+                ).strip()
+
+        return "Success!", attributes, listing_copy, social_copy, response
+    except Exception as e:
+        # Catch and return error output
+        return f"Error during model analysis: {str(e)}", "", "", "", ""
+
+
+def run_agent_task(prompt):
+    """Traces and executes administrative business tasks using smolagents."""
+    # Verify input exists
+    if not prompt.strip():
+        return "Please input a query or task instruction.", "", None, "Trace idle."
+
+    try:
+        # Trigger smolagents CodeAgent execution loop
+        res = agent.run_agent(prompt)
+
+        # Initialize export files collector list
+        exported_files = []
+        # Get active directory path
+        workspace_dir = os.path.dirname(os.path.abspath(__file__))
+        # Scan workspace for generated PDF invoices or email text drafts
+        for file in os.listdir(workspace_dir):
+            if (file.startswith("invoice_order_") and file.endswith(".pdf")) or (
+                file.startswith("email_draft_") and file.endswith(".txt")
+            ):
+                exported_files.append(os.path.join(workspace_dir, file))
+
+        # Format output strings
+        result_text = str(res["result"])
+        # Format Hub trace sharing confirmation message
+        trace_status = (
+            "Trace successfully shared on Hugging Face Hub!"
+            if res["trace_shared"]
+            else "Trace saved locally in agent_traces/"
+        )
+
+        # Read contents from generated local trace JSON file
+        trace_path = os.path.join(workspace_dir, res["local_trace_path"])
+        trace_log = ""
+        if os.path.exists(trace_path):
+            with open(trace_path, "r", encoding="utf-8") as f:
+                trace_log = f.read()
+
+        return (
+            result_text,
+            trace_log,
+            exported_files if exported_files else None,
+            trace_status,
+        )
+    except Exception as e:
+        # Return error output if agent crashes
+        return f"Error executing agent task: {str(e)}", "", None, "Trace failed."
+
+
+# --- Gradio UI Layout Building ---
+
+# Initialize Blocks with custom browser title
+with gr.Blocks(title="Vessel: Creative Studio Client") as demo:
+    # Render main header styling panel
+    gr.HTML("""
+    <div class="header-row" style="text-align: center; margin-bottom: 2rem;">
+        <h1 style="color: #2dd4bf; font-weight: 900; font-size: 2.8rem; margin-bottom: 0.2rem; letter-spacing: 0.05em;">VESSEL</h1>
+        <p style="color: #e5e7eb; font-size: 1.15rem; font-weight: 500; max-width: 800px; margin: 0.5rem auto 1rem auto; line-height: 1.6;">
+            A Local-First Creative Studio Client and Agentic Assistant for Artisans, automating content curation and studio administration.
+        </p>
+        <!-- Horizontal highlight pills mapping model specifications -->
+        <div class="badge-container">
+            <span class="vessel-badge">🏺 google/gemma-4-12b-it</span>
+            <span class="vessel-badge">🤖 smolagents framework</span>
+            <span class="vessel-badge">💾 local sqlite db</span>
+            <span class="vessel-badge">🎨 off-brand theme</span>
+            <span class="vessel-badge vessel-badge-orange">🌐 track 1: backyard ai</span>
+            <span class="vessel-badge vessel-badge-orange">🔒 off the grid</span>
+        </div>
+    </div>
+    """)
+
+    # Render collapsible testing instructions accordion
+    with gr.Accordion("📖 Quick Start & Testing Instructions", open=False):
+        gr.Markdown("""
+        ### How to test Vessel Studio:
+        
+        #### 1. Ingest & Copywriting Tab
+        * **Objective**: Automatically analyze a raw product photo to generate attributes, descriptions, and social posts.
+        * **Action**: Drag and drop a product image (e.g. ceramic mug or plate) into the **Product Canvas** panel, optionally add notes, and click **Ingest & Generate Copy**.
+        * **Result**: Gemma 4 extracts materials/styles and writes SEO-optimized listings and captions inside copy-to-clipboard cards.
+        
+        #### 2. Assistant Terminal Tab
+        * **Objective**: Query and modify the local database, generate PDF invoices, and draft client emails.
+        * **Action**: Try typing one of these mock instructions into the **Task Command** input field and click **Execute Studio Task**:
+          * *Type*: `Query the customer list to find John Doe's email and shipping address.`
+          * *Type*: `Create a PDF invoice for order #1 and save it.`
+          * *Type*: `Draft a thank you email for order #2 to the customer's email address.`
+          * *Type*: `Update the status of order #1 in the database to 'Shipped'.`
+        * **Result**: The agent writes and runs local Python commands on-the-fly, updates SQLite records, generates files for download, and logs its trace!
+        """)
+
+    # Render primary layout tabs
+    with gr.Tabs():
+        # Setup Studio Ingest Tab
+        with gr.Tab("Studio Ingest"):
+            with gr.Row():
+                # Setup Ingest canvas column (Left Column)
+                with gr.Column(scale=1):
+                    gr.HTML(
+                        "<h3 style='color: #2dd4bf; margin-bottom: 1rem;'>Product Canvas</h3>"
+                    )
+                    # Upload image container
+                    product_image = gr.Image(
+                        type="pil",
+                        label="Upload Product Photo",
+                        sources=["upload", "webcam"],
+                    )
+                    # Input notes text field
+                    artisan_notes = gr.Textbox(
+                        label="Artisan Notes (Optional)",
+                        placeholder="Add notes on custom dimensions, inspiration, or custom customer stories...",
+                        lines=3,
+                    )
+                    # Submit button
+                    ingest_btn = gr.Button("Ingest & Generate Copy", variant="primary")
+                    # Processing feedback textbox
+                    status_indicator = gr.Textbox(
+                        label="Ingest Status", interactive=False
+                    )
+
+                # Setup Output Canvas column (Right Column)
+                with gr.Column(scale=2):
+                    gr.HTML(
+                        "<h3 style='color: #2dd4bf; margin-bottom: 1rem;'>Generated Studio Deliverables</h3>"
+                    )
+
+                    with gr.Tabs():
+                        # Structured attributes metadata tab
+                        with gr.Tab("Structured Attributes"):
+                            attr_output = gr.Textbox(
+                                label="Visual Metadata", lines=6, interactive=False
+                            )
+                            copy_attr_btn = gr.Button(
+                                "Copy Attributes to Clipboard", variant="secondary"
+                            )
+                            # Register JS click event
+                            copy_attr_btn.click(
+                                fn=None,
+                                inputs=[attr_output],
+                                js="(text) => copyToClipboard(text)",
+                            )
+
+                        # SEO listings copywriting tab
+                        with gr.Tab("SEO Listings"):
+                            listing_output = gr.Textbox(
+                                label="Shopify / Etsy Listing Draft",
+                                lines=12,
+                                interactive=False,
+                            )
+                            copy_listing_btn = gr.Button(
+                                "Copy Listing to Clipboard", variant="secondary"
+                            )
+                            # Register JS click event
+                            copy_listing_btn.click(
+                                fn=None,
+                                inputs=[listing_output],
+                                js="(text) => copyToClipboard(text)",
+                            )
+
+                        # Social marketing copywriting tab
+                        with gr.Tab("Social Marketing"):
+                            social_output = gr.Textbox(
+                                label="Pinterest & Instagram Drafts",
+                                lines=10,
+                                interactive=False,
+                            )
+                            copy_social_btn = gr.Button(
+                                "Copy Marketing Content to Clipboard",
+                                variant="secondary",
+                            )
+                            # Register JS click event
+                            copy_social_btn.click(
+                                fn=None,
+                                inputs=[social_output],
+                                js="(text) => copyToClipboard(text)",
+                            )
+
+                        # Raw completion response debugging tab
+                        with gr.Tab("Raw Response"):
+                            raw_output = gr.Textbox(
+                                label="Gemma 4 Raw Output", lines=15, interactive=False
+                            )
+
+            # Map the Ingestion trigger to backend analysis logic
+            ingest_btn.click(
+                fn=analyze_and_draft_copy,
+                inputs=[product_image, artisan_notes],
+                outputs=[
+                    status_indicator,
+                    attr_output,
+                    listing_output,
+                    social_output,
+                    raw_output,
+                ],
+            )
+
+        # Setup Assistant Terminal Tab
+        with gr.Tab("Assistant Terminal"):
+            with gr.Row():
+                # Setup Assistant Control Column (Left Column)
+                with gr.Column(scale=1):
+                    gr.HTML(
+                        "<h3 style='color: #2dd4bf; margin-bottom: 1rem;'>Assistant Control</h3>"
+                    )
+                    # Text prompt query input
+                    agent_prompt = gr.Textbox(
+                        label="Task Command",
+                        placeholder="e.g., Query the customer database, find Sarah's email, and compile a PDF invoice for order #1.",
+                        lines=4,
+                    )
+                    # Action execution trigger button
+                    run_agent_btn = gr.Button("Execute Studio Task", variant="primary")
+
+                    gr.HTML(
+                        "<h4 style='color: #e5e7eb; margin-top: 2rem; margin-bottom: 0.5rem;'>Exported Documents</h4>"
+                    )
+                    # Output file downloader container
+                    output_files = gr.File(
+                        label="Download Generated Invoices / Email Text Files",
+                        file_count="multiple",
+                        interactive=False,
+                    )
+
+                # Setup Agent Workspace Trace Column (Right Column)
+                with gr.Column(scale=2):
+                    gr.HTML(
+                        "<h3 style='color: #2dd4bf; margin-bottom: 1rem;'>Agent Workspace Trace</h3>"
+                    )
+
+                    # Wrap terminal text area in a custom window component
+                    with gr.Column(elem_classes=["terminal-window"]):
+                        gr.HTML("""
+                        <div class="terminal-header">
+                            <span class="dot dot-red"></span>
+                            <span class="dot dot-yellow"></span>
+                            <span class="dot dot-green"></span>
+                            <span class="terminal-title">smolagents@vessel-studio-terminal ~ bash</span>
+                        </div>
+                        """)
+                        # Execution logs console view
+                        agent_trace_view = gr.Textbox(
+                            label="Execution Log",
+                            lines=18,
+                            interactive=False,
+                        )
+
+                    # Task execution summary textbox
+                    agent_result_view = gr.Textbox(
+                        label="Task Result Summary", lines=3, interactive=False
+                    )
+                    # Hub trace upload status feedback label
+                    trace_upload_status = gr.Label(label="Trace Hub Sharing Status")
+
+            # Map the Assistant execution trigger to backend agent loop
+            run_agent_btn.click(
+                fn=run_agent_task,
+                inputs=[agent_prompt],
+                outputs=[
+                    agent_result_view,
+                    agent_trace_view,
+                    output_files,
+                    trace_upload_status,
+                ],
+            )
+
+# Run web app server with custom styling layers
+if __name__ == "__main__":
+    demo.launch(
+        server_name="0.0.0.0",
+        server_port=7860,
+        css=custom_css,
+        js=custom_js,
+    )

database.py

@@ -0,0 +1,221 @@
+# Import native sqlite engine and file path system utilities
+import os
+import sqlite3
+from datetime import datetime
+
+# Resolve the absolute path to the local database file inside the project directory
+DB_PATH = os.path.join(os.path.dirname(os.path.abspath(__file__)), "vessel_studio.db")
+
+
+def get_connection():
+    """Returns a connection to the SQLite database with row factory enabled."""
+    # Establish a connection to the SQLite database file
+    conn = sqlite3.connect(DB_PATH)
+    # Enable dict-like row formatting to access columns by their name keys
+    conn.row_factory = sqlite3.Row
+    return conn
+
+
+def db_query(sql_query: str, params: tuple = ()) -> list:
+    """Executes a SELECT query and returns the results as a list of dicts."""
+    # Retrieve a fresh database connection instance
+    conn = get_connection()
+    try:
+        # Initialize the cursor to execute SQL commands
+        cursor = conn.cursor()
+        # Execute the SELECT statement with the provided parameter tuple
+        cursor.execute(sql_query, params)
+        # Fetch all matching database records
+        rows = cursor.fetchall()
+        # Convert row objects to standard Python dictionaries and return the list
+        return [dict(row) for row in rows]
+    except Exception as e:
+        # Return the error message inside a list to prevent application crashes
+        return [{"error": str(e)}]
+    finally:
+        # Guarantee database connection closure in all execution paths
+        conn.close()
+
+
+def db_execute(sql_command: str, params: tuple = ()) -> str:
+    """Executes an INSERT, UPDATE, or DELETE command and commits changes."""
+    # Retrieve a fresh database connection instance
+    conn = get_connection()
+    try:
+        # Initialize the cursor to execute SQL commands
+        cursor = conn.cursor()
+        # Execute the database modification statement
+        cursor.execute(sql_command, params)
+        # Commit the modification transaction to write changes to disk
+        conn.commit()
+        # Capture the primary key of the last inserted row
+        last_row_id = cursor.lastrowid
+        # Calculate the total number of rows modified by the command
+        changes = conn.total_changes
+        return f"Success. Row ID affected/inserted: {last_row_id}. Rows changed: {changes}."
+    except Exception as e:
+        # Return a descriptive error message if execution fails
+        return f"Error executing command: {str(e)}"
+    finally:
+        # Guarantee database connection closure in all execution paths
+        conn.close()
+
+
+def initialize_database():
+    """Creates the SQLite database tables and populates them with initial mock data if empty."""
+    # Open connection and get cursor
+    conn = get_connection()
+    cursor = conn.cursor()
+
+    # Create the customer profile registry table
+    cursor.execute("""
+    CREATE TABLE IF NOT EXISTS customers (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        email TEXT UNIQUE NOT NULL,
+        shipping_address TEXT
+    )
+    """)
+
+    # Create the inventory and product stock details table
+    cursor.execute("""
+    CREATE TABLE IF NOT EXISTS inventory (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL,
+        description TEXT,
+        price REAL NOT NULL,
+        stock INTEGER NOT NULL DEFAULT 0,
+        materials TEXT,
+        style TEXT
+    )
+    """)
+
+    # Create the customer orders transaction header table
+    cursor.execute("""
+    CREATE TABLE IF NOT EXISTS orders (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        customer_id INTEGER NOT NULL,
+        order_date TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'Pending',
+        total_price REAL,
+        FOREIGN KEY (customer_id) REFERENCES customers (id)
+    )
+    """)
+
+    # Create the line item association details table for orders
+    cursor.execute("""
+    CREATE TABLE IF NOT EXISTS order_items (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        order_id INTEGER NOT NULL,
+        product_id INTEGER NOT NULL,
+        quantity INTEGER NOT NULL,
+        price REAL NOT NULL,
+        FOREIGN KEY (order_id) REFERENCES orders (id),
+        FOREIGN KEY (product_id) REFERENCES inventory (id)
+    )
+    """)
+
+    # Commit structural tables creation
+    conn.commit()
+
+    # Query if customers already exist to skip seeding if data is present
+    cursor.execute("SELECT COUNT(*) FROM customers")
+    if cursor.fetchone()[0] == 0:
+        # Seed customer database rows
+        customers_data = [
+            (
+                "Sarah Jenkins",
+                "sarah.j@example.com",
+                "123 Maple Street, Portland, OR 97201",
+            ),
+            ("John Doe", "johndoe@example.com", "456 Oak Avenue, Seattle, WA 98101"),
+            (
+                "Emma Watson",
+                "emma@example.com",
+                "789 Pine Lane, San Francisco, CA 94103",
+            ),
+        ]
+        # Insert customer profiles in bulk
+        cursor.executemany(
+            "INSERT INTO customers (name, email, shipping_address) VALUES (?, ?, ?)",
+            customers_data,
+        )
+
+        # Seed inventory database items
+        inventory_data = [
+            (
+                "Rustic Teal Stoneware Mug",
+                "Hand-thrown ceramic mug with a beautiful teal drip glaze. Holds 12oz.",
+                24.00,
+                15,
+                "stoneware clay, teal glaze",
+                "rustic",
+            ),
+            (
+                "Minimalist White Vase",
+                "Stoneware bud vase with a matte white finish. Ideal for single stems.",
+                38.00,
+                8,
+                "ceramic clay, matte white glaze",
+                "minimalist",
+            ),
+            (
+                "Whimsical Forest Spoon Rest",
+                "Playful ceramic spoon rest stamped with leaf impressions and finished in olive green.",
+                18.00,
+                12,
+                "earth clay, olive green glaze",
+                "whimsical",
+            ),
+            (
+                "Terracotta Planter",
+                "Raw terracotta plant pot with matching saucer. Breathable clay base.",
+                28.00,
+                20,
+                "terracotta clay",
+                "rustic",
+            ),
+        ]
+        # Insert product specifications in bulk
+        cursor.executemany(
+            "INSERT INTO inventory (name, description, price, stock, materials, style) VALUES (?, ?, ?, ?, ?, ?)",
+            inventory_data,
+        )
+
+        # Create initial pending order transaction for customer Sarah Jenkins
+        cursor.execute(
+            "INSERT INTO orders (customer_id, order_date, status, total_price) VALUES (1, ?, 'Pending', 24.00)",
+            (datetime.now().strftime("%Y-%m-%d"),),
+        )
+        # Capture the ID of the newly generated order
+        order_id = cursor.lastrowid
+        # Add order line item mapping order to the Teal Stoneware Mug
+        cursor.execute(
+            "INSERT INTO order_items (order_id, product_id, quantity, price) VALUES (?, 1, 1, 24.00)",
+            (order_id,),
+        )
+
+        # Create second completed order transaction for customer Emma Watson
+        cursor.execute(
+            "INSERT INTO orders (customer_id, order_date, status, total_price) VALUES (3, ?, 'Shipped', 56.00)",
+            (datetime.now().strftime("%Y-%m-%d"),),
+        )
+        # Capture the ID of the second order
+        order_id = cursor.lastrowid
+        # Add multiple order line items in bulk
+        cursor.executemany(
+            "INSERT INTO order_items (order_id, product_id, quantity, price) VALUES (?, ?, ?, ?)",
+            [(order_id, 2, 1, 38.00), (order_id, 3, 1, 18.00)],
+        )
+
+        # Save all seeded records transaction to disk
+        conn.commit()
+
+    # Close connection
+    conn.close()
+    print("Database initialized successfully.")
+
+
+# Initialize SQLite tables on direct script execution
+if __name__ == "__main__":
+    initialize_database()

models.py

@@ -0,0 +1,162 @@
+# Import environment loaders and deep learning frameworks
+import os
+from dotenv import load_dotenv
+from PIL import Image
+import torch
+from transformers import AutoModelForMultimodalLM, AutoProcessor
+
+# Load token variables from local environment file
+load_dotenv()
+
+# Specify the Hugging Face hub repository target for Gemma 4
+MODEL_ID = "google/gemma-4-12B-it"
+
+# Initialize global cache elements to keep load states persistent
+_model = None
+_processor = None
+_device = None
+
+
+def get_device():
+    """Determines and returns the best available device."""
+    global _device
+    # Return device if already determined and cached
+    if _device is not None:
+        return _device
+
+    # Use NVIDIA GPU if CUDA framework is active
+    if torch.cuda.is_available():
+        _device = "cuda"
+    # Use Metal Performance Shaders if running on Apple Silicon
+    elif torch.backends.mps.is_available():
+        _device = "mps"
+    # Fall back to standard CPU processing if no accelerators are present
+    else:
+        _device = "cpu"
+    return _device
+
+
+def load_gemma_model():
+    """Loads and caches the Gemma 4 12B-it model and processor."""
+    global _model, _processor
+    # Avoid reload if model and processor are already warm in memory
+    if _model is not None and _processor is not None:
+        return _model, _processor
+
+    # Retrieve Hugging Face authentication token from environment
+    token = os.getenv("HF_TOKEN")
+    # Verify the token is present and not set to default template value
+    if not token or token == "hf_YOUR_WRITE_TOKEN_HERE":
+        raise ValueError(
+            "HF_TOKEN not set or invalid in the .env file. Please add your Hugging Face write token."
+        )
+
+    # Detect the active target execution hardware
+    device = get_device()
+    print(f"Loading {MODEL_ID} on device: {device}...")
+
+    # Download and instantiate the native multimodal processor config
+    _processor = AutoProcessor.from_pretrained(MODEL_ID, token=token)
+
+    # Initialize model options depending on device classification
+    if device == "cuda":
+        # Load in half-precision bfloat16 on server CUDA hardware
+        _model = AutoModelForMultimodalLM.from_pretrained(
+            MODEL_ID, dtype=torch.bfloat16, device_map="auto", token=token
+        )
+    elif device == "mps":
+        # Load in half-precision bfloat16 using CPU low memory options on local Mac
+        _model = AutoModelForMultimodalLM.from_pretrained(
+            MODEL_ID,
+            dtype=torch.bfloat16,
+            low_cpu_mem_usage=True,
+            device_map="auto",
+            token=token,
+        )
+    else:
+        # Load in standard 32-bit floating point precision on standard CPU
+        _model = AutoModelForMultimodalLM.from_pretrained(
+            MODEL_ID,
+            dtype=torch.float32,
+            low_cpu_mem_usage=True,
+            device_map="cpu",
+            token=token,
+        )
+
+    # Print success log when model initialization is finished
+    print("Model loaded successfully.")
+    return _model, _processor
+
+
+def generate_response(
+    prompt: str,
+    image: Image.Image | None = None,
+    max_new_tokens: int = 1024,
+    temperature: float = 0.4,
+) -> str:
+    """Generates a text response from Gemma 4 given a prompt and optional image."""
+    # Retrieve the model and processor from cache
+    model, processor = load_gemma_model()
+    # Resolve the active hardware device
+    device = get_device()
+
+    # Initialize message list
+    content = []
+    # Append the image item if it is provided
+    if image is not None:
+        content.append({"type": "image", "image": image})
+    # Append the text prompt item
+    content.append({"type": "text", "text": prompt})
+
+    # Wrap the contents inside a user role dict structure
+    messages = [{"role": "user", "content": content}]
+
+    # Format user inputs into the model's native chat syntax
+    text_prompt = processor.apply_chat_template(messages, add_generation_prompt=True)
+
+    # Run tokenization with the image if present
+    if image is not None:
+        inputs = processor(text=text_prompt, images=image, return_tensors="pt")
+    # Run tokenization with text-only parameters if image is absent
+    else:
+        inputs = processor(text=text_prompt, return_tensors="pt")
+
+    # Shift all input tensors to the target hardware device
+    inputs = {k: v.to(device) for k, v in inputs.items()}
+    # Convert visual features to match the exact data type of the model weights
+    if "pixel_values" in inputs:
+        inputs["pixel_values"] = inputs["pixel_values"].to(model.dtype)
+    # Convert audio features to match the model weights dtype
+    if "audio_values" in inputs:
+        inputs["audio_values"] = inputs["audio_values"].to(model.dtype)
+
+    # Generate text completions using no-gradient evaluation
+    with torch.no_grad():
+        generated_ids = model.generate(
+            **inputs,
+            max_new_tokens=max_new_tokens,
+            temperature=temperature,
+            do_sample=True if temperature > 0.0 else False,
+        )
+
+    # Extract the length of the input sequence to isolate the output completion
+    input_len = inputs["input_ids"].shape[1]
+    # Decode the newly generated token IDs, discarding the prompt tokens
+    response_ids = generated_ids[0][input_len:]
+    # Convert token IDs back to a readable text string
+    response_text = processor.decode(response_ids, skip_special_tokens=True)
+    return response_text.strip()
+
+
+# Test loading mechanism when running the script directly
+if __name__ == "__main__":
+    try:
+        # Load the model and print the resolved hardware configuration
+        model, processor = load_gemma_model()
+        print(
+            "Device map:",
+            model.hf_device_map if hasattr(model, "hf_device_map") else "CPU",
+        )
+    except Exception as e:
+        # Print failure trace
+        print("Error during test loading:", e)

pyrightconfig.json

@@ -0,0 +1,9 @@
+{
+  "exclude": [
+    "**/node_modules",
+    "**/__pycache__",
+    ".venv"
+  ],
+  "reportMissingImports": true,
+  "typeCheckingMode": "basic"
+}

run.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Vessel Auto-activating Runner Script
+
+# Resolve directory of this script
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+cd "$DIR"
+
+# Automatically activate virtual environment if it exists
+if [ -d ".venv" ]; then
+    source .venv/bin/activate
+else
+    echo "⚠️  Warning: Local python virtual environment (.venv) not found."
+    echo "Please run: python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt"
+fi
+
+# Determine script target (default to app.py)
+TARGET="${1:-app.py}"
+
+if [ "$TARGET" == "verify" ]; then
+    python3 verify_code.py "${@:2}"
+elif [ "$TARGET" == "db" ]; then
+    python3 database.py "${@:2}"
+elif [ -f "$TARGET" ]; then
+    python3 "$TARGET" "${@:2}"
+else
+    echo "❌ Error: Target script '$TARGET' not found."
+    echo "Usage:"
+    echo "  ./run.sh          # Launch the main Gradio application"
+    echo "  ./run.sh verify   # Run code format, lint, and type checks"
+    echo "  ./run.sh db       # Initialize/seed SQLite database"
+fi

script.js

@@ -0,0 +1,74 @@
+// Vessel Studio Frontend Javascript Utilities
+
+/**
+ * Copies the provided string content to the system clipboard and displays a visual toast.
+ * @param {string} text - Content to copy.
+ */
+function copyToClipboard(text) {
+    if (!text) return;
+    navigator.clipboard.writeText(text).then(function() {
+        showVesselToast("Copied to clipboard!");
+    }, function(err) {
+        console.error('Could not copy text: ', err);
+    });
+}
+
+/**
+ * Creates and displays a premium animated toast notification.
+ * @param {string} message - Content message to display.
+ */
+function showVesselToast(message) {
+    // Delete existing toast if active to prevent overlapping
+    let existingToast = document.querySelector(".vessel-toast");
+    if (existingToast) {
+        document.body.removeChild(existingToast);
+    }
+
+    let toast = document.createElement("div");
+    toast.className = "vessel-toast";
+    toast.innerText = message;
+    
+    // Apply styling parameters
+    Object.assign(toast.style, {
+        position: "fixed",
+        bottom: "30px",
+        right: "30px",
+        backgroundColor: "#0d9488",
+        color: "#ffffff",
+        padding: "14px 24px",
+        borderRadius: "8px",
+        boxShadow: "0 10px 25px -5px rgba(13, 148, 136, 0.4)",
+        zIndex: "99999",
+        opacity: "0",
+        transition: "opacity 0.25s ease, transform 0.25s ease",
+        transform: "translateY(15px)",
+        fontFamily: "'Plus Jakarta Sans', system-ui, sans-serif",
+        fontSize: "0.9rem",
+        fontWeight: "600",
+        letterSpacing: "0.02em"
+    });
+    
+    document.body.appendChild(toast);
+    
+    // Trigger entrance animation
+    setTimeout(() => {
+        toast.style.opacity = "1";
+        toast.style.transform = "translateY(0)";
+    }, 30);
+    
+    // Trigger dismissal animation
+    setTimeout(() => {
+        toast.style.opacity = "0";
+        toast.style.transform = "translateY(15px)";
+        setTimeout(() => {
+            if (toast.parentNode) {
+                document.body.removeChild(toast);
+            }
+        }, 250);
+    }, 2800);
+}
+
+// Initialize custom event integrations when Gradio loads
+document.addEventListener("DOMContentLoaded", () => {
+    console.log("Vessel Studio frontend initialized successfully.");
+});

style.css

@@ -0,0 +1,252 @@
+/* Vessel Studio Premium Glassmorphic Theme */
+
+@import url('https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:wght@300;400;500;600;700&display=swap');
+
+/* Global Reset & Font Mapping */
+body, .gradio-container {
+    font-family: 'Plus Jakarta Sans', system-ui, -apple-system, sans-serif !important;
+    background: radial-gradient(circle at top left, #0d1e2d 0%, #090d16 100%) !important;
+    color: #f3f4f6 !important;
+    margin: 0;
+    padding: 0;
+    min-height: 100vh;
+    display: flex !important;
+    justify-content: center !important;
+}
+
+/* Custom Scrollbar styling */
+::-webkit-scrollbar {
+    width: 8px;
+    height: 8px;
+}
+::-webkit-scrollbar-track {
+    background: rgba(17, 24, 39, 0.3);
+}
+::-webkit-scrollbar-thumb {
+    background: rgba(13, 148, 136, 0.4);
+    border-radius: 4px;
+}
+::-webkit-scrollbar-thumb:hover {
+    background: rgba(13, 148, 136, 0.6);
+}
+
+/* Glassmorphic Container Overrides */
+.gradio-container {
+    width: 100% !important;
+    padding: 2rem !important;
+}
+
+/* Header customization */
+header, .header-row {
+    margin-bottom: 2rem;
+    text-align: center;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+    padding-bottom: 1.5rem;
+}
+
+/* Card and Column Styling */
+.gr-box, .gr-padded, .gr-panel, .block {
+    background: rgba(17, 24, 39, 0.65) !important;
+    backdrop-filter: blur(16px) !important;
+    -webkit-backdrop-filter: blur(16px) !important;
+    border: 1px solid rgba(255, 255, 255, 0.08) !important;
+    border-radius: 16px !important;
+    box-shadow: 0 8px 32px 0 rgba(0, 0, 0, 0.3) !important;
+    padding: 1.5rem !important;
+    margin-bottom: 1rem;
+    transition: border-color 0.3s, box-shadow 0.3s;
+}
+
+.block:hover {
+    border-color: rgba(13, 148, 136, 0.3) !important;
+    box-shadow: 0 8px 32px 0 rgba(13, 148, 136, 0.05) !important;
+}
+
+/* Inputs and Forms */
+input, textarea, select {
+    background-color: rgba(31, 41, 55, 0.5) !important;
+    border: 1px solid rgba(255, 255, 255, 0.08) !important;
+    color: #f9fafb !important;
+    border-radius: 8px !important;
+    padding: 10px 14px !important;
+    font-size: 0.95rem !important;
+    transition: all 0.2s ease-in-out !important;
+}
+
+input:focus, textarea:focus, select:focus {
+    border-color: #0d9488 !important;
+    box-shadow: 0 0 0 2px rgba(13, 148, 136, 0.25) !important;
+    background-color: rgba(31, 41, 55, 0.8) !important;
+    outline: none !important;
+}
+
+/* Form labels */
+.block span, label {
+    color: #9ca3af !important;
+    font-weight: 500 !important;
+    font-size: 0.85rem !important;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    margin-bottom: 4px;
+}
+
+/* Tab Headers */
+.tabs {
+    border-bottom: 1px solid rgba(255, 255, 255, 0.08) !important;
+    margin-bottom: 1.5rem !important;
+}
+
+.tab-nav button {
+    color: #9ca3af !important;
+    border-bottom: 2px solid transparent !important;
+    font-weight: 600 !important;
+    padding: 12px 20px !important;
+    transition: all 0.3s !important;
+}
+
+.tab-nav button.selected {
+    color: #2dd4bf !important;
+    border-bottom: 2px solid #0d9488 !important;
+    background: transparent !important;
+}
+
+.tab-nav button:hover:not(.selected) {
+    color: #f3f4f6 !important;
+    border-bottom: 2px solid rgba(13, 148, 136, 0.3) !important;
+}
+
+/* Buttons Styling */
+button.primary {
+    background: linear-gradient(135deg, #0d9488 0%, #0f766e 100%) !important;
+    color: #ffffff !important;
+    border: none !important;
+    font-weight: 600 !important;
+    border-radius: 8px !important;
+    padding: 12px 24px !important;
+    cursor: pointer !important;
+    box-shadow: 0 4px 14px 0 rgba(13, 148, 136, 0.3) !important;
+    transition: all 0.2s ease-in-out !important;
+}
+
+button.primary:hover {
+    transform: translateY(-1px) !important;
+    box-shadow: 0 6px 20px 0 rgba(13, 148, 136, 0.5) !important;
+    background: linear-gradient(135deg, #0f766e 0%, #115e59 100%) !important;
+}
+
+button.primary:active {
+    transform: translateY(1px) !important;
+}
+
+button.secondary, button:not(.primary) {
+    background: rgba(31, 41, 55, 0.5) !important;
+    color: #e5e7eb !important;
+    border: 1px solid rgba(255, 255, 255, 0.1) !important;
+    font-weight: 500 !important;
+    border-radius: 8px !important;
+    padding: 12px 24px !important;
+    transition: all 0.2s !important;
+}
+
+button:not(.primary):hover {
+    background: rgba(55, 65, 81, 0.7) !important;
+    border-color: rgba(255, 255, 255, 0.2) !important;
+}
+
+/* Visual Studio Client Terminal (Agent panel) */
+.terminal-window {
+    background: #05070c !important;
+    border: 1px solid rgba(13, 148, 136, 0.25) !important;
+    border-radius: 12px !important;
+    padding: 1rem !important;
+    font-family: 'Fira Code', 'Courier New', Courier, monospace !important;
+    box-shadow: inset 0 0 10px rgba(0,0,0,0.8), 0 4px 20px rgba(0,0,0,0.5) !important;
+}
+
+.terminal-header {
+    display: flex;
+    align-items: center;
+    border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+    padding-bottom: 8px;
+    margin-bottom: 10px;
+}
+
+.dot {
+    width: 10px;
+    height: 10px;
+    border-radius: 50%;
+    margin-right: 6px;
+    display: inline-block;
+}
+
+.dot-red { background-color: #ef4444; }
+.dot-yellow { background-color: #f59e0b; }
+.dot-green { background-color: #10b981; }
+
+.terminal-title {
+    color: #6b7280;
+    font-size: 0.75rem;
+    font-weight: 600;
+    margin-left: 8px;
+    letter-spacing: 0.05em;
+}
+
+/* Copy Card Widget styling */
+.copy-card {
+    border-left: 4px solid #0d9488 !important;
+    background: rgba(13, 148, 136, 0.05) !important;
+}
+
+/* Hide standard Gradio footer for a clean product feel */
+footer {
+    display: none !important;
+}
+
+/* Progress indicator override */
+.generating {
+    border-color: #0d9488 !important;
+    animation: pulse 1.5s infinite;
+}
+
+@keyframes pulse {
+    0% { opacity: 0.6; }
+    50% { opacity: 1; }
+    100% { opacity: 0.6; }
+}
+
+/* Custom UI Badges & Pills styling */
+.badge-container {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: 8px;
+    margin-top: 14px;
+    margin-bottom: 8px;
+}
+
+.vessel-badge {
+    background: rgba(13, 148, 136, 0.15) !important;
+    border: 1px solid rgba(13, 148, 136, 0.3) !important;
+    color: #2dd4bf !important;
+    padding: 5px 14px !important;
+    border-radius: 9999px !important;
+    font-size: 0.75rem !important;
+    font-weight: 600 !important;
+    letter-spacing: 0.05em !important;
+    text-transform: uppercase;
+}
+
+.vessel-badge-orange {
+    background: rgba(249, 115, 22, 0.12) !important;
+    border: 1px solid rgba(249, 115, 22, 0.25) !important;
+    color: #fb923c !important;
+}
+
+/* Accordion instruction block overrides */
+.instruction-box {
+    margin-top: 1rem !important;
+    border: 1px solid rgba(255, 255, 255, 0.06) !important;
+    border-radius: 12px !important;
+    background: rgba(17, 24, 39, 0.4) !important;
+}
+

verify_code.py

@@ -0,0 +1,123 @@
+# Import standard OS path features
+import os
+
+# Import sys to handle runtime exits
+import sys
+
+# Import command-line argument parser utilities
+import argparse
+
+# Import subprocess to execute linter binaries
+import subprocess
+
+
+def run_command(command: list, description: str) -> bool:
+    """Runs a shell command and displays output with color markers."""
+    # Display the active task title
+    print(f"\n=== Running {description} ===")
+    # Print the exact command list parsed into a string
+    print(f"Command: {' '.join(command)}")
+
+    try:
+        # Run binary in subprocess, capturing output text blocks
+        result = subprocess.run(command, capture_output=True, text=True)
+        # Check if the execution returned exit code zero (success)
+        if result.returncode == 0:
+            print("✅ SUCCESS")
+            # Print standard output if text is present
+            if result.stdout.strip():
+                print(result.stdout.strip())
+            return True
+        # Handle execution failure (non-zero exit code)
+        else:
+            print("❌ FAILED")
+            # Print output logs to support troubleshooting
+            if result.stdout.strip():
+                print("\nStdout:")
+                print(result.stdout.strip())
+            # Print error logs if present
+            if result.stderr.strip():
+                print("\nStderr:")
+                print(result.stderr.strip())
+            return False
+    except FileNotFoundError:
+        # Log failure if linter binary cannot be found in virtual env
+        print(
+            f"❌ ERROR: Command '{command[0]}' not found. Make sure dependencies are installed in your virtual environment."
+        )
+        return False
+
+
+def main():
+    # Setup CLI argument parser
+    parser = argparse.ArgumentParser(
+        description="Code hygiene and quality verification pipeline."
+    )
+    # Register the auto-fix parameter flag
+    parser.add_argument(
+        "--fix",
+        "-f",
+        action="store_true",
+        help="Attempt to auto-format files and auto-fix linter issues.",
+    )
+    # Parse incoming CLI command arguments
+    args = parser.parse_args()
+
+    # Resolve the absolute workspace directory of this checker script
+    workspace_dir = os.path.dirname(os.path.abspath(__file__))
+    # Shift current working directory to workspace base
+    os.chdir(workspace_dir)
+
+    # Resolve virtual environment bin executable directory path
+    venv_bin = os.path.join(workspace_dir, ".venv", "bin")
+    # Prepend virtual environment bin path to PATH to locate local ruff/pyright binaries
+    if os.path.exists(venv_bin):
+        os.environ["PATH"] = venv_bin + os.pathsep + os.environ.get("PATH", "")
+
+    # Execute auto-fixing parameters if flag is parsed
+    if args.fix:
+        print("🔧 Attempting to auto-correct issues...")
+        # Execute Ruff formatting in write mode
+        fmt_passed = run_command(
+            ["ruff", "format", "."], "Ruff Code Formatting (Auto-fixing)"
+        )
+        # Execute Ruff linter in auto-fix write mode
+        lint_passed = run_command(
+            ["ruff", "check", "--fix", "."], "Ruff Linter (Auto-fixing)"
+        )
+    # Execute default validation parameters (dry run)
+    else:
+        # Execute Ruff formatting in validation check-only mode
+        fmt_passed = run_command(
+            ["ruff", "format", "--check", "."], "Ruff Code Formatting Validation"
+        )
+        # Execute Ruff linter in check-only validation mode
+        lint_passed = run_command(["ruff", "check", "."], "Ruff Linter Validation")
+
+    # Run Pyright static type checker against the codebase
+    type_passed = run_command(["pyright", "."], "Pyright Static Type Validation")
+
+    # Evaluate if all checkers completed successfully
+    if fmt_passed and lint_passed and type_passed:
+        print(
+            "\n🎉 CODEBASE IS PRISTINE: Formatting is correct, lint checks passed, and type signatures are valid!"
+        )
+        # Exit with success code
+        sys.exit(0)
+    else:
+        # Report failure if any validation check fails
+        print(
+            "\n⚠️ CODE BASE ISSUES FOUND: Please resolve the formatting, lint, or type signatures issues listed above."
+        )
+        # Suggest auto-fix parameter tip if running in dry-run mode
+        if not args.fix:
+            print(
+                "💡 TIP: Run 'python verify_code.py --fix' to automatically resolve formatting and simple linter warnings."
+            )
+        # Exit with failure code
+        sys.exit(1)
+
+
+# Execute checks when running checker script directly
+if __name__ == "__main__":
+    main()