Fix: pin pydantic<2.11.0 + api_name=generate for Gradio 5 API

SETUP_GUIDE.sh

@@ -0,0 +1,225 @@
+# ===========================================================
+# AI 3D Model Generator — Complete Setup & Deployment Guide
+# ===========================================================
+#
+# This file contains step-by-step instructions for deploying
+# the pipeline to Hugging Face Spaces and connecting it to n8n.
+#
+# Table of Contents:
+# 1. Overview
+# 2. Hugging Face Space Deployment
+# 3. n8n Workflow Setup
+# 4. Testing the Pipeline
+# 5. API Reference
+# ===========================================================
+
+# ===========================================================
+# 1. OVERVIEW
+# ===========================================================
+#
+# Pipeline Flow:
+#
+#   [n8n Webhook] ──▶ [Parse Request] ──▶ [Download Images]
+#       │                                        │
+#       ▼                                        ▼
+#   [Receive POST with]              [Convert URLs to base64]
+#   [images + prompt]                         │
+#                                             ▼
+#                          [Call HF Space Gradio API]
+#                                  │
+#                                  ▼
+#                        [TripoSG Pipeline]
+#                        ├─ Background Removal (RMBG-1.4)
+#                        ├─ Best View Selection
+#                        ├─ 3D Reconstruction
+#                        ├─ Manifold Repair
+#                        ├─ Dimension Scaling
+#                        └─ (Optional) Part Segmentation
+#                                  │
+#                                  ▼
+#                     [Download GLB/OBJ/STL File]
+#                                  │
+#                                  ▼
+#                     [Respond with Binary File]
+#
+# ===========================================================
+
+
+# ===========================================================
+# 2. HUGGING FACE SPACE DEPLOYMENT
+# ===========================================================
+
+# Step 1: Create a new Hugging Face Space
+# ----------------------------------------
+# Go to: https://huggingface.co/new-space
+# - Owner: your-username
+# - Space name: ai-3d-generator
+# - License: MIT
+# - SDK: Gradio
+# - Hardware: ZeroGPU (or GPU Basic for testing)
+# - Click "Create Space"
+
+# Step 2: Upload files via Git
+# ----------------------------------------
+# Clone your new space locally:
+
+git clone https://huggingface.co/spaces/YOUR-USERNAME/ai-3d-generator
+cd ai-3d-generator
+
+# Copy all files from this directory:
+cp /path/to/ai-3d-generation-print-ready/* .
+
+# The following files should be in the space:
+# ├── README.md          (HF Space config — already has YAML frontmatter)
+# ├── app.py             (Main Gradio application)
+# ├── mesh_utils.py      (Mesh processing utilities)
+# ├── requirements.txt   (Python dependencies)
+# └── workflow.json      (n8n workflow — for your reference, not needed in Space)
+
+# Push to Hugging Face:
+git add .
+git commit -m "Initial deployment: AI 3D Model Generator"
+git push
+
+# Step 3: Configure HF Space secrets (optional)
+# ----------------------------------------
+# Go to your Space Settings → Variables and Secrets
+# Add if using private models:
+#   HF_TOKEN = hf_xxxxxxxxxxxxxxxxxxxxx
+
+# Step 4: Wait for build
+# ----------------------------------------
+# The Space will automatically build and deploy.
+# Watch the "Build" tab for progress (~5-10 minutes first time).
+# Once running, your Space URL will be:
+#   https://YOUR-USERNAME-ai-3d-generator.hf.space
+
+
+# ===========================================================
+# 3. N8N WORKFLOW SETUP
+# ===========================================================
+
+# Step 1: Import the workflow
+# ----------------------------------------
+# In n8n, go to: Workflows → Import from File
+# Select: workflow.json from this directory
+# The workflow will be imported with all nodes pre-configured.
+
+# Step 2: Configure variables
+# ----------------------------------------
+# In n8n, go to: Settings → Variables
+# Add these variables:
+#
+#   HF_SPACE_URL = YOUR-USERNAME-ai-3d-generator.hf.space
+#   HF_TOKEN     = hf_xxxxxxxxxxxxxxxxxxxxx  (your HF access token)
+#
+# Alternatively, set up HuggingFace API credentials in n8n:
+# Settings → Credentials → Add Credential → Hugging Face API
+
+# Step 3: Activate the workflow
+# ----------------------------------------
+# Toggle the workflow to "Active"
+# Note your webhook URL:
+#   https://your-n8n-instance.com/webhook/generate-3d-model
+
+
+# ===========================================================
+# 4. TESTING THE PIPELINE
+# ===========================================================
+
+# Test via curl (images as URLs):
+curl -X POST https://your-n8n-instance.com/webhook/generate-3d-model \
+  -H "Content-Type: application/json" \
+  -d '{
+    "images": [
+      "https://example.com/front-view.jpg",
+      "https://example.com/side-view.jpg",
+      "https://example.com/back-view.jpg"
+    ],
+    "prompt": "Industrial bracket, base is 10cm x 5cm, M6 bolt holes on corners, matte steel finish",
+    "faces": 50000,
+    "format": "glb",
+    "modular": false
+  }' \
+  --output model.glb
+
+# Test via curl (images as base64):
+IMAGE_B64=$(base64 -w0 my_photo.jpg)
+curl -X POST https://your-n8n-instance.com/webhook/generate-3d-model \
+  -H "Content-Type: application/json" \
+  -d "{
+    \"images\": [\"data:image/jpeg;base64,$IMAGE_B64\"],
+    \"prompt\": \"Phone stand, height: 12cm, modern minimalist design\",
+    \"faces\": 30000,
+    \"format\": \"stl\"
+  }" \
+  --output model.stl
+
+# Test via Python:
+# import requests
+# response = requests.post(
+#     "https://your-n8n-instance.com/webhook/generate-3d-model",
+#     json={
+#         "images": ["https://example.com/object.jpg"],
+#         "prompt": "Coffee mug, diameter: 8cm, height: 10cm",
+#         "faces": 50000,
+#         "format": "glb",
+#     },
+# )
+# with open("model.glb", "wb") as f:
+#     f.write(response.content)
+
+# Test the HF Space directly (without n8n):
+# Open your Space URL in a browser and use the web UI directly.
+
+
+# ===========================================================
+# 5. API REFERENCE
+# ===========================================================
+
+# Webhook Request Format:
+# POST /webhook/generate-3d-model
+# Content-Type: application/json
+#
+# {
+#   "images": [                          // Array of image sources
+#     "https://example.com/front.jpg",   // Image URLs (auto-downloaded)
+#     "data:image/png;base64,iVBOR..."   // Or base64 encoded images
+#   ],
+#   "prompt": "string",                  // Text instructions
+#                                        // Supports dimension extraction:
+#                                        //   "base is 10cm"
+#                                        //   "10cm x 5cm x 3cm"
+#                                        //   "height: 200mm"
+#                                        //   "scale 1:10"
+#   "faces": 50000,                      // Target face count (5000-90000)
+#   "format": "glb",                     // Export format: glb, obj, stl
+#   "modular": false                     // Split into modular parts
+# }
+#
+# Response:
+# 200 OK — Binary file (GLB/OBJ/STL)
+# Headers:
+#   Content-Disposition: attachment; filename="model_20260224_120000.glb"
+#   Content-Type: model/gltf-binary
+#   X-Pipeline-Status: "✅ Complete in 45.2s — manifold: True, vertices: 12345, faces: 50000"
+#
+# Error Response:
+# 500 Internal Server Error
+# { "success": false, "error": "...", "message": "..." }
+
+# ===========================================================
+# SUPPORTED TEXT PROMPT PATTERNS
+# ===========================================================
+# The pipeline parses your text prompt to extract dimensions:
+#
+# Pattern                         Example
+# ─────────────────────────────── ──────────────────────────────
+# 3D dimensions:                  "10cm x 5cm x 3cm"
+# Individual dims:                "base is 10cm", "height: 200mm"
+# Scale ratios:                   "scale 1:10", "ratio is 1:5"
+# Materials (passed to model):    "matte steel finish"
+# Details (passed to model):      "M6 bolt holes on each corner"
+# Style (passed to model):        "modern minimalist design"
+#
+# Units supported: mm, cm, m, in, inch, inches, ft, feet