# Implementation Plan

## Phase 1: Split The Pipeline Into Explicit Modes

Files:

- `automation/n8n_ai_image_generator.json`
- `app/services/generate_ai_image/models/requests.py`
- `app/services/generate_ai_image/service.py`

Changes:

1. Add a mode field to the request model.
2. Default the mode for new realistic-scene callers to `photorealistic_scene`.
3. Keep the existing poster behavior behind `poster`.
4. Stop forcing `type`, `title`, `content`, and `language` for `photorealistic_scene`.

Why:

- The current required fields encode poster behavior directly into the API contract.
- Realistic scene generation needs a different contract.

## Phase 2: Replace Generic n8n Prompt Construction For Realism Mode

File:

- `automation/n8n_ai_image_generator.json`

Changes:

1. Update `Validate Initial Request` to branch by mode.
2. For `photorealistic_scene`:
   - accept a realism profile such as `wine_reference_v1`
   - accept optional structured variables instead of poster text blocks
   - build `systemPrompt` and `prompt` from the canonical realism template
3. Preserve the current poster prompt builder only for `poster`.
4. Record the selected realism profile in `ai_request`.

Why:

- The workflow is the first place where poster wording currently dominates the request.
- If n8n keeps injecting poster rules, backend improvements alone will not fix output quality.

## Phase 3: Make The Python Service Own The Final Prompt Contract

File:

- `app/services/generate_ai_image/service.py`

Changes:

1. Add a dedicated builder for `photorealistic_scene`.
2. Add fixed realism profiles, starting with:
   - `wine_reference_v1`
3. Ensure the final prompt includes:
   - scene breakdown
   - composition
   - lighting
   - textures
   - atmosphere
   - style
   - focus
   - negative prompt
4. Ensure caller-provided additions are appended, not substituted.
5. Prevent `poster` wording from leaking into `photorealistic_scene`.
6. Keep reference images mandatory guidance whenever provided.

Why:

- The service is the final code path before the OpenAI API call.
- It needs to be the last enforcement point for realism quality.

## Phase 4: Introduce Realism Profiles Instead Of One-Off Prompts

Files:

- `app/services/generate_ai_image/service.py`
- optionally new prompt-profile module under `app/services/generate_ai_image/`

Changes:

1. Add profile constants like:
   - `wine_reference_v1`
   - future: `beer_bucket_v1`
   - future: `dessert_box_v1`
2. Each profile should define:
   - base goal
   - scene objects
   - composition rules
   - lighting rules
   - texture rules
   - negative prompt
3. Keep `problems/prompt.md` as the source prompt reference, but move the live production prompt into code or versioned prompt assets.

Why:

- You want repeatable output quality, not ad hoc prompt editing.
- A named profile is easier to test, evolve, and call from n8n.

## Phase 5: Tighten The Request Schema

Files:

- `app/services/generate_ai_image/models/requests.py`
- `app/services/generate_ai_image/routes.py`

Changes:

1. Add fields such as:
   - `mode`
   - `scene_prompt_profile`
   - `subject_type`
   - `prompt_variables`
2. Make `content` optional or irrelevant for `photorealistic_scene`.
3. Make `language` optional unless visible text is explicitly requested.
4. Add validation errors when callers send poster-only fields into realism mode without need.

Why:

- The contract should express the real generation intent.
- Prompt quality becomes unstable when the schema itself is ambiguous.

## Phase 6: Add Regression Tests Around Prompt Intent

File:

- `tests/services/test_generate_ai_image_service.py`

Add tests for:

1. `photorealistic_scene` uses the realism profile sections.
2. `photorealistic_scene` includes the negative prompt block.
3. `photorealistic_scene` does not inject poster-layout wording.
4. reference images remain explicit mandatory visual guidance.
5. `poster` mode still keeps current poster behavior.

Why:

- Existing tests prove transport and analytics, not visual intent.
- This change needs prompt-shape regression coverage.

## Phase 7: Add Lightweight Operational Visibility

Files:

- `app/services/generate_ai_image/service.py`
- optional logging updates in `automation/n8n_ai_image_generator.json`

Changes:

1. Log:
   - `mode`
   - `scene_prompt_profile`
   - prompt length
   - reference image count
2. Save a short prompt preview in analytics payloads.
3. Distinguish poster vs realism mode in logs.

Why:

- When output drifts, prompt visibility matters.
- This avoids guessing whether the wrong mode or profile was used.

## Phase 8: Rollout Sequence

Order:

1. add request schema support
2. add backend realism prompt builder
3. add n8n branching by mode
4. add tests
5. run controlled manual samples
6. switch callers to realism mode
7. retire accidental poster-only assumptions for realism callers

## Non-Goals For The First Pass

Do not do these in the first implementation:

- rewrite the older `create_restaurant_offer` pipeline
- merge the old and new services together
- add automatic image scoring with another model
- change storage/upload behavior
- change auth behavior

## Definition Of Done

This work is done when:

1. a request in `photorealistic_scene` mode builds a prompt clearly based on the wine reference template
2. the prompt no longer reads like a poster brief
3. the backend tests lock this behavior
4. n8n and Python agree on the same mode and profile
5. manual outputs consistently resemble the realism level and composition style of `problems/wine.png`