Milhas WhatsApp Agent

An automated agent that scrapes credit card and miles promotions from Melhores Cartões and formats them into WhatsApp-friendly messages using Groq's LLM.

Features

• Web Scraping: Automatically extracts promotions from Melhores Cartões
• AI-Powered Formatting: Uses Groq's LLM to format promotions into clear, engaging messages
• Multiple Output Options:
  • Console output (default)
  • Save to file
  • Send via Email
  • WhatsApp (coming soon)
• Easy Configuration: Environment variable support for all configurations
• Error Handling: Comprehensive error handling and logging

🛠️ Setup

1. Clone this repository
2. Install dependencies:

   pip install -r requirements.txt

3. Copy the example environment file:

   cp .env.example .env

4. Edit the .env file with your configuration (see below for details)

🔑 Environment Configuration

Create a .env file in the project root with the following variables:

Required Variables

• GROQ_API_KEY: Your Groq API key for LLM processing
  • Get it from: https://console.groq.com/keys

Output Configuration (Choose One)

For Email Output (Recommended)

OUTPUT_DESTINATION_FORMAT=email
GMAIL_EMAIL=your_email@gmail.com
GMAIL_APP_PASSWORD=your_gmail_app_password  # See below for how to generate
EMAIL_RECIPIENT=recipient@example.com
EMAIL_SUBJECT=Promoções de Milhas  # Optional

For File Output

OUTPUT_DESTINATION_FORMAT=file
OUTPUT_FILE_NAME=promotions.txt  # Optional, defaults to 'promotions.txt'

For Console Output (Default)

OUTPUT_DESTINATION_FORMAT=console

📧 How to Generate a Gmail App Password

To send emails through Gmail, you'll need to generate an App Password:

1. Enable 2-Step Verification (if not already enabled):

   • Go to your Google Account: https://myaccount.google.com/
   • Select "Security" in the left navigation panel
   • Under "Signing in to Google," select 2-Step Verification
   • Follow the on-screen steps to set up 2-Step Verification

2. Generate an App Password:

   • Go to the App passwords page: https://myaccount.google.com/apppasswords
   • At the top, click Select app and choose Other (Custom name)
   • Enter a name that identifies this application (e.g., "Milhas Agent")
   • Click Generate
   • A 16-character password will be displayed. Copy this password immediately as you won't be able to see it again

3. Use the App Password:

   • In your .env file, set GMAIL_APP_PASSWORD to the 16-character password you just generated
   • The email address (GMAIL_EMAIL) must be the same Gmail account where you generated the App Password

⚠️ Important Security Notes:

• Never share your App Password or commit it to version control
• If you suspect your App Password is compromised, revoke it immediately and generate a new one
• Each application should have its own unique App Password

🏃 Usage

Run the main script with the desired output option:

Basic Usage

1. Console Output (default):

   python main.py

2. Save to File:

   python main.py --output file --output-file my_promotions.txt

3. Send via Email:

   python main.py --output email

   Make sure you've configured the email settings in your .env file first.

Advanced Options

• Debug Mode:

  python main.py --debug

• Override Configuration:

  python main.py --output email --gmail-email your_email@gmail.com --gmail-app-password your_app_password

• Help:

  python main.py --help

📁 Project Structure

milhas_whatsapp_agent/
├── ai_agents/          # AI agent implementations for data processing
├── formatters/         # Output formatters (HTML, text, etc.)
├── scraping/           # Web scraping logic
├── services/           # Core services and business logic
├── .env                # Environment variables (not versioned)
├── .env.example        # Example environment configuration
├── main.py            # Main script entry point
└── requirements.txt    # Python dependencies

⚙️ Configuration Options

Environment Variables

All configuration is done through environment variables in the .env file. The following options are available:

Core Configuration

• DEBUG_MODE: Set to True to enable debug logging (default: False)
• LOG_LEVEL: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Email Configuration

• GMAIL_EMAIL: Your Gmail address (required for email output)
• GMAIL_APP_PASSWORD: App Password for Gmail (see above for how to generate)
• EMAIL_RECIPIENT: Recipient email address (can be the same as GMAIL_EMAIL)
• EMAIL_SUBJECT: Email subject (default: 'Promoções de Milhas')

File Output

• OUTPUT_FILE_NAME: Path to output file (default: 'promotions.txt')

Command Line Arguments

You can override some settings via command line:

python main.py [--output {console,file,email}] [--output-file FILE] [--debug]

Options:

• --output: Output destination (console, file, or email)
• --output-file: File path when output is set to file (overrides OUTPUT_FILE_NAME)
• --debug: Enable debug mode (overrides DEBUG_MODE)

🔒 Security Best Practices

1. Never commit sensitive information

   • The .env file is included in .gitignore by default
   • Double-check that no API keys or passwords are committed to version control

2. Regularly rotate credentials

   • Periodically update your Gmail App Password
   • Revoke and regenerate API keys that may have been compromised

3. Use environment-specific configurations

   • Maintain separate .env files for development and production
   • Never use production credentials in development environments

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Melhores Cartões for the promotions data
• Groq for the LLM processing
• Python for making this all possible!