# Prompt Contract

## Purpose

This contract defines the canonical prompt structure for realism-first image generation. It should become the source of truth for both:

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

## New Generation Modes

Add a required or defaulted mode field:

- `poster`
- `photorealistic_scene`

For the wine-reference style, use:

- `photorealistic_scene`

## Behavior For `photorealistic_scene`

Rules:

- prioritize photography over typography
- allow zero visible text by default
- do not ask the model to create a mobile poster layout unless explicitly requested
- do not require title, content, or type `9/10/11`
- scene styling must come from a fixed template, not freeform caller text alone

## Canonical Prompt Sections

The generated prompt should always contain these sections in this order:

1. Goal
2. Scene
3. Composition
4. Lighting
5. Textures
6. Atmosphere
7. Style
8. Focus
9. Negative prompt

## Canonical Base Template

This should be derived directly from `problems/prompt.md`.

```text
Create an ultra-photorealistic luxury romantic gift box product photo.

SCENE:
- handcrafted rustic wooden gift crate on a vintage white wooden table
- warm cozy luxury interior
- premium bottle of red wine with elegant dark label
- two crystal wine glasses
- luxury chocolate box with golden wrapped pralines
- premium scented candle in red glass jar, lit
- romantic greeting card
- blush pink roses
- white roses
- eucalyptus leaves
- soft cream satin ribbon tied into an elegant bow

COMPOSITION:
- centered symmetrical arrangement
- all objects balanced naturally
- realistic premium gift styling
- gift box is the main hero object
- close-up perspective
- slight top-front camera angle
- shallow depth of field

LIGHTING:
- warm ambient indoor lighting
- soft candle glow
- cinematic bokeh lights in background
- golden warm highlights
- realistic shadows
- natural side light blend

TEXTURES:
- visible wood grain
- realistic glass reflections
- glossy wine bottle reflections
- natural rose petal softness
- satin ribbon silk texture
- chocolate metallic wrapping reflections
- candle wax realism

ATMOSPHERE:
- romantic
- intimate
- warm
- elegant
- premium gift experience
- anniversary mood
- proposal vibe

STYLE:
- ultra-photorealistic
- luxury product photography
- cinematic realism
- editorial commercial quality
- premium ad quality
- 85mm lens look
- f/1.8 depth of field
- HDR feel
- hyper-detailed
- natural realistic colors

FOCUS:
- razor-sharp foreground details
- soft blurred background
- realistic depth separation
- premium luxury composition

NEGATIVE PROMPT:
- cartoon
- CGI
- fake flowers
- blurry glass
- distorted objects
- duplicated items
- text artifacts
- plastic textures
- oversaturated colors
- low quality
- bad anatomy
- extra objects
```

## What Must Be Removed In This Mode

Remove or suppress these ideas when `photorealistic_scene` mode is active:

- poster title hierarchy
- event announcement framing
- mobile poster readability framing
- menu poster layout framing
- large visible copy blocks
- CTA-style text instructions
- mandatory language/content copy unless explicitly requested

## Controlled Customization

Allowed dynamic substitutions:

- product or occasion type
- object list
- color palette
- lighting mood
- scene environment
- camera framing
- reference image hints
- logo usage rules

Not allowed:

- arbitrary freeform caller prompts replacing the realism base template
- mixing poster layout rules into photo mode
- generating lots of visible text by default

## Prompt Builder Strategy

Implementation rule:

- caller input can extend the template
- caller input cannot weaken the realism template

Safe order:

1. fixed realism template
2. structured request data
3. optional caller additions
4. reference-image instructions
5. hard negative constraints

## Example Request Contract For This Mode

Suggested fields:

```json
{
  "mode": "photorealistic_scene",
  "subject_type": "luxury_gift_box",
  "scene_prompt_profile": "wine_reference_v1",
  "logo_image_url": "https://example.com/logo.png",
  "reference_image_urls": [
    "https://example.com/ref-1.png"
  ],
  "prompt_variables": {
    "occasion": "romantic anniversary",
    "primary_product": "premium bottle of red wine",
    "secondary_products": [
      "two crystal wine glasses",
      "luxury pralines",
      "lit scented candle"
    ]
  }
}
```

## Acceptance Standard

If the built prompt can still be honestly described as "a restaurant poster prompt with a realism sentence added", the contract has failed.