utim-cli 1.0.0__py3-none-any.whl

utim_cli/blender_agent.py

@@ -0,0 +1,1018 @@
+"""
+UTIM Blender Agent — Advanced Image-to-3D Pipeline (v2)
+========================================================
+
+Architecture (4 Phases)
+------------------------
+Phase 0 – Deep Image Analysis
+    OpenCV + Pillow analyse the image locally: dominant colours, contours,
+    depth-map estimation, feature regions (face, body, hair, clothing).
+    A rich "scene_brief" dict is assembled for Phase 1.
+
+Phase 1 – Vision-LLM Scene Understanding
+    The image AND scene_brief are sent to a vision-capable LLM with a
+    comprehensive system prompt that asks for:
+      • Structured part decomposition (head, body, hair, accessory…)
+      • Per-part geometry strategy (primitive hint, mesh complexity)
+      • Material and colour information per part
+      • Tattoo / decal texture descriptions
+      • Overall proportions, pose, and scene context
+
+Phase 2 – Procedural Blender Script Generation
+    A code-generation LLM receives the scene analysis and writes a
+    complete, sophisticated bpy Python script that:
+      1. Builds each body part using Blender primitives + modifiers
+         (Subdivision Surface, Solidify, Skin, Curve-based hair, etc.)
+      2. Applies per-part Principled BSDF materials with the analysed colours
+      3. Projects the original image as a texture on the main surface using
+         Smart UV Project + image texture nodes
+      4. Optionally generates procedural tattoo decals via overlay material
+      5. Sets up a 3-point studio light rig
+      6. Exports to the requested format
+
+Phase 3 – Execution, Validation & Retry
+    The script is executed via Blender in headless mode. If it fails a
+    parse-and-fix loop runs up to MAX_RETRIES times before raising.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import mimetypes
+import os
+import pathlib
+import re
+import subprocess
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+_OPENROUTER_URL = "https://openrouter.ai/api/v1/chat/completions"
+
+# Vision models (must support image_url content parts)
+_VISION_MODELS: List[str] = [
+    "google/gemma-4-31b-it:free",
+    "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
+    "nvidia/nemotron-nano-12b-v2-vl:free",
+    "google/gemma-4-26b-a4b-it:free",
+    "nvidia/llama-nemotron-embed-vl-1b-v2:free",
+    "nvidia/llama-nemotron-rerank-vl-1b-v2:free",
+    "openrouter/free"
+]
+
+_CODE_MODELS: List[str] = [
+    "poolside/laguna-m.1:free",
+    "cohere/north-mini-code:free",
+    "qwen/qwen3-coder:free",
+    "nvidia/nemotron-3-ultra-550b-a55b:free",
+    "openrouter/free"
+]
+
+MAX_RETRIES = 3  # Script fix-and-retry attempts
+
+# ---------------------------------------------------------------------------
+# System prompts
+# ---------------------------------------------------------------------------
+
+_VISION_SYSTEM_PROMPT = """\
+You are an expert Blender 3D artist and scene analyst. Examine the image and
+produce a detailed JSON scene description that will be used to procedurally
+rebuild this image as a 3D scene in Blender.
+
+CRITICAL ANALYSIS GUIDELINES:
+- DEPTH CUES: Analyze perspective, shading gradients, and contour lines to estimate depth/z-distance
+- PROPORTIONS: Provide precise relative measurements (values 0.0-1.0 for size/position ratios)
+
+MANDATORY - CHECK THESE BEFORE OUTPUT:
+1. TATTOOS: If ANY symbols/markings on skin, set has_tattoos=true and list EACH in tattoos array with location and shape_description
+2. EYE COLOR: Extract EXACT iris color - check carefully, may be red/yellow/etc
+3. HAIR GRADIENTS: If hair has color transitions, extract dark_root_color, mid_color, tip_color
+4. EXPRESSION: Describe accurately (smirk, neutral, angry, etc)
+
+- EYES: Must detail exact eye construction (color, size, shape, pupil, cornea)
+- Multi-object scenes: If multiple objects exist, provide "objects" array with each object's own structure
+
+OUTPUT FORMAT — a single raw JSON object (no markdown, no explanation):
+
+{
+  "scene_type": "character",
+  "description": "<one-paragraph description>",
+  "subject_label": "<e.g. anime_character, human_face, vehicle, animal>",
+
+  "parts": [
+    {
+      "id": "head",
+      "label": "Head / Face",
+      "geometry_hint": "uv_sphere_deformed",
+      "dominant_colors": [[r,g,b]],
+      "material": {
+        "name": "Skin",
+        "base_color": [r, g, b, 1.0],
+        "roughness": 0.6,
+        "metallic": 0.0,
+        "subsurface": 0.0,
+        "subsurface_color": [r, g, b],
+        "emission": [0,0,0]
+      },
+      "relative_size": [w, h, d],
+      "relative_position": [x, y, z],
+      "depth_hint": "convex/front-facing",
+      "notes": "describe shape details"
+    }
+  ],
+
+  "hair": {
+    "style": "spiky_anime",
+    "color": [r, g, b],
+    "secondary_color": [r, g, b],
+    "dark_root_color": [r, g, b],
+    "tip_color": [r, g, b],
+    "length": "medium",
+    "spike_count": 14,
+    "spike_directions": [
+      {"angle": 45, "direction": "forward_left", "width": 0.15},
+      {"angle": 60, "direction": "up_right", "width": 0.12}
+    ],
+    "notes": "describe spike shapes and flow direction"
+  },
+
+  "face_details": {
+    "has_tattoos": true,
+    "tattoos": [
+      {
+        "location": "forehead_center",
+        "relative_position": [0.0, 0.85, 0.02],
+        "size": [0.35, 0.12],
+        "color": [r, g, b],
+        "shape_description": "double-trident with dot between (example: like Jujutsu Kaisen symbol)",
+        "depth_hint": "flat_on_surface"
+      }
+    ],
+    "eyebrows": true,
+    "eyebrow_color": [r, g, b],
+    "eye_color": [r, g, b],
+    "eye_style": "anime_large",
+    "eye_size_ratio": 0.25,
+    "pupil_color": [r, g, b],
+    "expression": "smirk",
+    "eye_details": {
+      "iris_size": 0.7,
+      "shine_position": "upper_left",
+      "cornea_ior": 1.4
+    }
+  },
+
+  "clothing": [
+    {
+      "item": "scarf",
+      "color": [r, g, b],
+      "secondary_color": [r, g, b],
+      "material_hint": "fabric_thick",
+      "coverage": "neck_to_chin",
+      "thickness": 0.02,
+      "fold_directions": ["down_center", "out_sides"],
+      "relative_position": [0.0, -0.1, 0.0]
+    }
+  ],
+
+  "objects": [
+    {
+      "id": "background",
+      "label": "Background Object",
+      "geometry_hint": "plane",
+      "dominant_colors": [[r,g,b]],
+      "relative_size": [w, h, d],
+      "relative_position": [x, y, z]
+    }
+  ],
+
+  "lighting_suggestion": {
+    "type": "three_point",
+    "key_color": [r, g, b],
+    "fill_color": [r, g, b],
+    "rim_color": [r, g, b]
+  },
+
+  "overall_proportions": {
+    "head_scale": 1.0,
+    "body_visible": true,
+    "visible_parts": ["head", "neck", "shoulders"],
+    "head_to_body_ratio": 0.25
+  },
+
+  "depth_estimation": {
+    "foreground": "head/neck",
+    "background": "image_background",
+    "depth_layers": 3
+  },
+
+  "image_texture_applicable": true,
+  "background_color": [r, g, b]
+}
+
+Rules:
+- All color values are 0.0-1.0 floats.
+- For anime characters: subsurface=0.0, roughness=0.7, eye_style="anime_large".
+- **TATTOOS/DECALS ARE MANDATORY**: If ANY markings, symbols, or special patterns are VISIBLE on skin, hair, or clothing, you MUST set has_tattoos=true and populate the tattoos array with precise positioning.
+- **Eye details are mandatory**: ALWAYS populate eye_details with iris_size, shine_position, and cornea_ior.
+- Hair spikes MUST have spike_count matching actual visible hair strands - count carefully and list ALL directions.
+- Eye_size_ratio should be a decimal like 0.25 for 25% of head width.
+- Tattoo relative_position uses 0-1 scale from head center (x,y,z) where z=0 is head center, z>0 is up.
+- Output ONLY the raw JSON object — no backticks, no text before or after.
+"""
+
+_CODE_SYSTEM_PROMPT = """\
+You are a world-class Blender Python scripting expert specialising in
+procedural character and object creation. You will receive a JSON scene
+description and must output ONLY a complete, runnable bpy Python script.
+
+CRITICAL COMPATIBILITY — Blender 5.x STRICT RULES:
+1. Use `bpy.context.scene.collection.objects.link(obj)` — NEVER `bpy.context.collection.objects.link(obj)`
+2. NEVER use `mesh.use_auto_smooth` — removed in Blender 5.x
+3. NEVER use `mesh.normals_split_custom_set()` or `mesh.normals_split_custom_set_from_vertices()`
+4. NEVER use `bmesh` for mesh creation — use `mesh.from_pydata(vertices, [], faces)` instead
+5. `bpy.context.view_layer.objects.active` requires an object already linked to the scene
+6. Use `obj.select_set(True)` to select objects
+7. For Subdivision Surface: `mod = obj.modifiers.new("Subsurf", "SUBSURF"); mod.levels = 2`
+8. NEVER set vertex normals directly — they are read-only in Blender 5.x
+
+MANDATORY CONSTRUCTION ELEMENTS - ALWAYS INCLUDE THESE:
+**These elements MUST be in EVERY script generated. No exceptions.**
+
+1. **Eye Construction (Layered)** - ALWAYS create separate eye objects if character:
+   - Create sclera sphere (white of eye), slightly flattened on X axis
+   - Add iris plane positioned at front of sclera with eye_color material
+   - Add thin transparent cornea shell with IOR=1.4 for shine/reflection
+   - Add white highlight (small sphere) on upper left of iris for eye sparkle
+   - Eye size should match eye_size_ratio relative to head
+   - Position symmetrically: left eye at negative X, right eye at positive X
+
+2. **Tattoo Decal Construction** - ALWAYS create if has_tattoos=true:
+   - For EACH tattoo in tattoos array, create a flat plane object
+   - Position using relative_position scaled to head size
+   - Use Shrinkwrap modifier to conform to head surface
+   - Use emission material for glowing tattoos, or regular material for skin markings
+   - For forehead tattoos: position at top/front of head with z=0.1 to 0.15
+   - Create BEFORE linking to collection, then shrinkwrap to target
+
+3. **Hair Curves** - ALWAYS create if hair style is spiky_anime or spike_count > 0:
+   - Create CURVE objects with `bpy.data.curves.new('HairCurve', 'CURVE')`
+   - Use `curve.extrude = 0.02` and `curve.bevel_depth = 0.01` for thickness
+   - For each spike: define spline points, set handle types to 'VECTOR'
+   - Rotate spikes outward using spike_directions angle and direction hints
+   - Apply gradient colors (dark_root at base, color middle, tip_color at top)
+   - If hair.style is "spiky" WITHOUT explicit spike_directions, create 12-16 cones around head with varied angles
+   - Hair spikes should emerge from head surface (z offset from head radius)
+   - Vary spike lengths: some short (0.3), some long (0.6), for natural chaos
+
+4. **Fallback Hair Construction** (when curve data insufficient):
+   - Use `bpy.ops.mesh.primitive_cone_add(radius1=0.12, radius2=0.02, depth=0.5)`
+   - Position cones around head circumference with slight randomness
+   - Apply hair.material to each spike
+   - Add Subdivision Surface modifier for smoother hair strands
+
+5. Clothing with Thickness:
+   - Add Solidify modifier for fabric thickness: `mod = obj.modifiers.new("Solidify", "SOLIDIFY"); mod.thickness = 0.02`
+   - Use fold_directions for edge crease weights if applicable
+
+6. Image Texture Projection:
+   - Add image texture node: `nodes.new('ShaderNodeTexImage')`
+   - Use 'CAMERA' projection for correct alignment: `tex.projection = 'CAMERA'`
+   - Connect to Principled BSDF Base Color
+
+7. Multi-Object Scene Support - If the scene contains multiple objects:
+   - Iterate through scene_data.get('objects', []) array
+   - For each object, build complete geometry including its own parts, materials, and positioning
+   - Position objects using their relative_position field
+   - Scale using relative_scale field
+   - Add appropriate spacing between objects to avoid intersection
+
+SCRIPT STRUCTURE:
+- Clear the scene using bpy.ops.object.select_all + bpy.ops.object.delete
+- Build HEAD first, then EYES, then HAIR, then CLOTHING, then TATTOOS
+- Apply materials with the exact colors from the scene JSON
+- If hair uses curve-based spikes, create separate Curve objects for each spike
+- Set up 3-point lighting rig (key light, fill light, rim light)
+- Set world background color from background_color field
+- ALWAYS include UTIM_BLENDER_SUCCESS print at end
+
+EXPORT CODE (hardcode the exact values given in the user prompt, NOT placeholders):
+```python
+export_path = "<ACTUAL_PATH_STRING>"
+export_format = "<ACTUAL_FORMAT_STRING>"
+if export_format == 'blend':
+    bpy.ops.wm.save_as_mainfile(filepath=export_path, copy=True)
+elif export_format == 'obj':
+    bpy.ops.wm.obj_export(filepath=export_path)
+elif export_format == 'glb':
+    bpy.ops.export_scene.gltf(filepath=export_path, export_format='GLB')
+elif export_format == 'fbx':
+    bpy.ops.export_scene.fbx(filepath=export_path)
+print(f"UTIM_BLENDER_SUCCESS: {export_path}")
+```
+
+Output ONLY the Python script — no markdown, no explanation, no fences.
+"""
+
+_FIX_SYSTEM_PROMPT = """\
+You are a Blender Python debugging expert. A bpy script failed with an error.
+Fix the script so it runs correctly in Blender 5.x.
+
+Rules:
+- Output ONLY the corrected Python script, no explanation, no markdown fences.
+- Keep all the original logic intact; only fix the errors.
+- NEVER use bmesh, mesh.use_auto_smooth, normals_split_custom_set.
+- ALWAYS use bpy.context.scene.collection.objects.link(obj).
+- If a modifier or operator is unavailable, comment it out gracefully.
+- Make sure export_path and export_format are hardcoded strings.
+- BLNDER 5.x FIX: Change principled.inputs['Subsurface'] to principled.inputs['Subsurface Weight']
+- End the script with: print(f"UTIM_BLENDER_SUCCESS: {export_path}")
+"""
+
+# ---------------------------------------------------------------------------
+# Low-level LLM call
+# ---------------------------------------------------------------------------
+
+def _llm_call(
+    system: str,
+    user_text: str,
+    models: List[str],
+    image_b64: Optional[str] = None,
+    image_mime: Optional[str] = None,
+    max_tokens: int = 8192,
+    timeout: int = 120,
+) -> str:
+    """Call OpenRouter with a system+user message, returning the assistant text.
+
+    Tries each model in *models* until one succeeds.
+    """
+    from utim_cli.config import config
+    api_key = os.getenv("OPENROUTER_API_KEY", "") or config.get("api_key")
+    if not api_key:
+        raise RuntimeError("Neither OPENROUTER_API_KEY nor UTIM API key is set.")
+
+    if image_b64 and image_mime:
+        user_content: Any = [
+            {"type": "text", "text": user_text},
+            {"type": "image_url", "image_url": {"url": f"data:{image_mime};base64,{image_b64}"}},
+        ]
+    else:
+        user_content = user_text
+
+    last_err: Exception = RuntimeError("No models tried.")
+    for model in models:
+        for attempt in range(3):
+            try:
+                from utim_cli.client_utils import proxy_openrouter_request
+                resp = proxy_openrouter_request(
+                    json_data={
+                        "model": model,
+                        "messages": [
+                            {"role": "system", "content": system},
+                            {"role": "user", "content": user_content},
+                        ],
+                        "max_tokens": max_tokens,
+                        "stream": False,
+                    },
+                    stream=False,
+                    timeout=timeout,
+                )
+                resp.raise_for_status()
+                data = resp.json()
+                text = data["choices"][0]["message"]["content"]
+                return text.strip()
+            except Exception as exc:  # noqa: BLE001
+                last_err = exc
+                code = getattr(getattr(exc, "response", None), "status_code", 0)
+                if code == 429 and attempt < 2:
+                    time.sleep(5 * (attempt + 1))
+                    continue
+                break  # try next model
+    raise RuntimeError(f"All LLM models failed. Last error: {last_err}") from last_err
+
+
+# ---------------------------------------------------------------------------
+# Phase 0 — Local image pre-analysis (no LLM needed)
+# ---------------------------------------------------------------------------
+
+def _phase0_local_analysis(image_path: str) -> Dict[str, Any]:
+    """Extract dominant colours, basic image stats, and depth hints using Pillow."""
+    brief: Dict[str, Any] = {
+        "width": 0,
+        "height": 0,
+        "dominant_colors": [],
+        "aspect_ratio": 1.0,
+        "has_transparency": False,
+        "brightness": 0.5,
+        "depth_hints": {},
+        "face_landmarks": {},
+    }
+
+    try:
+        from PIL import Image, ImageFilter, ImageDraw  # type: ignore
+        import statistics
+        
+        img = Image.open(image_path).convert("RGBA")
+        brief["width"] = img.width
+        brief["height"] = img.height
+        brief["aspect_ratio"] = round(img.width / max(img.height, 1), 3)
+        brief["has_transparency"] = img.mode == "RGBA"
+
+        # Quantise to 8 dominant colours
+        small = img.convert("RGB").resize((150, 150), Image.LANCZOS)
+        quantised = small.quantize(colors=8, method=Image.Quantize.FASTOCTREE)
+        palette = quantised.getpalette()
+        if palette:
+            colors = []
+            for i in range(0, min(24, len(palette)), 3):
+                r, g, b = palette[i], palette[i + 1], palette[i + 2]
+                colors.append([round(r / 255, 3), round(g / 255, 3), round(b / 255, 3)])
+            brief["dominant_colors"] = colors
+
+        # Average brightness
+        grey = small.convert("L")
+        pixels = list(grey.getdata())
+        brief["brightness"] = round(statistics.mean(pixels) / 255, 3)
+
+        # --- Depth Estimation: Enhanced edge and gradient analysis ---
+        # Blur and find edges to approximate depth contours
+        blurred = grey.filter(ImageFilter.GaussianBlur(radius=2))
+        edges = blurred.filter(ImageFilter.FIND_EDGES)
+        
+        # Analyze edge density in different regions (vertical slices)
+        edge_pixels = list(edges.getdata())
+        width_small = 150
+        height_small = 150
+        total_pixels = width_small * height_small
+        
+        # Divide image into vertical strips and count edges (proxy for depth changes)
+        strip_counts = []
+        for x in range(0, width_small, 15):  # 10 vertical strips
+            edge_count = 0
+            total_in_strip = 0
+            for y in range(height_small):
+                for dx in range(15):
+                    if x + dx < width_small:
+                        idx = y * width_small + (x + dx)
+                        if idx < len(edge_pixels):
+                            total_in_strip += 1
+                            if edge_pixels[idx] > 50:
+                                edge_count += 1
+            strip_counts.append(edge_count / max(total_in_strip, 1))
+        
+        # Horizontal strips for depth layers
+        horizontal_edge_density = []
+        for y in range(0, height_small, 15):
+            strip_start = y * width_small
+            strip_end = min(strip_start + 15 * width_small, len(edge_pixels))
+            strip_edges = edge_pixels[strip_start:strip_end]
+            edge_count = sum(1 for p in strip_edges if p > 50)
+            horizontal_edge_density.append(edge_count / max(len(strip_edges), 1))
+        
+        # Depth hints from edge distribution
+        center_strip = len(strip_counts) // 2 if strip_counts else 0
+        brief["depth_hints"] = {
+            "vertical_edge_density": strip_counts,
+            "horizontal_edge_density": horizontal_edge_density,
+            "center_focus": strip_counts[center_strip] if strip_counts else 0.5,
+            "has_center_subject": bool(strip_counts[center_strip] > 0.1) if strip_counts else True,
+            "estimated_layer_depth": len([c for c in horizontal_edge_density if c > 0.15]) if horizontal_edge_density else 1,
+            "depth_variance": round(statistics.stdev(strip_counts) if len(strip_counts) > 1 else 0, 3),
+        }
+
+        # --- Simple face landmark estimation (center of mass for skin tones) ---
+        # Look for face-like region using simple luminance analysis
+        face_region_found = False
+        for y in range(0, height_small, 15):
+            row_lum = grey.crop((0, y, width_small, min(y + 15, height_small)))
+            row_pixels = list(row_lum.getdata())
+            avg_bright = statistics.mean(row_pixels)
+            if 0.3 < avg_bright / 255 < 0.7:  # skin tone range
+                face_region_found = True
+                break
+        
+        brief["face_landmarks"] = {
+            "estimated_face_present": face_region_found,
+            "skin_tone_range": [min(pixels), max(pixels)] if pixels else [128, 128],
+        }
+
+        # --- Dark mark/tattoo detection hint ---
+        # Look for dark marks on lighter skin regions (typical tattoo contrast)
+        # This is a heuristic to hint that tattoos may be present
+        forehead_dark_pixels = 0
+        if height_small > 0:
+            # Top 20% of image is forehead area
+            forehead_strip = grey.crop((0, 0, width_small, max(20, height_small // 5)))
+            forehead_pixels = list(forehead_strip.getdata())
+            forehead_dark_pixels = sum(1 for p in forehead_pixels if p < 100)  # Dark pixels
+        
+        brief["potential_tattoos"] = {
+            "dark_marks_on_forehead": forehead_dark_pixels > 50,
+            "check_tattoos": forehead_dark_pixels > 50,
+        }
+
+    except ImportError:
+        pass  # Pillow not available — skip local analysis
+    except Exception:
+        pass  # Silently ignore analysis errors
+
+    return brief
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 — Vision-LLM scene understanding
+# ---------------------------------------------------------------------------
+
+def _phase1_vision(image_path: str, scene_brief: Dict[str, Any]) -> Dict[str, Any]:
+    """Send the image to a vision model and parse the returned scene JSON."""
+    if not os.path.isfile(image_path):
+        raise FileNotFoundError(f"Image not found: {image_path}")
+
+    mime_type, _ = mimetypes.guess_type(image_path)
+    if not mime_type or not mime_type.startswith("image/"):
+        ext = os.path.splitext(image_path)[1].lower()
+        mime_map = {
+            ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+            ".webp": "image/webp", ".gif": "image/gif", ".bmp": "image/bmp",
+        }
+        mime_type = mime_map.get(ext)
+        if not mime_type:
+            raise ValueError(f"Unsupported image format: {image_path}")
+
+    with open(image_path, "rb") as fh:
+        image_b64 = base64.b64encode(fh.read()).decode()
+
+    brief_text = (
+        f"Image pre-analysis (local):\n"
+        f"  Resolution : {scene_brief.get('width')}x{scene_brief.get('height')} px\n"
+        f"  Brightness : {scene_brief.get('brightness')}\n"
+        f"  Dominant colours (0-1 RGB): {json.dumps(scene_brief.get('dominant_colors', []))}\n"
+        f"  Depth hints: {json.dumps(scene_brief.get('depth_hints', {}))}\n"
+        f"  Face landmarks: {json.dumps(scene_brief.get('face_landmarks', {}))}\n"
+        f"  Potential tattoos: {json.dumps(scene_brief.get('potential_tattoos', {}))}\n\n"
+        "MANDATORY: If the pre-analysis shows potential_tattoos.check_tattoos=true, you MUST detect and list those tattoos!\n"
+        "MANDATORY: Re-examine the eyes - extract the EXACT iris color (may be red, yellow, etc.)\n"
+        "Examine this image carefully and output the JSON scene description exactly as specified."
+    )
+
+    raw = _llm_call(
+        system=_VISION_SYSTEM_PROMPT,
+        user_text=brief_text,
+        models=_VISION_MODELS,
+        image_b64=image_b64,
+        image_mime=mime_type,
+        max_tokens=8192,
+    )
+
+    # Strip possible markdown fences the model emits despite instructions
+    clean = re.sub(r"```(?:json)?\s*|\s*```", "", raw).strip()
+    
+    # Find the outermost JSON object using brace counting for robustness
+    start = clean.find("{")
+    if start < 0:
+        raise ValueError(
+            f"Vision model did not return a JSON object.\nRaw output:\n{raw}"
+        )
+    
+    # Count braces to find matching end brace
+    brace_count = 0
+    end = start
+    for i, char in enumerate(clean[start:], start):
+        if char == "{":
+            brace_count += 1
+        elif char == "}":
+            brace_count -= 1
+            if brace_count == 0:
+                end = i + 1
+                break
+    
+    if end <= start:
+        # Fallback to original method
+        end = clean.rfind("}") + 1
+    
+    json_str = clean[start:end]
+    
+    try:
+        scene_data: Dict[str, Any] = json.loads(json_str)
+    except json.JSONDecodeError as e:
+        # Try to repair common JSON issues
+        # Remove trailing commas before } or ]
+        json_str = re.sub(r",\s*([}\]])", r"\1", json_str)
+        # Remove comments (not standard JSON but models sometimes include them)
+        json_str = re.sub(r"//.*$", "", json_str, flags=re.MULTILINE)
+        try:
+            scene_data = json.loads(json_str)
+        except json.JSONDecodeError as e2:
+            raise ValueError(
+                f"Vision model returned malformed JSON at position {e2.pos}:\n"
+                f"Error: {e2.msg}\n"
+                f"JSON snippet: {json_str[max(0,e2.pos-50):e2.pos+50]}\n"
+                f"Raw output:\n{raw[:2000]}"
+            ) from e2
+
+    # Ensure defaults
+    scene_data.setdefault("parts", [])
+    scene_data.setdefault("hair", {})
+    scene_data.setdefault("face_details", {})
+    scene_data.setdefault("clothing", [])
+    scene_data.setdefault("objects", [])
+    scene_data.setdefault("lighting_suggestion", {"type": "three_point"})
+    scene_data.setdefault("depth_estimation", {"depth_layers": 1})
+    scene_data.setdefault("image_texture_applicable", True)
+    scene_data.setdefault("background_color", [0.95, 0.95, 0.95])
+    scene_data.setdefault("overall_proportions", {"head_to_body_ratio": 0.25})
+    
+    # Ensure nested defaults
+    scene_data["lighting_suggestion"].setdefault("rim_color", [0.8, 0.8, 1.0])
+    scene_data["face_details"].setdefault("tattoos", [])
+    scene_data["face_details"].setdefault("has_tattoos", bool(scene_data["face_details"].get("tattoos")))
+
+    return scene_data
+
+
+# ---------------------------------------------------------------------------
+# Phase 2 — Blender script generation
+# ---------------------------------------------------------------------------
+
+def _phase2_generate_script(
+    scene_data: Dict[str, Any],
+    image_path: str,
+    name: str,
+    export_path: str,
+    export_format: str,
+) -> str:
+    """Ask a code model to write a complete bpy script for the scene."""
+
+    # Forward-slash paths for Blender (works cross-platform)
+    blender_image_path = image_path.replace("\\", "/")
+    blender_export_path = export_path.replace("\\", "/")
+
+    user_prompt = (
+        f"Object name: {name}\n"
+        f"Export path: {blender_export_path}\n"
+        f"Export format: {export_format}\n"
+        f"Source image path (for texture projection): {blender_image_path}\n\n"
+        f"Scene description JSON:\n{json.dumps(scene_data, indent=2)}\n\n"
+        "Generate the complete Blender Python script now.\n\n"
+        "IMPORTANT INSTRUCTIONS FOR ENHANCED SCENE DATA:\n"
+        "- Build every part listed in scene_data['parts'] as a separate named object\n"
+        "- Use the EXACT export_path and export_format strings above — do NOT use placeholders\n"
+        "- For hair with spike_directions: create CURVE objects with bevel depth for flowing hair, OR create multiple cone/cylinder strands positioned according to each spike's angle and direction\n"
+        "- For tattoos with relative_position [x,y]: use these as UV coordinates or shrinkwrap positions on the head mesh\n"
+        "- For clothing items with fold_directions: add simple geometry hints for fabric folds (use simple planes or slight vertex offsets)\n"
+        "- For parts with depth_hint='convex': extend geometry outward slightly; 'front-facing': keep flat\n"
+        "- Create separate objects for each item in scene_data['clothing'] array\n"
+        "- If scene_data['parts'] contains multiple objects, position them according to their relative_position values using depth_estimation hints\n"
+        "- Apply multi-material support if material_regions is specified\n"
+        "- Set up rim lighting using lighting_suggestion.rim_color\n"
+    )
+
+    raw_script = _llm_call(
+        system=_CODE_SYSTEM_PROMPT,
+        user_text=user_prompt,
+        models=_CODE_MODELS,
+        max_tokens=16384,
+    )
+
+    return _clean_and_patch_script(raw_script, blender_export_path, export_format, blender_image_path)
+
+
+# ---------------------------------------------------------------------------
+# Script cleaning & Blender 5.x compatibility patching
+# ---------------------------------------------------------------------------
+
+def _clean_and_patch_script(
+    raw: str,
+    export_path: str,
+    export_format: str,
+    image_path: str = "",
+) -> str:
+    """Strip markdown fences, replace placeholders, and fix Blender 5.x issues."""
+    # Strip fences
+    script = re.sub(r"```(?:python)?\s*|\s*```", "", raw).strip()
+
+    # ── Placeholder replacement ──────────────────────────────────────────────
+    esc_path = export_path.replace("\\", "/")
+    esc_fmt = export_format
+
+    placeholder_patterns = [
+        (r'export_path\s*=\s*__EXPORT_PATH__', f'export_path = "{esc_path}"'),
+        (r'export_format\s*=\s*__EXPORT_FORMAT__', f'export_format = "{esc_fmt}"'),
+        (r'export_path\s*=\s*["\']__EXPORT_PATH__["\']', f'export_path = "{esc_path}"'),
+        (r'export_format\s*=\s*["\']__EXPORT_FORMAT__["\']', f'export_format = "{esc_fmt}"'),
+        (r'export_path\s*=\s*["\']<ACTUAL[^"\']*>["\']', f'export_path = "{esc_path}"'),
+        (r'export_format\s*=\s*["\']<ACTUAL[^"\']*>["\']', f'export_format = "{esc_fmt}"'),
+        (r'export_path\s*=\s*["\']<ACTUAL_EXPORT_PATH_STRING>["\']', f'export_path = "{esc_path}"'),
+        (r'export_format\s*=\s*["\']<ACTUAL_EXPORT_FORMAT_STRING>["\']', f'export_format = "{esc_fmt}"'),
+    ]
+    for pattern, replacement in placeholder_patterns:
+        script = re.sub(pattern, replacement, script)
+
+    if image_path:
+        esc_img = image_path.replace("\\", "/")
+        script = re.sub(
+            r'image_path\s*=\s*["\']<[^"\']*>["\']',
+            f'image_path = "{esc_img}"',
+            script,
+        )
+
+    # ── Blender 5.x compatibility fixes ─────────────────────────────────────
+    script = script.replace(
+        "bpy.context.collection.objects.link(obj)",
+        "bpy.context.scene.collection.objects.link(obj)",
+    )
+    script = re.sub(
+        r"mesh\.use_auto_smooth\s*=\s*(True|False)",
+        "# mesh.use_auto_smooth removed in Blender 5.x",
+        script,
+    )
+    script = re.sub(
+        r"mesh\.normals_split_custom_set_from_vertices\([^)]*\)",
+        "# normals_split_custom_set_from_vertices removed in Blender 5.x",
+        script,
+    )
+    script = re.sub(
+        r"mesh\.normals_split_custom_set\([^)]*\)",
+        "# normals_split_custom_set removed in Blender 5.x",
+        script,
+    )
+    script = re.sub(
+        r"v\.normal\s*=\s*[^#\n]+",
+        "# vertex.normal is read-only in Blender 5.x",
+        script,
+    )
+    script = re.sub(
+        r"mesh\.vertices\[[^\]]+\]\.normal\s*=\s*[^#\n]+",
+        "# vertex.normal is read-only in Blender 5.x",
+        script,
+    )
+    # Blender 5.x renamed 'Subsurface' to 'Subsurface Weight'
+    script = re.sub(
+        r"principled\.inputs\['Subsurface'\]\s*=\s*([^#\n]+)",
+        r"principled.inputs['Subsurface Weight'].default_value = \1",
+        script,
+    )
+    script = re.sub(
+        r"principled\.inputs\['Subsurface'\]\.default_value\s*=\s*([^#\n]+)",
+        r"principled.inputs['Subsurface Weight'].default_value = \1",
+        script,
+    )
+
+    # Ensure the success marker is present
+    if "UTIM_BLENDER_SUCCESS" not in script:
+        script += f'\nprint(f"UTIM_BLENDER_SUCCESS: {esc_path}")\n'
+
+    return script
+
+
+# ---------------------------------------------------------------------------
+# Phase 3 — Blender execution with retry
+# ---------------------------------------------------------------------------
+
+def _phase3_execute(
+    script: str,
+    scene_data: Dict[str, Any],
+    image_path: str,
+    name: str,
+    export_path: str,
+    export_format: str,
+    tmp_dir: pathlib.Path,
+) -> str:
+    """Execute the Blender script, retrying with LLM-assisted fixes on failure."""
+    from utim_cli.config import BLENDER_PATH  # noqa: PLC0415
+    if not BLENDER_PATH:
+        raise RuntimeError(
+            "Blender executable not found. Set UTIM_BLENDER_PATH environment variable "
+            "or install Blender on the system PATH."
+        )
+
+    current_script = script
+    last_error = ""
+
+    for attempt in range(MAX_RETRIES + 1):
+        # Save script
+        script_path = tmp_dir / f"gen_{name}_{uuid.uuid4().hex[:8]}.py"
+        script_path.write_text(current_script, encoding="utf-8")
+
+        # Build command
+        if os.name == "nt":
+            cmd = f'& "{BLENDER_PATH}" -b -noaudio -P "{script_path}"'
+        else:
+            cmd = f'"{BLENDER_PATH}" -b -noaudio -P "{script_path}"'
+
+        # Auto-approve in sandbox mode
+        try:
+            from utim_cli.tools import _SANDBOX_MODE, is_command_approved, approve_command  # noqa: PLC0415
+            if _SANDBOX_MODE and not is_command_approved(cmd):
+                approve_command(cmd)
+        except Exception:
+            pass
+
+        result = subprocess.run(
+            cmd if os.name != "nt" else ["powershell", "-Command", cmd],
+            capture_output=True,
+            text=True,
+            timeout=300,
+        )
+
+        combined_output = (result.stdout or "") + (result.stderr or "")
+
+        if result.returncode == 0:
+            # Verify export file exists
+            if pathlib.Path(export_path).exists():
+                return export_path
+            match = re.search(r"UTIM_BLENDER_SUCCESS:\s*(.+)", combined_output)
+            if match:
+                found_path = match.group(1).strip()
+                if pathlib.Path(found_path).exists():
+                    return found_path
+            last_error = (
+                f"Blender exit 0 but export not found at: {export_path}\n"
+                f"Output:\n{combined_output[-2000:]}"
+            )
+        else:
+            last_error = (
+                f"Blender exit code {result.returncode}\n"
+                f"Output:\n{combined_output[-2000:]}"
+            )
+
+        if attempt < MAX_RETRIES:
+            # Ask LLM to fix the script
+            fix_prompt = (
+                f"The following Blender Python script failed with this error:\n\n"
+                f"--- ERROR ---\n{last_error}\n\n"
+                f"--- SCRIPT ---\n{current_script}\n\n"
+                f"Fix the script. "
+                f"Export path must be: {export_path.replace(chr(92), '/')}\n"
+                f"Export format must be: {export_format}"
+            )
+            try:
+                raw_fixed = _llm_call(
+                    system=_FIX_SYSTEM_PROMPT,
+                    user_text=fix_prompt,
+                    models=_CODE_MODELS,
+                    max_tokens=16384,
+                )
+                current_script = _clean_and_patch_script(
+                    raw_fixed,
+                    export_path.replace("\\", "/"),
+                    export_format,
+                    image_path.replace("\\", "/"),
+                )
+            except Exception as fix_exc:
+                raise RuntimeError(
+                    f"Script execution failed and LLM fix also failed.\n"
+                    f"Blender error:\n{last_error}\n"
+                    f"Fix error: {fix_exc}"
+                ) from fix_exc
+
+    raise RuntimeError(
+        f"Blender script failed after {MAX_RETRIES + 1} attempts.\n"
+        f"Last error:\n{last_error}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Public entry point
+# ---------------------------------------------------------------------------
+
+def blender_agent_create_from_image(
+    image_path: str,
+    name: str,
+    output_path: Optional[str] = None,
+    output_format: str = "blend",
+) -> str:
+    """Create a detailed 3-D model from an image using the 4-phase Blender pipeline.
+
+    Parameters
+    ----------
+    image_path:
+        Absolute or relative path to the source image (PNG, JPG, WEBP, BMP).
+    name:
+        Base name for the Blender object and the exported file (no extension).
+    output_path:
+        Directory where the exported file will be saved.
+        Defaults to ``blender_assets/`` in the current working directory.
+    output_format:
+        ``"blend"``, ``"obj"``, ``"glb"``, or ``"fbx"``. Defaults to ``"blend"``.
+
+    Returns
+    -------
+    str
+        A human-readable progress log including the path to the exported
+        file, or an error description.
+    """
+    output_format = output_format.lower()
+    if output_format not in ("blend", "obj", "glb", "fbx"):
+        output_format = "blend"
+
+    output_dir = output_path or os.path.join(os.getcwd(), ".utim_tmp", "blender_assets")
+    assets_dir = pathlib.Path(output_dir).absolute()
+    assets_dir.mkdir(parents=True, exist_ok=True)
+
+    safe_name = re.sub(r"[^\w\-]", "_", name)
+    export_filename = f"{safe_name}_{uuid.uuid4().hex[:8]}.{output_format}"
+    export_path = str(assets_dir / export_filename)
+
+    tmp_dir = pathlib.Path(".utim_tmp/blender")
+    tmp_dir.mkdir(parents=True, exist_ok=True)
+
+    log_lines: List[str] = []
+
+    def _log(msg: str) -> None:
+        log_lines.append(msg)
+
+    # Time tracking
+    timings = {}
+    overall_start = time.time()
+
+    def _time_log(phase: str) -> float:
+        elapsed = time.time() - overall_start
+        timings[phase] = elapsed
+        return elapsed
+
+    # ── Phase 0: Local image analysis ────────────────────────────────────────
+    _log("[Blender Agent] Phase 0: Local image analysis...")
+    phase0_start = time.time()
+    scene_brief = _phase0_local_analysis(image_path)
+    _time_log("Phase 0")
+    _log(
+        f"  Resolution  : {scene_brief.get('width')}x{scene_brief.get('height')} px\n"
+        f"  Brightness  : {scene_brief.get('brightness')}\n"
+        f"  Dom. colours: {len(scene_brief.get('dominant_colors', []))} found"
+    )
+
+    # ── Phase 1: Vision-LLM scene understanding ───────────────────────────────
+    _log("[Blender Agent] Phase 1: Vision-LLM scene analysis...")
+    phase1_start = time.time()
+    try:
+        scene_data = _phase1_vision(image_path, scene_brief)
+    except Exception as exc:
+        _time_log("Phase 1")
+        return "\n".join(log_lines) + f"\n[Blender Agent] Phase 1 FAILED.\nReason: {exc}"
+    _time_log("Phase 1")
+
+    part_count = len(scene_data.get("parts", []))
+    tattoos = scene_data.get("face_details", {}).get("tattoos", [])
+    _log(
+        f"  Scene type  : {scene_data.get('scene_type', 'unknown')}\n"
+        f"  Subject     : {scene_data.get('subject_label', 'unknown')}\n"
+        f"  Description : {scene_data.get('description', '')[:120]}...\n"
+        f"  Parts found : {part_count}\n"
+        f"  Hair style  : {scene_data.get('hair', {}).get('style', 'n/a')}\n"
+        f"  Has tattoos : {len(tattoos) if isinstance(tattoos, list) else bool(tattoos)}\n"
+        f"  Clothing    : {len(scene_data.get('clothing', []))} item(s)\n"
+        f"  Objects     : {len(scene_data.get('objects', []))} background objects"
+    )
+
+    # Save the scene description JSON alongside the script for inspection
+    json_path = tmp_dir / f"scene_{safe_name}.json"
+    json_path.write_text(json.dumps(scene_data, indent=2), encoding="utf-8")
+    _log(f"  Scene JSON  : {json_path}")
+
+    # ── Phase 2: Blender script generation ───────────────────────────────────
+    _log("[Blender Agent] Phase 2: Generating Blender Python script...")
+    phase2_start = time.time()
+    try:
+        script = _phase2_generate_script(
+            scene_data=scene_data,
+            image_path=image_path,
+            name=safe_name,
+            export_path=export_path,
+            export_format=output_format,
+        )
+    except Exception as exc:
+        _time_log("Phase 2")
+        return "\n".join(log_lines) + f"\n[Blender Agent] Phase 2 FAILED.\nReason: {exc}"
+    _time_log("Phase 2")
+
+    script_preview_path = tmp_dir / f"gen_{safe_name}_preview.py"
+    script_preview_path.write_text(script, encoding="utf-8")
+    _log(f"  Script saved: {script_preview_path}")
+
+    # ── Phase 3: Execute & validate ───────────────────────────────────────────
+    _log("[Blender Agent] Phase 3: Running Blender headless...")
+    phase3_start = time.time()
+    try:
+        final_path = _phase3_execute(
+            script=script,
+            scene_data=scene_data,
+            image_path=image_path,
+            name=safe_name,
+            export_path=export_path,
+            export_format=output_format,
+            tmp_dir=tmp_dir,
+        )
+    except Exception as exc:
+        _time_log("Phase 3")
+        return "\n".join(log_lines) + f"\n[Blender Agent] Phase 3 FAILED.\nReason: {exc}"
+    _time_log("Phase 3")
+
+    total_elapsed = time.time() - overall_start
+    _log(f"[Blender Agent] SUCCESS - exported to: {final_path}")
+    _log(f"[Blender Agent] Total elapsed time: {total_elapsed:.1f}s")
+    return "\n".join(log_lines)