Improve the promt for sending email always

README.md

@@ -12,6 +12,12 @@ short_description: Agent for Topcoder Challenge
 
 An intelligent agent that helps developers discover and get notified about relevant Topcoder challenges based on their preferences.
 
+See `docs/` folder for all modules and refer to `demo.mov` for demo. It's running in https://huggingface.co/spaces/togitoon/tc-agent
+
+**IMPORTANT: Hugging face environment uses my personal email for sending emails, so it will end up in spam folder**
+
+**IMPORTANT: The images in the modules are hosted on git lfs, so use hugging face to be able to view those documents**
+
 ## Configuration
 
 ### Environment Variables
@@ -45,15 +51,53 @@ The daily notification schedule can be customized using the `DAILY_NOTIFICATION_
 - `"*/30 9-17 * * 1-5"` - Every 30 minutes during business hours (9 AM to 5 PM) on weekdays
 - `"*/5 * * * *"` - Every 5 minutes (for testing)
 
-To override the default schedule, set the environment variable:
+To override the default schedule, set the environment variable for local development to see it in action:
 ```bash
-export DAILY_NOTIFICATION_CRON="0 9 * * 1-5"  # Weekdays at 9:00 AM UTC
+export DAILY_NOTIFICATION_CRON="*/5 * * * *"  # Every 5 mins
 ```
 
 ## Usage
 
 ### 1. Setup Environment
 
+Before running the application, you'll need to set up accounts with the following SaaS providers. All of them offer generous free tiers that are perfect for getting started:
+
+#### **Mistral AI** - AI Model Provider
+- **Free Tier**: Personal AI assistant with access to high-performing models, unlimited projects, voice mode, web searches, and more
+- **Sign up**: [https://chat.mistral.ai/](https://chat.mistral.ai/)
+- **API Access**: [https://console.mistral.ai/](https://console.mistral.ai/)
+- Get your API key from the console to use the `mistral-large-latest` model for intelligent challenge matching
+
+#### **Supabase** - Database & Backend
+- **Free Tier**: 500MB database, 50,000 monthly active users, 5GB bandwidth, 1GB file storage
+- **Sign up**: [https://supabase.com/dashboard/new?plan=free](https://supabase.com/dashboard/new?plan=free)
+- **Pricing**: [https://supabase.com/pricing](https://supabase.com/pricing)
+- **Setup Steps**:
+  1. Create a new project and verify your email address when prompted
+  2. Navigate to Settings → API to get your `SUPABASE_URL` and `SUPABASE_ANON_KEY`
+  3. Go to SQL Editor in your Supabase dashboard
+  4. Copy the contents of `database/supabase_schema.sql` and paste it into the editor
+  5. Click "Run" to create the required database tables and indexes
+
+#### **SendGrid** - Email Service
+- **Free Trial**: 60 days free, send up to 100 emails/day (no credit card required)
+- **Sign up**: [https://signup.sendgrid.com/](https://signup.sendgrid.com/)
+- **Pricing**: [https://sendgrid.com/pricing](https://sendgrid.com/pricing)
+- **Setup Steps**:
+  1. Create your account and verify your email address
+  2. **Important**: Set up Single Sender Verification in Settings → Sender Authentication
+     - Add your personal email address as a verified sender
+     - Click the verification link sent to your email
+     - This is required before you can send any emails through SendGrid
+  3. Navigate to Settings → API Keys to create your `SENDGRID_API_KEY`
+  4. For production use, consider Domain Authentication for better deliverability
+
+**Note**: SendGrid requires sender identity verification to prevent spam and maintain reputation. Single Sender Verification is perfect for testing, while Domain Authentication is recommended for production environments.
+
+#### Environment Variables Setup
+
+Once you have your accounts set up, configure the following environment variables:
+
 ```bash
 export MISTRAL_API_KEY="your_mistral_api_key"
 export SUPABASE_URL="your_supabase_url"
@@ -61,6 +105,8 @@ export SUPABASE_ANON_KEY="your_supabase_anon_key"
 export SENDGRID_API_KEY="your_sendgrid_api_key"
 ```
 
+**Why these services?** All three platforms are industry leaders that offer robust free tiers, making them perfect for development and small-scale production deployments. They scale seamlessly as your application grows, ensuring you only pay for what you actually use.
+
 ### 2. Install Dependencies
 
 ```bash

docs/module-8/Readme.md

@@ -0,0 +1,11 @@
+### Hugging Face Deployment
+
+## Step 1 
+
+Configure required variables as secret
+
+## Step 2 
+
+Let the build happen and application starts
+
+See: https://huggingface.co/spaces/togitoon/tc-agent

docs/module-9/Readme.md

@@ -0,0 +1 @@
+# See Readme in the root

prompts/challenge_prompts.py

@@ -64,7 +64,8 @@ User Preferences: {preferences}
 Your task:
 1. Query Topcoder for active challenges with good prizes (preferably $500+)
 2. Filter challenges that match the user's preferences
-3. If you find relevant challenges, send a professional email notification
+3. If you find relevant challenges, send a professional email notification.
+!!!IMPORTANT!!! If you find relevant challanges, always send an email using email tool
 
 Email Guidelines:
 - Subject should be compelling: "🏆 Relevant Topcoder Challenges Available"

tools/email_tool.py

@@ -2,34 +2,141 @@ from sendgrid import SendGridAPIClient
 from sendgrid.helpers.mail import Mail
 from strands import tool
 from config.settings import settings
+from typing import Dict, Union
 import logging
 
 logger = logging.getLogger(__name__)
 
-@tool
-def send_email(to: str, html_content: str, subject: str) -> str:
-    """Send an email notification about relevant Topcoder challenges"""
+@tool(
+    name="send_notification_email", 
+    description="Sends HTML email notifications about Topcoder challenges to registered users"
+)
+def send_email(to: str, html_content: str, subject: str) -> Dict[str, Union[str, list]]:
+    """Send an email notification about relevant Topcoder challenges using SendGrid.
     
-    logger.info(f"Sending email to {to} with subject: {subject}")
+    This tool handles the complete email delivery process including validation,
+    formatting, and error handling. It uses the configured SendGrid API to send
+    HTML-formatted challenge notifications to registered users.
     
-    # Use centralized configuration
+    Args:
+        to: The recipient's email address (must be a valid email format)
+        html_content: The HTML-formatted content of the email notification
+        subject: The subject line for the email notification
+        
+    Returns:
+        Dictionary with status and content indicating success or failure details
+    """
+    
+    logger.info(f"Attempting to send email to {to} with subject: '{subject}'")
+    
+    # Validate required configuration
     if not settings.SENDGRID_API_KEY:
-        error_msg = "SENDGRID_API_KEY environment variable is not set"
+        error_msg = "SENDGRID_API_KEY environment variable is not set. Please configure SendGrid API key."
+        logger.error(error_msg)
+        return {
+            "status": "error",
+            "content": [
+                {"text": error_msg}
+            ]
+        }
+    
+    if not settings.SENDGRID_FROM_EMAIL:
+        error_msg = "SENDGRID_FROM_EMAIL is not configured. Please set the sender email address."
+        logger.error(error_msg)
+        return {
+            "status": "error",
+            "content": [
+                {"text": error_msg}
+            ]
+        }
+    
+    # Validate input parameters
+    if not to or "@" not in to:
+        error_msg = f"Invalid recipient email address: {to}"
+        logger.error(error_msg)
+        return {
+            "status": "error",
+            "content": [
+                {"text": error_msg}
+            ]
+        }
+    
+    if not html_content.strip():
+        error_msg = "Email content cannot be empty"
         logger.error(error_msg)
-        raise ValueError(error_msg)
+        return {
+            "status": "error",
+            "content": [
+                {"text": error_msg}
+            ]
+        }
     
-    message = Mail(
-        from_email=settings.SENDGRID_FROM_EMAIL,
-        to_emails=to,
-        subject=subject,
-        html_content=html_content
-    )
+    if not subject.strip():
+        error_msg = "Email subject cannot be empty"
+        logger.error(error_msg)
+        return {
+            "status": "error",
+            "content": [
+                {"text": error_msg}
+            ]
+        }
     
+    # Construct the email message
+    try:
+        message = Mail(
+            from_email=settings.SENDGRID_FROM_EMAIL,
+            to_emails=to,
+            subject=subject,
+            html_content=html_content
+        )
+    except Exception as e:
+        error_msg = f"Failed to construct email message: {str(e)}"
+        logger.error(error_msg)
+        return {
+            "status": "error",
+            "content": [
+                {"text": error_msg}
+            ]
+        }
+    
+    # Send the email via SendGrid API
     try:
         sg = SendGridAPIClient(settings.SENDGRID_API_KEY)
         response = sg.send(message)
-        logger.info(f"Email sent successfully to {to}. Status: {response.status_code}")
-        return f"Mail sent successfully to {to}"
+        
+        # Check response status
+        if response.status_code in [200, 201, 202]:
+            success_msg = f"Email sent successfully to {to}"
+            logger.info(f"{success_msg}. SendGrid status: {response.status_code}")
+            return {
+                "status": "success",
+                "content": [
+                    {"text": success_msg},
+                    {"json": {
+                        "recipient": to,
+                        "subject": subject,
+                        "status_code": response.status_code,
+                        "message_id": response.headers.get("X-Message-Id", "N/A")
+                    }}
+                ]
+            }
+        else:
+            error_msg = f"SendGrid returned unexpected status code: {response.status_code}"
+            logger.warning(error_msg)
+            return {
+                "status": "error", 
+                "content": [
+                    {"text": error_msg},
+                    {"json": {"status_code": response.status_code, "response_body": str(response.body)}}
+                ]
+            }
+            
     except Exception as e:
-        logger.error(f"Error sending email to {to}: {str(e)}")
-        return f"Failed to send email to {to}: {str(e)}"
+        error_msg = f"Error sending email to {to}: {str(e)}"
+        logger.error(error_msg)
+        return {
+            "status": "error",
+            "content": [
+                {"text": error_msg}
+            ]
+        }