docs/plan.md

# 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.