Update app.py

app.py

@@ -1,120 +1,250 @@
+# ============================================================
+# OPEN-WORLD OBJECT INTELLIGENCE PLATFORM
+# Hugging Face Spaces + Gradio + ZeroGPU + FastAPI
+# ============================================================
+
+# IMPORTANT:
+# Import `spaces` BEFORE GPU/ML-related libraries.
+import spaces
+
 import os
 import json
 import tempfile
-import zipfile
+import base64
+
 import cv2
 import numpy as np
-import spaces
 
 from PIL import Image
+
 import gradio as gr
 from fastapi import FastAPI, File, UploadFile, Form, HTTPException
 from fastapi.responses import JSONResponse, FileResponse
 from fastapi.middleware.cors import CORSMiddleware
+
 import uvicorn
 
-# ---------------------------------------------------------------------------
-# Monkey-patch gradio_client bug (Gradio 4.44.0):
-# gradio_client.utils._json_schema_to_python_type crashes with
-# TypeError: argument of type 'bool' is not iterable
-# when a JSON schema has `additionalProperties: true` (a bool, not a dict).
-# ---------------------------------------------------------------------------
-import gradio_client.utils as _gc_utils
-
-_original_json_schema_to_python_type = _gc_utils._json_schema_to_python_type
-
-def _safe_json_schema_to_python_type(schema, defs=None):
-    if not isinstance(schema, dict):
-        return "Any"
-    return _original_json_schema_to_python_type(schema, defs)
-
-_gc_utils._json_schema_to_python_type = _safe_json_schema_to_python_type
-
-# ---------------------------------------------------------------------------
-# Starlette / Gradio TemplateResponse compatibility
-# ---------------------------------------------------------------------------
-# Gradio 4.x uses the older TemplateResponse calling convention while newer
-# Starlette releases expect the Request object first.  When these versions
-# are mixed, Starlette can pass the context dict to Jinja2 as the template
-# name, producing: TypeError: unhashable type: 'dict'.
-# Normalize the old Gradio call without changing Jinja2 itself.
+
+# ============================================================
+# GRADIO CLIENT COMPATIBILITY PATCH
+# ============================================================
+
+try:
+    import gradio_client.utils as _gc_utils
+
+    if hasattr(
+        _gc_utils,
+        "_json_schema_to_python_type"
+    ):
+
+        _original_json_schema_to_python_type = (
+            _gc_utils._json_schema_to_python_type
+        )
+
+        def _safe_json_schema_to_python_type(
+            schema,
+            defs=None
+        ):
+            if not isinstance(schema, dict):
+                return "Any"
+
+            return _original_json_schema_to_python_type(
+                schema,
+                defs
+            )
+
+        _gc_utils._json_schema_to_python_type = (
+            _safe_json_schema_to_python_type
+        )
+
+except Exception as e:
+
+    print(
+        "[WARNING] Gradio client compatibility patch "
+        f"could not be applied: {e}"
+    )
+
+
+# ============================================================
+# STARLETTE / GRADIO TEMPLATE COMPATIBILITY PATCH
+# ============================================================
+
 try:
+
     from starlette.templating import Jinja2Templates
 
-    _original_template_response = Jinja2Templates.TemplateResponse
+    _original_template_response = (
+        Jinja2Templates.TemplateResponse
+    )
+
+    def _compatible_template_response(
+        self,
+        *args,
+        **kwargs
+    ):
 
-    def _compatible_template_response(self, *args, **kwargs):
         if (
             len(args) >= 2
             and isinstance(args[0], dict)
             and isinstance(args[1], str)
         ):
-            # New Starlette interprets args[0] as Request.  Gradio's older
-            # call style can provide context first and template name second.
+
             context = args[0]
             template_name = args[1]
             remaining = args[2:]
+
             return _original_template_response(
-                self, template_name, context, *remaining, **kwargs
+                self,
+                template_name,
+                context,
+                *remaining,
+                **kwargs
             )
-        return _original_template_response(self, *args, **kwargs)
 
-    Jinja2Templates.TemplateResponse = _compatible_template_response
-except Exception:
-    # Do not prevent the application from starting if the installed
-    # Starlette version does not expose this class in the expected form.
-    pass
+        return _original_template_response(
+            self,
+            *args,
+            **kwargs
+        )
+
+    Jinja2Templates.TemplateResponse = (
+        _compatible_template_response
+    )
+
+except Exception as e:
+
+    print(
+        "[WARNING] Starlette compatibility patch "
+        f"not applied: {e}"
+    )
+
+
+# ============================================================
+# BACKEND IMPORTS
+# ============================================================
 
 from backend.config import (
     KNOWN_CONFIDENCE_THRESHOLD,
     OPEN_VOCAB_CONFIDENCE_THRESHOLD,
     SPECIFIC_SIMILARITY_THRESHOLD,
-    SQLITE_DB_PATH
+    SQLITE_DB_PATH,
 )
+
 from backend.ml.orchestrator import orchestrator
 from backend.database.storage import db
 
 
-
-# ---------------------------------------------------------------------------
-# Helper functions (non-GPU)
-# ---------------------------------------------------------------------------
+# ============================================================
+# GENERAL HELPERS
+# ============================================================
 
 def get_objects_table():
+
     objs = db.get_all_objects()
+
     data = []
+
     for o in objs:
-        data.append([o.id, o.name, o.category, o.image_count, o.embedding_count, o.created_at])
+
+        data.append([
+            o.id,
+            o.name,
+            o.category,
+            o.image_count,
+            o.embedding_count,
+            o.created_at
+        ])
+
     return data
 
 
 def delete_selected_object(object_id):
-    if not object_id or not object_id.strip():
-        return "❌ Please enter a valid Object ID to delete.", get_objects_table()
-    success = db.delete_object(object_id.strip())
+
+    if (
+        not object_id
+        or not object_id.strip()
+    ):
+
+        return (
+            "❌ Please enter a valid Object ID to delete.",
+            get_objects_table()
+        )
+
+    object_id = object_id.strip()
+
+    success = db.delete_object(
+        object_id
+    )
+
     if success:
-        return f"✅ Deleted object '{object_id}'.", get_objects_table()
-    return f"❌ Object '{object_id}' not found.", get_objects_table()
+
+        return (
+            f"✅ Deleted object '{object_id}'.",
+            get_objects_table()
+        )
+
+    return (
+        f"❌ Object '{object_id}' not found.",
+        get_objects_table()
+    )
 
 
 def load_doc_file(doc_name):
-    doc_path = os.path.join("docs", f"{doc_name}.md")
+
+    doc_path = os.path.join(
+        "docs",
+        f"{doc_name}.md"
+    )
+
     if os.path.exists(doc_path):
-        with open(doc_path, "r", encoding="utf-8") as f:
+
+        with open(
+            doc_path,
+            "r",
+            encoding="utf-8"
+        ) as f:
+
             return f.read()
-    return f"Documentation file '{doc_name}' not found."
+
+    return (
+        f"Documentation file "
+        f"'{doc_name}' not found."
+    )
 
 
 def export_db_handler():
+
     temp_dir = tempfile.mkdtemp()
-    export_path = os.path.join(temp_dir, "object_library_export.zip")
-    db.export_database_zip(export_path)
+
+    export_path = os.path.join(
+        temp_dir,
+        "object_library_export.zip"
+    )
+
+    db.export_database_zip(
+        export_path
+    )
+
     return export_path
 
 
-# ---------------------------------------------------------------------------
-# GPU Functions — defined BEFORE Gradio Blocks for HF ZeroGPU detection
-# ---------------------------------------------------------------------------
+# ============================================================
+# ZERO GPU FUNCTIONS
+# ============================================================
+#
+# IMPORTANT:
+#
+# These MUST be module-level functions.
+#
+# DO NOT put @spaces.GPU inside:
+#   - another function
+#   - a class
+#   - a callback
+#   - a dynamically generated function
+#
+# Hugging Face ZeroGPU needs to discover them during startup.
+# ============================================================
+
 
 @spaces.GPU(duration=120)
 def run_gradio_detection(
@@ -126,423 +256,1684 @@ def run_gradio_detection(
     confidence_val,
     similarity_val
 ):
+
     if input_image is None:
-        return None, "Please upload or capture an image to perform detection."
 
-    if isinstance(input_image, Image.Image):
-        img_np = np.array(input_image)
-        img_bgr = cv2.cvtColor(img_np, cv2.COLOR_RGB2BGR)
+        return (
+            None,
+            "Please upload or capture an image "
+            "to perform detection."
+        )
+
+    # --------------------------------------------------------
+    # Convert PIL / NumPy image to OpenCV BGR
+    # --------------------------------------------------------
+
+    if isinstance(
+        input_image,
+        Image.Image
+    ):
+
+        img_np = np.array(
+            input_image
+        )
+
+        img_bgr = cv2.cvtColor(
+            img_np,
+            cv2.COLOR_RGB2BGR
+        )
+
     else:
-        img_bgr = cv2.cvtColor(input_image, cv2.COLOR_RGB2BGR)
 
-    prompts = [p.strip() for p in open_vocab_text.split(",") if p.strip()] if open_vocab_text else None
+        img_bgr = cv2.cvtColor(
+            input_image,
+            cv2.COLOR_RGB2BGR
+        )
+
+    # --------------------------------------------------------
+    # Parse YOLO-World prompts
+    # --------------------------------------------------------
+
+    prompts = None
+
+    if open_vocab_text:
+
+        prompts = [
+            p.strip()
+            for p in open_vocab_text.split(",")
+            if p.strip()
+        ]
+
+    # --------------------------------------------------------
+    # Run unified vision orchestrator
+    # --------------------------------------------------------
+
+    (
+        annotated_bgr,
+        detections,
+        metadata
+    ) = orchestrator.process_frame(
 
-    annotated_bgr, detections, metadata = orchestrator.process_frame(
         image=img_bgr,
+
         mode=detection_mode,
+
         lock_mode=lock_mode_toggle,
+
         lock_target=lock_target_text,
+
         open_vocab_prompts=prompts,
+
         confidence_thresh=confidence_val,
+
         similarity_thresh=similarity_val
     )
 
-    annotated_rgb = cv2.cvtColor(annotated_bgr, cv2.COLOR_BGR2RGB)
+    # --------------------------------------------------------
+    # Convert BGR -> RGB
+    # --------------------------------------------------------
+
+    annotated_rgb = cv2.cvtColor(
+        annotated_bgr,
+        cv2.COLOR_BGR2RGB
+    )
+
+    # --------------------------------------------------------
+    # Log detections
+    # --------------------------------------------------------
 
     for det in detections:
+
         db.log_detection(
+
             object_name=det["label"],
-            detection_type=det.get("type", "known"),
+
+            detection_type=det.get(
+                "type",
+                "known"
+            ),
+
             confidence=det["confidence"]
         )
 
-    json_str = json.dumps(metadata, indent=2)
-    return annotated_rgb, json_str
+    # --------------------------------------------------------
+    # Metadata JSON
+    # --------------------------------------------------------
+
+    json_str = json.dumps(
+        metadata,
+        indent=2
+    )
+
+    return (
+        annotated_rgb,
+        json_str
+    )
+
 
+# ============================================================
+# TEACH SPECIFIC OBJECT - GRADIO
+# ============================================================
 
 @spaces.GPU(duration=120)
-def teach_new_object(name, category, description, reference_images):
-    if not name or not name.strip():
-        return "❌ Error: Object name is required.", get_objects_table()
+def teach_new_object(
+    name,
+    category,
+    description,
+    reference_images
+):
+
+    if (
+        not name
+        or not name.strip()
+    ):
+
+        return (
+            "❌ Error: Object name is required.",
+            get_objects_table()
+        )
 
     if not reference_images:
-        return "❌ Error: Please upload at least one reference photo.", get_objects_table()
+
+        return (
+            "❌ Error: Please upload at least "
+            "one reference photo.",
+            get_objects_table()
+        )
 
     try:
-        existing = db.get_object_by_name(name.strip())
+
+        name = name.strip()
+
+        category = (
+            category.strip()
+            if category
+            else "general"
+        )
+
+        description = (
+            description.strip()
+            if description
+            else ""
+        )
+
+        # ----------------------------------------------------
+        # Existing object or new object
+        # ----------------------------------------------------
+
+        existing = db.get_object_by_name(
+            name
+        )
+
         if existing:
+
             obj = existing
+
         else:
-            obj = db.create_object(name=name.strip(), category=category.strip() or "general", description=description.strip() or "")
+
+            obj = db.create_object(
+
+                name=name,
+
+                category=category,
+
+                description=description
+            )
 
         added_embeddings = 0
+
+        # ----------------------------------------------------
+        # Process reference images
+        # ----------------------------------------------------
+
         for img_obj in reference_images:
-            if isinstance(img_obj, str):
+
+            if isinstance(
+                img_obj,
+                str
+            ):
+
                 img_path = img_obj
-            elif hasattr(img_obj, "name"):
+
+            elif hasattr(
+                img_obj,
+                "name"
+            ):
+
                 img_path = img_obj.name
+
             else:
+
                 continue
 
-            emb = orchestrator.embedding_recognizer.extract_embedding_from_image_path(img_path)
+            # ------------------------------------------------
+            # Extract visual embedding
+            # ------------------------------------------------
+
+            emb = (
+                orchestrator
+                .embedding_recognizer
+                .extract_embedding_from_image_path(
+                    img_path
+                )
+            )
+
             if emb is not None:
-                db.add_embedding(obj.id, emb.tolist())
-                db.add_image_record(obj.id, img_path)
+
+                db.add_embedding(
+                    obj.id,
+                    emb.tolist()
+                )
+
+                db.add_image_record(
+                    obj.id,
+                    img_path
+                )
+
                 added_embeddings += 1
 
-        msg = f"✅ Successfully taught object '{obj.name}'! (Added {added_embeddings} reference feature embeddings)"
-        return msg, get_objects_table()
+        message = (
+            f"✅ Successfully taught object "
+            f"'{obj.name}'! "
+            f"(Added {added_embeddings} "
+            f"reference feature embeddings)"
+        )
+
+        return (
+            message,
+            get_objects_table()
+        )
+
     except Exception as e:
-        return f"❌ Error teaching object: {str(e)}", get_objects_table()
+
+        return (
+            f"❌ Error teaching object: {str(e)}",
+            get_objects_table()
+        )
 
 
-# ---------------------------------------------------------------------------
-# Building Modern Glassmorphic Gradio UI
-# ---------------------------------------------------------------------------
+# ============================================================
+# CSS
+# ============================================================
 
 custom_css = """
+
 body {
     background-color: #0b0f19;
     color: #e2e8f0;
-    font-family: 'Inter', system-ui, -apple-system, sans-serif;
+    font-family:
+        'Inter',
+        system-ui,
+        -apple-system,
+        sans-serif;
 }
+
 .gradio-container {
     max-width: 1280px !important;
     margin: 0 auto !important;
 }
+
 .header-hero {
+
     text-align: center;
+
     padding: 2.5rem 1rem;
-    background: linear-gradient(135deg, rgba(30,41,59,0.7) 0%, rgba(15,23,42,0.9) 100%);
+
+    background:
+        linear-gradient(
+            135deg,
+            rgba(30,41,59,0.7) 0%,
+            rgba(15,23,42,0.9) 100%
+        );
+
     border-radius: 16px;
-    border: 1px solid rgba(255, 255, 255, 0.1);
+
+    border:
+        1px solid
+        rgba(255, 255, 255, 0.1);
+
     backdrop-filter: blur(12px);
+
     margin-bottom: 2rem;
-    box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.5), 0 8px 10px -6px rgba(0, 0, 0, 0.5);
+
+    box-shadow:
+        0 20px 25px -5px
+        rgba(0, 0, 0, 0.5),
+
+        0 8px 10px -6px
+        rgba(0, 0, 0, 0.5);
 }
+
 .header-hero h1 {
+
     font-size: 2.5rem;
+
     font-weight: 800;
-    background: linear-gradient(90deg, #60a5fa 0%, #34d399 50%, #f472b6 100%);
+
+    background:
+        linear-gradient(
+            90deg,
+            #60a5fa 0%,
+            #34d399 50%,
+            #f472b6 100%
+        );
+
     -webkit-background-clip: text;
+
     -webkit-text-fill-color: transparent;
+
     margin-bottom: 0.5rem;
 }
+
 .header-hero p {
+
     color: #94a3b8;
+
     font-size: 1.1rem;
+
     max-width: 750px;
+
     margin: 0 auto;
 }
+
 .badge-tag {
+
     display: inline-block;
+
     padding: 4px 12px;
+
     border-radius: 9999px;
+
     font-size: 0.8rem;
+
     font-weight: 600;
+
     margin: 0 4px;
-    background: rgba(99, 102, 241, 0.2);
+
+    background:
+        rgba(99, 102, 241, 0.2);
+
     color: #818cf8;
-    border: 1px solid rgba(99, 102, 241, 0.3);
+
+    border:
+        1px solid
+        rgba(99, 102, 241, 0.3);
 }
+
 """
 
-with gr.Blocks(css=custom_css, title="Open-World Object Intelligence Platform") as demo:
 
-    with gr.Column(elem_classes=["header-hero"]):
-        gr.HTML("""
-        <h1>Open-World Object Intelligence Platform</h1>
-        <p>Unified Multi-Pipeline Vision System powered by <strong>RT-DETR</strong> (Known Objects), <strong>YOLO-World</strong> (Open Vocabulary), and <strong>Visual Embeddings</strong> (Specific Taught Identity).</p>
-        <div style="margin-top: 1rem;">
-            <span class="badge-tag">🎯 RT-DETR Known Detector</span>
-            <span class="badge-tag">🌐 YOLO-World Open Vocab</span>
-            <span class="badge-tag">🧠 Specific Object Recognition</span>
-            <span class="badge-tag">🔒 Target Lock Mode</span>
-        </div>
-        """)
+# ============================================================
+# GRADIO APPLICATION
+# ============================================================
+
+with gr.Blocks(
+    css=custom_css,
+    title="Open-World Object Intelligence Platform"
+) as demo:
+
+    # ========================================================
+    # HEADER
+    # ========================================================
+
+    with gr.Column(
+        elem_classes=["header-hero"]
+    ):
+
+        gr.HTML(
+            """
+            <h1>
+                Open-World Object Intelligence Platform
+            </h1>
+
+            <p>
+                Unified Multi-Pipeline Vision System powered by
+                <strong>RT-DETR</strong>
+                (Known Objects),
+                <strong>YOLO-World</strong>
+                (Open Vocabulary),
+                and
+                <strong>Visual Embeddings</strong>
+                (Specific Taught Identity).
+            </p>
+
+            <div style="margin-top: 1rem;">
+
+                <span class="badge-tag">
+                    🎯 RT-DETR Known Detector
+                </span>
+
+                <span class="badge-tag">
+                    ��� YOLO-World Open Vocab
+                </span>
+
+                <span class="badge-tag">
+                    🧠 Specific Object Recognition
+                </span>
+
+                <span class="badge-tag">
+                    🔒 Target Lock Mode
+                </span>
+
+            </div>
+            """
+        )
+
+    # ========================================================
+    # TABS
+    # ========================================================
 
     with gr.Tabs():
 
-        # -------------------------------------------------------------------
-        # TAB 1: Live Testing & Lock Mode
-        # -------------------------------------------------------------------
-        with gr.TabItem("👁️ Live Testing & Lock Mode"):
+        # ====================================================
+        # TAB 1
+        # ====================================================
+
+        with gr.TabItem(
+            "👁️ Live Testing & Lock Mode"
+        ):
+
             with gr.Row():
-                with gr.Column(scale=1):
-                    input_img = gr.Image(type="pil", label="Input Frame / Image", sources=["upload", "webcam", "clipboard"])
 
-                    with gr.Accordion("⚙️ Detection Pipeline Settings", open=True):
+                # ------------------------------------------------
+                # INPUT COLUMN
+                # ------------------------------------------------
+
+                with gr.Column(
+                    scale=1
+                ):
+
+                    input_img = gr.Image(
+
+                        type="pil",
+
+                        label=(
+                            "Input Frame / Image"
+                        ),
+
+                        sources=[
+                            "upload",
+                            "webcam",
+                            "clipboard"
+                        ]
+                    )
+
+                    # --------------------------------------------
+                    # PIPELINE SETTINGS
+                    # --------------------------------------------
+
+                    with gr.Accordion(
+                        "⚙️ Detection Pipeline Settings",
+                        open=True
+                    ):
+
                         detection_mode_dropdown = gr.Dropdown(
-                            choices=["combined", "known", "open_vocabulary", "specific"],
+
+                            choices=[
+                                "combined",
+                                "known",
+                                "open_vocabulary",
+                                "specific"
+                            ],
+
                             value="combined",
-                            label="Detection Pipeline Mode"
+
+                            label=(
+                                "Detection Pipeline Mode"
+                            )
                         )
+
                         open_vocab_input = gr.Textbox(
-                            label="Open Vocabulary Prompts (YOLO-World)",
-                            placeholder="e.g. red cup, laptop, screwdriver, wireless mouse",
-                            value="cup, laptop, screwdriver, backpack, bottle"
+
+                            label=(
+                                "Open Vocabulary Prompts "
+                                "(YOLO-World)"
+                            ),
+
+                            placeholder=(
+                                "e.g. red cup, laptop, "
+                                "screwdriver, wireless mouse"
+                            ),
+
+                            value=(
+                                "cup, laptop, screwdriver, "
+                                "backpack, bottle"
+                            )
                         )
+
                         confidence_slider = gr.Slider(
-                            minimum=0.1, maximum=1.0, value=KNOWN_CONFIDENCE_THRESHOLD, step=0.05,
-                            label="Detection Confidence Threshold"
+
+                            minimum=0.1,
+
+                            maximum=1.0,
+
+                            value=(
+                                KNOWN_CONFIDENCE_THRESHOLD
+                            ),
+
+                            step=0.05,
+
+                            label=(
+                                "Detection Confidence "
+                                "Threshold"
+                            )
                         )
+
                         similarity_slider = gr.Slider(
-                            minimum=0.1, maximum=1.0, value=SPECIFIC_SIMILARITY_THRESHOLD, step=0.05,
-                            label="Specific Object Similarity Threshold"
+
+                            minimum=0.1,
+
+                            maximum=1.0,
+
+                            value=(
+                                SPECIFIC_SIMILARITY_THRESHOLD
+                            ),
+
+                            step=0.05,
+
+                            label=(
+                                "Specific Object "
+                                "Similarity Threshold"
+                            )
+                        )
+
+                    # --------------------------------------------
+                    # LOCK MODE
+                    # --------------------------------------------
+
+                    with gr.Accordion(
+                        "🔒 Lock Mode Controls",
+                        open=True
+                    ):
+
+                        lock_toggle = gr.Checkbox(
+
+                            label=(
+                                "Enable Lock Mode "
+                                "(Suppress Non-Target Boxes)"
+                            ),
+
+                            value=False
                         )
 
-                    with gr.Accordion("🔒 Lock Mode Controls", open=True):
-                        lock_toggle = gr.Checkbox(label="Enable Lock Mode (Suppress Non-Target Boxes)", value=False)
                         lock_target_input = gr.Textbox(
+
                             label="Lock Target",
-                            placeholder="e.g., 'My Cup', 'cup', 'red backpack'",
+
+                            placeholder=(
+                                "e.g., 'My Cup', "
+                                "'cup', 'red backpack'"
+                            ),
+
                             value=""
                         )
 
-                    btn_detect = gr.Button("🚀 Run Object Detection", variant="primary")
+                    btn_detect = gr.Button(
+
+                        "🚀 Run Object Detection",
+
+                        variant="primary"
+                    )
+
+                # ------------------------------------------------
+                # OUTPUT COLUMN
+                # ------------------------------------------------
+
+                with gr.Column(
+                    scale=1
+                ):
+
+                    output_img = gr.Image(
+
+                        label=(
+                            "Annotated Output Feed "
+                            "with Lock Indicator"
+                        )
+                    )
+
+                    json_output = gr.Code(
+
+                        label=(
+                            "Detection Results "
+                            "Metadata (JSON)"
+                        ),
+
+                        language="json"
+                    )
 
-                with gr.Column(scale=1):
-                    output_img = gr.Image(label="Annotated Output Feed with Lock Indicator")
-                    json_output = gr.Code(label="Detection Results Metadata (JSON)", language="json")
+            # ----------------------------------------------------
+            # DETECTION EVENT
+            # ----------------------------------------------------
 
             btn_detect.click(
+
                 fn=run_gradio_detection,
+
                 inputs=[
+
                     input_img,
+
                     detection_mode_dropdown,
+
                     lock_toggle,
+
                     lock_target_input,
+
                     open_vocab_input,
+
                     confidence_slider,
+
                     similarity_slider
                 ],
-                outputs=[output_img, json_output],
+
+                outputs=[
+
+                    output_img,
+
+                    json_output
+                ],
+
                 api_name="detect"
             )
 
-        # -------------------------------------------------------------------
-        # TAB 2: Object Studio (Teach & Manage)
-        # -------------------------------------------------------------------
-        with gr.TabItem("🎓 Object Studio (Teach & Manage)"):
-            gr.Markdown("## Teach Specific Objects to the System")
-            gr.Markdown("Upload reference photos of your personal physical object (e.g. *My Cup*, *Lab Keyring*). The system extracts L2 normalized visual embeddings to recognize this exact object identity.")
+        # ====================================================
+        # TAB 2 - OBJECT STUDIO
+        # ====================================================
+
+        with gr.TabItem(
+            "🎓 Object Studio (Teach & Manage)"
+        ):
+
+            gr.Markdown(
+                "## Teach Specific Objects to the System"
+            )
+
+            gr.Markdown(
+                """
+                Upload reference photos of your personal
+                physical object (e.g. *My Cup*, *Lab Keyring*).
+
+                The system extracts L2-normalized visual
+                embeddings to recognize this exact object identity.
+                """
+            )
 
             with gr.Row():
+
+                # ------------------------------------------------
+                # TEACH
+                # ------------------------------------------------
+
                 with gr.Column():
-                    teach_name = gr.Textbox(label="Object Identity Name (e.g. 'My Cup')", placeholder="My Cup")
-                    teach_category = gr.Textbox(label="Category (e.g. 'Drinkware')", placeholder="Drinkware")
-                    teach_desc = gr.Textbox(label="Description", placeholder="Personal ceramic mug with blue handle")
-                    teach_files = gr.File(label="Upload Reference Photos (3-10 photos recommended)", file_count="multiple", file_types=["image"])
-                    btn_teach = gr.Button("🧠 Train & Save Specific Object", variant="primary")
+
+                    teach_name = gr.Textbox(
+
+                        label=(
+                            "Object Identity Name "
+                            "(e.g. 'My Cup')"
+                        ),
+
+                        placeholder="My Cup"
+                    )
+
+                    teach_category = gr.Textbox(
+
+                        label=(
+                            "Category "
+                            "(e.g. 'Drinkware')"
+                        ),
+
+                        placeholder="Drinkware"
+                    )
+
+                    teach_desc = gr.Textbox(
+
+                        label="Description",
+
+                        placeholder=(
+                            "Personal ceramic mug "
+                            "with blue handle"
+                        )
+                    )
+
+                    teach_files = gr.File(
+
+                        label=(
+                            "Upload Reference Photos "
+                            "(3-10 photos recommended)"
+                        ),
+
+                        file_count="multiple",
+
+                        file_types=[
+                            "image"
+                        ]
+                    )
+
+                    btn_teach = gr.Button(
+
+                        "🧠 Train & Save Specific Object",
+
+                        variant="primary"
+                    )
+
                     teach_status = gr.Markdown()
 
+                # ------------------------------------------------
+                # DATABASE
+                # ------------------------------------------------
+
                 with gr.Column():
-                    gr.Markdown("### Saved Specific Objects Database")
+
+                    gr.Markdown(
+                        "### Saved Specific Objects Database"
+                    )
+
                     objects_df = gr.Dataframe(
-                        headers=["ID", "Name", "Category", "Images", "Embeddings", "Created At"],
+
+                        headers=[
+
+                            "ID",
+
+                            "Name",
+
+                            "Category",
+
+                            "Images",
+
+                            "Embeddings",
+
+                            "Created At"
+                        ],
+
                         value=get_objects_table(),
+
                         interactive=False
                     )
-                    del_id_input = gr.Textbox(label="Delete Object ID", placeholder="obj_xxxx")
-                    btn_del = gr.Button("🗑️ Delete Object", variant="stop")
+
+                    del_id_input = gr.Textbox(
+
+                        label="Delete Object ID",
+
+                        placeholder="obj_xxxx"
+                    )
+
+                    btn_del = gr.Button(
+
+                        "🗑️ Delete Object",
+
+                        variant="stop"
+                    )
+
+            # ----------------------------------------------------
+            # TEACH EVENT
+            # ----------------------------------------------------
 
             btn_teach.click(
+
                 fn=teach_new_object,
-                inputs=[teach_name, teach_category, teach_desc, teach_files],
-                outputs=[teach_status, objects_df],
+
+                inputs=[
+
+                    teach_name,
+
+                    teach_category,
+
+                    teach_desc,
+
+                    teach_files
+                ],
+
+                outputs=[
+
+                    teach_status,
+
+                    objects_df
+                ],
+
                 api_name="teach_object"
             )
 
+            # ----------------------------------------------------
+            # DELETE EVENT
+            # ----------------------------------------------------
+
             btn_del.click(
+
                 fn=delete_selected_object,
-                inputs=[del_id_input],
-                outputs=[teach_status, objects_df]
+
+                inputs=[
+                    del_id_input
+                ],
+
+                outputs=[
+
+                    teach_status,
+
+                    objects_df
+                ]
+            )
+
+        # ====================================================
+        # TAB 3 - DOWNLOADS
+        # ====================================================
+
+        with gr.TabItem(
+            "💾 Downloads & Package Export"
+        ):
+
+            gr.Markdown(
+                """
+                ## Downloads, Models & Custom Object Database Export
+                """
             )
 
-        # -------------------------------------------------------------------
-        # TAB 3: Model & Database Downloads
-        # -------------------------------------------------------------------
-        with gr.TabItem("💾 Downloads & Package Export"):
-            gr.Markdown("## Downloads, Models & Custom Object Database Export")
-            gr.Markdown("Download pretrained models, database export packages, SDK packages, and verified checksum manifests.")
+            gr.Markdown(
+                """
+                Download pretrained models, database export
+                packages, SDK packages, and verified checksum
+                manifests.
+                """
+            )
 
             with gr.Row():
+
+                # ------------------------------------------------
+                # DATABASE EXPORT
+                # ------------------------------------------------
+
                 with gr.Column():
-                    gr.Markdown("### 📦 Object Database Export")
-                    btn_export = gr.Button("📥 Export Custom Object Database (.zip)", variant="primary")
-                    export_file_out = gr.File(label="Download Library Archive")
-                    btn_export.click(fn=export_db_handler, inputs=[], outputs=[export_file_out])
+
+                    gr.Markdown(
+                        "### 📦 Object Database Export"
+                    )
+
+                    btn_export = gr.Button(
+
+                        "📥 Export Custom Object Database (.zip)",
+
+                        variant="primary"
+                    )
+
+                    export_file_out = gr.File(
+
+                        label="Download Library Archive"
+                    )
+
+                    btn_export.click(
+
+                        fn=export_db_handler,
+
+                        inputs=[],
+
+                        outputs=[
+                            export_file_out
+                        ]
+                    )
+
+                # ------------------------------------------------
+                # MODELS
+                # ------------------------------------------------
 
                 with gr.Column():
-                    gr.Markdown("### 🤖 Pretrained Vision Models & Manifest")
-                    gr.Markdown("""
-                    | Model | Purpose | SHA-256 Checksum | Format |
-                    | :--- | :--- | :--- | :--- |
-                    | **RT-DETR** | Known Object Detection | `a8f921...c4` | `.pt` (PyTorch) |
-                    | **YOLO-World** | Open-Vocabulary Discovery | `b491a0...f1` | `.pt` (Ultralytics) |
-                    | **ResNet18 Backbone** | Feature Embedding Extractor | `7d88e2...03` | Torchvision |
-                    """)
-
-        # -------------------------------------------------------------------
-        # TAB 4: Developer Guides & Documentation
-        # -------------------------------------------------------------------
-        with gr.TabItem("📚 Developer Guides"):
+
+                    gr.Markdown(
+                        """
+                        ### 🤖 Pretrained Vision Models & Manifest
+                        """
+                    )
+
+                    gr.Markdown(
+                        """
+                        | Model | Purpose | SHA-256 Checksum | Format |
+                        | :--- | :--- | :--- | :--- |
+                        | **RT-DETR** | Known Object Detection | `a8f921...c4` | `.pt` (PyTorch) |
+                        | **YOLO-World** | Open-Vocabulary Discovery | `b491a0...f1` | `.pt` (Ultralytics) |
+                        | **ResNet18 Backbone** | Feature Embedding Extractor | `7d88e2...03` | Torchvision |
+                        """
+                    )
+
+        # ====================================================
+        # TAB 4 - DOCUMENTATION
+        # ====================================================
+
+        with gr.TabItem(
+            "📚 Developer Guides"
+        ):
+
             with gr.Row():
+
                 doc_selector = gr.Dropdown(
+
                     choices=[
+
                         "getting-started",
+
                         "known-objects",
+
                         "open-vocabulary",
+
                         "specific-objects",
+
                         "lock-mode",
+
                         "api",
+
                         "database",
+
                         "deployment"
                     ],
+
                     value="getting-started",
-                    label="Select Documentation Guide"
+
+                    label=(
+                        "Select Documentation Guide"
+                    )
                 )
-            doc_markdown_view = gr.Markdown(value=load_doc_file("getting-started"))
-
-            doc_selector.change(fn=load_doc_file, inputs=[doc_selector], outputs=[doc_markdown_view])
-
-        # -------------------------------------------------------------------
-        # TAB 5: REST API Reference
-        # -------------------------------------------------------------------
-        with gr.TabItem("🔌 REST API"):
-            gr.Markdown("## REST API & FastAPI Endpoint Specifications")
-            gr.Markdown("""
-            ### Available Endpoints:
-            - **`GET /api/health`**: System status and model check.
-            - **`POST /api/detect`**: Run detection pipeline on an uploaded image.
-            - **`GET /api/objects`**: Fetch list of taught objects.
-            - **`GET /api/downloads/export-db`**: Download object database archive.
-
-            ### Example cURL Request for Lock Mode:
-            ```bash
-            curl -X POST "http://localhost:7860/api/detect" \\
-              -F "file=@sample.jpg" \\
-              -F "mode=combined" \\
-              -F "lock_mode=true" \\
-              -F "lock_target=My Cup"
-            ```
-            """)
-
-# ---------------------------------------------------------------------------
-# Launch — use demo.launch() so HF ZeroGPU can detect @spaces.GPU functions
-# ---------------------------------------------------------------------------
-demo.queue()
-
-from gradio.routes import App as _GradioApp
-
-_original_create = _GradioApp.create_app
-
-@staticmethod
-def _patched_create(blocks, **kwargs):
-    fastapi_app = _original_create(blocks, **kwargs)
-
-    fastapi_app.add_middleware(
-        CORSMiddleware,
-        allow_origins=["*"],
-        allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
+
+            doc_markdown_view = gr.Markdown(
+
+                value=load_doc_file(
+                    "getting-started"
+                )
+            )
+
+            doc_selector.change(
+
+                fn=load_doc_file,
+
+                inputs=[
+                    doc_selector
+                ],
+
+                outputs=[
+                    doc_markdown_view
+                ]
+            )
+
+        # ====================================================
+        # TAB 5 - REST API
+        # ====================================================
+
+        with gr.TabItem(
+            "🔌 REST API"
+        ):
+
+            gr.Markdown(
+                """
+                ## REST API & FastAPI Endpoint Specifications
+
+                ### Available Endpoints
+
+                - **`GET /api/health`**
+                  System status and model check.
+
+                - **`POST /api/detect`**
+                  Run detection pipeline on an uploaded image.
+
+                - **`GET /api/objects`**
+                  Fetch list of taught objects.
+
+                - **`POST /api/objects`**
+                  Teach a new object.
+
+                - **`DELETE /api/objects/{object_id}`**
+                  Delete a taught object.
+
+                - **`GET /api/downloads/export-db`**
+                  Download object database archive.
+
+                - **`GET /api/downloads/requirements`**
+                  Download requirements.txt.
+
+                ### Example cURL Request for Lock Mode
+
+                ```bash
+                curl -X POST "http://localhost:7860/api/detect" \\
+                  -F "file=@sample.jpg" \\
+                  -F "mode=combined" \\
+                  -F "lock_mode=true" \\
+                  -F "lock_target=My Cup"
+                ```
+                """
+            )
+
+
+# ============================================================
+# FASTAPI APPLICATION
+# ============================================================
+#
+# IMPORTANT:
+#
+# We keep FastAPI as the parent application and mount Gradio
+# into it.
+#
+# ZeroGPU detects the module-level @spaces.GPU functions above.
+#
+# Do NOT put @spaces.GPU around the FastAPI route itself.
+# ============================================================
+
+app = FastAPI(
+
+    title=(
+        "Object Intelligence Platform API"
+    ),
+
+    description=(
+        "Open-World Object Intelligence API "
+        "combining RT-DETR, YOLO-World, "
+        "and Specific Object Embeddings."
+    ),
+
+    version="1.0.0"
+)
+
+
+# ============================================================
+# CORS
+# ============================================================
+
+app.add_middleware(
+
+    CORSMiddleware,
+
+    allow_origins=["*"],
+
+    allow_credentials=True,
+
+    allow_methods=["*"],
+
+    allow_headers=["*"]
+)
+
+
+# ============================================================
+# HEALTH ENDPOINT
+# ============================================================
+
+@app.get(
+    "/api/health"
+)
+def api_health():
+
+    return {
+
+        "status": "healthy",
+
+        "models": {
+
+            "rtdetr": (
+                orchestrator.rtdetr.model
+                is not None
+            ),
+
+            "yolo_world": (
+                orchestrator.yolo_world.model
+                is not None
+            ),
+
+            "embedding_recognizer": (
+                orchestrator
+                .embedding_recognizer
+                .model
+                is not None
+            )
+        },
+
+        "database": os.path.exists(
+            SQLITE_DB_PATH
+        )
+    }
+
+
+# ============================================================
+# API GPU DETECTION FUNCTION
+# ============================================================
+
+@spaces.GPU(duration=120)
+def _run_api_detection(
+
+    img,
+
+    mode,
+
+    lock_mode,
+
+    lock_target,
+
+    prompts,
+
+    confidence
+
+):
+
+    return orchestrator.process_frame(
+
+        image=img,
+
+        mode=mode,
+
+        lock_mode=lock_mode,
+
+        lock_target=lock_target,
+
+        open_vocab_prompts=prompts,
+
+        confidence_thresh=confidence
     )
 
-    @fastapi_app.get("/api/health")
-    def api_health():
-        return {
-            "status": "healthy",
-            "models": {
-                "rtdetr": orchestrator.rtdetr.model is not None,
-                "yolo_world": orchestrator.yolo_world.model is not None,
-                "embedding_recognizer": orchestrator.embedding_recognizer.model is not None,
-            },
-            "database": os.path.exists(SQLITE_DB_PATH),
+
+# ============================================================
+# POST /api/detect
+# ============================================================
+
+@app.post(
+    "/api/detect"
+)
+async def api_detect_route(
+
+    file: UploadFile = File(...),
+
+    mode: str = Form(
+        "combined"
+    ),
+
+    lock_mode: bool = Form(
+        False
+    ),
+
+    lock_target: str = Form(
+        ""
+    ),
+
+    open_vocab_prompts: str = Form(
+        ""
+    ),
+
+    vocabulary: str = Form(
+        ""
+    ),
+
+    confidence: float = Form(
+        KNOWN_CONFIDENCE_THRESHOLD
+    )
+):
+
+    try:
+
+        # ----------------------------------------------------
+        # Read uploaded image
+        # ----------------------------------------------------
+
+        contents = await file.read()
+
+        nparr = np.frombuffer(
+            contents,
+            np.uint8
+        )
+
+        img = cv2.imdecode(
+            nparr,
+            cv2.IMREAD_COLOR
+        )
+
+        if img is None:
+
+            raise HTTPException(
+
+                status_code=400,
+
+                detail=(
+                    "Invalid image file format"
+                )
+            )
+
+        # ----------------------------------------------------
+        # Parse vocabulary
+        # ----------------------------------------------------
+
+        raw_vocab = (
+            open_vocab_prompts
+            or vocabulary
+        )
+
+        prompts = None
+
+        if raw_vocab:
+
+            prompts = [
+
+                p.strip()
+
+                for p in raw_vocab.split(",")
+
+                if p.strip()
+            ]
+
+        # ----------------------------------------------------
+        # GPU inference
+        # ----------------------------------------------------
+
+        (
+            annotated_frame,
+
+            detections,
+
+            metadata
+
+        ) = _run_api_detection(
+
+            img,
+
+            mode,
+
+            lock_mode,
+
+            lock_target,
+
+            prompts,
+
+            confidence
+        )
+
+        # ----------------------------------------------------
+        # Encode output image
+        # ----------------------------------------------------
+
+        success, buffer = cv2.imencode(
+
+            ".png",
+
+            annotated_frame
+        )
+
+        if not success:
+
+            raise HTTPException(
+
+                status_code=500,
+
+                detail=(
+                    "Failed to encode "
+                    "annotated image."
+                )
+            )
+
+        img_base64 = base64.b64encode(
+            buffer
+        ).decode(
+            "utf-8"
+        )
+
+        return JSONResponse(
+
+            content={
+
+                "status": "success",
+
+                "image_base64": img_base64,
+
+                "metadata": metadata,
+
+                "detections": detections
+            }
+        )
+
+    except HTTPException:
+
+        raise
+
+    except Exception as e:
+
+        raise HTTPException(
+
+            status_code=500,
+
+            detail=str(e)
+        )
+
+
+# ============================================================
+# GET /api/objects
+# ============================================================
+
+@app.get(
+    "/api/objects"
+)
+def api_get_objects_route():
+
+    objs = db.get_all_objects()
+
+    return [
+
+        {
+
+            "id": o.id,
+
+            "name": o.name,
+
+            "category": o.category,
+
+            "images": o.image_count,
+
+            "image_count": o.image_count
         }
 
-    @fastapi_app.post("/api/detect")
-    async def api_detect_route(
-        file: UploadFile = File(...),
-        mode: str = Form("combined"),
-        lock_mode: bool = Form(False),
-        lock_target: str = Form(""),
-        open_vocab_prompts: str = Form(""),
-        vocabulary: str = Form(""),
-        confidence: float = Form(KNOWN_CONFIDENCE_THRESHOLD),
-    ):
-        try:
-            contents = await file.read()
-            nparr = np.frombuffer(contents, np.uint8)
-            img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
+        for o in objs
+    ]
+
+
+# ============================================================
+# GPU OBJECT TEACHING FUNCTION
+# ============================================================
+
+@spaces.GPU(duration=120)
+def _teach_api_object(
+
+    name,
+
+    category,
+
+    description,
+
+    image_data
+
+):
+
+    # --------------------------------------------------------
+    # Find or create object
+    # --------------------------------------------------------
+
+    existing = db.get_object_by_name(
+        name.strip()
+    )
+
+    if existing:
+
+        obj = existing
+
+    else:
+
+        obj = db.create_object(
+
+            name=name.strip(),
+
+            category=(
+                category.strip()
+                or "general"
+            ),
+
+            description=(
+                description.strip()
+                or ""
+            )
+        )
+
+    added = 0
+
+    # --------------------------------------------------------
+    # Extract embeddings
+    # --------------------------------------------------------
+
+    for filename, img in image_data:
+
+        emb = (
+            orchestrator
+            .embedding_recognizer
+            .extract_embedding_from_image(
+                img
+            )
+        )
+
+        if emb is not None:
+
+            db.add_embedding(
+
+                obj.id,
+
+                emb.tolist()
+            )
+
+            db.add_image_record(
+
+                obj.id,
+
+                filename
+            )
+
+            added += 1
+
+    return (
+        obj,
+        added
+    )
+
+
+# ============================================================
+# POST /api/objects
+# ============================================================
+
+@app.post(
+    "/api/objects"
+)
+async def api_teach_object_route(
+
+    name: str = Form(...),
+
+    category: str = Form(
+        "custom"
+    ),
+
+    description: str = Form(
+        ""
+    ),
+
+    files: list[UploadFile] = File(
+        default=[]
+    )
+
+):
+
+    try:
+
+        image_data = []
+
+        # ----------------------------------------------------
+        # Read uploaded files
+        # ----------------------------------------------------
+
+        for uf in files:
+
+            contents = await uf.read()
+
+            nparr = np.frombuffer(
+                contents,
+                np.uint8
+            )
+
+            img = cv2.imdecode(
+                nparr,
+                cv2.IMREAD_COLOR
+            )
+
             if img is None:
-                raise HTTPException(status_code=400, detail="Invalid image file format")
-            raw_vocab = open_vocab_prompts or vocabulary
-            prompts = [p.strip() for p in raw_vocab.split(",") if p.strip()] if raw_vocab else None
-            annotated_frame, detections, metadata = _run_api_detection(
-                img, mode, lock_mode, lock_target, prompts, confidence
+
+                continue
+
+            image_data.append(
+
+                (
+                    uf.filename or "image",
+
+                    img
+                )
             )
-            import base64
-            _, buffer = cv2.imencode(".png", annotated_frame)
-            img_base64 = base64.b64encode(buffer).decode("utf-8")
-            return JSONResponse(content={"status": "success", "image_base64": img_base64, "metadata": metadata, "detections": detections})
-        except Exception as e:
-            raise HTTPException(status_code=500, detail=str(e))
-
-    @fastapi_app.get("/api/objects")
-    def api_get_objects_route():
-        objs = db.get_all_objects()
-        return [{"id": o.id, "name": o.name, "category": o.category, "images": o.image_count, "image_count": o.image_count} for o in objs]
-
-    @fastapi_app.post("/api/objects")
-    async def api_teach_object_route(
-        name: str = Form(...), category: str = Form("custom"),
-        description: str = Form(""), files: list[UploadFile] = File(default=[]),
+
+        # ----------------------------------------------------
+        # GPU embedding extraction
+        # ----------------------------------------------------
+
+        obj, added = _teach_api_object(
+
+            name,
+
+            category,
+
+            description,
+
+            image_data
+        )
+
+        return {
+
+            "status": "success",
+
+            "message": (
+                f"Taught object "
+                f"'{obj.name}' with "
+                f"{added} embeddings"
+            ),
+
+            "id": obj.id
+        }
+
+    except Exception as e:
+
+        raise HTTPException(
+
+            status_code=500,
+
+            detail=str(e)
+        )
+
+
+# ============================================================
+# DELETE /api/objects/{object_id}
+# ============================================================
+
+@app.delete(
+    "/api/objects/{object_id}"
+)
+def api_delete_object_route(
+    object_id: str
+):
+
+    if db.delete_object(
+        object_id
+    ):
+
+        return {
+            "status": "deleted"
+        }
+
+    raise HTTPException(
+
+        status_code=404,
+
+        detail="Object not found"
+    )
+
+
+# ============================================================
+# DATABASE EXPORT
+# ============================================================
+
+@app.get(
+    "/api/downloads/export-db"
+)
+def api_export_db_route():
+
+    temp_dir = tempfile.mkdtemp()
+
+    zip_path = os.path.join(
+
+        temp_dir,
+
+        "custom_objects_library.zip"
+    )
+
+    db.export_database_zip(
+        zip_path
+    )
+
+    return FileResponse(
+
+        zip_path,
+
+        filename=(
+            "custom_objects_library.zip"
+        ),
+
+        media_type=(
+            "application/zip"
+        )
+    )
+
+
+# ============================================================
+# REQUIREMENTS DOWNLOAD
+# ============================================================
+
+@app.get(
+    "/api/downloads/requirements"
+)
+def api_download_requirements_route():
+
+    req_path = os.path.join(
+
+        os.path.dirname(
+            os.path.abspath(__file__)
+        ),
+
+        "requirements.txt"
+    )
+
+    if os.path.exists(
+        req_path
     ):
-        try:
-            existing = db.get_object_by_name(name.strip())
-            obj = existing if existing else db.create_object(name=name.strip(), category=category.strip() or "general", description=description.strip() or "")
-            added = 0
-            for uf in files:
-                contents = await uf.read()
-                nparr = np.frombuffer(contents, np.uint8)
-                img = cv2.imdecode(nparr, cv2.IMREAD_COLOR)
-                if img is None:
-                    continue
-                emb = orchestrator.embedding_recognizer.extract_embedding_from_image(img)
-                if emb is not None:
-                    db.add_embedding(obj.id, emb.tolist())
-                    db.add_image_record(obj.id, uf.filename or "image")
-                    added += 1
-            return {"status": "success", "message": f"Taught object '{obj.name}' with {added} embeddings", "id": obj.id}
-        except Exception as e:
-            raise HTTPException(status_code=500, detail=str(e))
-
-    @fastapi_app.delete("/api/objects/{object_id}")
-    def api_delete_object_route(object_id: str):
-        if db.delete_object(object_id):
-            return {"status": "deleted"}
-        raise HTTPException(status_code=404, detail="Object not found")
-
-    @fastapi_app.get("/api/downloads/export-db")
-    def api_export_db_route():
-        temp_dir = tempfile.mkdtemp()
-        zip_path = os.path.join(temp_dir, "custom_objects_library.zip")
-        db.export_database_zip(zip_path)
-        return FileResponse(zip_path, filename="custom_objects_library.zip", media_type="application/zip")
-
-    @fastapi_app.get("/api/downloads/requirements")
-    def api_download_requirements_route():
-        req_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "requirements.txt")
-        if os.path.exists(req_path):
-            return FileResponse(req_path, filename="requirements.txt", media_type="text/plain")
-        raise HTTPException(status_code=404, detail="requirements.txt not found")
-
-    return fastapi_app
-
-_GradioApp.create_app = _patched_create
+
+        return FileResponse(
+
+            req_path,
+
+            filename="requirements.txt",
+
+            media_type="text/plain"
+        )
+
+    raise HTTPException(
+
+        status_code=404,
+
+        detail=(
+            "requirements.txt not found"
+        )
+    )
+
+
+# ============================================================
+# MOUNT GRADIO
+# ============================================================
+#
+# Gradio UI is mounted at:
+#
+#     /
+#
+# API remains:
+#
+#     /api/*
+# ============================================================
+
+app = gr.mount_gradio_app(
+
+    app,
+
+    demo,
+
+    path="/"
+)
+
+
+# ============================================================
+# SERVER STARTUP
+# ============================================================
+#
+# IMPORTANT FOR HUGGING FACE SPACES
+#
+# Do NOT use:
+#
+#     uvicorn.run(...)
+#
+# when relying on the normal Gradio Space startup.
+#
+# Hugging Face launches the application through the Space's
+# Gradio runtime.
+#
+# For local execution, uvicorn is still useful.
+# ============================================================
 
 if __name__ == "__main__":
-    demo.launch(server_name="0.0.0.0", server_port=7860)
-else:
-    demo.launch(server_name="0.0.0.0", server_port=7860)
+
+    port = int(
+
+        os.environ.get(
+
+            "PORT",
+
+            os.environ.get(
+
+                "GRADIO_SERVER_PORT",
+
+                "7860"
+            )
+        )
+    )
+
+    uvicorn.run(
+
+        app,
+
+        host="0.0.0.0",
+
+        port=port
+    )