userIdc2024/Creative_Breakthrough

PsyAdGenesis

Design ads that stop the scroll.

Generate high-converting ad creatives for Home Insurance and GLP-1 niches using psychological triggers and AI-powered image generation.

Features

• —Multiple Generation Modes:
• —Standard generation using random angle × concept combinations
• —Batch generation for multiple ads
• —Angle × Concept matrix system (100 angles × 100 concepts)
• —Extensive generation with researcher → creative director → designer → copywriter flow

• —Image Generation: Supports multiple models (z-image-turbo, nano-banana, nano-banana-pro, imagen-4-ultra, recraft-v3, ideogram-v3, photon, seedream-3)

• —Image Correction: AI-powered image correction for spelling mistakes and visual issues

• —Database Storage: MongoDB integration for storing generated ads

• —Authentication: JWT-based authentication system

Setup

Environment Variables

Copy .env.example to .env and fill in your API keys:

cp .env.example .env

Required variables:

• —OPENAI_API_KEY: Your OpenAI API key
• —REPLICATE_API_TOKEN: Your Replicate API token
• —JWT_SECRET_KEY: Secret key for JWT tokens (change in production!)

Optional variables:

• —MONGODB_URL: MongoDB connection string (for database features)
• —R2 Storage credentials (for cloud image storage):
• —R2_ENDPOINT: Cloudflare R2 endpoint URL
• —R2_BUCKET_NAME: R2 bucket name
• —R2_ACCESS_KEY: R2 access key
• —R2_SECRET_KEY: R2 secret key
• —R2_PUBLIC_DOMAIN: Optional custom domain for public URLs

Production & Storage Settings:

• —ENVIRONMENT: Set to "production" for production deployment (default: "development")
• —SAVE_IMAGES_LOCALLY: Whether to save images locally (default: true)
• —In production: Set to false to disable local storage completely
• —In production: Set to true to save temporarily (will be auto-deleted after retention period)
• —LOCAL_IMAGE_RETENTION_HOURS: Hours to keep images locally before cleanup (default: 24)
• —Only applies when ENVIRONMENT=production and SAVE_IMAGES_LOCALLY=true

Running Locally

1. 1.Install dependencies:

pip install -r requirements.txt

1. 1.Run the server:

uvicorn main:app --reload

1. 1.Access the API at http://localhost:8000

API Documentation

Once running, visit:

• —API docs: http://localhost:8000/docs
• —Alternative docs: http://localhost:8000/redoc

Deployment on Hugging Face Spaces

This app is configured for deployment on Hugging Face Spaces using Docker.

Steps to Deploy

1. 1.Create a new Space on Hugging Face:
2. 2.Go to https://huggingface.co/spaces
3. 3.Click "Create new Space"
4. 4.Choose "Docker" as the SDK
5. 5.Name your space (e.g., your-username/psyadgenesis)

1. 1.Push your code to the Space:

   git clone https://huggingface.co/spaces/your-username/psyadgenesis
   cd psyadgenesis
   # Copy your files here
   git add .
   git commit -m "Initial commit"
   git push

1. 1.Set Environment Variables:
2. 2.Go to your Space settings
3. 3.Navigate to "Variables and secrets"
4. 4.Add all required environment variables from .env.example
5. 5.Important: Set JWT_SECRET_KEY to a secure random string

1. 1.Wait for Build:
2. 2.Hugging Face will automatically build and deploy your Docker container
3. 3.Check the "Logs" tab for build progress

Space Configuration

The huggingface.yml file configures:

• —Docker-based deployment
• —Port 8000 for the FastAPI app
• —Health check endpoint

Production Configuration

For production deployments on Hugging Face Spaces, set these environment variables:

ENVIRONMENT=production
SAVE_IMAGES_LOCALLY=true  # Set to false to disable local storage completely
LOCAL_IMAGE_RETENTION_HOURS=24  # Images older than this will be auto-deleted

Important Notes:

• —In production with SAVE_IMAGES_LOCALLY=true: Images are saved temporarily and automatically cleaned up after the retention period
• —In production with SAVE_IMAGES_LOCALLY=false: Images are NOT saved locally (only uploaded to R2)
• —Automatic cleanup runs every hour in production
• —Use the /admin/storage/stats endpoint to monitor storage usage

Accessing Your Deployed App

Once deployed, your app will be available at:

https://your-username-psyadgenesis.hf.space

API Endpoints

Authentication

• —POST /auth/login - Login and get JWT token

Generation

• —POST /generate - Generate single ad (requires auth)
• —POST /generate/batch - Generate multiple ads (requires auth)
• —POST /matrix/generate - Generate using Angle × Concept matrix (requires auth)
• —POST /matrix/testing - Generate testing matrix
• —POST /extensive/generate - Extensive generation flow (requires auth)

Matrix System

• —GET /matrix/angles - List all 100 angles
• —GET /matrix/concepts - List all 100 concepts
• —GET /matrix/angle/{key} - Get specific angle details
• —GET /matrix/concept/{key} - Get specific concept details
• —GET /matrix/compatible/{angle_key} - Get compatible concepts

Image Correction

• —POST /api/correct - Correct image for spelling/visual issues (requires auth)

Database

• —GET /db/stats - Get database statistics (requires auth)
• —GET /db/ads - List stored ads (requires auth)
• —GET /db/ad/{ad_id} - Get specific ad
• —DELETE /db/ad/{ad_id} - Delete ad (requires auth)

Admin (Storage Management)

• —GET /admin/storage/stats - Get storage statistics for locally saved images (requires auth)
• —POST /admin/storage/cleanup - Manually trigger image cleanup (requires auth)
• —Query parameter: dry_run=true to preview what would be deleted

Health

• —GET /health - Health check
• —GET / - API information

Supported Niches

• —home_insurance: Fear, urgency, savings, authority, guilt strategies
• —glp1: Shame, transformation, FOMO, authority, simplicity strategies

Matrix System

The app uses a systematic Angle × Concept matrix for all ad generation:

• —100 Angles: Psychological triggers (10 categories)
• —100 Concepts: Visual approaches (10 categories)
• —10,000 possible combinations

Standard Generation: Randomly selects an angle × concept combination for each ad Matrix Generation: Allows explicit selection of specific angle × concept combinations

Formula: 1 Offer → 5-8 Angles → 3-5 Concepts per angle

License

[Add your license here]