Skip to content

README.md

Latest commit

 

History

History
123 lines (100 loc) · 2.72 KB

README.md

File metadata and controls

123 lines (100 loc) · 2.72 KB

Forge Master Agent Service

Intelligent 4-agent pipeline for production-ready 3D model generation.

Architecture

User Request
     ↓
[1] Prompt Enhancement Agent (Gemini)
     ↓
[2] Generation Coordinator Agent → GPU Service
     ↓
[3] Quality Assurance Agent (Gemini + Rules)
     ↓
[4] Enhancement Agent (Gemini) [if needed]
     ↓
Production-Ready 3D Model

Agents

1. Prompt Enhancement Agent

  • Optimizes user prompts for 3D generation
  • Adds materials, details, rendering hints
  • Uses Gemini for intelligent enhancement

2. Generation Coordinator Agent

  • Communicates with GPU service
  • Handles retries and errors
  • Returns model URLs and statistics

3. Quality Assurance Agent

  • Analyzes mesh topology and statistics
  • Uses Gemini for intelligent QA
  • Assigns quality scores (0-10)
  • Determines production-readiness

4. Enhancement Agent

  • Proposes improvements for failed models
  • Suggests parameter adjustments
  • Recommends post-processing steps

API Endpoints

POST /generate

Main endpoint - executes complete pipeline

Request:

{
  "prompt": "a medieval sword",
  "num_inference_steps": 75,
  "guidance_scale": 4.0
}

Response:

{
  "pipeline_id": "20250109_120000",
  "status": "success",
  "user_prompt": "a medieval sword",
  "enhanced_prompt": "A medieval longsword with steel blade...",
  "model_urls": {
    "glb": "https://...",
    "obj": "https://...",
    "stl": "https://..."
  },
  "quality_score": 8.5,
  "is_production_ready": true,
  "stages": { /* all agent outputs */ }
}

GET /health

Health check for service and all agents

POST /enhance-prompt

Test prompt enhancement only (no generation)

Security

This service uses Cloud Run IAM authentication when calling the GPU service:

  • Automatically obtains identity tokens via metadata server
  • GPU service only accepts requests with valid service account credentials
  • Prevents unauthorized access to expensive GPU operations

Local Development

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GOOGLE_API_KEY=your-key
export GPU_SERVICE_URL=https://your-gpu-service-url

# Run server
python main.py

# Test
python test_local.py

Deployment

# Set environment
export GOOGLE_API_KEY=your-key
export GPU_SERVICE_URL=https://your-gpu-service-url
export PROJECT_ID=your-project
export BUCKET_NAME=your-bucket

# Deploy
./deploy.sh

Environment Variables

  • GOOGLE_API_KEY - Gemini API key (required)
  • GPU_SERVICE_URL - GPU service URL from Phase 2 (required)
  • PROJECT_ID - GCP project ID
  • BUCKET_NAME - Cloud Storage bucket
  • REGION - GCP region (default: europe-west1)
  • GEMINI_MODEL - Gemini model (default: gemini-2.0-flash-exp)