README.md

metadata

title: PsyAdGenesis
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 8000
pinned: false

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. Install dependencies:

pip install -r requirements.txt

2. Run the server:

uvicorn main:app --reload

3. 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. Create a new Space on Hugging Face:

   • Go to https://huggingface.co/spaces
   • Click "Create new Space"
   • Choose "Docker" as the SDK
   • Name your space (e.g., your-username/psyadgenesis)

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

3. Set Environment Variables:

   • Go to your Space settings
   • Navigate to "Variables and secrets"
   • Add all required environment variables from .env.example
   • Important: Set JWT_SECRET_KEY to a secure random string

4. Wait for Build:

   • Hugging Face will automatically build and deploy your Docker container
   • 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]