README.md

---
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:

```bash
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:
```bash
pip install -r requirements.txt
```

2. Run the server:
```bash
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:
   ```bash
   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:

```bash
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]