loops-ai 0.1.0
AI-powered ad generation pipeline that transforms product briefs into creative ad visuals
License: MIT
Requires Python: >=3.13

# Loops — AI-Powered Ad Generation Pipeline

Pipeline automatisé de génération d'annonces publicitaires utilisant plusieurs modèles d'IA.

## Project Overview

Loops est un pipeline de génération d'annonces publicitaires en 4 étapes qui transforme un brief produit et des visuels d'inspiration en une nouvelle annonce visuelle :

1. **Generate concept**: Extraction du concept créatif depuis un brief produit (PDF) et une annonce d'inspiration
2. **Generate prompt for nanobanana**: Création d'un prompt détaillé pour la génération d'image
3. **Generate new ad visual**: Génération d'une nouvelle annonce visuelle combinant l'image produit avec le style d'inspiration
4. **Fix text (optional)**: Correction du texte via OCR pour corriger les erreurs de génération

## Installation

### Depuis GitHub Packages (package interne)

```bash
pip install loops --index-url https://pypi.python.org/simple --extra-index-url https://USERNAME:TOKEN@pypi.github.com/denemlabs/loops.git/simple
```

Ou avec un fichier `.pypirc` configuré:

```bash
pip install loops
```

**Note:** Configurez vos credentials GitHub (token avec permissions `read:packages`).

### Développement local

```bash
git clone git@github.com:denemlabs/loops.git
cd loops
uv install
```

## Prerequisites

- **Python 3.13+** (verify with `python3 --version`)
- **uv package manager** (pour développement local)
  - macOS (Homebrew): `brew install uv`
  - Official installer (all platforms): `curl -LsSf https://astral.sh/uv/install.sh | sh`
  - Verify: `uv --version`
- **Tesseract OCR** (pour correction de texte)
  - macOS (Homebrew): `brew install tesseract`
  - Ubuntu/Debian: `sudo apt-get install tesseract-ocr`
  - Verify: `tesseract --version`
  - **French language data**: Download `fra.traineddata` and place it in the tessdata directory:
    - macOS (Homebrew): `/opt/homebrew/share/tessdata`
    - Ubuntu/Debian: `/usr/share/tesseract-ocr/*/tessdata`
    - Download from: https://github.com/tesseract-ocr/tessdata/raw/main/fra.traineddata
    - Example (macOS): `curl -L -o /opt/homebrew/share/tessdata/fra.traineddata https://github.com/tesseract-ocr/tessdata/raw/main/fra.traineddata`

## Configuration

1. Copiez le fichier d'exemple d'environnement:

```bash
cp .env.example .env
```

2. Ouvrez `.env` et remplissez vos clés API:

```dotenv
ANTHROPIC_API_KEY=your_anthropic_key
OPENAI_API_KEY=your_openai_key
GOOGLE_CLOUD_PROJECT=your_gcp_project_id
GOOGLE_API_KEY=your_google_api_key
LANGSMITH_API_KEY=your_langsmith_key
```

**Note**: Gardez `.env` hors du contrôle de version.

## Utilisation

### Pipeline complet

```python
from loops import AdGenerationPipeline

pipeline = AdGenerationPipeline(
    brand_brief_path="path/to/brief.pdf",
    inspiration_path="path/to/inspiration.jpg",
    product_image_path="path/to/product.png",
    output_path="output/ad.jpg",
)

results = pipeline.generate(fix_text=True)
print(f"Raw image: {results['raw_image']}")
print(f"Fixed image: {results['fixed_image']}")
```

### Utilisation modulaire

```python
from loops import NewAdConcept, PromptNanobanana, NewAdVisual

# Step 1: Generate concept
concept = NewAdConcept("brief.pdf").generate_from("inspiration.jpg")

# Step 2: Generate prompt
prompt = PromptNanobanana().generate_from(concept)

# Step 3: Generate visual
visual = NewAdVisual("product.png").generate_following(prompt)
```

## Structure du Package

- `loops.pipeline`: Pipeline principal (`AdGenerationPipeline`)
- `loops.generators`: Générateurs de concepts, prompts et visuels
  - `NewAdConcept`: Génération de concept avec GPT-O3
  - `PromptNanobanana`: Génération de prompt avec GPT-4.1
  - `NewAdVisual`: Génération de visuel avec Gemini
- `loops.processors`: Processeurs d'images et OCR
  - `EncodedImage`: Gestion d'images encodées en base64
  - `RawAdVisual`: Correction OCR avec Claude
- `loops.core`: Modules core
  - `BrandBrief`: Lecture de briefs PDF
  - `PromptedImage`: Formatage d'images pour LangChain
  - `SystemPrompt`: Chargement de prompts système

## Example Data Setup

Fournissez les assets suivants dans le dossier `examples` (référence à l'exemple `doucea`):

- Un document brief (PDF)
- Une annonce d'inspiration (JPEG)
- Une image produit (PNG)

Structure d'exemple:

```
examples/
  doucea/
    Doucéa Brief.pdf
    inspiration_ad.jpeg
    product_image.png
    outputs/
```

## Running the Application

Depuis la racine du projet:

```bash
uv run main.py
```

Ou utilisez l'exemple:

```bash
uv run examples/example_usage.py
```

## What the Application Does

Le pipeline exécute 4 étapes:

1. **Step 1**: Génère un concept créatif depuis le brief produit et l'annonce d'inspiration
2. **Step 2**: Produit un prompt détaillé pour nanobanana guidé par le concept
3. **Step 3**: Génère une nouvelle annonce visuelle qui combine l'image produit avec le style d'inspiration
4. **Step 4** (optionnel): Corrige le texte via OCR pour corriger les erreurs de génération

Les sorties seront sauvegardées dans le dossier `outputs` de votre exemple (e.g., `examples/doucea/outputs/doucea_new_ad_raw.jpg` et `doucea_new_ad_fixed.jpg`).

## Utilisation dans une API

Une fois installé depuis GitHub, dans votre API:

```python
# requirements.txt ou pyproject.toml
loops @ git+https://github.com/denemlabs/loops.git

# Dans votre API
from loops import AdGenerationPipeline

@app.post("/generate-ad")
async def generate_ad(request: AdRequest):
    pipeline = AdGenerationPipeline(
        brand_brief=request.brief_content,  # String avec le contenu du brief
        inspiration_path=request.inspiration_path,
        product_image_path=request.product_path,
    )
    results = pipeline.generate(fix_text=True)
    # results contient: concept, prompt, raw_image (bytes), fixed_image (bytes)
    return results
```