Prompt Synchronization Guide

Last Updated: December 5, 2024
Source Schema: category_metadata_schema_test.json from S3 bucket metamock-ai

Overview

This guide documents the process of synchronizing category prompt implementations with their S3 schema definitions. As schemas evolve in the admin interface, prompt code must be updated to handle new attributes and options.

Architecture

S3 Schema (Source of Truth) → descriptions.py → main.py → GenericPromptBuilder
        ↓                        ↓              ↓               ↓
category_metadata_schema_test.json  Attribute    Prompt      Final Generated
                                   Descriptions  Templates    Prompt

Schema Source

Development: category_metadata_schema_test.json Production: category_metadata_schema.json S3 Bucket: metamock-ai Cache Behavior: Test mode always bypasses cache for fresh data

Synchronization Process

Step 1: Get Current S3 Schema

Use the cache service to retrieve the latest schema:

docker exec metamock-backend python -c "
from backend.services.cache import get_category_metadata_schema
import json
schema = get_category_metadata_schema(test_mode=True)
if schema and '{category}' in schema:
    print(json.dumps(schema['{category}'], indent=2))
else:
    print('Category not found')
"

Step 2: Analyze Schema Changes

Compare S3 schema with current descriptions.py to identify:

  1. New Attributes: Entirely new attribute types
  2. New Options: Additional values within existing attributes
  3. Removed Options: Values no longer available
  4. Case Changes: Capitalization differences

Step 3: Update descriptions.py

Add missing attribute handlers and options:

def get_description(attribute_name: str, value: str) -> str:
    # Add new attribute handler
    elif attribute_name == 'new_attribute':
        descriptions = {
            "option1": "descriptive text for option1",
            "option2": "descriptive text for option2"
        }
        return descriptions.get(value.lower(), "fallback description")

Step 4: Update main.py Templates

Incorporate new attributes into prompt templates:

human_model_prompt = [
    "A {demographics} wearing a {color_desc} {style_desc}.",
    "{new_attribute_desc}.",  # Add new dynamic variable
    "{background_setting}."
]

Step 5: Test Integration

Verify the changes work with prompt testing:

curl -X POST "http://localhost:8000/api/v1/prompt-testing/categories/{category}/test" \
  -H "Content-Type: application/json" \
  -d '{"count": 3, "attribute_overrides": {"new_attribute": "test_value"}}'

Recent Synchronization Examples

Coffee Mugs (December 5, 2024)

Schema Changes Identified: - New Attributes: focus, angle - New Material Options: textured ceramic, color-changing glaze, matte minimalist, eco-recycled stoneware, asymmetrical stainless steel - New Background Options: 13 additional background settings (marble counters, cafe nooks, etc.)

Files Updated: - server/config/prompts/coffee_mugs/descriptions.py: Added all missing options - server/config/prompts/coffee_mugs/main.py: Added {focus_desc} and {angle_desc} variables

Result: Full synchronization with 6 S3 attributes (type, material, background, color_palette, focus, angle)

Hoodies (December 5, 2024)

Schema Changes Identified: - Removed Option: "no pockets" from pocket attribute - Status: All other attributes already synchronized

Files Updated: - server/config/prompts/hoodies/descriptions.py: Removed outdated pocket option - server/config/prompts/hoodies/main.py: No changes needed

Result: Clean synchronization with all current S3 attributes

Key Patterns and Best Practices

Attribute Naming Conventions

  • S3 Schema: Often uses title case ("Standard mug", "Travel mug")
  • descriptions.py: Use .lower() for matching ("standard mug", "travel mug")
  • Dynamic Variables: Use descriptive suffixes ({type_desc}, {material_desc})

Common Attribute Types

  1. Style/Type: Product variation (pullover, zip-up, standard mug)
  2. Material: Construction material (ceramic, stainless steel, cotton)
  3. Background: Photo setting (studio, lifestyle, outdoor)
  4. Color Palette: Color schemes (warm, cool, neutral)
  5. Focus: Photography focus technique (rim, handle, texture)
  6. Angle: Camera angle (top-down, 45-degree, side profile)

Template Integration

Always add new attributes to both prompt templates: - human_model_prompt: For images with human models - product_only_prompt: For product-only shots

Error Prevention

  • Use .get() with fallbacks for missing values
  • Handle case sensitivity with .lower()
  • Test with actual S3 schema values
  • Verify GenericPromptBuilder recognizes new variables

Troubleshooting

Common Issues

  1. Missing Attribute Handler: Add complete elif block in descriptions.py
  2. Case Mismatch: Ensure consistent .lower() usage
  3. Undefined Variable: Check dynamic variable names in templates
  4. Outdated Cache: Use test_mode=True for fresh schema data

Debugging Commands

Check Available Categories:

docker exec metamock-backend python -c "
from backend.services.cache import get_category_metadata_schema
schema = get_category_metadata_schema(test_mode=True)
print('Categories:', list(schema.keys()) if schema else 'None')
"

Test Attribute Resolution:

docker exec metamock-backend python -c "
from config.prompts.{category}.descriptions import get_description
print(get_description('attribute_name', 'test_value'))
"

Verify Prompt Generation:

docker exec metamock-backend python -c "
from config.prompts.{category}.main import build_prompt
result = build_prompt({'attribute': 'value'})
print(result)
"

Schema Change Detection

Monitoring Schema Evolution

The S3 schema includes a changes array tracking all modifications:

{
  "changes": [
    {
      "change_data": "Added new attribute 'focus' with options: [...]",
      "change_time": "2025-12-05T06:56:57.055Z"
    }
  ]
}

Regular Sync Schedule

Recommendation: Sync prompt code with S3 schema: - After significant admin interface changes - Before major releases - When prompt testing shows missing attributes - Monthly maintenance reviews

File Locations

Schema Files: - Test: s3://metamock-ai/category_metadata_schema_test.json - Production: s3://metamock-ai/category_metadata_schema.json

Prompt Implementation: - Descriptions: server/config/prompts/{category}/descriptions.py - Templates: server/config/prompts/{category}/main.py - Builder: server/config/prompts/generic_prompt_builder.py

Cache Service: server/backend/services/cache.py

This synchronization ensures that prompt generation always reflects the latest category definitions and provides rich, accurate prompts for image generation.