semantic_analyzer.py

"""Semantic Analyzer - Uses Gemini vision to analyze World Labs renders.

This module takes an image of a generated 3D world and identifies objects
with their game-relevant properties (navigation, physics, tags).
"""

import os
import json
import logging
import base64
from typing import Optional, Dict, Any, List

import requests
from dotenv import load_dotenv

load_dotenv()

logger = logging.getLogger("BloomPath.Analysis.Semantic")

# Gemini API Configuration
GEMINI_API_KEY = os.getenv("GEMINI_API_KEY")
# Upgraded to Gemini 3 Flash (Preview) for enhanced agentic vision capabilities
GEMINI_API_URL = "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent"


ANALYSIS_PROMPT = """You are an expert game development AI with spatial intelligence. Analyze this 3D rendered scene using multi-step reasoning.

## Step 1: Scene Understanding
First, describe the overall scene composition, lighting, and spatial layout.

## Step 2: Object Identification
For each distinct object, provide:
1. semantic_type: What is it? (e.g., rock, wall, path, water, plant, furniture, fireplace, desk, table, counter)
   - CRITICAL: Explicitly identify flat surfaces that can support other objects (e.g., DeskTop, CounterTop, TableTop, Floor).
2. estimated_position: Relative position in scene (front/back, left/right, near/far)
3. estimated_scale: small/medium/large
4. tags: Game-relevant tags (Walkable, Obstacle, Climbable, Interactable, Decorative, LightSource, ObjectSpawner)
5. physics:
   - friction: 0.0 (ice) to 1.0 (rough stone)
   - mass_category: light/medium/heavy/static
   - destructible: true/false

## Step 3: Spatial Relationships
Note any important relationships between objects (e.g., "table is next to fireplace", "path leads to door").

Focus on objects relevant to gameplay and navigation. Think step-by-step about the 3D layout.

Return ONLY valid JSON in this format:
{
  "scene_description": "Brief description of the scene",
  "spatial_notes": "Key spatial relationships observed",
  "objects": [
    {
      "id": "obj_001",
      "semantic_type": "stone_path",
      "estimated_position": {"x": "center", "y": "ground", "z": "front"},
      "estimated_scale": "large",
      "tags": ["Walkable", "SoundFootstep_Stone"],
      "physics": {"friction": 0.7, "mass_category": "static", "destructible": false}
    }
  ]
}
"""


def encode_image_base64(image_path: str) -> Optional[str]:
    """Encode an image file to base64 string."""
    try:
        with open(image_path, "rb") as f:
            return base64.standard_b64encode(f.read()).decode("utf-8")
    except Exception as e:
        logger.error(f"Failed to encode image: {e}")
        return None


def analyze_world(image_path: str) -> Optional[Dict[str, Any]]:
    """
    Analyze a World Labs render using Gemini vision.
    
    Args:
        image_path: Path to the rendered image (PNG/JPG)
        
    Returns:
        World Manifest dict or None on failure
    """
    if not GEMINI_API_KEY:
        logger.error("GEMINI_API_KEY not configured")
        return None
        
    if not os.path.exists(image_path):
        logger.error(f"Image not found: {image_path}")
        return None
    
    # Encode image
    image_data = encode_image_base64(image_path)
    if not image_data:
        return None
    
    # Determine MIME type
    ext = os.path.splitext(image_path)[1].lower()
    mime_type = "image/png" if ext == ".png" else "image/jpeg"
    
    # Build Gemini request
    payload = {
        "contents": [{
            "parts": [
                {"text": ANALYSIS_PROMPT},
                {
                    "inline_data": {
                        "mime_type": mime_type,
                        "data": image_data
                    }
                }
            ]
        }],
        "generationConfig": {
            "temperature": 0.2,
            "maxOutputTokens": 2048,
            "responseMimeType": "application/json"
        }
    }
    
    headers = {"Content-Type": "application/json"}
    url = f"{GEMINI_API_URL}?key={GEMINI_API_KEY}"
    
    try:
        logger.info(f"Analyzing image: {image_path}")
        response = requests.post(url, json=payload, headers=headers, timeout=30)
        response.raise_for_status()
        
        result = response.json()
        
        # Extract text from response
        candidates = result.get("candidates", [])
        if not candidates:
            logger.error("No candidates in Gemini response")
            return None
            
        text_content = candidates[0].get("content", {}).get("parts", [{}])[0].get("text", "")
        
        # Parse JSON from response (may be wrapped in markdown)
        json_str = text_content.strip()
        if json_str.startswith("```"):
            # Remove markdown code block
            lines = json_str.split("\n")
            json_str = "\n".join(lines[1:-1])
        
        try:
            manifest = json.loads(json_str)
        except json.JSONDecodeError as e:
            logger.warning(f"Standard JSON parse failed, attempting fallback: {e}")
            import re
            # Try to fix trailing commas
            fixed_json = re.sub(r',\s*([\]}])', r'\1', json_str)
            manifest = json.loads(fixed_json)

        logger.info(f"✅ Identified {len(manifest.get('objects', []))} objects")
        return manifest
        
    except json.JSONDecodeError as e:
        logger.error(f"Failed to parse Gemini response as JSON: {e}")
        logger.debug(f"Raw response: {text_content[:500]}")
        return None
    except Exception as e:
        logger.error(f"Gemini API error: {e}")
        return None


def save_manifest(manifest: Dict[str, Any], output_path: str) -> bool:
    """Save manifest to JSON file."""
    try:
        os.makedirs(os.path.dirname(output_path), exist_ok=True)
        with open(output_path, "w", encoding="utf-8") as f:
            json.dump(manifest, f, indent=2)
        logger.info(f"Manifest saved: {output_path}")
        return True
    except Exception as e:
        logger.error(f"Failed to save manifest: {e}")
        return False