added a new flow

.gitignore

@@ -29,3 +29,5 @@ backend/data/creativity_examples/*.png
 backend/data/creativity_examples/*.jpg
 backend/data/creativity_examples/*.jpeg
 backend/data/creativity_examples/*.webp
+
+output_creatives/

backend/app/analysis_flows.py

@@ -1,6 +1,6 @@
 """
-Alternative creative analysis flows: Cross-vertical inspiration and Archetype rotation.
-These flows use reference images (creativity examples) and return ad creatives JSON directly,
+Alternative creative analysis flow: Cross-vertical inspiration.
+Uses reference images (creativity examples) and returns ad creatives JSON directly,
 ready for image generation with product reference images.
 """
 
@@ -307,233 +307,3 @@ def _is_llm_refusal(text: str) -> bool:
     return any(p in lower for p in refusal_phrases) and len(text) < 500
 
 
-def analyze_product_archetype(
-    product_data: dict,
-    target_audience: list[str] | None = None,
-    image_urls: list[str] | None = None,
-) -> dict:
-    """
-    Performance-driven direct response creative analysis with archetype rotation.
-    Returns 50 ad creatives as JSON directly, ready for image generation with product references.
-    """
-    category = product_data.get("category") or "Necklace"
-    product_name = product_data.get("product_name", "")
-    price = product_data.get("price", "")
-    ref_urls = _get_reference_image_urls(image_urls)
-    log.info("archetype: starting analysis, category=%s, image_count=%d", category, len(ref_urls))
-    if ref_urls:
-        log.info("creativity_examples: used for archetype flow (dir=%s)", _get_creativity_examples_dir() or "override")
-    audience_block = ""
-    if target_audience and len(target_audience) > 0:
-        audience_list = ", ".join(target_audience)
-        audience_block = f"""
-TARGET AUDIENCES (tailor strategies to these segments):
-{audience_list}
-"""
-
-    prompt = f"""
-You are a performance-driven direct response creative strategist.
-
-Your only priority is:
-- Scroll stopping power
-- Emotional tension
-- 2-second clarity
-- Identity signaling
-- Conversion psychology
-- Simplicity over cleverness
-
-Category: {category}
-{audience_block}
-
-━━━━━━━━━━━━━━━━━━
-CREATIVE INTELLIGENCE MODE
-━━━━━━━━━━━━━━━━━━
-
-Before generating creatives, internally identify:
-
-- Core emotional pain of the buyer
-- Hidden insecurity related to the product
-- Desired identity transformation
-- Social proof triggers
-- Purchase objections
-- Visual proof mechanisms
-
-Do NOT output this analysis.
-Use it to engineer stronger creatives.
-
-━━━━━━━━━━━━━━━━━━
-CREATIVE DIRECTION
-━━━━━━━━━━━━━━━━━━
-
-While the product is jewelry, do NOT think like a jewelry advertiser.
-
-Break category expectations.
-Borrow emotional structures from:
-- Movements
-- Rituals
-- Status symbols
-- Cultural moments
-- Social dynamics
-- Milestones
-- Symbolism
-- Personal declarations
-
-Every creative must anchor the product to:
-- A moment
-- A decision
-- A turning point
-- A social interaction
-- Or an identity shift
-
-Avoid generic "model wearing necklace" concepts unless paired with strong narrative tension.
-
-━━━━━━━━━━━━━━━━━━
-CREATIVITY EXAMPLES = TEMPLATES (MANDATORY WHEN PROVIDED)
-━━━━━━━━━━━━━━━━━━
-
-If creativity example images are attached, treat them as template references for creative construction.
-Use those templates to shape:
-- composition and framing
-- visual hierarchy
-- text placement style
-- lighting and color treatment
-- emotional tone and ad format structure
-
-For each generated creative, follow a template-like structure inspired by one or more reference examples,
-but adapt the scene and copy to this product and audience. Do not copy exact text from examples.
-Create fresh ad copy while preserving the template's creative pattern.
-
-Keep outputs diverse across all 30 creatives by rotating template influence and combining different template traits.
-Do not produce near-duplicates.
-
-━━━━━━━━━━━━━━━━━━
-PRODUCT DATA
-━━━━━━━━━━━━━━━━━━
-{json.dumps(product_data, indent=2)}
-
-━━━━━━━━━━━━━━━━━━
-OBJECTIVE
-━━━━━━━━━━━━━━━━━━
-
-Generate 25 concepts internally.
-Return ONLY the strongest 20.
-
-Affiliate marketing is performance-based.
-The goal is to maximize clicks, leads, or sales while remaining compliant.
-
-Low-production, realistic visuals preferred unless premium aesthetic clearly strengthens identity signaling.
-
-Assume the ad is viewed on a 6-inch mobile screen.
-If the hook is not clear within 2 seconds, it fails.
-
-━━━━━━━━━━━━━━━━━━
-ARCHETYPE ROTATION (MANDATORY)
-━━━━━━━━━━━━━━━━━━
-
-Use these archetypes:
-
-- Unexpected analogy visual (50% creatives)
-
-Each creative must be different from the others.
-
-Each creative: ONE dominant motivator, mobile-first, strong contrast. Avoid clutter, fake authority, sci-fi. Feel photographable. Lean into tension, declaration, transformation—reject weak jewelry-ad tropes.
-
-━━━━━━━━━━━━━━━━━━
-CREATIVE RULES
-━━━━━━━━━━━━━━━━━━
-
-Do NOT use "elegance" or "elegant" in any creative (titles, headlines, body, etc.). Use other descriptive terms.
-
-Each creative must:
-- Focus on ONE dominant motivator only
-- Be mobile-first
-- Use strong contrast
-- Avoid clutter
-- Avoid fake authority
-- Avoid fabricated claims
-- Avoid impersonation
-- Avoid unrealistic guarantees
-- Avoid abstract sci-fi or unrealistic imagery
-- Feel photographable in real life
-
-Increase emotional intensity beyond typical jewelry ads.
-Avoid soft, safe romance tones.
-Lean into tension, declaration, or transformation.
-
-Reject weak, safe, or predictable ideas.
-If a concept feels like a typical jewelry ad, discard it and replace it with a stronger one.
-
-Provide concise, execution-ready output.
-No explanations.
-No reasoning.
-No fluff.
-
-━━━━━━━━━━━━━━━━━━
-PRODUCT DATA (use for scene_prompt—describe size, shape, material accurately for image generation)
-━━━━━━━━━━━━━━━━━━
-{json.dumps(product_data, indent=2)}
-
-━━━━━━━━━━━━━━━━━━
-JEWELRY PLACEMENT (MANDATORY for PRODUCT creatives)
-━━━━━━━━━━━━━━━━━━
-
-In every scene_prompt you MUST specify WHERE the jewelry appears in the frame, in a way that is logical for the product type and the concept:
-
-- Necklace / pendant / chain: worn at collarbone/neck, or laid flat on surface for flat lay; never floating or in a random spot.
-- Earrings: on the model's ears, or placed on a surface for flat lay; never floating.
-- Bracelet / bangle: on wrist, or on surface for flat lay.
-- Ring: on finger, or centered on surface for flat lay.
-- Any product: lifestyle shot = worn on body in the correct position; flat lay = product on surface, centered or composed clearly; close-up = product fills frame in a natural way (e.g. neck for necklace, ear for earrings).
-
-Placement must match the shot type and concept. The image should look like a real photo: jewelry in a believable, on-concept position.
-Do NOT leave placement vague (e.g. "jewelry in the scene"). Always state the exact placement (e.g. "necklace at collarbone", "earrings on model's ears", "bracelet on wrist", "ring on finger", "pendant centered on marble surface").
-
-━━━━━━━━━━━━━━━━━━
-OUTPUT SCHEMA (structured JSON)
-━━━━━━━━━━━━━━━━━━
-
-Return 50 creatives. Each creative has:
-- creative_number: 1–50
-- archetype: one of the archetypes (Testimonial snapshot, Screenshot-style message, Comparison, Emotional turning-point, Identity declaration, Ritual/symbolism, Social proof, Scarcity, Movement/belonging, Unexpected analogy)
-- title: short concept name
-- visual_strategy: scene_prompt (describe background, lighting, framing AND explicit logical placement of the jewelry as above; end with: Ensure the jewelry is the dominant focal point in sharp focus. Preserve the product exactly as shown. Square 1:1, 1080x1080px.), shooting_angle, color_world, creative_type (PRODUCT or NO_PRODUCT), best_platform
-- text_on_image: headline_serif (UPPERCASE), headline_script, body (1–2 lines), cta, price_original/price_final where relevant (use ₹ format, product "{product_name}", price "{price}")
-
-Include price in exactly 17 creatives. Most creatives should be PRODUCT; up to 8 NO_PRODUCT.
-"""
-
-    content: list[dict] = [{"type": "text", "text": prompt}]
-    for url in ref_urls:
-        content.append({"type": "image_url", "image_url": {"url": url}})
-
-    messages = [{"role": "user", "content": content}]
-    raw = call_llm_vision(
-        messages=messages,
-        model="gpt-4o",
-        temperature=0.85,
-        response_format=CREATIVE_OUTPUT_JSON_SCHEMA,
-    )
-    result = raw or ""
-    if _is_llm_refusal(result) and ref_urls:
-        log.warning("archetype: LLM refused with images, retrying without reference images")
-        content = [{"type": "text", "text": prompt}]
-        raw = call_llm_vision(
-            messages=[{"role": "user", "content": content}],
-            model="gpt-4o",
-            temperature=0.85,
-            response_format=CREATIVE_OUTPUT_JSON_SCHEMA,
-        )
-        result = raw or ""
-    if _is_llm_refusal(result):
-        log.warning("archetype: LLM returned refusal")
-        raise ValueError(
-            "Creative analysis was blocked. Try with different images in CREATIVITY_EXAMPLES_DIR, "
-            "or ensure the folder contains only ad/creative inspiration images."
-        )
-    try:
-        out = json.loads(result)
-    except json.JSONDecodeError:
-        out = extract_json(result)
-    creatives = out.get("creatives", [])
-    log.info("archetype: analysis complete, creatives_count=%d", len(creatives))
-    return {"creatives": creatives}

backend/app/main.py

@@ -15,11 +15,11 @@ from fastapi import Depends, FastAPI, File, HTTPException, Request, UploadFile
 from fastapi.middleware.cors import CORSMiddleware
 from pathlib import Path
 from fastapi.responses import FileResponse, RedirectResponse, Response, StreamingResponse
-from urllib.parse import urlparse
+from urllib.parse import quote, urlparse
 from pydantic import BaseModel
 
 from app.analysis import analyze_product
-from app.analysis_flows import analyze_product_archetype, analyze_product_cross_vertical
+from app.analysis_flows import analyze_product_cross_vertical
 from app.auth import authenticate_user, create_access_token, get_current_user
 from app.creatives import generate_ad_creatives
 from app.mongo import ensure_mongo_indexes, mongo_is_configured, ping_mongo
@@ -45,15 +45,32 @@ from app.canva_export import (
 )
 from app.replicate_image import MODEL_REGISTRY, REFERENCE_IMAGE_MODELS, generate_image
 from app.scraper import scrape_product
+from app.template_flow import run_template_based_creatives
 from app.variation import generate_variations, generate_variations_stream
 
 load_dotenv()
 
+
+class _SuppressNoisyAccessFilter(logging.Filter):
+    """Hide very noisy access-log endpoints from terminal output."""
+
+    _SUPPRESSED_PATHS = (
+        "/api/proxy-image",
+    )
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        try:
+            msg = record.getMessage()
+            return not any(path in msg for path in self._SUPPRESSED_PATHS)
+        except Exception:
+            return True
+
 # Env vars the app uses. (key, required, is_secret). Required = needed for core features; missing optional is just logged.
 _ENV_SPEC = [
     ("DATA_DIR", False, False),           # Hugging Face writable dir; optional locally
     ("CREATIVITY_EXAMPLES_DIR", False, False),  # Cross-vertical/archetype reference images
     ("OPENAI_API_KEY", True, True),       # Analysis + creatives
+    ("ANTHROPIC_API_KEY", False, True),   # Template-based analysis flow
     ("REPLICATE_API_TOKEN", False, True), # Generate ad images; optional
     ("KIE_API_KEY", False, True),         # Kie.ai for nano-banana-pro; optional (see kie.ai/nano-banana-pro)
     ("BASE_URL", False, False),           # Public URL for reference images (Replicate fetch)
@@ -87,6 +104,15 @@ def _check_env_on_startup():
         log.warning("Missing required env: %s — some endpoints will return 500.", ", ".join(missing_required))
 
 
+def _configure_access_log_filters():
+    """Attach a filter to uvicorn access logger to reduce terminal spam."""
+    access_logger = logging.getLogger("uvicorn.access")
+    for f in access_logger.filters:
+        if isinstance(f, _SuppressNoisyAccessFilter):
+            return
+    access_logger.addFilter(_SuppressNoisyAccessFilter())
+
+
 app = FastAPI(
     title="Amalfa Ad Creative Pipeline",
     description="Scrape product → deep analysis → generate ad creatives for Amalfa jewelry.",
@@ -122,13 +148,21 @@ class LoginRequest(BaseModel):
 
 CREATIVE_FLOW_PURELY_AESTHETIC = "purely_aesthetic"
 CREATIVE_FLOW_CROSS_VERTICAL = "cross_vertical"
-CREATIVE_FLOW_ARCHETYPE = "archetype_rotation"
+CREATIVE_FLOW_TEMPLATE_BASED = "template_based_creatives"
 
 
 class RunPipelineRequest(BaseModel):
     url: str  # Amalfa product page URL
     target_audience: list[str] | None = None  # Optional audience segments for analysis/creatives (multi-select)
-    creative_flow: str = CREATIVE_FLOW_PURELY_AESTHETIC  # purely_aesthetic | cross_vertical | archetype_rotation
+    creative_flow: str = CREATIVE_FLOW_PURELY_AESTHETIC  # purely_aesthetic | cross_vertical | template_based_creatives
+
+
+def _flow_label(flow: str) -> str:
+    if flow == CREATIVE_FLOW_CROSS_VERTICAL:
+        return "Cross-vertical inspiration"
+    if flow == CREATIVE_FLOW_TEMPLATE_BASED:
+        return "Template based creatives"
+    return "Purely aesthetic"
 
 
 def _ratio_to_width_height(ratio: str) -> tuple[int, int]:
@@ -161,6 +195,16 @@ class GenerateVariationsRequest(BaseModel):
     user_prompt: str | None = None
 
 
+class TemplateCreativesRunRequest(BaseModel):
+    product_url: str
+    template_image_urls: list[str]
+    product_image_urls: list[str] | None = None
+    logo_image_url: str | None = None
+    model_key: str = "nano-banana-2"
+    num_outputs: int = 1
+    aspect_ratio: str = "1:1"
+
+
 # ----- Correction -----
 class ImageCorrectRequest(BaseModel):
     image_id: str  # gallery entry id or "temp-id" when image not in gallery
@@ -178,6 +222,7 @@ class ImageCorrectResponse(BaseModel):
 STATIC_DIR = Path(__file__).resolve().parent / "static"
 # Amalfa logo served at GET /api/logo so Replicate can fetch it as second reference image
 LOGO_PATH = Path(__file__).resolve().parent / "amalfa_logo.png"
+TEMPLATE_EXAMPLES_SAFE = re.compile(r"^[A-Za-z0-9 _().\-]+$", re.I)
 
 
 def _run_gallery_cleanup():
@@ -196,9 +241,24 @@ def _run_gallery_cleanup():
         logging.getLogger("uvicorn.error").warning("Gallery cleanup failed: %s", e)
 
 
+def _is_supported_image_file(path: Path) -> bool:
+    return path.suffix.lower() in {".png", ".jpg", ".jpeg", ".webp"}
+
+
+def _get_creativity_examples_dir() -> Path:
+    env_dir = (os.environ.get("CREATIVITY_EXAMPLES_DIR") or "").strip()
+    if env_dir:
+        p = Path(env_dir)
+        if p.is_dir():
+            return p
+    fallback = Path(__file__).resolve().parent.parent / "data" / "creativity_examples"
+    return fallback
+
+
 @app.on_event("startup")
 def _startup():
     """Check env vars and initialize MongoDB."""
+    _configure_access_log_filters()
     _check_env_on_startup()
     log = logging.getLogger("uvicorn.error")
     if mongo_is_configured():
@@ -245,7 +305,7 @@ def _run_creatives_step(
     """Run the creatives step based on flow type."""
     if creative_flow == CREATIVE_FLOW_CROSS_VERTICAL:
         return analysis_or_strategies
-    if creative_flow == CREATIVE_FLOW_ARCHETYPE:
+    if creative_flow == CREATIVE_FLOW_TEMPLATE_BASED:
         return analysis_or_strategies
     # purely_aesthetic (default): analysis -> generate_ad_creatives
     return generate_ad_creatives(
@@ -259,7 +319,11 @@ def run_pipeline(body: RunPipelineRequest, _user: dict = Depends(get_current_use
     if not os.environ.get("OPENAI_API_KEY"):
         raise HTTPException(status_code=500, detail="OPENAI_API_KEY is not set")
     flow = body.creative_flow or CREATIVE_FLOW_PURELY_AESTHETIC
-    if flow not in (CREATIVE_FLOW_PURELY_AESTHETIC, CREATIVE_FLOW_CROSS_VERTICAL, CREATIVE_FLOW_ARCHETYPE):
+    if flow not in (
+        CREATIVE_FLOW_PURELY_AESTHETIC,
+        CREATIVE_FLOW_CROSS_VERTICAL,
+        CREATIVE_FLOW_TEMPLATE_BASED,
+    ):
         flow = CREATIVE_FLOW_PURELY_AESTHETIC
     log = logging.getLogger("uvicorn.error")
     log.info("run_pipeline: url=%s flow=%s", body.url[:60] + "..." if len(body.url) > 60 else body.url, flow)
@@ -272,10 +336,6 @@ def run_pipeline(body: RunPipelineRequest, _user: dict = Depends(get_current_use
             analysis_or_strategies = analyze_product_cross_vertical(
                 product_data, target_audience=body.target_audience
             )
-        elif flow == CREATIVE_FLOW_ARCHETYPE:
-            analysis_or_strategies = analyze_product_archetype(
-                product_data, target_audience=body.target_audience
-            )
         else:
             analysis_or_strategies = analyze_product(
                 product_data, target_audience=body.target_audience
@@ -283,7 +343,7 @@ def run_pipeline(body: RunPipelineRequest, _user: dict = Depends(get_current_use
     except Exception as e:
         raise HTTPException(status_code=500, detail=f"Analysis failed: {str(e)}")
     creatives = None
-    if flow == CREATIVE_FLOW_CROSS_VERTICAL or flow == CREATIVE_FLOW_ARCHETYPE:
+    if flow in (CREATIVE_FLOW_CROSS_VERTICAL, CREATIVE_FLOW_TEMPLATE_BASED):
         creatives = analysis_or_strategies
         log.info("run_pipeline: creatives from analysis (direct), count=%d", len(creatives.get("creatives", [])))
     else:
@@ -298,7 +358,7 @@ def run_pipeline(body: RunPipelineRequest, _user: dict = Depends(get_current_use
     if flow == CREATIVE_FLOW_PURELY_AESTHETIC:
         analysis_out = analysis_or_strategies
     else:
-        flow_label = "Cross-vertical inspiration" if flow == CREATIVE_FLOW_CROSS_VERTICAL else "Archetype rotation"
+        flow_label = _flow_label(flow)
     creative_list = creatives.get("creatives", [])
     def _concept_name(c):
         return c.get("title") or c.get("concept_name") or ""
@@ -443,7 +503,11 @@ def _stream_pipeline(
         yield _sse_message({"event": "error", "message": "OPENAI_API_KEY is not set"})
         return
     flow = creative_flow or CREATIVE_FLOW_PURELY_AESTHETIC
-    if flow not in (CREATIVE_FLOW_PURELY_AESTHETIC, CREATIVE_FLOW_CROSS_VERTICAL, CREATIVE_FLOW_ARCHETYPE):
+    if flow not in (
+        CREATIVE_FLOW_PURELY_AESTHETIC,
+        CREATIVE_FLOW_CROSS_VERTICAL,
+        CREATIVE_FLOW_TEMPLATE_BASED,
+    ):
         flow = CREATIVE_FLOW_PURELY_AESTHETIC
     log = logging.getLogger("uvicorn.error")
     log.info("stream_pipeline: url=%s flow=%s", url[:60] + "..." if len(url) > 60 else url, flow)
@@ -456,9 +520,9 @@ def _stream_pipeline(
             yield _sse_message({"event": "step", "step": "analysis", "message": "Running cross-vertical inspiration…"})
             analysis_or_strategies = analyze_product_cross_vertical(product_data, target_audience=target_audience)
             creatives = analysis_or_strategies
-        elif flow == CREATIVE_FLOW_ARCHETYPE:
-            yield _sse_message({"event": "step", "step": "analysis", "message": "Running archetype rotation…"})
-            analysis_or_strategies = analyze_product_archetype(product_data, target_audience=target_audience)
+        elif flow == CREATIVE_FLOW_TEMPLATE_BASED:
+            yield _sse_message({"event": "step", "step": "analysis", "message": "Running template based creatives…"})
+            analysis_or_strategies = analyze_product(product_data, target_audience=target_audience)
             creatives = analysis_or_strategies
         else:
             yield _sse_message({"event": "step", "step": "analysis", "message": "Running marketing analysis…"})
@@ -469,7 +533,7 @@ def _stream_pipeline(
         if flow == CREATIVE_FLOW_PURELY_AESTHETIC:
             analysis_out = analysis_or_strategies
         else:
-            flow_label = "Cross-vertical inspiration" if flow == CREATIVE_FLOW_CROSS_VERTICAL else "Archetype rotation"
+            flow_label = _flow_label(flow)
             creative_list = creatives.get("creatives", [])
             def _concept_name(c):
                 return c.get("title") or c.get("concept_name") or ""
@@ -1152,6 +1216,158 @@ async def upload_reference(
     return {"url": f"{base}/api/serve-reference/{name}", "filename": name}
 
 
+@app.get("/api/template-examples")
+def list_template_examples(request: Request, _user: dict = Depends(get_current_user)):
+    """List available creativity example templates for template-based flow."""
+    examples_dir = _get_creativity_examples_dir()
+    if not examples_dir.is_dir():
+        return {"templates": []}
+    names = sorted(
+        [p.name for p in examples_dir.iterdir() if p.is_file() and _is_supported_image_file(p)],
+        key=lambda x: x.lower(),
+    )
+    return {
+        "templates": [
+            {
+                "name": name,
+                # Same-origin relative URL avoids broken previews when BASE_URL points elsewhere.
+                "url": f"/api/template-example/{quote(name)}",
+            }
+            for name in names
+        ]
+    }
+
+
+@app.get("/api/template-example/{filename}")
+def serve_template_example(filename: str):
+    """Serve a template example image from configured creativity examples directory."""
+    if not TEMPLATE_EXAMPLES_SAFE.match(filename):
+        raise HTTPException(status_code=400, detail="Invalid filename")
+    examples_dir = _get_creativity_examples_dir()
+    if not examples_dir.is_dir():
+        raise HTTPException(status_code=404, detail="Template examples directory not found")
+    path = (examples_dir / filename).resolve()
+    try:
+        path.relative_to(examples_dir.resolve())
+    except ValueError:
+        raise HTTPException(status_code=400, detail="Invalid filename")
+    if not path.is_file() or not _is_supported_image_file(path):
+        raise HTTPException(status_code=404, detail="Template not found")
+    media = "image/png" if path.suffix.lower() == ".png" else "image/jpeg" if path.suffix.lower() in (".jpg", ".jpeg") else "image/webp"
+    return FileResponse(path, media_type=media)
+
+
+@app.post("/api/template-creatives/run")
+async def run_template_creatives(
+    body: TemplateCreativesRunRequest,
+    request: Request,
+    _user: dict = Depends(get_current_user),
+):
+    """
+    Run full template-based flow and return final generated image URLs directly.
+    """
+    if not body.product_url.strip():
+        raise HTTPException(status_code=400, detail="product_url is required")
+    template_urls = [u.strip() for u in (body.template_image_urls or []) if isinstance(u, str) and u.strip()]
+    if not template_urls:
+        raise HTTPException(status_code=400, detail="template_image_urls is required")
+    if body.num_outputs < 1 or body.num_outputs > 6:
+        raise HTTPException(status_code=400, detail="num_outputs must be between 1 and 6")
+    if body.model_key not in MODEL_REGISTRY:
+        raise HTTPException(status_code=400, detail=f"Unknown model: {body.model_key}")
+    width, height = _ratio_to_width_height(body.aspect_ratio)
+    template_image_url = template_urls[0]
+    additional_template_urls = template_urls[1:]
+    logo_image_url = body.logo_image_url.strip() if body.logo_image_url else None
+    # Allow frontend to send same-origin relative URLs for local previews.
+    # For generation, prefer BASE_URL/public host so Replicate can fetch references.
+    public_base = _reference_image_base_url(request).rstrip("/")
+    if template_image_url.startswith("/"):
+        template_image_url = f"{public_base}{template_image_url}"
+    normalized_additional_template_urls: list[str] = []
+    for u in additional_template_urls:
+        if u.startswith("/"):
+            normalized_additional_template_urls.append(f"{public_base}{u}")
+        else:
+            normalized_additional_template_urls.append(u)
+    if logo_image_url and logo_image_url.startswith("/"):
+        logo_image_url = f"{public_base}{logo_image_url}"
+    # Replicate cannot fetch localhost/loopback URLs from cloud workers.
+    # Fail early with an actionable message instead of retry noise.
+    blocked_hosts = {"127.0.0.1", "localhost", "0.0.0.0"}
+    check_urls = [template_image_url, *normalized_additional_template_urls]
+    if logo_image_url:
+        check_urls.append(logo_image_url)
+    for u in check_urls:
+        host = (urlparse(u).hostname or "").lower()
+        if host in blocked_hosts:
+            raise HTTPException(
+                status_code=400,
+                detail=(
+                    "Template/logo reference URL is localhost and cannot be fetched by Replicate. "
+                    "Set a public BASE_URL (for example ngrok/cloudflared URL) and retry."
+                ),
+            )
+    try:
+        result = await asyncio.to_thread(
+            run_template_based_creatives,
+            body.product_url.strip(),
+            template_image_url,
+            normalized_additional_template_urls,
+            body.product_image_urls,
+            logo_image_url,
+            1,
+            width,
+            height,
+            body.model_key,
+        )
+    except Exception as e:
+        logging.getLogger("uvicorn.error").exception(
+            "template_creatives_run failed: product_url=%s template_count=%d aspect_ratio=%s",
+            body.product_url.strip(),
+            len(template_urls),
+            body.aspect_ratio,
+        )
+        raise HTTPException(status_code=500, detail=f"Template flow failed: {str(e)}")
+    # Persist generated template creatives to gallery (same storage path as /api/generate-ads).
+    username = (_user or {}).get("username", "")
+    product_name = ((result.get("meta") or {}).get("product_name") or "").strip()
+    scene_prompt = ((result.get("analysis") or {}).get("image_generation_prompt") or "").strip()
+    out_images = result.get("images") or []
+    saved_images: list[str] = []
+    for idx, src_url in enumerate(out_images, start=1):
+        final_url = src_url
+        r2_key = None
+        try:
+            r2_url, r2_key = await _save_creative_to_r2(
+                src_url,
+                creative_id=idx,
+                concept_name=f"Template based creative {idx}",
+                product_name=product_name,
+            )
+            if r2_url:
+                final_url = r2_url
+        except Exception:
+            r2_key = None
+        if r2_key and username:
+            try:
+                await asyncio.to_thread(
+                    gallery_append_entry,
+                    username,
+                    r2_key=r2_key,
+                    concept_name=f"Template based creative {idx}",
+                    creative_id=idx,
+                    product_name=product_name,
+                    scene_prompt=scene_prompt or None,
+                    image_model=body.model_key,
+                )
+            except Exception:
+                pass
+        saved_images.append(final_url)
+    result["images"] = saved_images
+    return result
+
+
 @app.get("/api/serve-reference/{filename}")
 def serve_reference(filename: str):
     """Serve an uploaded reference image. Filename must be uuid.ext (safe)."""
@@ -1177,43 +1393,47 @@ async def proxy_image(url: str):
     """
     from urllib.parse import urlparse
 
-    parsed = urlparse(url)
-    if parsed.scheme not in ("http", "https") or not parsed.netloc:
-        raise HTTPException(status_code=400, detail="Invalid URL")
-    if not parsed.netloc.endswith(R2_PROXY_ALLOWED_HOST_SUFFIX):
-        raise HTTPException(status_code=403, detail="URL not allowed")
-
     try:
-        async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
-            r = await client.get(url)
-    except httpx.RequestError:
-        # Network / DNS / timeout issues talking to R2
-        raise HTTPException(status_code=502, detail="Upstream request failed")
-
-    # If R2 returns an error (e.g. expired or invalid presigned URL),
-    # surface that status code to the client instead of a generic 502.
-    if r.status_code >= 400:
-        # Common case: expired presigned URL → 403 from R2
-        detail = "Upstream returned error status"
+        parsed = urlparse(url)
+        host = (parsed.hostname or "").lower()
+        if parsed.scheme not in ("http", "https") or not host:
+            raise HTTPException(status_code=400, detail="Invalid URL")
+        if not host.endswith(R2_PROXY_ALLOWED_HOST_SUFFIX):
+            raise HTTPException(status_code=403, detail="URL not allowed")
+
         try:
-            # Best-effort to pull a short message from JSON/text bodies
-            data = r.json()
-            msg = data.get("message") or data.get("error") or None
-            if isinstance(msg, str) and msg:
-                detail = msg
-        except Exception:
-            text = (r.text or "").strip()
-            if text:
-                # Truncate very long HTML/XML error pages
-                detail = text[:512]
-        raise HTTPException(status_code=r.status_code, detail=detail)
-
-    content_type = r.headers.get("content-type", "image/png")
-    return Response(
-        content=r.content,
-        media_type=content_type,
-        headers={"Cache-Control": "private, max-age=3600"},
-    )
+            async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+                r = await client.get(url)
+        except httpx.HTTPError:
+            # Network / DNS / timeout issues talking to R2
+            raise HTTPException(status_code=502, detail="Upstream request failed")
+
+        if r.status_code >= 400:
+            detail = "Upstream returned error status"
+            try:
+                data = r.json()
+                msg = data.get("message") or data.get("error") or None
+                if isinstance(msg, str) and msg:
+                    detail = msg
+            except Exception:
+                body = (r.content or b"")[:512]
+                if body:
+                    detail = body.decode("utf-8", errors="replace").strip() or detail
+            # Never mirror upstream 5xx as our own 5xx.
+            status = r.status_code if 400 <= r.status_code < 500 else 502
+            raise HTTPException(status_code=status, detail=detail)
+
+        content_type = r.headers.get("content-type", "image/png")
+        return Response(
+            content=r.content,
+            media_type=content_type,
+            headers={"Cache-Control": "private, max-age=3600"},
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logging.getLogger("uvicorn.error").warning("proxy_image unexpected error: %s", e)
+        raise HTTPException(status_code=502, detail="Image proxy failed")
 
 
 # SPA fallback: serve index.html for non-API routes when static build is present

backend/app/template_flow.py

@@ -0,0 +1,213 @@
+"""
+Template-based creative generation flow used by the app API.
+
+Flow:
+1) Scrape product URL and pick product image
+2) Send one fixed prompt + ordered references directly to image model
+3) Return final generated image URLs
+"""
+
+import logging
+import os
+import time
+
+from app.replicate_image import generate_image_sync
+from app.scraper import scrape_product
+
+DEFAULT_MODEL_KEY = "nano-banana-2"
+REPLICATE_API_KEY = os.getenv("REPLICATE_API_KEY") or os.getenv("REPLICATE_API_TOKEN") or ""
+GENERATION_MAX_ATTEMPTS = 3
+GENERATION_RETRY_DELAY_SEC = 4
+log = logging.getLogger("uvicorn.error")
+
+VISION_USER_PROMPT = """Use the first (left) image as the design template and layout reference. Create a high-converting advertisement for the product shown in the second (middle) image. and third (last) image is the brand logo of this jewellery brand product.
+Maintain the same structure, typography style, and visual hierarchy from the template, but adapt it creatively to fit the new product.
+Focus on:
+
+Clean product placement
+
+Short, benefit-driven copy (not generic)
+
+Modern, premium aesthetic
+
+Feel free to enhance colors, lighting, and composition to make the product stand out and look more desirable."""
+
+
+def _is_url(value: str) -> bool:
+    return value.startswith("http://") or value.startswith("https://")
+
+
+def scrape_product_image_url(product_url: str) -> tuple[str, dict]:
+    data = scrape_product(product_url)
+    images = [u.strip() for u in (data.get("product_images") or "").split(",") if u.strip()]
+    first = next((u for u in images if _is_url(u)), "")
+    if not first:
+        raise ValueError("No valid product image URL found after scraping.")
+    return first, data
+
+
+def generate_with_nano_banana(
+    base_prompt: str,
+    reference_image_urls: list[str],
+    width: int,
+    height: int,
+    num_outputs: int,
+    model_key: str = DEFAULT_MODEL_KEY,
+) -> list[str]:
+    os.environ["REPLICATE_API_TOKEN"] = REPLICATE_API_KEY
+    refs = [u for i, u in enumerate(reference_image_urls) if u and u not in reference_image_urls[:i]]
+    log.info(
+        "template_flow: generation start model=%s refs=%d size=%sx%s outputs=%d",
+        model_key,
+        len(refs),
+        width,
+        height,
+        num_outputs,
+    )
+    urls: list[str] = []
+    for output_idx in range(num_outputs):
+        final_url = None
+        final_err = "Image generation failed."
+        for attempt in range(1, GENERATION_MAX_ATTEMPTS + 1):
+            log.info(
+                "template_flow: generation attempt output=%d/%d attempt=%d/%d",
+                output_idx + 1,
+                num_outputs,
+                attempt,
+                GENERATION_MAX_ATTEMPTS,
+            )
+            url, err = generate_image_sync(
+                prompt=base_prompt,
+                model_key=model_key,
+                width=width,
+                height=height,
+                reference_image_urls=refs,
+            )
+            if url and not err:
+                final_url = url
+                log.info(
+                    "template_flow: generation success output=%d/%d attempt=%d url=%s",
+                    output_idx + 1,
+                    num_outputs,
+                    attempt,
+                    final_url,
+                )
+                break
+            final_err = err or "Image generation returned no URL."
+            log.warning(
+                "template_flow: generation failed output=%d/%d attempt=%d err=%s",
+                output_idx + 1,
+                num_outputs,
+                attempt,
+                final_err,
+            )
+            if attempt < GENERATION_MAX_ATTEMPTS:
+                time.sleep(GENERATION_RETRY_DELAY_SEC)
+        if not final_url:
+            raise RuntimeError(f"Image generation failed after {GENERATION_MAX_ATTEMPTS} attempts: {final_err}")
+        urls.append(final_url)
+    return urls
+
+
+def run_template_based_creatives(
+    product_url: str,
+    template_image_url: str,
+    additional_template_image_urls: list[str] | None,
+    product_image_urls: list[str] | None,
+    logo_image_url: str | None,
+    num_outputs: int,
+    width: int,
+    height: int,
+    model_key: str = DEFAULT_MODEL_KEY,
+) -> dict:
+    if not template_image_url:
+        raise ValueError("template_image_url is required")
+    log.info(
+        "template_flow: run start product_url=%s template_url=%s additional_templates=%d selected_product_refs=%d logo=%s",
+        product_url,
+        template_image_url,
+        len(additional_template_image_urls or []),
+        len(product_image_urls or []),
+        bool(logo_image_url),
+    )
+    product_image_url, product_data = scrape_product_image_url(product_url)
+    selected_product_refs = [u for u in (product_image_urls or []) if isinstance(u, str) and _is_url(u)]
+    if selected_product_refs:
+        product_image_url = selected_product_refs[0]
+    templates = [template_image_url] + [u for u in (additional_template_image_urls or []) if u]
+    # Preserve order while de-duplicating.
+    ordered_templates = [u for i, u in enumerate(templates) if u not in templates[:i]]
+    output_urls: list[str] = []
+    analyses: list[dict] = []
+    # Generate one image per template x product-reference combination.
+    product_variants = selected_product_refs if selected_product_refs else [product_image_url]
+    for idx, template_ref in enumerate(ordered_templates):
+        log.info(
+            "template_flow: processing template %d/%d template_ref=%s",
+            idx + 1,
+            len(ordered_templates),
+            template_ref,
+        )
+        try:
+            # Simple direct mode: use one fixed prompt for generation.
+            analyses.append({
+                "template_analysis": "direct_template_prompt_mode",
+                "image_generation_prompt": VISION_USER_PROMPT,
+            })
+            base_prompt = VISION_USER_PROMPT
+            for ref_idx, product_ref in enumerate(product_variants):
+                # Prompt expects ordered references: 1) template, 2) product, 3) logo.
+                refs = [template_ref, product_ref]
+                if logo_image_url:
+                    refs.append(logo_image_url)
+                log.info(
+                    "template_flow: variant generation template=%d/%d product_ref=%d/%d",
+                    idx + 1,
+                    len(ordered_templates),
+                    ref_idx + 1,
+                    len(product_variants),
+                )
+                per_variant_urls = generate_with_nano_banana(
+                    base_prompt,
+                    refs,
+                    width,
+                    height,
+                    1,
+                    model_key=model_key,
+                )
+                output_urls.extend(per_variant_urls)
+        except Exception:
+            log.exception(
+                "template_flow: failed while processing template %d/%d template_ref=%s",
+                idx + 1,
+                len(ordered_templates),
+                template_ref,
+            )
+            raise
+    log.info(
+        "template_flow: run complete product=%s templates=%d product_variants=%d generated_images=%d",
+        product_data.get("product_name", ""),
+        len(ordered_templates),
+        len(product_variants),
+        len(output_urls),
+    )
+    return {
+        "images": output_urls,
+        "analysis": analyses[0] if analyses else {},
+        "analyses": analyses,
+        "meta": {
+            "product_url": product_url,
+            "selected_product_image_url": product_image_url,
+            "selected_product_image_urls": selected_product_refs,
+            "template_image_url": template_image_url,
+            "template_image_urls": ordered_templates,
+            "additional_template_image_urls": additional_template_image_urls or [],
+            "logo_image_url": logo_image_url,
+            "product_name": product_data.get("product_name", ""),
+            "model_key": model_key,
+            "num_outputs": len(output_urls),
+            "width": width,
+            "height": height,
+        },
+        "product_data": product_data,
+    }

fourth_flow.py

@@ -0,0 +1,364 @@
+"""
+Ad Creative Generator (Fourth Flow)
+-----------------------------------
+Flow:
+  1) Scrape product URL to fetch product image
+  2) Run one Gemini vision call for analysis + generation prompt
+  3) Generate image via nano-banana-2 with product/template/logo references
+  4) Save creative + analysis payload to output_creatives/
+"""
+
+import base64
+import json
+import os
+import shutil
+import sys
+import time
+import uuid
+from pathlib import Path
+
+import requests
+from dotenv import load_dotenv
+from google import genai
+from google.genai import types
+
+load_dotenv()
+
+# Local backend imports
+BACKEND_DIR = Path(__file__).resolve().parent / "backend"
+if str(BACKEND_DIR) not in sys.path:
+    sys.path.insert(0, str(BACKEND_DIR))
+
+from app.replicate_image import generate_image_sync  # noqa: E402  # type: ignore[reportMissingImports]
+from app.scraper import scrape_product  # noqa: E402  # type: ignore[reportMissingImports]
+
+GEMINI_API_KEY = os.getenv("GEMINI_API_KEY", "YOUR_GEMINI_API_KEY")
+GEMINI_MODEL = os.getenv("GEMINI_MODEL", "gemini-3.1-pro-preview")
+MODEL_KEY = "nano-banana-2"
+REPLICATE_API_KEY = os.getenv("REPLICATE_API_KEY") or os.getenv("REPLICATE_API_TOKEN") or "YOUR_REPLICATE_API_KEY"
+GENERATION_MAX_ATTEMPTS = 3
+GENERATION_RETRY_DELAY_SEC = 4
+
+OUTPUT_DIR = Path("output_creatives")
+OUTPUT_DIR.mkdir(exist_ok=True)
+REFERENCE_UPLOAD_DIR = BACKEND_DIR / "reference_uploads"
+REFERENCE_UPLOAD_DIR.mkdir(parents=True, exist_ok=True)
+
+
+VISION_USER_PROMPT = """You are an expert creative director and ad-tech specialist.
+Analyse these images and return ONLY valid JSON with exactly these keys:
+- template_analysis
+- product_description
+- brand_info
+- image_generation_prompt
+- negative_prompt
+
+Use first image as template/layout reference, second image as product, third image (if present) as logo/brand cue.
+CRITICAL: Treat the template like a copy-paste layout lock.
+- Keep the same composition, block structure, spacing, framing, and text placement zones as template.
+- Keep the same visual style direction (editorial/commercial look), not a new design.
+- Only change the content inside the template: product subject, brand/logo presence, and copy text.
+- Do NOT invent a different layout or scene format.
+
+Make image_generation_prompt optimized for premium photorealistic jewelry ad output"""
+
+
+def load_image_as_b64(path: str) -> str:
+    with open(path, "rb") as f:
+        return base64.b64encode(f.read()).decode("utf-8")
+
+
+def _is_supported_image(path: Path) -> bool:
+    return path.suffix.lower() in {".png", ".jpg", ".jpeg", ".webp"}
+
+
+def _reference_image_base_url() -> str:
+    return (os.getenv("BASE_URL") or "http://localhost:8002").rstrip("/")
+
+
+def _publish_local_reference(path: str) -> str:
+    src = Path(path)
+    if not src.exists():
+        raise FileNotFoundError(f"reference image not found: {path}")
+    if not _is_supported_image(src):
+        raise ValueError(f"unsupported reference image format: {path}")
+    name = f"{uuid.uuid4().hex}{src.suffix.lower()}"
+    dst = REFERENCE_UPLOAD_DIR / name
+    shutil.copy2(src, dst)
+    return f"{_reference_image_base_url()}/api/serve-reference/{name}"
+
+
+def resolve_template_path(template_path: str | None, examples_dir: str, example_file: str | None) -> str:
+    if template_path:
+        p = Path(template_path)
+        if not p.exists():
+            raise FileNotFoundError(f"template image not found: {template_path}")
+        if not _is_supported_image(p):
+            raise ValueError(f"unsupported template image format: {template_path}")
+        return str(p)
+    if example_file:
+        p = Path(examples_dir) / example_file
+        if not p.exists():
+            raise FileNotFoundError(f"example template not found: {p}")
+        if not _is_supported_image(p):
+            raise ValueError(f"unsupported example template format: {p}")
+        return str(p)
+    raise ValueError("Provide either --template or --example-file.")
+
+
+def list_template_paths(examples_dir: str, bulk_limit: int = 0) -> list[str]:
+    p = Path(examples_dir)
+    if not p.exists() or not p.is_dir():
+        raise FileNotFoundError(f"examples dir not found: {examples_dir}")
+    files = sorted(
+        [f for f in p.iterdir() if f.is_file() and _is_supported_image(f)],
+        key=lambda x: x.name.lower(),
+    )
+    if not files:
+        raise ValueError(f"No supported template images found in: {examples_dir}")
+    if bulk_limit > 0:
+        files = files[:bulk_limit]
+    return [str(f) for f in files]
+
+
+def scrape_product_image_url(product_url: str) -> tuple[str, dict]:
+    data = scrape_product(product_url)
+    images = [u.strip() for u in (data.get("product_images") or "").split(",") if u.strip()]
+    first = next((u for u in images if u.startswith("http://") or u.startswith("https://")), "")
+    if not first:
+        raise ValueError("No valid product image URL found after scraping.")
+    return first, data
+
+
+def analyse_images(template_path: str, product_image_url: str, logo_path: str | None = None) -> dict:
+    if GEMINI_API_KEY == "YOUR_GEMINI_API_KEY":
+        raise RuntimeError("GEMINI_API_KEY is not set.")
+    client = genai.Client(api_key=GEMINI_API_KEY)
+    template_mime = "image/png" if Path(template_path).suffix.lower() == ".png" else "image/jpeg"
+    parts: list = [
+        VISION_USER_PROMPT,
+        {"inline_data": {"mime_type": template_mime, "data": load_image_as_b64(template_path)}},
+        {"file_data": {"mime_type": "image/jpeg", "file_uri": product_image_url}},
+    ]
+    if logo_path:
+        logo_mime = "image/png" if Path(logo_path).suffix.lower() == ".png" else "image/jpeg"
+        parts.append({"inline_data": {"mime_type": logo_mime, "data": load_image_as_b64(logo_path)}})
+    response = client.models.generate_content(
+        model=GEMINI_MODEL,
+        contents=parts,
+        config=types.GenerateContentConfig(
+            temperature=0.35,
+            response_mime_type="application/json",
+            thinking_config=types.ThinkingConfig(thinking_level="medium"),
+        ),
+    )
+    raw = (response.text or "").strip()
+    if raw.startswith("```"):
+        raw = raw.strip().strip("`")
+        if raw.lower().startswith("json"):
+            raw = raw[4:].strip()
+    return json.loads(raw)
+
+
+def build_base_prompt_from_analysis(analysis: dict) -> str:
+    direct = (analysis.get("image_generation_prompt") or "").strip()
+    product_lock = (
+        "CRITICAL PRODUCT LOCK: Keep the exact same product from the reference image. "
+        "Do not change product type, silhouette, geometry, metal tone, gemstone colors, gemstone count, "
+        "stone shapes, setting style, proportions, or signature details. "
+        "No redesign, no substitutions, no style drift."
+    )
+    logic_lock = (
+        "LOGICAL REALISM LOCK: Final creative must be physically and contextually believable. "
+        "Jewelry placement must be natural (ring on a finger or realistic display surface), "
+        "hand anatomy must be correct, perspective/scale must be coherent, lighting and shadows must match scene geometry, "
+        "materials must look real (metal reflectance and gemstone refraction), and text placement must feel intentional/readable. "
+        "Avoid impossible poses, floating objects, mismatched reflections, or visually confusing composition."
+    )
+    if direct:
+        return (
+            f"{direct} "
+            f"{product_lock} "
+            f"{logic_lock} "
+            "Strictly preserve the template layout and composition one-to-one; "
+            "only replace content (product/copy/logo) inside the same structure."
+        ).strip()
+    synthesized = (
+        "Create a premium photorealistic jewelry ad. "
+        f"Template guidance: {analysis.get('template_analysis', '')}. "
+        f"Product guidance: {analysis.get('product_description', '')}. "
+        f"Brand guidance: {analysis.get('brand_info', '')}. "
+        "Luxury tone, clear hierarchy, readable text, clean composition."
+    )
+    neg = (analysis.get("negative_prompt") or "").strip()
+    if neg:
+        synthesized += f" Avoid: {neg}."
+    print("  ⚠️  image_generation_prompt missing; synthesized from analysis.")
+    return (
+        f"{synthesized} "
+        f"{product_lock} "
+        f"{logic_lock} "
+        "Strictly preserve the template layout and composition one-to-one; "
+        "only replace content (product/copy/logo) inside the same structure."
+    ).strip()
+
+
+def generate_with_nano_banana(base_prompt: str, reference_image_urls: list[str], width: int, height: int, num_outputs: int) -> list[str]:
+    os.environ["REPLICATE_API_TOKEN"] = REPLICATE_API_KEY
+    refs = [u for i, u in enumerate(reference_image_urls) if u and u not in reference_image_urls[:i]]
+    urls: list[str] = []
+    for _ in range(num_outputs):
+        final_url = None
+        final_err = "Image generation failed."
+        for attempt in range(1, GENERATION_MAX_ATTEMPTS + 1):
+            url, err = generate_image_sync(
+                prompt=base_prompt,
+                model_key=MODEL_KEY,
+                width=width,
+                height=height,
+                reference_image_urls=refs,
+            )
+            if url and not err:
+                final_url = url
+                break
+            final_err = err or "Image generation returned no URL."
+            print(f"  ⚠️  Attempt {attempt}/{GENERATION_MAX_ATTEMPTS} failed: {final_err}")
+            if attempt < GENERATION_MAX_ATTEMPTS:
+                time.sleep(GENERATION_RETRY_DELAY_SEC)
+        if not final_url:
+            raise RuntimeError(f"Image generation failed after {GENERATION_MAX_ATTEMPTS} attempts: {final_err}")
+        urls.append(final_url)
+    return urls
+
+
+def save_image_from_url(url: str, filename: str) -> Path:
+    resp = requests.get(url, timeout=60)
+    resp.raise_for_status()
+    out = OUTPUT_DIR / filename
+    out.write_bytes(resp.content)
+    return out
+
+
+def generate_ad_creative(template_path: str, product_url: str, logo_path: str | None, num_outputs: int, width: int, height: int) -> list[Path]:
+    print("\n" + "═" * 56)
+    print("   AD CREATIVE GENERATOR  •  Gemini + Nano Banana 2")
+    print("═" * 56)
+    print(f"  🧩  Template image: {template_path}")
+    print(f"  🌍  Reference base URL: {_reference_image_base_url()}")
+
+    print("\n[0/3] 🌐  Scraping product page …")
+    product_image_url, product_data = scrape_product_image_url(product_url)
+    print(f"  ✅  Product: {product_data.get('product_name', '')}")
+    print(f"  ✅  Product image: {product_image_url}")
+
+    template_ref = _publish_local_reference(template_path)
+    print(f"  ✅  Published template reference: {template_ref}")
+    logo_ref = None
+    if logo_path:
+        logo_ref = _publish_local_reference(logo_path)
+        print(f"  ✅  Published logo reference: {logo_ref}")
+
+    print(f"\n[1/3] 🔍  Analysing images + building prompt with {GEMINI_MODEL} …")
+    analysis = analyse_images(template_path, product_image_url, logo_path)
+    print("  ✅  Analysis complete.")
+    base_prompt = build_base_prompt_from_analysis(analysis)
+
+    ts = int(time.time())
+    payload = {
+        "analysis": analysis,
+        "meta": {
+            "product_url": product_url,
+            "selected_product_image_url": product_image_url,
+            "template_reference_url": template_ref,
+            "logo_reference_url": logo_ref,
+            "used_template_image": template_path,
+            "product_name": product_data.get("product_name", ""),
+            "model_key": MODEL_KEY,
+            "template_path": template_path,
+            "logo_path": logo_path,
+            "timestamp": ts,
+        },
+    }
+    analysis_file = OUTPUT_DIR / f"analysis_{ts}.json"
+    analysis_file.write_text(json.dumps(payload, indent=2))
+    print("  🧾  Payload:")
+    print(json.dumps(payload, indent=2))
+    print(f"  📄  Analysis JSON → {analysis_file}")
+
+    print("\n[3/3] 🚀  Generating with nano-banana-2 …")
+    refs = [product_image_url, template_ref]
+    if logo_ref:
+        refs.append(logo_ref)
+    print(f"  📦  Generation references ({len(refs)}): {refs}")
+    out_urls = generate_with_nano_banana(base_prompt, refs, width, height, num_outputs)
+
+    saved: list[Path] = []
+    for i, url in enumerate(out_urls, start=1):
+        p = save_image_from_url(url, f"ad_creative_{ts}_{i}.png")
+        saved.append(p)
+        print(f"  ✅  Saved → {p}")
+
+    print("\n" + "═" * 56)
+    print(f"   ✨  {len(saved)} creative(s) ready in ./{OUTPUT_DIR}/")
+    print("═" * 56 + "\n")
+    return saved
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Generate ad creatives — Gemini Vision + Nano Banana 2")
+    parser.add_argument("--template", default=None, help="Direct template path")
+    parser.add_argument("--examples-dir", default="backend/data/creativity_examples", help="Examples dir")
+    parser.add_argument("--example-file", default=None, help="Template filename inside examples dir")
+    parser.add_argument("--product-url", default="https://amalfa.in/products/thalia-prism-ring", help="Product URL")
+    parser.add_argument("--logo", default=None, help="Optional logo path")
+    parser.add_argument("--num", type=int, default=1, help="Number of outputs")
+    parser.add_argument("--width", type=int, default=1024)
+    parser.add_argument("--height", type=int, default=1024)
+    parser.add_argument("--bulk-templates", action="store_true", help="Run generation for all templates in --examples-dir")
+    parser.add_argument("--bulk-limit", type=int, default=0, help="Optional cap on number of templates in bulk mode")
+    args = parser.parse_args()
+
+    try:
+        files: list[Path] = []
+        if args.bulk_templates:
+            templates = list_template_paths(args.examples_dir, args.bulk_limit)
+            print(f"Running bulk mode for {len(templates)} template(s) from {args.examples_dir}")
+            failed: list[str] = []
+            for idx, template in enumerate(templates, start=1):
+                print(f"\n--- [{idx}/{len(templates)}] Template: {template} ---")
+                try:
+                    out = generate_ad_creative(
+                        template_path=template,
+                        product_url=args.product_url,
+                        logo_path=args.logo,
+                        num_outputs=args.num,
+                        width=args.width,
+                        height=args.height,
+                    )
+                    files.extend(out)
+                except Exception as ex:
+                    print(f"  ❌ Template failed: {template} | {ex}")
+                    failed.append(template)
+            if failed:
+                print(f"\nBulk completed with {len(failed)} failed template(s).")
+            else:
+                print("\nBulk completed with no template failures.")
+        else:
+            template = resolve_template_path(args.template, args.examples_dir, args.example_file)
+            files = generate_ad_creative(
+                template_path=template,
+                product_url=args.product_url,
+                logo_path=args.logo,
+                num_outputs=args.num,
+                width=args.width,
+                height=args.height,
+            )
+        print("Output files:")
+        for p in files:
+            print(f"  → {p}")
+    except Exception as e:
+        print(f"\n❌ Flow failed: {e}")
+        raise SystemExit(1)
+

frontend/src/App.jsx

@@ -167,7 +167,11 @@ const THEME_CYCLE_MS = 60000
 const CREATIVE_FLOW_OPTIONS = [
   { id: 'purely_aesthetic', label: 'Purely aesthetic flow' },
   { id: 'cross_vertical', label: 'Cross-vertical inspiration flow' },
-  { id: 'archetype_rotation', label: 'Archetype rotation flow' },
+  { id: 'template_based_creatives', label: 'Template based creatives' },
+]
+const STUDIO_MODES = [
+  { id: 'standard', label: 'Standard flows' },
+  { id: 'template', label: 'Template based creatives' },
 ]
 
 function authHeaders() {
@@ -176,6 +180,17 @@ function authHeaders() {
   return { Authorization: `Bearer ${token}` }
 }
 
+function toSameOriginDisplayUrl(url) {
+  if (!url || typeof window === 'undefined') return url
+  try {
+    const u = new URL(url, window.location.origin)
+    if (u.origin !== window.location.origin) return `${u.pathname}${u.search}`
+    return url
+  } catch {
+    return url
+  }
+}
+
 function LoginPage({ onLogin }) {
   const [username, setUsername] = useState('')
   const [password, setPassword] = useState('')
@@ -278,6 +293,7 @@ export default function App() {
   const [useSmartMatching, setUseSmartMatching] = useState(false) // AI-powered product image matching
   const [aspectRatio, setAspectRatio] = useState('1:1') // 1:1 | 16:9 | 9:16 for generated ad images
   const [creativeFlow, setCreativeFlow] = useState('purely_aesthetic')
+  const [studioMode, setStudioMode] = useState('standard')
   const [lastRunCreativeFlow, setLastRunCreativeFlow] = useState(null)
   const [targetAudiences, setTargetAudiences] = useState([]) // selected audience segments for analysis/creatives (multi-select)
   const [targetAudienceOpen, setTargetAudienceOpen] = useState(false)
@@ -289,6 +305,19 @@ export default function App() {
   const prevGeneratingRef = useRef(false)
   const [canvaStatus, setCanvaStatus] = useState({ configured: false, connected: false })
   const [exportingToCanvaId, setExportingToCanvaId] = useState(null)
+  const [templateSource, setTemplateSource] = useState('examples') // examples | upload
+  const [templateExamples, setTemplateExamples] = useState([])
+  const [templateImageUrl, setTemplateImageUrl] = useState('')
+  const [selectedTemplateUrls, setSelectedTemplateUrls] = useState([])
+  const [templateLogoUrl, setTemplateLogoUrl] = useState('/api/logo')
+  const [templateResults, setTemplateResults] = useState([])
+  const [templateMeta, setTemplateMeta] = useState(null)
+  const [templateAnalysis, setTemplateAnalysis] = useState(null)
+  const [templateLoading, setTemplateLoading] = useState(false)
+  const [templateScrapeLoading, setTemplateScrapeLoading] = useState(false)
+  const [templateSelectedProductUrls, setTemplateSelectedProductUrls] = useState([])
+  const [templateError, setTemplateError] = useState(null)
+  const [templateUploadLoading, setTemplateUploadLoading] = useState(false)
 
   // Close target audience dropdown on outside click
   useEffect(() => {
@@ -321,6 +350,21 @@ export default function App() {
       .catch(() => {})
   }, [adCreatives?.length])
 
+  useEffect(() => {
+    if (!token || studioMode !== 'template') return
+    fetch(`${API_BASE}/image-models`, { headers: authHeaders() })
+      .then((r) => {
+        if (r.status === 401) { localStorage.removeItem(AUTH_TOKEN_KEY); setToken(null); return null }
+        return r.ok ? r.json() : null
+      })
+      .then((data) => {
+        if (!data) return
+        setImageModels(data.models || [])
+        if (data.default) setSelectedImageModel((prev) => prev || data.default)
+      })
+      .catch(() => {})
+  }, [token, studioMode])
+
   // Canva status (for export to Canva)
   useEffect(() => {
     if (!token) return
@@ -351,6 +395,28 @@ export default function App() {
     }
   }, [token])
 
+  useEffect(() => {
+    if (!token || studioMode !== 'template') return
+    fetch(`${API_BASE}/template-examples`, { headers: authHeaders() })
+      .then((r) => {
+        if (r.status === 401) {
+          localStorage.removeItem(AUTH_TOKEN_KEY)
+          setToken(null)
+          return null
+        }
+        return r.ok ? r.json() : null
+      })
+      .then((data) => {
+        const list = data?.templates || []
+        setTemplateExamples(list)
+        if (!templateImageUrl && list.length > 0 && templateSource === 'examples') {
+          setTemplateImageUrl(list[0].url)
+          setSelectedTemplateUrls([list[0].url])
+        }
+      })
+      .catch(() => {})
+  }, [token, studioMode, templateSource])
+
   useEffect(() => {
     const id = setInterval(() => {
       setTheme((prev) => {
@@ -400,6 +466,123 @@ export default function App() {
     prevGeneratingRef.current = generatingAds
   }, [generatingAds, generatedAds.length])
 
+  async function uploadReferenceImage(file) {
+    const form = new FormData()
+    form.append('file', file, file.name || 'image.png')
+    const res = await fetch('/api/upload-reference', {
+      method: 'POST',
+      headers: authHeaders(),
+      body: form,
+    })
+    const data = await res.json().catch(() => ({}))
+    if (res.status === 401) {
+      localStorage.removeItem(AUTH_TOKEN_KEY)
+      setToken(null)
+      throw new Error('Session expired')
+    }
+    if (!res.ok) throw new Error(data.detail || 'Upload failed')
+    return data.url
+  }
+
+  async function handleTemplateFileChange(e) {
+    const file = e.target?.files?.[0]
+    e.target.value = ''
+    if (!file || !file.type.startsWith('image/')) return
+    setTemplateError(null)
+    setTemplateUploadLoading(true)
+    try {
+      const url = await uploadReferenceImage(file)
+      setTemplateImageUrl(url)
+      setSelectedTemplateUrls([url])
+      setTemplateSource('upload')
+    } catch (err) {
+      setTemplateError(err.message || 'Template upload failed')
+    } finally {
+      setTemplateUploadLoading(false)
+    }
+  }
+
+  async function handleTemplateRun() {
+    const trimmed = url.trim()
+    if (!trimmed) {
+      setTemplateError('Please enter an Amalfa product URL.')
+      return
+    }
+    const templateUrls = (selectedTemplateUrls || []).filter(Boolean)
+    if (templateUrls.length === 0) {
+      setTemplateError('Please select or upload a template image.')
+      return
+    }
+    setTemplateError(null)
+    setTemplateLoading(true)
+    setTemplateResults([])
+    setTemplateMeta(null)
+    setTemplateAnalysis(null)
+    try {
+      const imageUrls = (productData?.product_images || '').split(',').map((s) => s.trim()).filter(Boolean)
+      const selectedProductUrls = (templateSelectedProductUrls || []).filter((u) => imageUrls.includes(u)).slice(0, 3)
+      const res = await fetch(`${API_BASE}/template-creatives/run`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...authHeaders() },
+        body: JSON.stringify({
+          product_url: trimmed,
+          template_image_urls: templateUrls,
+          product_image_urls: selectedProductUrls.length ? selectedProductUrls : null,
+          logo_image_url: templateLogoUrl || null,
+          model_key: selectedImageModel,
+          num_outputs: 1,
+          aspect_ratio: aspectRatio,
+        }),
+      })
+      if (res.status === 401) {
+        localStorage.removeItem(AUTH_TOKEN_KEY)
+        setToken(null)
+        return
+      }
+      const data = await res.json().catch(() => ({}))
+      if (!res.ok) throw new Error(data.detail || res.statusText)
+      setTemplateResults(data.images || [])
+      setTemplateMeta(data.meta || null)
+      setTemplateAnalysis(data.analysis || null)
+      setProductData(data.product_data || null)
+    } catch (e) {
+      setTemplateError(e.message || 'Template generation failed')
+    } finally {
+      setTemplateLoading(false)
+    }
+  }
+
+  async function handleTemplateScrapeProductImages() {
+    const trimmed = url.trim()
+    if (!trimmed) {
+      setTemplateError('Please enter an Amalfa product URL.')
+      return
+    }
+    setTemplateError(null)
+    setTemplateScrapeLoading(true)
+    try {
+      const res = await fetch(`${API_BASE}/scrape`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', ...authHeaders() },
+        body: JSON.stringify({ url: trimmed }),
+      })
+      if (res.status === 401) {
+        localStorage.removeItem(AUTH_TOKEN_KEY)
+        setToken(null)
+        return
+      }
+      const data = await res.json().catch(() => ({}))
+      if (!res.ok) throw new Error(data.detail || res.statusText)
+      setProductData(data)
+      const imageUrls = (data?.product_images || '').split(',').map((s) => s.trim()).filter(Boolean)
+      setTemplateSelectedProductUrls(imageUrls.length ? [imageUrls[0]] : [])
+    } catch (e) {
+      setTemplateError(e.message || 'Failed to scrape product images')
+    } finally {
+      setTemplateScrapeLoading(false)
+    }
+  }
+
   async function handleRun() {
     const trimmed = url.trim()
     if (!trimmed) {
@@ -555,41 +738,60 @@ export default function App() {
         <p className="hero-desc">
           Paste an Amalfa product page URL. We’ll scrape the product, run a deep marketing analysis, and generate ad creative packages (product & no-product) for Meta.
         </p>
+        <div className="studio-mode-switch" role="tablist" aria-label="Studio mode">
+          {STUDIO_MODES.map((opt) => (
+            <button
+              key={opt.id}
+              type="button"
+              role="tab"
+              aria-selected={studioMode === opt.id}
+              className={`studio-mode-btn ${studioMode === opt.id ? 'studio-mode-btn--active' : ''}`}
+              onClick={() => setStudioMode(opt.id)}
+              disabled={loading || templateLoading}
+            >
+              {opt.label}
+            </button>
+          ))}
+        </div>
         <div className="input-row">
           <input
             type="url"
             placeholder="https://amalfa.in/products/..."
             value={url}
             onChange={(e) => setUrl(e.target.value)}
-            onKeyDown={(e) => e.key === 'Enter' && handleRun()}
-            disabled={loading}
+            onKeyDown={(e) => e.key === 'Enter' && (studioMode === 'template' ? handleTemplateScrapeProductImages() : handleRun())}
+            disabled={loading || templateLoading || templateScrapeLoading}
             className="url-input"
           />
           <button
             type="button"
-            onClick={handleRun}
-            disabled={loading}
+            onClick={studioMode === 'template' ? handleTemplateScrapeProductImages : handleRun}
+            disabled={loading || templateLoading || templateScrapeLoading}
             className="btn-run"
           >
-            {loading ? 'Generating…' : 'Generate'}
+            {studioMode === 'template'
+              ? (templateScrapeLoading ? 'Scraping…' : 'Scrape')
+              : ((loading || templateLoading) ? 'Generating…' : 'Generate')}
           </button>
         </div>
+        {studioMode === 'standard' ? (
+          <>
         <div className="creative-flow-row">
-          <label className="creative-flow-label">Creative flow</label>
-          <select
-            value={creativeFlow}
-            onChange={(e) => setCreativeFlow(e.target.value)}
-            disabled={loading}
-            className="creative-flow-select"
-          >
-            {CREATIVE_FLOW_OPTIONS.map((opt) => (
-              <option key={opt.id} value={opt.id}>
-                {opt.label}
-              </option>
-            ))}
-          </select>
-        </div>
-        <div className="target-audience-row" ref={targetAudienceDropdownRef}>
+            <label className="creative-flow-label">Creative flow</label>
+            <select
+              value={creativeFlow}
+              onChange={(e) => setCreativeFlow(e.target.value)}
+              disabled={loading}
+              className="creative-flow-select"
+            >
+              {CREATIVE_FLOW_OPTIONS.filter((f) => f.id !== 'template_based_creatives').map((opt) => (
+                <option key={opt.id} value={opt.id}>
+                  {opt.label}
+                </option>
+              ))}
+            </select>
+          </div>
+          <div className="target-audience-row" ref={targetAudienceDropdownRef}>
           <span className="target-audience-label">Target audiences (optional)</span>
           <div className="target-audience-multiselect">
             <button
@@ -642,18 +844,213 @@ export default function App() {
             )}
           </div>
         </div>
-        {error && <p className="error">{error}</p>}
+          {error && <p className="error">{error}</p>}
+          </>
+        ) : (
+          <div className="template-mode-panel">
+            <div className="template-step-card">
+              <div className="template-step-head">
+                <span className="template-step-badge">1</span>
+                <div>
+                  <h3>Scrape product references</h3>
+                  <p>Use the product URL above, then fetch product images for selection.</p>
+                </div>
+              </div>
+              <div className="creative-flow-row">
+                <span className="analysis-preview-meta">
+                  Selected: {templateSelectedProductUrls.length}/3 product references
+                </span>
+              </div>
+              {(productData?.product_images || '').trim() && (
+                <ProductCard
+                  data={productData}
+                  selectedReferenceUrls={templateSelectedProductUrls}
+                  onToggleReference={(imgUrl) => {
+                    setTemplateSelectedProductUrls((prev) => {
+                      const has = prev.includes(imgUrl)
+                      if (has) return prev.filter((u) => u !== imgUrl)
+                      if (prev.length >= 3) return prev
+                      return [...prev, imgUrl]
+                    })
+                  }}
+                  onImageClick={(src, alt) => setLightboxImage({ src, alt })}
+                />
+              )}
+            </div>
+
+            <div className="template-step-card">
+              <div className="template-step-head">
+                <span className="template-step-badge">2</span>
+                <div>
+                  <h3>Choose templates</h3>
+                  <p>Select one or more templates to guide the generated creative.</p>
+                </div>
+              </div>
+              <div className="creative-flow-row">
+                <label className="creative-flow-label">Template source</label>
+                <select
+                  value={templateSource}
+                  onChange={(e) => {
+                    const src = e.target.value
+                    setTemplateSource(src)
+                    if (src === 'examples' && templateExamples.length > 0) {
+                      setTemplateImageUrl(templateExamples[0].url)
+                      setSelectedTemplateUrls([templateExamples[0].url])
+                    }
+                  }}
+                  disabled={templateLoading}
+                  className="creative-flow-select"
+                >
+                  <option value="examples">Example gallery</option>
+                  <option value="upload">Upload template</option>
+                </select>
+                <span className="analysis-preview-meta">
+                  Selected templates: {selectedTemplateUrls.length}
+                </span>
+              </div>
+              {templateSource === 'examples' ? (
+                <div className="template-examples-grid">
+                  <div className="template-selection-actions">
+                    <button
+                      type="button"
+                      className="target-audience-action-btn"
+                      onClick={() => setSelectedTemplateUrls(templateExamples.map((t) => t.url))}
+                      disabled={templateLoading || templateExamples.length === 0}
+                    >
+                      Select all
+                    </button>
+                    <button
+                      type="button"
+                      className="target-audience-action-btn"
+                      onClick={() => {
+                        setSelectedTemplateUrls([])
+                        setTemplateImageUrl('')
+                      }}
+                      disabled={templateLoading || selectedTemplateUrls.length === 0}
+                    >
+                      Clear
+                    </button>
+                  </div>
+                  {templateExamples.map((t) => (
+                    <button
+                      key={t.url}
+                      type="button"
+                      className={`template-example-card ${selectedTemplateUrls.includes(t.url) ? 'template-example-card--active' : ''}`}
+                      onClick={() => {
+                        setSelectedTemplateUrls((prev) => {
+                          const has = prev.includes(t.url)
+                          const next = has ? prev.filter((u) => u !== t.url) : [...prev, t.url]
+                          setTemplateImageUrl(next[0] || '')
+                          return next
+                        })
+                      }}
+                      disabled={templateLoading}
+                    >
+                    <img src={toSameOriginDisplayUrl(t.url)} alt={t.name} className="template-example-img" />
+                      <span className="template-example-name">{t.name}</span>
+                    </button>
+                  ))}
+                </div>
+              ) : (
+                <div className="creative-flow-row template-upload-row">
+                  <label className="creative-flow-label">Upload template image</label>
+                  <label className="template-file-btn">
+                    <input
+                      type="file"
+                      accept="image/*"
+                      onChange={handleTemplateFileChange}
+                      disabled={templateLoading || templateUploadLoading}
+                    />
+                    {templateUploadLoading ? 'Uploading...' : 'Choose template image'}
+                  </label>
+                </div>
+              )}
+            </div>
+
+            <div className="template-step-card">
+              <div className="template-step-head">
+                <span className="template-step-badge">3</span>
+                <div>
+                  <h3>Review references and generate</h3>
+                  <p>Confirm selected references and run one final creative.</p>
+                </div>
+              </div>
+              <div className="template-controls-row">
+                <div className="template-control-item">
+                  <label className="creative-flow-label">Image model</label>
+                  <select
+                    value={selectedImageModel}
+                    onChange={(e) => setSelectedImageModel(e.target.value)}
+                    disabled={templateLoading}
+                    className="creative-flow-select"
+                  >
+                    {imageModels.length > 0 ? (
+                      imageModels.map((m) => (
+                        <option key={m.key} value={m.key}>
+                          {m.label || m.key}
+                        </option>
+                      ))
+                    ) : (
+                      <option value="nano-banana-2">Nano Banana 2 (Replicate)</option>
+                    )}
+                  </select>
+                </div>
+                <div className="template-control-item">
+                  <label className="creative-flow-label">Outputs</label>
+                  <span className="template-control-value">
+                    {Math.max(1, selectedTemplateUrls.length) * Math.max(1, templateSelectedProductUrls.length)} image
+                    {Math.max(1, selectedTemplateUrls.length) * Math.max(1, templateSelectedProductUrls.length) > 1 ? 's' : ''}
+                  </span>
+                </div>
+                <div className="template-control-item">
+                  <label className="creative-flow-label">Aspect ratio</label>
+                  <select
+                    value={aspectRatio}
+                    onChange={(e) => setAspectRatio(e.target.value)}
+                    disabled={templateLoading}
+                    className="creative-flow-select"
+                  >
+                    <option value="1:1">1:1</option>
+                    <option value="16:9">16:9</option>
+                    <option value="9:16">9:16</option>
+                  </select>
+                </div>
+              </div>
+              <div className="template-summary-row">
+                <span className="template-summary-chip">Templates selected: {selectedTemplateUrls.length}</span>
+                <span className="template-summary-chip">Product refs: {templateSelectedProductUrls.length}/3</span>
+                <span className="template-summary-chip">
+                  Expected outputs: {Math.max(1, selectedTemplateUrls.length) * Math.max(1, templateSelectedProductUrls.length)}
+                </span>
+              </div>
+              <div className="template-generate-row">
+                <button
+                  type="button"
+                  className="btn-run"
+                  onClick={handleTemplateRun}
+                  disabled={templateLoading}
+                >
+                  {templateLoading ? 'Generating…' : 'Generate Template Creative'}
+                </button>
+              </div>
+            </div>
+            {templateUploadLoading && (
+              <p className="loading-step">Uploading reference image…</p>
+            )}
+            {templateError && <p className="error">{templateError}</p>}
+          </div>
+        )}
       </section>
 
-      {loading && (
+      {(loading || templateLoading) && (
         <section className="loading">
           <div className="spinner" />
-          <p className="loading-step">{streamStep || 'Starting…'}</p>
+          <p className="loading-step">{studioMode === 'template' ? 'Generating template based creatives…' : (streamStep || 'Starting…')}</p>
           <p className="loading-hint">Results will appear below as each step completes.</p>
         </section>
       )}
 
-      {(productData || analysis || (adCreatives && adCreatives.length > 0)) && (
+      {studioMode === 'standard' && (productData || analysis || (adCreatives && adCreatives.length > 0)) && (
         <div className="results">
           {productData && (
             <ProductCard
@@ -910,6 +1307,18 @@ export default function App() {
           )}
         </div>
       )}
+      {studioMode === 'template' && (
+        <div className="results">
+          {templateResults && templateResults.length > 0 && (
+            <TemplateResultsSection
+              images={templateResults}
+              meta={templateMeta}
+              analysis={templateAnalysis}
+              onImageClick={(src, alt) => setLightboxImage({ src, alt })}
+            />
+          )}
+        </div>
+      )}
 
       <footer className="footer">
         <p>Because love deserves a little extra ❤️</p>
@@ -953,6 +1362,41 @@ export default function App() {
   )
 }
 
+function TemplateResultsSection({ images = [], meta = null, analysis = null, onImageClick }) {
+  if (!images?.length) return null
+  return (
+    <section className="card creatives-card template-results-card">
+      <h2>Template based creatives ({images.length})</h2>
+      {meta?.product_name && (
+        <p className="creatives-flow-badge">Product: {meta.product_name}</p>
+      )}
+      <div className="template-results-grid">
+        {images.map((url, idx) => (
+          <div key={`${url}-${idx}`} className="template-result-item">
+            <div className="template-result-media">
+              <img
+                src={url}
+                alt={`Template creative ${idx + 1}`}
+                className={`template-result-img ${onImageClick ? 'img-expandable' : ''}`}
+                onClick={() => onImageClick?.(url, `Template creative ${idx + 1}`)}
+              />
+            </div>
+            <div className="template-result-meta">
+              <span className="template-result-id">Creative {idx + 1}</span>
+            </div>
+          </div>
+        ))}
+      </div>
+      {analysis && (
+        <details className="analysis-card" style={{ marginTop: '1rem' }}>
+          <summary>Show analysis JSON</summary>
+          <pre style={{ whiteSpace: 'pre-wrap' }}>{JSON.stringify(analysis, null, 2)}</pre>
+        </details>
+      )}
+    </section>
+  )
+}
+
 function ProductCard({ data, selectedReferenceUrls = [], onToggleReference, onImageClick }) {
   const imageUrls = (data?.product_images || '')
     .split(',')

frontend/src/index.css

@@ -409,6 +409,50 @@ a:hover {
   line-height: 1.6;
 }
 
+.studio-mode-switch {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.35rem;
+  padding: 0.3rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--surface-soft);
+  margin-bottom: 1rem;
+}
+
+.studio-mode-btn {
+  border: 0;
+  background: transparent;
+  color: var(--text-soft);
+  padding: 0.55rem 1rem;
+  border-radius: 999px;
+  font-size: 0.86rem;
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  cursor: pointer;
+  transition: background 0.2s ease, color 0.2s ease, box-shadow 0.2s ease;
+}
+
+.studio-mode-btn:hover:not(:disabled) {
+  color: var(--text);
+}
+
+.studio-mode-btn--active {
+  background: linear-gradient(135deg, var(--accent), var(--accent-hover));
+  color: #fff;
+  box-shadow: none;
+}
+
+.studio-mode-btn--active:hover:not(:disabled) {
+  color: #fff;
+  background: linear-gradient(135deg, var(--accent), var(--accent-hover));
+}
+
+.studio-mode-btn:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
 .input-row {
   display: flex;
   gap: 0.75rem;
@@ -449,6 +493,271 @@ a:hover {
   cursor: not-allowed;
 }
 
+.template-mode-panel {
+  margin-top: 1rem;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+}
+
+.template-step-card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  padding: 0.9rem;
+  margin-top: 0.8rem;
+}
+
+.template-step-head {
+  display: flex;
+  gap: 0.65rem;
+  align-items: flex-start;
+}
+
+.template-step-head h3 {
+  margin: 0;
+  font-size: 0.95rem;
+}
+
+.template-step-head p {
+  margin: 0.2rem 0 0;
+  color: var(--text-soft);
+  font-size: 0.8rem;
+}
+
+.template-step-badge {
+  width: 24px;
+  height: 24px;
+  border-radius: 999px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.78rem;
+  font-weight: 700;
+  color: #fff;
+  background: linear-gradient(135deg, var(--accent), var(--accent-hover));
+  flex-shrink: 0;
+}
+
+.template-examples-grid {
+  margin-top: 0.75rem;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
+  gap: 0.75rem;
+}
+
+.template-selection-actions {
+  grid-column: 1 / -1;
+  display: flex;
+  gap: 0.5rem;
+}
+
+.template-example-card {
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 0.35rem;
+  background: var(--surface);
+  display: flex;
+  flex-direction: column;
+  gap: 0.35rem;
+  cursor: pointer;
+  transition: transform 0.18s ease, box-shadow 0.18s ease, border-color 0.18s ease;
+}
+
+.template-example-card:hover:not(:disabled) {
+  transform: translateY(-2px);
+  border-color: var(--accent);
+  box-shadow: 0 10px 24px rgba(0, 0, 0, 0.14);
+}
+
+.template-example-card--active {
+  border-color: var(--accent);
+  box-shadow: 0 0 0 2px rgba(var(--accent-focus, 100, 116, 139), 0.3);
+}
+
+.template-example-card:disabled {
+  opacity: 0.7;
+  cursor: not-allowed;
+}
+
+.template-example-img {
+  width: 100%;
+  aspect-ratio: 1;
+  object-fit: cover;
+  border-radius: 8px;
+}
+
+.template-example-name {
+  font-size: 0.74rem;
+  color: var(--text-soft);
+  text-align: left;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  padding: 0 0.15rem 0.2rem;
+}
+
+.template-upload-row {
+  justify-content: space-between;
+}
+
+.template-file-btn {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.55rem 0.9rem;
+  border-radius: 8px;
+  border: 1px solid transparent;
+  background: var(--accent);
+  color: #fff;
+  font-weight: 600;
+  font-size: 0.84rem;
+  cursor: pointer;
+}
+
+.template-file-btn--secondary {
+  background: var(--surface);
+  color: var(--text);
+  border-color: var(--border);
+}
+
+.template-file-btn input {
+  position: absolute;
+  inset: 0;
+  opacity: 0;
+  cursor: pointer;
+}
+
+.template-controls-row {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(180px, 1fr));
+  gap: 0.75rem 1rem;
+  align-items: end;
+}
+
+.template-controls-row .creative-flow-row {
+  margin-top: 0.4rem;
+}
+
+.template-controls-row .creative-flow-select {
+  min-width: 130px;
+}
+
+.template-control-item {
+  display: flex;
+  align-items: center;
+  gap: 0.65rem;
+}
+
+.template-control-value {
+  font-size: 0.85rem;
+  color: var(--text);
+  background: var(--surface-soft);
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 0.25rem 0.55rem;
+}
+
+.template-preview-row {
+  margin-top: 0.5rem;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+  gap: 0.75rem;
+}
+
+.template-generate-row {
+  margin-top: 0.9rem;
+  display: flex;
+  justify-content: flex-end;
+}
+
+.template-summary-row {
+  margin-top: 0.65rem;
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+}
+
+.template-summary-chip {
+  font-size: 0.78rem;
+  color: var(--text-soft);
+  background: var(--surface-soft);
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  padding: 0.28rem 0.6rem;
+}
+
+.template-results-card {
+  overflow: hidden;
+}
+
+.template-results-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 320px));
+  gap: 1rem;
+  justify-content: start;
+}
+
+.template-result-item {
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--surface);
+}
+
+.template-result-media {
+  background: var(--surface-soft);
+  min-height: 280px;
+  max-height: 420px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.5rem;
+}
+
+.template-result-img {
+  max-width: 100%;
+  max-height: 400px;
+  width: auto;
+  height: auto;
+  display: block;
+  border-radius: 8px;
+}
+
+.template-result-meta {
+  padding: 0.55rem 0.75rem;
+  border-top: 1px solid var(--border-soft);
+}
+
+.template-result-id {
+  font-size: 0.82rem;
+  color: var(--text-soft);
+  font-weight: 600;
+}
+
+.template-preview-card {
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  padding: 0.5rem;
+}
+
+.template-preview-label {
+  display: inline-block;
+  margin-bottom: 0.35rem;
+  font-size: 0.76rem;
+  color: var(--text-soft);
+}
+
+.template-preview-img {
+  width: 100%;
+  aspect-ratio: 1;
+  object-fit: cover;
+  border-radius: 8px;
+}
+
 .target-audience-row {
   display: flex;
   align-items: center;