Add Gradio micro-trend app with LLM integrations and prompt loading

- add system prompt file under prompts/ and loader utilities
- implement settings loader with env overrides and example env file
- create schema validator/summary builder and LLM client wrappers (OpenAI/Gemini)
- build inference pipeline and Gradio UI (multi-image upload, previews, JSON + formatted summary)
- add requirements, README instructions, and ignore local config/secrets
- improve logging, error handling, and bullet formatting; support Gemini auth modes

.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+env/
+venv/
+.venv/
+ENV/
+
+# Packaging / build
+build/
+dist/
+*.egg-info/
+
+# IDE / editor
+.idea/
+.vscode/
+
+# OS
+.DS_Store
+
+# Local config/secrets
+.env
+settings.json
+.env.example
+
+# Gradio cache
+gradio_cached_examples/
+gradio_processed_images/

README.md

@@ -0,0 +1,36 @@
+# Micro-Trend Detection Gradio UI
+
+Gradio app that ingests garment images, calls GPT-5/GPT-5 mini or Gemini 3 vision models, and returns the micro-trend JSON plus a bullet summary.
+
+## Setup
+- Python 3.11+ recommended.
+- Install deps: `pip install -r requirements.txt`
+- Configure secrets via environment or `settings.json` (keys mirror `sample_code/settings.json`) or `.env`:
+  - `OPENAI_API_KEY`, `GEMINI_API_KEY`
+  - `OPENAI_MODEL` (default `gpt-5-mini`), `OPENAI_REASONING_EFFORT`
+  - `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`
+- The system prompt lives in `prompts/micro-trend-prompt.md` and is loaded automatically.
+
+## Run
+```bash
+python app.py
+```
+Use `PORT`/`HOST` env vars if you need custom binding (Gradio honors them).
+
+## How it works
+- `app.py` builds the Gradio UI (multi-image upload, model dropdown, optional downscale).
+- `pipeline.py` calls the unified LLM client, extracts/validates the JSON, and derives summary bullets.
+- `llm_clients.py` wraps OpenAI Responses API and Gemini 3 vision.
+- `schemas.py` provides structural validation and summary helper.
+- `settings.py` loads config with env overrides.
+- Prompt is read from `prompts/micro-trend-prompt.md` unchanged.
+
+## Gemini auth notes
+- Two modes:
+  - Vertex (default): set `GOOGLE_GENAI_USE_VERTEXAI=true` and ensure ADC is available (e.g., `gcloud auth application-default login`) plus `GOOGLE_CLOUD_PROJECT`/`GOOGLE_CLOUD_LOCATION`. Confirm the chosen model exists in your Vertex region.
+  - API key (HuggingFace / Studio): set `GOOGLE_GENAI_USE_VERTEXAI=false` and provide `GEMINI_API_KEY`.
+  - Default Gemini model name is `gemini-3-pro-preview` (multimodal text-out). Adjust to a region-available model if needed.
+
+## Notes
+- Testing is deferred for now; add unit tests later for schema validation and summary builder.
+- Downscale checkbox reduces images to 1024px for lower cost/latency. If downscale fails, original bytes are used.

app.py

@@ -0,0 +1,119 @@
+from __future__ import annotations
+
+import io
+import logging
+from pathlib import Path
+from typing import List
+
+import gradio as gr
+from PIL import Image
+
+from llm_clients import GEMINI_3_VISION, OPENAI_GPT5, OPENAI_GPT5_MINI
+from pipeline import DEFAULT_USER_PROMPT, process_images
+from settings import load_settings
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger("app")
+
+
+def _load_images(files: List[gr.File], downscale: bool) -> List[bytes]:
+    images: List[bytes] = []
+    for f in files or []:
+        data = Path(f.name).read_bytes()
+        if downscale:
+            try:
+                img = Image.open(io.BytesIO(data)).convert("RGB")
+                img.thumbnail((1024, 1024))
+                buf = io.BytesIO()
+                img.save(buf, format="PNG")
+                data = buf.getvalue()
+            except Exception as exc:  # noqa: BLE001
+                LOGGER.warning("Downscale failed for %s: %s; using original", f.name, exc)
+        images.append(data)
+    return images
+
+
+def make_interface():
+    settings = load_settings()
+    settings.require_api_keys()
+
+    def _infer(files, model, creativity, downscale_images):
+        images = _load_images(files, downscale_images)
+        if not images:
+            raise gr.Error("Please upload at least one image.")
+
+        try:
+            result = process_images(
+                images,
+                model,
+                settings,
+                system_prompt_path=None,
+                user_prompt=DEFAULT_USER_PROMPT,
+            )
+        except Exception as exc:  # noqa: BLE001
+            LOGGER.exception("Inference failed")
+            raise gr.Error(str(exc))
+
+        trends = result["trends"]
+        bullets = result["summary"]
+        md = "\n\n".join(f"- {b}" for b in bullets) if bullets else "No summary available."
+        return trends, md
+
+    def _on_files_change(files):
+        """Update preview and clear outputs when files are removed."""
+        if not files:
+            return [], None, ""
+        return files, gr.update(), gr.update()
+
+    with gr.Blocks(title="Garment Micro-Trend Detector") as demo:
+        gr.Markdown(
+            "Upload garment image(s), pick a model, and get structured micro-trend JSON plus a bullet summary."
+        )
+
+        with gr.Row():
+            image_input = gr.Files(file_count="multiple", label="Garment images")
+            with gr.Column():
+                model_choices = [OPENAI_GPT5, OPENAI_GPT5_MINI, GEMINI_3_VISION]
+                default_model = settings.openai_model if settings.openai_model in model_choices else OPENAI_GPT5_MINI
+                model_dd = gr.Dropdown(
+                    choices=model_choices,
+                    value=default_model,
+                    label="Model",
+                    allow_custom_value=True,  # allow custom OpenAI model overrides like gpt-5.1
+                )
+                creativity = gr.Slider(
+                    minimum=0.0,
+                    maximum=1.0,
+                    step=0.1,
+                    value=0.2,
+                    label="Creativity (temperature hint)",
+                    info="Not all models use this directly; for now it is informational.",
+                )
+                downscale_chk = gr.Checkbox(value=True, label="Downscale images to 1024px for speed/cost")
+                run_btn = gr.Button("Analyze", variant="primary")
+
+        preview = gr.Gallery(
+            label="Preview",
+            show_label=True,
+            object_fit="contain",  # preserve aspect ratio
+            height="auto",
+        )
+        json_out = gr.JSON(label="Micro-trend JSON")
+        summary_md = gr.Markdown(label="Summary")
+
+        image_input.change(_on_files_change, inputs=image_input, outputs=[preview, json_out, summary_md], queue=False)
+
+        run_btn.click(
+            _infer,
+            inputs=[image_input, model_dd, creativity, downscale_chk],
+            outputs=[json_out, summary_md],
+            queue=True,
+        )
+
+    return demo
+
+
+if __name__ == "__main__":
+    app = make_interface()
+    app.queue()
+    app.launch()

docs/plan.md

@@ -0,0 +1,48 @@
+# Gradio Micro-Trend Detector — Build Plan
+
+- **Use the provided prompt verbatim**: The system prompt in `docs/problem-statement.md` must be used as-is for all providers (OpenAI + Gemini). Only attach a minimal user prompt per request.
+- **Reuse the settings shape**: Follow the `sample_code/settings.json` structure for all configurable keys (API keys, model names, reasoning effort, project/location flags).
+- **Reference samples**: Mirror integration patterns shown in `sample_code/llm_client.py` (OpenAI responses API) and any other helpers in `sample_code/` for payloads, retries, and settings resolution.
+
+## Delivery Steps
+1) **Requirements & schema**
+   - Extract the output JSON contract from `docs/problem-statement.md` and codify it (Pydantic/TypedDict) for validation and downstream parsing.
+   - Decide on the response envelope: `{ "trends": <validated JSON>, "summary": <bullet list> }`.
+
+2) **Configuration layer**
+   - Implement a `settings` loader that reads `settings.json` (and env overrides) using the same keys as `sample_code/settings.json` (`OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENAI_MODEL`, `OPENAI_REASONING_EFFORT`, `GOOGLE_GENAI_USE_VERTEXAI`, `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`).
+   - Provide `.env.example` and document required vars in `README`.
+
+3) **Model abstraction**
+   - Create a unified `llm_clients.py` with `analyze(images: list[bytes], model: str) -> dict`.
+   - Providers: OpenAI GPT-5 and GPT-5 mini via the Responses API; Gemini 3 vision endpoint with safety params aligned to the sample.
+   - Shared concerns: timeouts, retries/backoff, logging, optional temperature/max_tokens, deterministic defaults.
+
+4) **Prompting strategy**
+   - System prompt = the exact content from `docs/problem-statement.md` (no edits).
+   - User prompt per call: short instruction to analyze the attached garment image(s) and emit only the specified JSON.
+   - Enforce “JSON first” responses; consider a post-parse repair/reprompt path if JSON is invalid.
+
+5) **Inference pipeline**
+   - Image intake: validate file types, normalize to RGB, optional downscale/compress for cost and latency.
+   - Call model abstraction; parse and validate JSON against the schema; if invalid, attempt regex extract or auto-reprompt with the model including the error.
+   - Derive the bullet-point summary from validated JSON (or accept model-provided summary if valid).
+
+6) **Gradio UI**
+   - Inputs: `gr.Files` (multiple images), model dropdown (`GPT-5`, `GPT-5-mini`, `Gemini 3`), creativity/temperature slider, optional checkbox for “downscale images”.
+   - Outputs: `gr.JSON` for the structured trends, `gr.Markdown` for bullet summary; error banner for validation issues; loading indicator/queue enabled.
+   - Add helper text describing acceptable formats and latency expectations; optional “Download JSON” button.
+
+7) **Observability & performance**
+   - Log per-request latency, model used, image count/size, and validation outcomes.
+   - Default to GPT-5 mini to control cost; allow overrides via settings or UI.
+   - Optional image downscaling knob; consider concurrency limits via Gradio queue.
+
+8) **Packaging & run**
+   - Add `requirements.txt/pyproject` entries (gradio, openai>=1.x, google-genai/vertex client, pydantic, pillow).
+   - Document `python app.py --settings settings.json` (or env-only) startup, including PORT/HOST env handling for deployment.
+
+9) **Acceptance checklist**
+    - Gradio UI renders, accepts multiple images, selects among the three models, and returns validated JSON + bullet summary.
+    - Prompt from `docs/problem-statement.md` is used unchanged.
+    - Settings follow the `sample_code/settings.json` shape; README and `.env.example` supplied.

docs/problem-statement.md

@@ -0,0 +1,195 @@
+Here’s a ready-to-paste meta-prompt you can drop into a Gemini Gem’s Instructions field to turn it into a garment micro-trend extractor (especially focused on print type + placement).
+Name: Garment-MicroTrend-JSON
+Description: Converts garment images into structured JSON capturing print/placement micro-trends.
+Instructions (System Prompt):
+You are MicroTrendStruct, an advanced Fashion Vision & Micro-Trend Serialization Engine. Your sole purpose is to ingest visual input (garment images) and transcode every discernible print, pattern, and placement detail into a rigorous, machine-readable JSON format suitable for micro-trend analysis.
+ROLE & OBJECTIVE
+Your focus is garments, not generic scenes.
+Your primary objective is to:
+Detect whether the garment has any print/pattern/graphic/texture beyond a flat solid.
+Describe the type of print, motifs, scale, density, layout, and print technique (if inferable).
+Describe where the print lives on the garment (placement zones, coverage, orientation, engineered vs all-over).
+Normalize these details into micro-trend tags that can be aggregated across large datasets.
+You are not describing art; you are building a fashion trend database row from pixels.
+CORE DIRECTIVE
+Do not summarize in prose outside the JSON schema.
+Do not offer high-level commentary unless it is in the dedicated fields for micro-trend tags or short “feel” strings.
+If a detail exists in pixels and is relevant to print, pattern, color story, or placement, it should appear somewhere in your JSON.
+If something is not visible or genuinely ambiguous, keep the field but set the value to null and lower confidence for that field. Do not silently omit fields.
+ANALYSIS PROTOCOL (SILENT)
+Before generating JSON, perform a silent multi-pass visual sweep (do not output this):
+Garment Sweep
+Count visible garments. Identify primary garment(s).
+Determine approximate category (dress, shirt, tee, blouse, skirt, jeans, trouser, co-ord top, co-ord bottom, jacket, etc.).
+Note view type (front, back, side, 3/4, flatlay, detail shot, runway/street on model).
+Print & Pattern Sweep
+Detect whether the garment is solid, textured, or printed.
+If printed/graphic, identify print families (floral, geometric, stripe, check, polka, animal, abstract, logo, slogan, photo, etc.).
+Check for multiple print layers (e.g., ditsy floral over a stripe, border prints, panel prints).
+Placement Sweep
+Map where prints appear: overall/all-over vs specific zones (chest, hem, sleeves, collar, yoke, side panels, back only, etc.).
+Estimate coverage percentage in each zone and whether the print is engineered/placed or repeated all-over.
+Micro-Trend Sweep
+Translate observable features into normalized micro-trend tags: e.g. ditsy_floral, oversized_floral, border_print_at_hem, front_chest_slogan, allover_logo, psychedelic_swirl, warped_stripes, photo_real_graphic, tonal_neutral_print, neon_accent_on_black, etc.
+OUTPUT FORMAT (STRICT)
+You must return ONLY a single valid JSON object.
+Do not include markdown fences (no ```json).
+Do not include any conversational text before or after the JSON.
+Use this schema (and expand arrays as needed):
+{
+"meta": {
+"image_quality": "Low/Medium/High",
+"image_type": "Photo/Illustration/Flatlay/Runway/Street/etc",
+"view_type": "Front/Back/Side/3_4/Flatlay/Detail/Full_body_on_model",
+"num_visible_garments": 1
+},
+"global_scene": {
+"setting": "Studio_white_bg/Studio_colored_bg/Street/Runway/Store/etc",
+"model_present": true,
+"occlusions_or_crops": "Brief note about parts of the garment that are cut off, hidden or overlapped, or null if none"
+},
+"garments": [
+{
+"id": "garment_001",
+"role": "primary/secondary/background",
+"category": "Dress/Top/Tee/Shirt/Blouse/Skirt/Jeans/Trouser/Jacket/Co_ord_top/Co_ord_bottom/Other",
+"sub_category": "Free-text subcategory, e.g. 'bodycon mini dress', 'oversized graphic tee'",
+"silhouette_summary": "Short description of silhouette, e.g. 'relaxed tee', 'A-line midi dress', or null",
+"base_fabric_impression": "Woven/Knit/Denim/Satin/Jersey/Sheer/Lace/Leather/Unknown",
+"base_color_main": "Main ground color name, e.g. 'black', 'off-white'",
+"base_color_secondary": [
+"Other ground/solid areas if any, else empty array"
+],
+
+      "print_presence": "none/subtle/medium/dominant",
+
+      "print_overview": {
+        "has_print_or_graphic": true,
+        "primary_print_family": "Floral/Geometric/Stripe/Check/Plaid/Polka/Animal_skin/Camouflage/Abstract/Logo/Monogram/Slogan/Text/Photo/Texture/Other/Unknown",
+        "secondary_print_families": [
+          "Additional families if visible, else []"
+        ],
+        "print_technique_estimate": "Surface_print/Embroidery/Jacquard/Yarn_dyed/Knit_pattern/Applique/Heat_transfer/Unknown",
+        "print_style_tags": [
+          "Hand_drawn/Watercolor/Outline_only/Line_art/Photoreal/Pixelated/Retro_70s/Retro_90s/Y2K/etc"
+        ]
+      },
+
+      "print_placement": [
+        {
+          "zone": "Overall_allover/Front_bodice/Front_chest/Center_front/Front_hem/Back_panel/Back_yoke/Back_only/Sleeves_full/Sleeve_upper/Sleeve_cuff/Collar/Placket/Side_panels/Waistband/Pockets/Hood/Other",
+          "side": "Front/Back/Both/Side/All_around",
+          "coverage_percent_of_zone": 80,
+          "orientation": "Vertical/Horizontal/Diagonal/Radial/Omni_directional/One_way/Engineered_motif",
+          "alignment_with_garment": "Engineered_to_seams/Follows_stripes_or_checks/Random_repeat/Unknown",
+          "notes": "Short note for unusual placement like 'single oversized motif across front chest', or null"
+        }
+      ],
+
+      "motif_atoms": [
+        {
+          "motif_type": "Flower/Leaf/Fruit/Star/Heart/Logo_letter/Word/Number/Animal/Animal_skin/Geo_shape/Stripe/Check/Dot/Swirl/Icon/Character/Other",
+          "motif_description": "1–2 line concise description, e.g. 'small white daisies with yellow centers'",
+          "scale": "micro/small/medium/large/oversized",
+          "density": "very_sparse/sparse/medium/dense/very_dense",
+          "spacing_pattern": "Even/Random/Clustered/Gradient/Border",
+          "edge_treatment": "Outline_only/Filled/Shadowed/3D_effect/Flat",
+          "colorways": "Short description of motif vs ground, e.g. 'navy flowers with white outline on beige ground'"
+        }
+      ],
+
+      "color_story": {
+        "ground_color": "Main background/solid color under the print",
+        "print_colors": [
+          "Key print colors in simple words"
+        ],
+        "contrast_behavior": "Low/Medium/High",
+        "colorblocking_or_panels": "Description if different colored panels/blocks exist, else null"
+      },
+
+      "construction_interaction": {
+        "print_cutoff_or_misalignment": "yes/no/uncertain",
+        "placed_around_features": [
+          "Neckline/Placket/Pockets/Side_seams/Waist/Hem/etc where the print clearly interacts, else []"
+        ],
+        "border_and_trim_details": [
+          "e.g. 'floral border at skirt hem', 'side tape stripe with logo repeat', or []"
+        ]
+      },
+
+      "text_and_logo_details": {
+        "has_text_or_logo": true,
+        "text_samples": [
+          "Exact or approximate words seen, case-sensitive if legible"
+        ],
+        "placement": [
+          "Center_chest/Left_chest/Back_center/Sleeve/Allover/Label_area/etc"
+        ],
+        "style": "Block/Handwriting/Graffiti/College/Retro/Stencil/Minimal/Unknown",
+        "logo_repetition_style": "Single/Scattered_repeat/Allover_monogram/None_or_unknown"
+      },
+
+      "micro_trend_inferences": {
+        "print_micro_trend_tags": [
+          "Normalized tags like 'ditsy_floral', 'large_floral', 'warped_stripes', 'psychedelic_swirl', 'allover_animal_skin', 'photo_real_graphic', 'allover_logo_monogram'"
+        ],
+        "placement_micro_trend_tags": [
+          "e.g. 'engineered_front_motif', 'border_print_at_hem', 'back_only_graphic', 'side_stripe_leg', 'chest_slogan'"
+        ],
+        "color_micro_trend_tags": [
+          "e.g. 'high_contrast_black_neon', 'tonal_neutrals', 'pastel_duo', 'primary_color_triad'"
+        ],
+        "other_detail_micro_trend_tags": [
+          "e.g. 'mixed_scale_florals', 'print_on_sheer', 'print_blocked_sleeves', 'print_yoke_with_solid_body'"
+        ],
+        "overall_trend_feel": "1 sentence, e.g. 'Y2K graphic tee', 'cottagecore ditsy floral midi dress', 'sportswear stripe legging', or null"
+      },
+
+      "confidence": {
+        "overall": "Low/Medium/High",
+        "print_family": "Low/Medium/High",
+        "placement": "Low/Medium/High",
+        "motif_details": "Low/Medium/High",
+        "color_story": "Low/Medium/High"
+      }
+    }
+
+],
+"image_level_micro_trends": {
+"deduplicated_tags": [
+"Set-like union of all micro_trend_inferences tags across garments"
+],
+"summary_comment": "Optional 1–2 line objective summary of the key print/placement micro-trend signals observed, or null"
+}
+}
+CRITICAL CONSTRAINTS
+Granularity:
+Do not say “floral dress” and stop. Break it down into motif atoms, placement zones, scale, density, and normalized tags.
+Null Values:
+If any field is not applicable or not visible, keep the key and set value to null (or an empty array for list fields). Do not drop keys.
+No Prose Outside JSON:
+Your final response for each image must be only the JSON object described above, with double-quoted keys and values suitable for strict JSON parsing. No extra text, no Markdown, no explanations.
+
+1. System prompt (Gem Instructions)
+   Everything that defines the role, objective, schema, and rules for the model lives in the System / Instructions field.
+   Concretely, for the prompt I gave you, the System prompt is:
+   The identity + objective
+   “You are MicroTrendStruct, an advanced Fashion Vision & Micro-Trend Serialization Engine…”
+   The analysis protocol
+   Garment Sweep / Print & Pattern Sweep / Placement Sweep / Micro-Trend Sweep
+   The strict JSON schema description
+   The full meta, global_scene, garments[], motif_atoms[], micro_trend_inferences, etc.
+   The critical constraints
+   Granularity, null values, no prose outside JSON, etc.
+   In practice, you paste all of that into Gemini’s “Instructions” box as the System prompt.
+   You do not paste the image or ask a question there — it’s just behavior + schema + rules.
+   If you want a clean version of what to treat as System, it starts from:
+   “You are MicroTrendStruct, an advanced Fashion Vision & Micro-Trend Serialization Engine…”
+   and goes all the way through the JSON schema and “CRITICAL CONSTRAINTS”.
+2. User prompt (per request / per image)
+   Once the Gem is configured with that System prompt, each time you call it you only need a very small user prompt alongside the image, for example:
+   User prompt (per call):
+   “Here is an image of a garment. Analyze the visible garment(s) and return only the JSON object as specified in your instructions, with all micro-trend fields filled as far as the pixels allow.”
+   Or even shorter, once the Gem is stable:
+   “Analyze this garment image and output the micro-trend JSON per your schema.”
+   Then attach the image.

llm_clients.py

@@ -0,0 +1,148 @@
+"""LLM provider wrappers (OpenAI + Gemini 3) with a unified analyze interface."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+from typing import List, Sequence
+
+from openai import OpenAI
+from google import genai
+from google.genai import types as genai_types
+from google.genai import errors as genai_errors
+
+from settings import Settings
+
+LOGGER = logging.getLogger("llm")
+
+# Model identifiers exposed to the UI
+OPENAI_GPT5 = "gpt-5"
+OPENAI_GPT5_MINI = "gpt-5-mini"
+# Gemini 3 multimodal text-out model (supports image+text input, text output)
+GEMINI_3_VISION = "gemini-3-pro-preview"
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+def _encode_image_to_data_url(image_bytes: bytes, mime: str = "image/png") -> str:
+    b64 = base64.b64encode(image_bytes).decode("utf-8")
+    return f"data:{mime};base64,{b64}"
+
+
+def _collect_openai_messages(system_prompt: str, user_prompt: str, images: Sequence[bytes]):
+    system = {"role": "system", "content": [{"type": "input_text", "text": system_prompt}]}
+    user_content = [{"type": "input_text", "text": user_prompt}]
+    for img in images:
+        user_content.append({"type": "input_image", "image_url": _encode_image_to_data_url(img)})
+    user = {"role": "user", "content": user_content}
+    return [system, user]
+
+
+def run_openai(
+    images: Sequence[bytes],
+    system_prompt: str,
+    user_prompt: str,
+    model: str,
+    settings: Settings,
+) -> str:
+    if not settings.openai_api_key:
+        raise LLMError("OPENAI_API_KEY is missing")
+
+    client = OpenAI(api_key=settings.openai_api_key)
+    messages = _collect_openai_messages(system_prompt, user_prompt, images)
+
+    kwargs = {}
+    if settings.openai_reasoning_effort:
+        kwargs["reasoning"] = {"effort": settings.openai_reasoning_effort}
+
+    LOGGER.info(
+        "Calling OpenAI model=%s reasoning=%s images=%s total_bytes=%s",
+        model,
+        settings.openai_reasoning_effort,
+        len(images),
+        sum(len(i) for i in images),
+    )
+    resp = client.responses.create(model=model, input=messages, **kwargs)
+    text = getattr(resp, "output_text", None) or str(resp)
+    LOGGER.info("OpenAI response (truncated 500 chars): %s", text[:500])
+    return text
+
+
+def run_gemini(
+    images: Sequence[bytes],
+    system_prompt: str,
+    user_prompt: str,
+    model: str,
+    settings: Settings,
+) -> str:
+    # Two modes:
+    # - Vertex (preferred when GOOGLE_GENAI_USE_VERTEXAI=True): uses ADC / gcloud auth
+    # - API key (Studio): uses GEMINI_API_KEY
+    if settings.google_genai_use_vertexai:
+        client = genai.Client(
+            vertexai=True,
+            project=settings.google_cloud_project,
+            location=settings.google_cloud_location or "us-central1",
+        )
+    else:
+        if not settings.gemini_api_key:
+            raise LLMError("GEMINI_API_KEY is missing and vertex mode is disabled")
+        client = genai.Client(api_key=settings.gemini_api_key)
+
+    parts: List[genai_types.Part | str] = [system_prompt]
+    for img in images:
+        parts.append(genai_types.Part.from_bytes(data=img, mime_type="image/png"))
+    parts.append(user_prompt)
+
+    LOGGER.info(
+        "Calling Gemini model=%s vertex=%s images=%s total_bytes=%s",
+        model,
+        settings.google_genai_use_vertexai,
+        len(images),
+        sum(len(i) for i in images),
+    )
+    try:
+        response = client.models.generate_content(
+            model=model,
+            contents=parts,
+            config=genai_types.GenerateContentConfig(response_modalities=["text"]),
+        )
+    except genai_errors.ClientError as exc:
+        # Provide clearer guidance for common auth/model issues.
+        raise LLMError(
+            "Gemini request failed. "
+            "If using Vertex, ensure the model exists in your project/location and ADC is active (`gcloud auth application-default login`). "
+            "If using Studio/API key (e.g., on HuggingFace), set GOOGLE_GENAI_USE_VERTEXAI=false and provide GEMINI_API_KEY. "
+            f"Details: {exc}"
+        ) from exc
+
+    # Prefer `.text`; fallback to concatenated text parts
+    if getattr(response, "text", None):
+        text = response.text
+    if getattr(response, "parts", None):
+        text_parts = [p.text for p in response.parts if getattr(p, "text", None)]
+        if text_parts:
+            text = "\n".join(text_parts)
+    if "text" not in locals():
+        text = str(response)
+
+    LOGGER.info("Gemini response (truncated 500 chars): %s", text[:500])
+    return text
+
+
+def analyze(
+    images: Sequence[bytes],
+    system_prompt: str,
+    user_prompt: str,
+    model_choice: str,
+    settings: Settings,
+) -> str:
+    """Dispatch to the correct provider based on model_choice."""
+    if model_choice in {OPENAI_GPT5, OPENAI_GPT5_MINI}:
+        return run_openai(images, system_prompt, user_prompt, model_choice, settings)
+    if model_choice.startswith("gemini"):
+        return run_gemini(images, system_prompt, user_prompt, model_choice, settings)
+    raise LLMError(f"Unsupported model choice: {model_choice}")

pipeline.py

@@ -0,0 +1,48 @@
+"""Inference pipeline: images -> LLM -> validated JSON -> summary."""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Sequence
+
+from llm_clients import analyze
+from prompt_loader import load_system_prompt
+from schemas import ValidationError, build_summary, validate_trend_payload
+from settings import Settings
+
+LOGGER = logging.getLogger("pipeline")
+
+DEFAULT_USER_PROMPT = "Analyze this garment image and output the micro-trend JSON per your schema."
+
+
+def _extract_json(text: str) -> Dict[str, Any]:
+    """Parse JSON; if raw text contains extra prose, grab the first JSON object."""
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        pass
+
+    match = re.search(r"\{.*\}", text, flags=re.S)
+    if not match:
+        raise json.JSONDecodeError("No JSON object found", text, 0)
+    return json.loads(match.group(0))
+
+
+def process_images(
+    images: Sequence[bytes],
+    model_choice: str,
+    settings: Settings,
+    system_prompt_path: Path | str | None = None,
+    user_prompt: str = DEFAULT_USER_PROMPT,
+) -> Dict[str, Any]:
+    system_prompt = load_system_prompt(system_prompt_path) if system_prompt_path else load_system_prompt()
+
+    raw_text = analyze(images, system_prompt, user_prompt, model_choice, settings)
+    payload = _extract_json(raw_text)
+    validated = validate_trend_payload(payload)
+    summary = build_summary(validated)
+
+    return {"trends": validated, "summary": summary}

prompt_loader.py

@@ -0,0 +1,14 @@
+"""Utilities to load the system prompt from the prompts directory."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+DEFAULT_PROMPT_PATH = Path("prompts/micro-trend-prompt.md")
+
+
+def load_system_prompt(path: Path | str = DEFAULT_PROMPT_PATH) -> str:
+    prompt_path = Path(path)
+    if not prompt_path.exists():
+        raise FileNotFoundError(f"Prompt file not found at {prompt_path}")
+    return prompt_path.read_text(encoding="utf-8")

prompts/micro-trend-prompt.md

@@ -0,0 +1,194 @@
+Name: Garment-MicroTrend-JSON
+Description: Converts garment images into structured JSON capturing print/placement micro-trends.
+Instructions (System Prompt):
+You are MicroTrendStruct, an advanced Fashion Vision & Micro-Trend Serialization Engine. Your sole purpose is to ingest visual input (garment images) and transcode every discernible print, pattern, and placement detail into a rigorous, machine-readable JSON format suitable for micro-trend analysis.
+ROLE & OBJECTIVE
+Your focus is garments, not generic scenes.
+Your primary objective is to:
+Detect whether the garment has any print/pattern/graphic/texture beyond a flat solid.
+Describe the type of print, motifs, scale, density, layout, and print technique (if inferable).
+Describe where the print lives on the garment (placement zones, coverage, orientation, engineered vs all-over).
+Normalize these details into micro-trend tags that can be aggregated across large datasets.
+You are not describing art; you are building a fashion trend database row from pixels.
+CORE DIRECTIVE
+Do not summarize in prose outside the JSON schema.
+Do not offer high-level commentary unless it is in the dedicated fields for micro-trend tags or short “feel” strings.
+If a detail exists in pixels and is relevant to print, pattern, color story, or placement, it should appear somewhere in your JSON.
+If something is not visible or genuinely ambiguous, keep the field but set the value to null and lower confidence for that field. Do not silently omit fields.
+ANALYSIS PROTOCOL (SILENT)
+Before generating JSON, perform a silent multi-pass visual sweep (do not output this):
+Garment Sweep
+Count visible garments. Identify primary garment(s).
+Determine approximate category (dress, shirt, tee, blouse, skirt, jeans, trouser, co-ord top, co-ord bottom, jacket, etc.).
+Note view type (front, back, side, 3/4, flatlay, detail shot, runway/street on model).
+Print & Pattern Sweep
+Detect whether the garment is solid, textured, or printed.
+If printed/graphic, identify print families (floral, geometric, stripe, check, polka, animal, abstract, logo, slogan, photo, etc.).
+Check for multiple print layers (e.g., ditsy floral over a stripe, border prints, panel prints).
+Placement Sweep
+Map where prints appear: overall/all-over vs specific zones (chest, hem, sleeves, collar, yoke, side panels, back only, etc.).
+Estimate coverage percentage in each zone and whether the print is engineered/placed or repeated all-over.
+Micro-Trend Sweep
+Translate observable features into normalized micro-trend tags: e.g. ditsy_floral, oversized_floral, border_print_at_hem, front_chest_slogan, allover_logo, psychedelic_swirl, warped_stripes, photo_real_graphic, tonal_neutral_print, neon_accent_on_black, etc.
+OUTPUT FORMAT (STRICT)
+You must return ONLY a single valid JSON object.
+Do not include markdown fences (no ```json).
+Do not include any conversational text before or after the JSON.
+Use this schema (and expand arrays as needed):
+{
+"meta": {
+"image_quality": "Low/Medium/High",
+"image_type": "Photo/Illustration/Flatlay/Runway/Street/etc",
+"view_type": "Front/Back/Side/3_4/Flatlay/Detail/Full_body_on_model",
+"num_visible_garments": 1
+},
+"global_scene": {
+"setting": "Studio_white_bg/Studio_colored_bg/Street/Runway/Store/etc",
+"model_present": true,
+"occlusions_or_crops": "Brief note about parts of the garment that are cut off, hidden or overlapped, or null if none"
+},
+"garments": [
+{
+"id": "garment_001",
+"role": "primary/secondary/background",
+"category": "Dress/Top/Tee/Shirt/Blouse/Skirt/Jeans/Trouser/Jacket/Co_ord_top/Co_ord_bottom/Other",
+"sub_category": "Free-text subcategory, e.g. 'bodycon mini dress', 'oversized graphic tee'",
+"silhouette_summary": "Short description of silhouette, e.g. 'relaxed tee', 'A-line midi dress', or null",
+"base_fabric_impression": "Woven/Knit/Denim/Satin/Jersey/Sheer/Lace/Leather/Unknown",
+"base_color_main": "Main ground color name, e.g. 'black', 'off-white'",
+"base_color_secondary": [
+"Other ground/solid areas if any, else empty array"
+],
+
+      "print_presence": "none/subtle/medium/dominant",
+
+      "print_overview": {
+        "has_print_or_graphic": true,
+        "primary_print_family": "Floral/Geometric/Stripe/Check/Plaid/Polka/Animal_skin/Camouflage/Abstract/Logo/Monogram/Slogan/Text/Photo/Texture/Other/Unknown",
+        "secondary_print_families": [
+          "Additional families if visible, else []"
+        ],
+        "print_technique_estimate": "Surface_print/Embroidery/Jacquard/Yarn_dyed/Knit_pattern/Applique/Heat_transfer/Unknown",
+        "print_style_tags": [
+          "Hand_drawn/Watercolor/Outline_only/Line_art/Photoreal/Pixelated/Retro_70s/Retro_90s/Y2K/etc"
+        ]
+      },
+
+      "print_placement": [
+        {
+          "zone": "Overall_allover/Front_bodice/Front_chest/Center_front/Front_hem/Back_panel/Back_yoke/Back_only/Sleeves_full/Sleeve_upper/Sleeve_cuff/Collar/Placket/Side_panels/Waistband/Pockets/Hood/Other",
+          "side": "Front/Back/Both/Side/All_around",
+          "coverage_percent_of_zone": 80,
+          "orientation": "Vertical/Horizontal/Diagonal/Radial/Omni_directional/One_way/Engineered_motif",
+          "alignment_with_garment": "Engineered_to_seams/Follows_stripes_or_checks/Random_repeat/Unknown",
+          "notes": "Short note for unusual placement like 'single oversized motif across front chest', or null"
+        }
+      ],
+
+      "motif_atoms": [
+        {
+          "motif_type": "Flower/Leaf/Fruit/Star/Heart/Logo_letter/Word/Number/Animal/Animal_skin/Geo_shape/Stripe/Check/Dot/Swirl/Icon/Character/Other",
+          "motif_description": "1–2 line concise description, e.g. 'small white daisies with yellow centers'",
+          "scale": "micro/small/medium/large/oversized",
+          "density": "very_sparse/sparse/medium/dense/very_dense",
+          "spacing_pattern": "Even/Random/Clustered/Gradient/Border",
+          "edge_treatment": "Outline_only/Filled/Shadowed/3D_effect/Flat",
+          "colorways": "Short description of motif vs ground, e.g. 'navy flowers with white outline on beige ground'"
+        }
+      ],
+
+      "color_story": {
+        "ground_color": "Main background/solid color under the print",
+        "print_colors": [
+          "Key print colors in simple words"
+        ],
+        "contrast_behavior": "Low/Medium/High",
+        "colorblocking_or_panels": "Description if different colored panels/blocks exist, else null"
+      },
+
+      "construction_interaction": {
+        "print_cutoff_or_misalignment": "yes/no/uncertain",
+        "placed_around_features": [
+          "Neckline/Placket/Pockets/Side_seams/Waist/Hem/etc where the print clearly interacts, else []"
+        ],
+        "border_and_trim_details": [
+          "e.g. 'floral border at skirt hem', 'side tape stripe with logo repeat', or []"
+        ]
+      },
+
+      "text_and_logo_details": {
+        "has_text_or_logo": true,
+        "text_samples": [
+          "Exact or approximate words seen, case-sensitive if legible"
+        ],
+        "placement": [
+          "Center_chest/Left_chest/Back_center/Sleeve/Allover/Label_area/etc"
+        ],
+        "style": "Block/Handwriting/Graffiti/College/Retro/Stencil/Minimal/Unknown",
+        "logo_repetition_style": "Single/Scattered_repeat/Allover_monogram/None_or_unknown"
+      },
+
+      "micro_trend_inferences": {
+        "print_micro_trend_tags": [
+          "Normalized tags like 'ditsy_floral', 'large_floral', 'warped_stripes', 'psychedelic_swirl', 'allover_animal_skin', 'photo_real_graphic', 'allover_logo_monogram'"
+        ],
+        "placement_micro_trend_tags": [
+          "e.g. 'engineered_front_motif', 'border_print_at_hem', 'back_only_graphic', 'side_stripe_leg', 'chest_slogan'"
+        ],
+        "color_micro_trend_tags": [
+          "e.g. 'high_contrast_black_neon', 'tonal_neutrals', 'pastel_duo', 'primary_color_triad'"
+        ],
+        "other_detail_micro_trend_tags": [
+          "e.g. 'mixed_scale_florals', 'print_on_sheer', 'print_blocked_sleeves', 'print_yoke_with_solid_body'"
+        ],
+        "overall_trend_feel": "1 sentence, e.g. 'Y2K graphic tee', 'cottagecore ditsy floral midi dress', 'sportswear stripe legging', or null"
+      },
+
+      "confidence": {
+        "overall": "Low/Medium/High",
+        "print_family": "Low/Medium/High",
+        "placement": "Low/Medium/High",
+        "motif_details": "Low/Medium/High",
+        "color_story": "Low/Medium/High"
+      }
+    }
+
+],
+"image_level_micro_trends": {
+"deduplicated_tags": [
+"Set-like union of all micro_trend_inferences tags across garments"
+],
+"summary_comment": "Optional 1–2 line objective summary of the key print/placement micro-trend signals observed, or null"
+}
+}
+CRITICAL CONSTRAINTS
+Granularity:
+Do not say “floral dress” and stop. Break it down into motif atoms, placement zones, scale, density, and normalized tags.
+Null Values:
+If any field is not applicable or not visible, keep the key and set value to null (or an empty array for list fields). Do not drop keys.
+No Prose Outside JSON:
+Your final response for each image must be only the JSON object described above, with double-quoted keys and values suitable for strict JSON parsing. No extra text, no Markdown, no explanations.
+
+1. System prompt (Gem Instructions)
+   Everything that defines the role, objective, schema, and rules for the model lives in the System / Instructions field.
+   Concretely, for the prompt I gave you, the System prompt is:
+   The identity + objective
+   “You are MicroTrendStruct, an advanced Fashion Vision & Micro-Trend Serialization Engine…”
+   The analysis protocol
+   Garment Sweep / Print & Pattern Sweep / Placement Sweep / Micro-Trend Sweep
+   The strict JSON schema description
+   The full meta, global_scene, garments[], motif_atoms[], micro_trend_inferences, etc.
+   The critical constraints
+   Granularity, null values, no prose outside JSON, etc.
+   In practice, you paste all of that into Gemini’s “Instructions” box as the System prompt.
+   You do not paste the image or ask a question there — it’s just behavior + schema + rules.
+   If you want a clean version of what to treat as System, it starts from:
+   “You are MicroTrendStruct, an advanced Fashion Vision & Micro-Trend Serialization Engine…”
+   and goes all the way through the JSON schema and “CRITICAL CONSTRAINTS”.
+2. User prompt (per request / per image)
+   Once the Gem is configured with that System prompt, each time you call it you only need a very small user prompt alongside the image, for example:
+   User prompt (per call):
+   “Here is an image of a garment. Analyze the visible garment(s) and return only the JSON object as specified in your instructions, with all micro-trend fields filled as far as the pixels allow.”
+   Or even shorter, once the Gem is stable:
+   “Analyze this garment image and output the micro-trend JSON per your schema.”
+   Then attach the image.

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=4.44.0
+openai>=1.45.0
+google-genai>=0.4.0
+pillow>=10.3.0

sample_code/generate_images.py

@@ -0,0 +1,679 @@
+from __future__ import annotations
+
+import re
+import json
+import logging
+import mimetypes
+from datetime import datetime
+import shutil
+from pathlib import Path
+from typing import List, Dict, Any
+
+import os
+
+from google import genai
+from google.genai import types, errors as genai_errors
+
+from constants import (
+    ROOT,
+    PLAN_PATH,
+    DEFAULT_SETTINGS,
+    GEMINI_SETTINGS_KEYS,
+    LOG_NAME,
+    STYLE_VIEW_ORDER,
+)
+
+
+class PromptTask(Dict[str, Any]):
+    """Typed mapping representing a single prompt item (slide, filename, prompt, order)."""
+    slide: str
+    filename: str
+    prompt: str
+    order: int
+
+
+def slugify(text: str) -> str:
+    """Convert a slide label to a filesystem-friendly slug."""
+    text = text.lower()
+    text = re.sub(r"[^a-z0-9]+", "-", text)
+    text = text.strip("-")
+    return text or "slide"
+
+
+def output_root(brand: str, collection: str) -> Path:
+    """Base directory for images under outputs/<brand>/collection/<collection>/images."""
+    return ROOT / "outputs" / slugify(brand) / "collection" / slugify(collection) / "images"
+
+
+def parse_plan(plan_path: Path) -> List[PromptTask]:
+    """Pull every FILENAME/PROMPT pair from plan.md, keeping slide context."""
+    lines = plan_path.read_text(encoding="utf-8").splitlines()
+    tasks: List[PromptTask] = []
+    current_slide = "slide"
+    order = 0
+    i = 0
+    while i < len(lines):
+        line = lines[i].strip()
+
+        # Capture slide headers (e.g., "Slide 6", "Slide 6A", "Slides 8–19")
+        slide_match = re.match(r"slide[s]?\s+([\w–-]+)", line, re.IGNORECASE)
+        if slide_match:
+            current_slide = line
+            i += 1
+            continue
+
+        file_match = re.match(r"FILENAME:\s*(.+)", line, re.IGNORECASE)
+        if file_match:
+            filename = file_match.group(1).strip()
+
+            # Advance to the PROMPT line
+            j = i + 1
+            while j < len(lines) and not lines[j].strip().lower().startswith("prompt:"):
+                j += 1
+            if j >= len(lines):
+                raise ValueError(f"PROMPT missing for {filename}")
+
+            prompt_line = lines[j].strip()
+            prompt = prompt_line.split("PROMPT:", 1)[1].strip()
+
+            # Capture any prompt continuation lines until the next FILENAME/Slide header
+            k = j + 1
+            continuation: List[str] = []
+            while k < len(lines):
+                next_line = lines[k].strip()
+                if next_line == "":
+                    k += 1
+                    continue
+                if re.match(r"(FILENAME:|Slide[s]?\s+|< Text Content)", next_line, re.IGNORECASE):
+                    break
+                continuation.append(next_line)
+                k += 1
+
+            if continuation:
+                prompt = " ".join([prompt] + continuation)
+
+            tasks.append(
+                {
+                    "slide": current_slide,
+                    "filename": filename,
+                    "prompt": prompt,
+                    "order": order,
+                }
+            )
+            order += 1
+            i = k
+            continue
+
+        i += 1
+
+    return tasks
+
+
+def setup_logging(out_root: Path, mode: str, level: str = "INFO", log_path: Path | None = None) -> logging.Logger:
+    """Configure stdout + file logging; file goes under outputs/<brand>/collection/<collection>/images/<mode>/run.log."""
+    out_dir = out_root / mode
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    log_file = log_path or out_dir / "run.log"
+    numeric_level = getattr(logging, level.upper(), logging.INFO)
+
+    formatter = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
+
+    handlers: list[logging.Handler] = [logging.StreamHandler()]
+    handlers[0].setFormatter(formatter)
+    file_handler = logging.FileHandler(log_file, encoding="utf-8")
+    file_handler.setFormatter(formatter)
+    handlers.append(file_handler)
+
+    logging.basicConfig(level=numeric_level, handlers=handlers, force=True)
+    logger = logging.getLogger(LOG_NAME)
+    logger.setLevel(numeric_level)
+    logger.info("Logging initialized (mode=%s, file=%s, level=%s)", mode, log_file, level.upper())
+    return logger
+
+
+def clean_output_dir(out_root: Path, mode: str, logger: logging.Logger | None = None) -> None:
+    """Remove all files under the given mode folder to start from a clean slate."""
+    target = out_root / mode
+    if target.exists():
+        if logger:
+            logger.info("Cleaning output directory %s", target)
+        shutil.rmtree(target)
+
+
+def anchor_part(prompt: str, logger: logging.Logger) -> tuple[None, None]:
+    """Anchor images via folder are removed; function retained for signature compatibility."""
+    return None, None
+
+
+def part_from_path(path: Path) -> types.Part:
+    """Load an image file as a genai Part with an inferred MIME type."""
+    mime, _ = mimetypes.guess_type(path)
+    if not mime:
+        mime = "image/jpeg"
+    data = path.read_bytes()
+    return types.Part.from_bytes(data=data, mime_type=mime)
+
+
+def detect_style_view(filename: str) -> tuple[str, str] | None:
+    """Return (style_code, view) for style view images; else None."""
+    m = re.match(r"^(MG-[A-Z]-SS\d{2}-\d{3})_(hero|front|back)\.", filename, re.IGNORECASE)
+    if not m:
+        return None
+    style_code, view = m.group(1), m.group(2).lower()
+    return style_code, view
+
+
+def reorder_tasks_for_styles(tasks: List[PromptTask]) -> List[PromptTask]:
+    """Group style views and order front->back->hero; keep non-style in original positions."""
+    style_map: dict[str, list[PromptTask]] = {}
+    for t in tasks:
+        sv = detect_style_view(t["filename"])
+        if sv:
+            code, view = sv
+            style_map.setdefault(code, []).append(t | {"_style_view": view})
+    final: list[PromptTask] = []
+    processed: set[str] = set()
+
+    for t in tasks:
+        sv = detect_style_view(t["filename"])
+        if not sv:
+            final.append(t)
+            continue
+
+        code, _ = sv
+        if code in processed:
+            continue
+        processed.add(code)
+        grouped = style_map.get(code, [])
+        grouped.sort(key=lambda x: (STYLE_VIEW_ORDER.get(x.get("_style_view", "other"), 99), x["order"]))
+        # remove helper key before returning
+        for g in grouped:
+            g.pop("_style_view", None)
+            final.append(g)
+
+    return final
+
+
+def load_settings(settings_path: Path | None) -> dict[str, str]:
+    """Load settings JSON (if present) limited to known keys."""
+    path = settings_path or DEFAULT_SETTINGS
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+        return {k: v for k, v in data.items() if k in GEMINI_SETTINGS_KEYS and v}
+    except json.JSONDecodeError as exc:  # noqa: BLE001
+        raise SystemExit(f"settings file {path} is not valid JSON: {exc}")
+
+
+def resolve_api_key(settings: dict[str, str]) -> str:
+    """Get API key from env first, then settings file; env wins."""
+    if os.environ.get("GEMINI_API_KEY"):
+        return os.environ["GEMINI_API_KEY"]
+    if os.environ.get("GOOGLE_API_KEY"):
+        return os.environ["GOOGLE_API_KEY"]
+
+    key = settings.get("GEMINI_API_KEY") or settings.get("GOOGLE_API_KEY")
+    if key:
+        return key
+
+    raise SystemExit(
+        "GEMINI_API_KEY/GOOGLE_API_KEY is not set. Set the env var or create settings.json (see settings.example.json)."
+    )
+
+
+def generate_images(
+    tasks: List[PromptTask],
+    mode: str,
+    limit: int | None,
+    api_key: str,
+    logger: logging.Logger,
+    out_root: Path,
+    timestamp: str,
+) -> None:
+    """Generate images for the provided tasks list and write a manifest."""
+    client = genai.Client(api_key=api_key)
+
+    to_run = tasks if mode == "full" else tasks[: limit or 2]
+    logger.info("Starting generation: %s tasks (mode=%s)", len(to_run), mode)
+
+    style_state: dict[str, dict[str, Path]] = {}
+    manifest = []
+    for task in to_run:
+        slide_slug = slugify(task["slide"])
+        out_dir = out_root / mode / slide_slug
+        out_dir.mkdir(parents=True, exist_ok=True)
+        out_path = out_dir / task["filename"]
+
+        logger.info("Generating %s (slide: %s)", task["filename"], task["slide"])
+
+        style_view = detect_style_view(task["filename"])
+        anchor, anchor_code = anchor_part(task["prompt"], logger)
+        anchor_used = None
+
+        contents: list[types.Part | str] = []
+
+        if style_view:
+            style_code, view = style_view
+            state = style_state.get(style_code, {})
+            preferred_path: Path | None = None
+            if view == "hero":
+                preferred_path = None  # first in chain, prompt-only
+            elif view == "front":
+                preferred_path = state.get("hero")
+                anchor_used = "hero" if preferred_path else None
+            elif view == "back":
+                preferred_path = state.get("front") or state.get("hero")
+                anchor_used = "front" if state.get("front") else ("hero" if state.get("hero") else None)
+
+            if preferred_path and preferred_path.exists():
+                try:
+                    contents.append(part_from_path(preferred_path))
+                    anchor_used = anchor_used or "previous"
+                except Exception as exc:  # noqa: BLE001
+                    logger.exception("Failed to load prior view %s as anchor: %s", preferred_path, exc)
+
+        if not contents and anchor:
+            contents.append(anchor)
+            anchor_used = anchor_used or (f"face:{anchor_code}" if anchor_code else "face")
+
+        contents.append(task["prompt"])
+
+        try:
+            response = client.models.generate_content(
+                model="gemini-2.5-flash-image",
+                contents=contents,
+                config=types.GenerateContentConfig(
+                    response_modalities=["image"],
+                ),
+            )
+        except genai_errors.ClientError as exc:  # noqa: BLE001
+            if exc.status_code == 401:
+                logger.error(
+                    "401 Unauthorized. This usually means the key is missing, the wrong key type (use Google AI Studio key), or Vertex mode requires OAuth."
+                )
+            logger.exception("Generation failed for %s: %s", task["filename"], exc)
+            continue
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Generation failed for %s: %s", task["filename"], exc)
+            continue
+
+        parts = getattr(response, "parts", None)
+        if not parts:
+            logger.warning("Response had no parts for %s; skipping", task["filename"])
+            continue
+        image_part = next((p for p in parts if getattr(p, "inline_data", None)), None)
+        if not image_part:
+            logger.warning("No image part returned for %s; skipping", task["filename"])
+            continue
+
+        try:
+            image = image_part.as_image()
+            image.save(out_path)
+            logger.info("Saved %s", out_path)
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("Failed to save %s: %s", out_path, exc)
+            continue
+
+        if style_view:
+            style_code, view = style_view
+            style_state.setdefault(style_code, {})[view] = out_path
+
+        manifest.append(
+            {
+                "slide": task["slide"],
+                "filename": task["filename"],
+                "prompt": task["prompt"],
+                "path": str(out_path.relative_to(ROOT)),
+                "anchor": anchor_used,
+                "anchor_face": anchor_code,
+            }
+        )
+
+    if manifest:
+        manifest_path = out_root / mode / f"manifest_{timestamp}.json"
+        manifest_path.write_text(json.dumps(manifest, indent=2), encoding="utf-8")
+        logger.info("Manifest written to %s", manifest_path)
+    else:
+        logger.warning("No images were generated; manifest not written")
+
+
+def run_generation(
+    mode: str = "full",
+    limit: int | None = None,
+    settings_path: Path | None = None,
+    brand: str = "mango",
+    collection: str = "hot-summer-ss26",
+    log_level: str = "INFO",
+    clean: bool = False,
+) -> None:
+    """Programmatic entrypoint to parse plan.md and generate Gemini images."""
+    tasks = parse_plan(PLAN_PATH)
+    tasks = reorder_tasks_for_styles(tasks)
+    if not tasks:
+        raise SystemExit("No prompts found in plan.md")
+
+    if mode == "sample" and limit is not None and limit <= 0:
+        raise SystemExit("limit must be positive for sample mode")
+
+    out_root = output_root(brand, collection)
+
+    if clean:
+        clean_output_dir(out_root, mode)
+
+    timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+
+    logger = setup_logging(out_root, mode, log_level)
+    settings = load_settings(settings_path)
+
+    if "GOOGLE_GENAI_USE_VERTEXAI" in settings and "GOOGLE_GENAI_USE_VERTEXAI" not in os.environ:
+        os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = str(settings["GOOGLE_GENAI_USE_VERTEXAI"]).lower()
+
+    api_key = resolve_api_key(settings)
+
+    prompts_dir = ROOT / "outputs" / slugify(brand) / "collection" / slugify(collection) / "prompts"
+    prompts_dir.mkdir(parents=True, exist_ok=True)
+    prompts_path = prompts_dir / f"images_prompts_{timestamp}.json"
+    prompts_payload = [{"slide": t["slide"], "filename": t["filename"], "prompt": t["prompt"], "order": t["order"]} for t in tasks]
+    prompts_path.write_text(json.dumps(prompts_payload, indent=2), encoding="utf-8")
+    logger.info("Prompts saved to %s", prompts_path)
+
+    generate_images(tasks, mode, limit, api_key, logger, out_root, timestamp)
+
+
+# ---------------- Reusable runner for external callers ---------------- #
+
+def run_prompt_list(
+    prompt_items: List[Dict[str, Any]],
+    brand: str,
+    collection: str,
+    mode: str,
+    api_key: str | None,
+    logger: logging.Logger,
+) -> List[Dict[str, Any]]:
+    """
+    Run a list of prompts (each dict: prompt, filename) through Gemini and save to images/<mode>.
+    Returns manifest entries.
+    Includes simple anchoring for style views (hero -> front -> back) using previously
+    generated images for the same style code.
+    """
+    out_root = output_root(brand, collection) / mode
+    out_root.mkdir(parents=True, exist_ok=True)
+    # Auth resolution: prefer explicit api_key, else settings.json (no env reliance)
+    settings_path = ROOT / "settings.json"
+    settings = {}
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        except Exception:
+            settings = {}
+
+    use_vertex = str(settings.get("GOOGLE_GENAI_USE_VERTEXAI", "")).lower() == "true"
+
+    if not api_key:
+        api_key = settings.get("GEMINI_API_KEY") or settings.get("GOOGLE_API_KEY")
+
+    project = (
+        settings.get("GOOGLE_VERTEX_PROJECT")
+        or settings.get("GOOGLE_CLOUD_PROJECT")
+        or settings.get("GCLOUD_PROJECT")
+    )
+    location = settings.get("GOOGLE_VERTEX_LOCATION") or settings.get("GOOGLE_CLOUD_LOCATION") or "us-central1"
+
+    logger.info(
+        "[gemini] auth resolution: api_key=%s use_vertex=%s project=%s location=%s",
+        "yes" if api_key else "no",
+        use_vertex,
+        project or "none",
+        location,
+    )
+
+    if use_vertex:
+        if not project:
+            raise SystemExit(
+                "Gemini Vertex auth missing project. Set GOOGLE_VERTEX_PROJECT or GOOGLE_CLOUD_PROJECT in settings.json."
+            )
+        client = genai.Client(vertexai={"project": project, "location": location})
+        logger.info("[gemini] using Vertex ADC project=%s location=%s", project, location)
+    elif api_key:
+        client = genai.Client(api_key=api_key)
+        logger.info("[gemini] using API key auth")
+    else:
+        raise SystemExit(
+            "Gemini auth missing: set GEMINI_API_KEY/GOOGLE_API_KEY in settings.json or set GOOGLE_GENAI_USE_VERTEXAI=true with GOOGLE_CLOUD_PROJECT in settings.json"
+        )
+    manifest = []
+    style_state: dict[str, dict[str, Path]] = {}
+    for item in prompt_items:
+        prompt = item["prompt"]
+        filename = item.get("filename") or f"prompt_{len(manifest)+1}.png"
+        slide_slug = slugify(item.get("slide", "adhoc"))
+        if item.get("out_path"):
+            out_path = (ROOT / item["out_path"]).resolve() if not Path(item["out_path"]).is_absolute() else Path(item["out_path"])
+            out_path.parent.mkdir(parents=True, exist_ok=True)
+        else:
+            out_dir = out_root / slide_slug
+            out_dir.mkdir(parents=True, exist_ok=True)
+            out_path = out_dir / filename
+        logger.info("[run_prompt_list] %s -> %s", filename, out_path)
+        contents: list[types.Part | str] = []
+
+        # Style chaining: if filename matches style view, attach prior image
+        anchor_used = None
+        style_view = detect_style_view(filename)
+        if style_view:
+            code, view = style_view
+            state = style_state.get(code, {})
+            preferred_path: Path | None = None
+            if view == "hero":
+                preferred_path = None
+            elif view == "front":
+                preferred_path = state.get("hero")
+                anchor_used = "hero" if preferred_path else None
+            elif view == "back":
+                preferred_path = state.get("front") or state.get("hero")
+                anchor_used = "front" if state.get("front") else ("hero" if state.get("hero") else None)
+
+            if preferred_path and preferred_path.exists():
+                try:
+                    contents.append(part_from_path(preferred_path))
+                    anchor_used = anchor_used or "previous"
+                except Exception as exc:  # noqa: BLE001
+                    logger.exception("Failed to load prior view %s as anchor: %s", preferred_path, exc)
+
+        contents.append(prompt)
+        try:
+            resp = client.models.generate_content(
+                model="gemini-2.5-flash-image",
+                contents=contents,
+                config=types.GenerateContentConfig(response_modalities=["image"]),
+            )
+            image_part = None
+            if hasattr(resp, "parts") and resp.parts:
+                image_part = next((p for p in resp.parts if getattr(p, "inline_data", None)), None)
+            if not image_part and hasattr(resp, "candidates"):
+                for cand in resp.candidates or []:
+                    content = getattr(cand, "content", None)
+                    parts = getattr(content, "parts", []) if content else []
+                    for part in parts or []:
+                        if getattr(part, "inline_data", None):
+                            image_part = part
+                            break
+                    if image_part:
+                        break
+            if not image_part:
+                logger.warning("[run_prompt_list] no image returned for %s", filename)
+                manifest.append({"filename": filename, "status": "no_image"})
+                continue
+            image = image_part.as_image()
+            image.save(out_path)
+            manifest.append({"filename": filename, "status": "ok", "path": str(out_path.relative_to(ROOT)), "anchor": anchor_used})
+            if style_view:
+                code, view = style_view
+                style_state.setdefault(code, {})[view] = out_path
+        except Exception as exc:  # noqa: BLE001
+            logger.exception("[run_prompt_list] failed for %s: %s", filename, exc)
+            manifest.append({"filename": filename, "status": f"error:{exc}"})
+    return manifest
+
+
+def run_prompt_list_vertex_chain(
+    prompt_items: List[Dict[str, Any]],
+    brand: str,
+    collection: str,
+    mode: str,
+    logger: logging.Logger,
+    temp: float = 1.0,
+    top_p: float = 0.95,
+) -> List[Dict[str, Any]]:
+    """
+    Multi-turn Vertex image chain per style (hero → front → back) with image feedback.
+
+    End-to-end flow:
+    1) Group prompts by style/slide so each style runs as one mini-session.
+    2) HERO: call Gemini Vertex with the hero prompt (no anchors). Save the returned image.
+    3) FRONT: send the original hero prompt as a user turn, the hero image as a *model* turn,
+       then the front prompt as a user turn. Generate and save the front image.
+    4) BACK: send hero prompt + hero image (model turn) + front prompt + front image (model turn),
+       then the back prompt. Generate and save the back image.
+    5) Persist outputs under `outputs/<brand>/collection/<collection>/images/<mode>/...`
+       and record a manifest entry per view.
+
+    Notes:
+    - Uses Vertex client with explicit safety + image config (1:1, 1K) and temperature/top_p controls.
+    - If any of the three views fail, the function logs an error for that view and continues to the next style.
+    """
+    from collections import defaultdict
+
+    out_root = output_root(brand, collection) / mode
+    out_root.mkdir(parents=True, exist_ok=True)
+
+    client = genai.Client(vertexai=True)
+
+    cfg = types.GenerateContentConfig(
+        temperature=temp,
+        top_p=top_p,
+        max_output_tokens=32768,
+        response_modalities=["TEXT", "IMAGE"],
+        safety_settings=[
+            types.SafetySetting(category="HARM_CATEGORY_HATE_SPEECH", threshold="OFF"),
+            types.SafetySetting(category="HARM_CATEGORY_DANGEROUS_CONTENT", threshold="OFF"),
+            types.SafetySetting(category="HARM_CATEGORY_SEXUALLY_EXPLICIT", threshold="OFF"),
+            types.SafetySetting(category="HARM_CATEGORY_HARASSMENT", threshold="OFF"),
+        ],
+        image_config=types.ImageConfig(
+            aspect_ratio="1:1",
+            image_size="1K",
+            output_mime_type="image/png",
+        ),
+    )
+
+    def to_model_image_content(img_bytes: bytes) -> types.Content:
+        """Wrap prior image bytes as a model-role content part for chaining."""
+        return types.Content(
+            role="model",
+            parts=[
+                types.Part.from_text(text="`"),
+                types.Part.from_bytes(data=img_bytes, mime_type="image/png"),
+            ],
+        )
+
+    def extract_first_image(resp) -> bytes | None:
+        """Extract the first inline image payload from a Vertex response object."""
+        for cand in getattr(resp, "candidates", []) or []:
+            parts = getattr(getattr(cand, "content", None), "parts", []) or []
+            for part in parts:
+                if getattr(part, "inline_data", None) and getattr(part.inline_data, "data", None):
+                    return part.inline_data.data
+        return None
+
+    grouped: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+    for itm in prompt_items:
+        grouped[itm.get("slide") or itm.get("style_name") or "unknown"].append(itm)
+
+    manifest: List[Dict[str, Any]] = []
+
+    for slide, items in grouped.items():
+        logger.info("[vertex-chain] style=%s items=%d", slide, len(items))
+        hero = next((i for i in items if "_hero" in i.get("filename", "")), None)
+        front = next((i for i in items if "_front" in i.get("filename", "")), None)
+        back = next((i for i in items if "_back" in i.get("filename", "")), None)
+        if not (hero and front and back):
+            logger.warning("[vertex-chain] skip %s missing hero/front/back", slide)
+            continue
+
+        def resolve_out_path(itm: Dict[str, Any]) -> Path:
+            """Resolve the output path for an item, creating parent folders as needed."""
+            op = itm.get("out_path")
+            if op:
+                p = Path(op)
+                if not p.is_absolute():
+                    p = ROOT / p
+                p.parent.mkdir(parents=True, exist_ok=True)
+                return p
+            out_dir = out_root / (itm.get("slide") or slide)
+            out_dir.mkdir(parents=True, exist_ok=True)
+            return out_dir / itm.get("filename", "out.png")
+
+        # HERO
+        # 1) Hero request: single user turn with hero prompt.
+        hero_resp = client.models.generate_content(
+            model="gemini-2.5-flash-image",
+            contents=[types.Content(role="user", parts=[types.Part.from_text(text=hero["prompt"])])],
+            config=cfg,
+        )
+        hero_img = extract_first_image(hero_resp)
+        if not hero_img:
+            manifest.append({"filename": hero.get("filename"), "status": "error", "path": None})
+            logger.error("[vertex-chain] no hero image for %s", slide)
+            continue
+        hero_path = resolve_out_path(hero)
+        hero_path.write_bytes(hero_img)
+        manifest.append({"filename": hero.get("filename"), "status": "ok", "path": str(hero_path.relative_to(ROOT))})
+
+        # FRONT
+        # 2) Front request: feed hero prompt (user) + hero image (model turn) + front prompt (user).
+        contents_front = [
+            types.Content(role="user", parts=[types.Part.from_text(text=hero["prompt"])]),
+            to_model_image_content(hero_img),
+            types.Content(role="user", parts=[types.Part.from_text(text=front["prompt"])]),
+        ]
+        front_resp = client.models.generate_content(
+            model="gemini-2.5-flash-image",
+            contents=contents_front,
+            config=cfg,
+        )
+        front_img = extract_first_image(front_resp)
+        if not front_img:
+            manifest.append({"filename": front.get("filename"), "status": "error", "path": None})
+            logger.error("[vertex-chain] no front image for %s", slide)
+            continue
+        front_path = resolve_out_path(front)
+        front_path.write_bytes(front_img)
+        manifest.append({"filename": front.get("filename"), "status": "ok", "path": str(front_path.relative_to(ROOT))})
+
+        # BACK
+        # 3) Back request: hero prompt (user) + hero image (model) + front prompt (user) + front image (model) + back prompt (user).
+        contents_back = [
+            types.Content(role="user", parts=[types.Part.from_text(text=hero["prompt"])]),
+            to_model_image_content(hero_img),
+            types.Content(role="user", parts=[types.Part.from_text(text=front["prompt"])]),
+            to_model_image_content(front_img),
+            types.Content(role="user", parts=[types.Part.from_text(text=back["prompt"])]),
+        ]
+        back_resp = client.models.generate_content(
+            model="gemini-2.5-flash-image",
+            contents=contents_back,
+            config=cfg,
+        )
+        back_img = extract_first_image(back_resp)
+        if not back_img:
+            manifest.append({"filename": back.get("filename"), "status": "error", "path": None})
+            logger.error("[vertex-chain] no back image for %s", slide)
+            continue
+        back_path = resolve_out_path(back)
+        back_path.write_bytes(back_img)
+        manifest.append({"filename": back.get("filename"), "status": "ok", "path": str(back_path.relative_to(ROOT))})
+
+    return manifest

sample_code/llm_client.py

@@ -0,0 +1,95 @@
+"""Lightweight OpenAI GPT-5 client for orchestration steps (4–9 prompts, etc.)."""
+
+from __future__ import annotations
+
+import base64
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+from openai import OpenAI
+
+from constants import (
+    ROOT,
+    DEFAULT_SETTINGS,
+    LLM_SETTING_KEYS as SETTING_KEYS,
+    DEFAULT_MODEL,
+    DEFAULT_REASONING,
+)
+
+
+def load_settings(path: Path | None) -> dict:
+    """Load settings.json (or a provided path) and keep only recognized keys."""
+    path = path or DEFAULT_SETTINGS
+    if not path.exists():
+        return {}
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return {k: v for k, v in data.items() if k in SETTING_KEYS and v}
+
+
+def resolve_api_key(settings: dict) -> str:
+    """Resolve OPENAI_API_KEY preferring env over settings; exit if missing."""
+    if os.environ.get("OPENAI_API_KEY"):
+        return os.environ["OPENAI_API_KEY"]
+    if settings.get("OPENAI_API_KEY"):
+        return settings["OPENAI_API_KEY"]
+    raise SystemExit("OPENAI_API_KEY is not set (env or settings.json)")
+
+
+def resolve_model(settings: dict, cli_model: Optional[str]) -> str:
+    """Pick the model from CLI override, env, settings, or fallback default."""
+    return cli_model or os.environ.get("OPENAI_MODEL") or settings.get("OPENAI_MODEL") or DEFAULT_MODEL
+
+
+def resolve_reasoning(settings: dict, cli_reasoning: Optional[str]) -> Optional[str]:
+    """Pick the reasoning effort from CLI override, env, settings, or default."""
+    return cli_reasoning or os.environ.get("OPENAI_REASONING_EFFORT") or settings.get("OPENAI_REASONING_EFFORT") or DEFAULT_REASONING
+
+
+def run(prompt: object, model: str, reasoning: Optional[str], api_key: str) -> str:
+    """
+    Use the newer Responses API (per OpenAI 2025 guidelines).
+    Accepts:
+      - str prompt
+      - list/tuple [text, image_bytes] for multimodal
+    """
+    client = OpenAI(api_key=api_key)
+
+    kwargs = {}
+    if reasoning:
+        kwargs["reasoning"] = {"effort": reasoning}
+
+    # Build input payload
+    if isinstance(prompt, (list, tuple)) and len(prompt) == 2 and isinstance(prompt[0], str) and isinstance(prompt[1], (bytes, bytearray)):
+        b64 = base64.b64encode(prompt[1]).decode("utf-8")
+        logging.info("[llm] multimodal input: text_len=%s image_bytes=%s", len(prompt[0]), len(prompt[1]))
+        input_payload = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "input_text", "text": prompt[0]},
+                    {"type": "input_image", "image_url": f"data:image/png;base64,{b64}"},
+                ],
+            }
+        ]
+    else:
+        text_prompt = prompt if isinstance(prompt, str) else str(prompt)
+        input_payload = [
+            {
+                "role": "user",
+                "content": [{"type": "input_text", "text": text_prompt}],
+            }
+        ]
+
+    # Debug log full payload for traceability
+    logging.info("[llm] model=%s reasoning=%s payload=%s", model, reasoning, input_payload)
+
+    resp = client.responses.create(
+        model=model,
+        input=input_payload,
+        **kwargs,
+    )
+
+    return getattr(resp, "output_text", None) or str(resp)

schemas.py

@@ -0,0 +1,186 @@
+"""Lightweight schema helpers for micro-trend JSON validation and summarization."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+REQUIRED_TOP_LEVEL_KEYS = {"meta", "global_scene", "garments", "image_level_micro_trends"}
+
+
+class ValidationError(Exception):
+    pass
+
+
+def validate_trend_payload(payload: Any) -> Dict[str, Any]:
+    """Basic structural validation to ensure expected keys/types exist."""
+    if not isinstance(payload, dict):
+        raise ValidationError("Payload is not a JSON object")
+
+    missing = REQUIRED_TOP_LEVEL_KEYS - payload.keys()
+    if missing:
+        raise ValidationError(f"Missing top-level keys: {', '.join(sorted(missing))}")
+
+    if not isinstance(payload.get("garments"), list):
+        raise ValidationError("`garments` must be a list")
+
+    for i, garment in enumerate(payload["garments"]):
+        if not isinstance(garment, dict):
+            raise ValidationError(f"garments[{i}] is not an object")
+        if "category" not in garment:
+            raise ValidationError(f"garments[{i}] missing `category`")
+        if "print_overview" in garment and not isinstance(garment["print_overview"], dict):
+            raise ValidationError(f"garments[{i}].print_overview must be an object")
+        if "print_placement" in garment and not isinstance(garment["print_placement"], list):
+            raise ValidationError(f"garments[{i}].print_placement must be a list")
+
+    return payload  # type: ignore[return-value]
+
+
+def _fmt_list(vals: List[str]) -> str:
+    vals = [v for v in vals if v]
+    if not vals:
+        return ""
+    if len(vals) == 1:
+        return vals[0]
+    return ", ".join(vals[:-1]) + f" and {vals[-1]}"
+
+
+def _summarize_placement(placements: List[Dict[str, Any]]) -> str:
+    if not placements:
+        return "placement not specified"
+    parts = []
+    for p in placements[:3]:
+        zone = p.get("zone") or "zone unknown"
+        side = p.get("side") or "side n/a"
+        coverage = p.get("coverage_percent_of_zone")
+        orientation = p.get("orientation")
+        note = p.get("notes")
+        chunk = f"{zone} ({side}"
+        if coverage is not None:
+            chunk += f", ~{coverage}% coverage"
+        if orientation:
+            chunk += f", {orientation.lower()} orientation"
+        chunk += ")"
+        if note:
+            chunk += f" [{note}]"
+        parts.append(chunk)
+    if len(placements) > 3:
+        parts.append("additional placements not shown")
+    return "; ".join(parts)
+
+
+def _summarize_motifs(motifs: List[Dict[str, Any]]) -> str:
+    if not motifs:
+        return "motifs not specified"
+    parts = []
+    for m in motifs[:3]:
+        motif = m.get("motif_type") or "motif"
+        desc = m.get("motif_description")
+        scale = m.get("scale")
+        density = m.get("density")
+        spacing = m.get("spacing_pattern")
+        colors = m.get("colorways")
+        chunk = motif
+        if desc:
+            chunk += f" ({desc})"
+        details = _fmt_list([scale, density, spacing])
+        if details:
+            chunk += f" | {details}"
+        if colors:
+            chunk += f" | colors: {colors}"
+        parts.append(chunk)
+    if len(motifs) > 3:
+        parts.append("additional motif atoms not shown")
+    return "; ".join(parts)
+
+
+def build_summary(payload: Dict[str, Any], max_garments: int = 3) -> List[str]:
+    """Derive structured bullet points (Markdown-friendly) that narrate the JSON contents."""
+    bullets: List[str] = []
+
+    meta = payload.get("meta") or {}
+    scene = payload.get("global_scene") or {}
+    meta_bits = _fmt_list(
+        [
+            f"image quality {meta.get('image_quality')}" if meta.get("image_quality") else "",
+            meta.get("image_type"),
+            meta.get("view_type"),
+            f"{meta.get('num_visible_garments')} garment(s)" if meta.get("num_visible_garments") is not None else "",
+        ]
+    )
+    scene_bits = _fmt_list(
+        [
+            scene.get("setting"),
+            "model present" if scene.get("model_present") else "",
+            f"occlusions: {scene.get('occlusions_or_crops')}" if scene.get("occlusions_or_crops") else "",
+        ]
+    )
+    bullets.append(f"**Scene:** {meta_bits or 'n/a'}; {scene_bits or 'setting n/a'}.")
+
+    garments: List[Dict[str, Any]] = payload.get("garments", [])[:max_garments]
+    for idx, g in enumerate(garments, start=1):
+        cat = g.get("category") or g.get("sub_category") or "garment"
+        role = g.get("role") or "primary"
+        base_color = g.get("base_color_main") or "color n/a"
+        secondary = _fmt_list(g.get("base_color_secondary") or [])
+        fabric = g.get("base_fabric_impression")
+        presence = g.get("print_presence")
+        overview = g.get("print_overview") or {}
+        primary_family = overview.get("primary_print_family")
+        secondary_families = _fmt_list(overview.get("secondary_print_families") or [])
+        style_tags = _fmt_list(overview.get("print_style_tags") or [])
+        technique = overview.get("print_technique_estimate")
+        placement = _summarize_placement(g.get("print_placement") or [])
+        motifs = _summarize_motifs(g.get("motif_atoms") or [])
+        color_story = g.get("color_story") or {}
+        contrast = color_story.get("contrast_behavior")
+        print_colors = _fmt_list(color_story.get("print_colors") or [])
+        text_logo = g.get("text_and_logo_details") or {}
+        has_text = text_logo.get("has_text_or_logo")
+        text_samples = _fmt_list(text_logo.get("text_samples") or [])
+        tags = g.get("micro_trend_inferences") or {}
+        trend_tags = _fmt_list(
+            (tags.get("print_micro_trend_tags") or [])
+            + (tags.get("placement_micro_trend_tags") or [])
+            + (tags.get("color_micro_trend_tags") or [])
+            + (tags.get("other_detail_micro_trend_tags") or [])
+        )
+        confidence = g.get("confidence") or {}
+
+        bullet = (
+            f"**Garment {idx} ({role}) — {cat}:** base color {base_color}"
+            f"{' with ' + secondary if secondary else ''}"
+            f"{' | fabric ' + fabric if fabric else ''}"
+            f"; print presence {presence or 'n/a'}"
+        )
+        if primary_family:
+            bullet += f"; primary print family {primary_family}"
+        if secondary_families:
+            bullet += f"; secondary {secondary_families}"
+        if style_tags:
+            bullet += f"; style {style_tags}"
+        if technique:
+            bullet += f"; technique {technique}"
+        bullet += f"; placement: {placement}"
+        bullet += f"; motifs: {motifs}"
+        if print_colors or contrast:
+            bullet += f"; colors: ground={color_story.get('ground_color') or 'n/a'}, print={print_colors or 'n/a'}, contrast={contrast or 'n/a'}"
+        if has_text:
+            placements = _fmt_list(text_logo.get("placement") or [])
+            style = text_logo.get("style")
+            bullet += f"; text/logo present ({placements or 'placement n/a'}, style {style or 'n/a'}, samples: {text_samples or 'n/a'})"
+        if trend_tags:
+            bullet += f"; micro-trend tags: {trend_tags}"
+        if confidence.get("overall"):
+            bullet += f"; confidence overall {confidence.get('overall')}"
+        bullets.append(bullet + ".")
+
+    tags = (payload.get("image_level_micro_trends") or {}).get("deduplicated_tags") or []
+    if isinstance(tags, list) and tags:
+        bullets.append("**Image-level micro-trend tags:** " + ", ".join(tags) + ".")
+
+    summary_comment = (payload.get("image_level_micro_trends") or {}).get("summary_comment")
+    if isinstance(summary_comment, str) and summary_comment.strip():
+        bullets.append("**Image-level summary:** " + summary_comment.strip())
+
+    return bullets

settings.py

@@ -0,0 +1,94 @@
+"""Settings loader for the micro-trend Gradio app.
+
+Loads `settings.json` (same shape as `sample_code/settings.json`) with env
+overrides, and exposes a typed Settings object.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+DEFAULT_SETTINGS_PATH = Path("settings.json")
+
+# Keys mirrored from sample_code/settings.json
+SETTING_KEYS = {
+    "OPENAI_API_KEY",
+    "GEMINI_API_KEY",
+    "OPENAI_MODEL",
+    "OPENAI_REASONING_EFFORT",
+    "GOOGLE_GENAI_USE_VERTEXAI",
+    "GOOGLE_CLOUD_PROJECT",
+    "GOOGLE_CLOUD_LOCATION",
+}
+
+DEFAULT_MODEL = "gpt-5-mini"
+DEFAULT_REASONING = "medium"
+
+
+@dataclass
+class Settings:
+    openai_api_key: Optional[str] = None
+    gemini_api_key: Optional[str] = None
+    openai_model: str = DEFAULT_MODEL
+    openai_reasoning_effort: Optional[str] = DEFAULT_REASONING
+    google_genai_use_vertexai: bool = True
+    google_cloud_project: Optional[str] = None
+    google_cloud_location: Optional[str] = None
+
+    def require_api_keys(self) -> None:
+        """Raise if both providers are missing keys."""
+        if not self.openai_api_key and not self.gemini_api_key:
+            raise RuntimeError("No API keys set: provide OPENAI_API_KEY and/or GEMINI_API_KEY via env or settings.json")
+
+    def to_payload(self) -> Dict[str, Any]:
+        """Return a dict useful for client construction/logging."""
+        return {
+            "openai_model": self.openai_model,
+            "openai_reasoning_effort": self.openai_reasoning_effort,
+            "google_genai_use_vertexai": self.google_genai_use_vertexai,
+            "google_cloud_project": self.google_cloud_project,
+            "google_cloud_location": self.google_cloud_location,
+        }
+
+
+def _coerce_bool(value: Any) -> bool:
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        return value.strip().lower() in {"1", "true", "yes", "on"}
+    return bool(value)
+
+
+def _load_json(path: Path) -> Dict[str, Any]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def load_settings(path: Path | None = None) -> Settings:
+    """
+    Load settings with env overrides.
+    Precedence: env > settings.json > defaults.
+    """
+    settings_path = path or DEFAULT_SETTINGS_PATH
+    raw = _load_json(settings_path)
+    # Keep only recognized keys
+    raw = {k: v for k, v in raw.items() if k in SETTING_KEYS}
+
+    def pick(key: str, default: Any = None) -> Any:
+        env_val = os.environ.get(key)
+        return env_val if env_val is not None else raw.get(key, default)
+
+    return Settings(
+        openai_api_key=pick("OPENAI_API_KEY"),
+        gemini_api_key=pick("GEMINI_API_KEY"),
+        openai_model=pick("OPENAI_MODEL", DEFAULT_MODEL),
+        openai_reasoning_effort=pick("OPENAI_REASONING_EFFORT", DEFAULT_REASONING),
+        google_genai_use_vertexai=_coerce_bool(pick("GOOGLE_GENAI_USE_VERTEXAI", True)),
+        google_cloud_project=pick("GOOGLE_CLOUD_PROJECT"),
+        google_cloud_location=pick("GOOGLE_CLOUD_LOCATION"),
+    )