README.md

---
title: nat-ad
sdk: docker
app_port: 7860
---
# Social Media Ads Creator

This project leverages AI agents to automatically generate social media ad copy for products from their URLs.

## How it Works

The system uses a Gradio interface (`app.py`) with three main tabs:

1.  **Social Media Ad Generator:** This tab takes product URLs and other parameters as input. Behind the scenes, a "crew" of AI agents, each with a specific role, processes this information:
    *   **Product Analyst:** This agent scrapes a product URL to extract key information like the product name, features, price, and any available discounts. It also uses a tool to shorten the URL.
    *   **Social Media Copywriter:** This agent takes the product information and crafts a compelling social media post in Portuguese, tailored for platforms like WhatsApp. The post includes a call to action, emojis, and the shortened URL.

2.  **Fragrantica Website Analyzer:** This new tab allows users to input a Fragrantica.com URL for a perfume. A dedicated "FragranticaCrew" analyzes the webpage using a stealthy web scraping tool (`StealthScrapeTool`) to bypass anti-bot measures. The crew then generates a comprehensive perfume analysis report.
    *   **Expert Perfume Analyst and Web Data Extractor:** This agent extracts detailed perfume information (notes, accords, longevity, sillage, similar fragrances, reviews) from the Fragrantica page.
    *   **Fragrance Expert Woman and Perfume Analysis Reporter:** This agent synthesizes the extracted data into a human-friendly report, including graded evaluations and personalized recommendations.

3.  **Image Ad Generator:** This tab allows users to generate a promotional image for a product. It takes the product name, original price, final price, a coupon code, and a product image URL as input. The tool then generates a promotional image with this information, based on a template. The generated image is saved as a temporary file and displayed in the interface.

## Merchant Support

The application now supports generating ad copy for both **Natura** and **Mercado Livre** products. The `merchs/merch.py` file defines a `Merchant` class with two subclasses: `NaturaMerchant` and `MercadoLivreMerchant`. This allows the application to use different templates and URL shorteners for each merchant.

## Setup and Usage

1.  **Prerequisites:**
    *   Docker installed
    *   An OpenAI API key
    *   A Natura API token (for the URL shortener)

2.  **Installation & Execution (Docker):**
    *   Build the Docker image:
        ```bash
        docker build -t natura-ads .
        ```
    *   Run the Docker container, mapping port 7860 and passing API keys as environment variables:
        ```bash
        docker run --rm -p 7860:7860 -e OPENAI_API_KEY="your_openai_api_key" -e NATURA_API_TOKEN="your_natura_api_token" -e OPENAI_BASE_URL="your_openai_base_url" -e OPENAI_MODEL_NAME="your_openai_model_name" natura-ads
        ```
    *   Access the Gradio interface in your web browser at `http://localhost:7860`.

## Key Files

*   `app.py`: The Gradio application that provides the user interface.
*   `social_media_crew.py`: Defines the AI agents and their tasks for social media ad generation.
*   `fragrantica_crew.py`: Defines the AI agents and their tasks for Fragrantica website analysis.
*   `merchs/merch.py`: Defines the merchant-specific logic for Natura and Mercado Livre.
*   `generate_image_tool.py`: A tool to generate promotional images for products.
*   `stealth_scrape_tool.py`: A custom tool for stealthy web scraping using Playwright.
*   `shortener_tool.py`: A custom tool for shortening URLs.
*   `Dockerfile`: Defines the Docker image for deploying the application.
*   `.env`: The configuration file for API keys (used for local development, environment variables preferred for Docker).
*   `pyproject.toml`: The project's metadata and dependencies.


# Roadmap

- [x] Add support for any model/api key supported by LiteLLM.
- [x] Add Fragrantica support, where user will input a Fragrantica URL and the agent will extract and generate a Perfume Analysis report.
- [x] Support Mercado Livre Merchant
- [x] Add image templates
- [wip] Add share button to images, that work with instagram on mobile. Android/IPhone.
- [] Make image template trigger/working seamless with data from generated post.
- [] Create carroussel images for Fragrantica post