Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,53 @@
+# Environment variables
+.env
+.env.local
+.env.production
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Gradio
+.gradio/
+gradio_cached_examples/
+
+# Logs
+*.log
+
+# Database
+*.db
+*.sqlite3
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp 

DEPLOYMENT.md

@@ -0,0 +1,85 @@
+# 🚀 Deployment Guide for Hugging Face Spaces
+
+## Quick Deploy to Hugging Face Spaces
+
+### Option 1: Direct Upload
+1. **Create a new Space** on [Hugging Face Spaces](https://huggingface.co/spaces)
+2. **Choose "Gradio" as the SDK**
+3. **Upload these files** from the `deep_research` folder:
+   - `app.py`
+   - `deep_research.py`
+   - `requirements.txt`
+   - `README.md`
+   - `metadata.json`
+   - All the agent files (`*_agent.py`, `research_manager.py`)
+
+### Option 2: Git Repository
+1. **Create a new repository** or fork this one
+2. **Copy the `deep_research` folder contents** to the root of your repository
+3. **Create a new Space** and connect it to your repository
+
+## Environment Configuration
+
+In your Hugging Face Space settings, add these secrets:
+
+### Required
+- `OPENAI_API_KEY`: Your OpenAI API key
+
+### Optional (for email functionality)
+- `SENDGRID_API_KEY`: Your SendGrid API key
+- `SENDGRID_FROM_EMAIL`: Your verified sender email
+
+## Files Structure for Deployment
+
+```
+your-space/
+├── app.py                 # Main entry point for HF Spaces
+├── deep_research.py       # Core application logic
+├── requirements.txt       # Python dependencies
+├── README.md             # Space documentation
+├── metadata.json         # HF Spaces configuration
+├── research_manager.py   # Research orchestration
+├── clarifier_agent.py    # Clarification agent
+├── planner_agent.py      # Planning agent
+├── search_agent.py       # Search agent
+├── writer_agent.py       # Writing agent
+├── evaluator_agent.py    # Quality evaluation agent
+├── email_agent.py        # Email delivery agent
+├── .gitignore           # Git ignore rules
+└── env_example.txt      # Environment variables template
+```
+
+## Testing Your Deployment
+
+1. **Local Testing**: Run `python app.py` to test locally
+2. **Check Dependencies**: Ensure all imports work correctly
+3. **Environment Variables**: Test with your actual API keys
+4. **Gradio Interface**: Verify the UI loads and functions work
+
+## Common Issues & Solutions
+
+### Import Errors
+- Make sure all agent files are in the same directory
+- Verify `openai-agents` package is installed correctly
+
+### API Key Issues
+- Check that environment variables are set correctly in HF Spaces
+- Ensure OpenAI API key has sufficient credits
+
+### Email Functionality
+- Email features are optional and will be disabled if SendGrid isn't configured
+- Verify your SendGrid sender email is verified
+
+## Performance Tips
+
+- The app uses OpenAI's Agents framework which can take 1-2 minutes for complex research
+- Consider upgrading to a paid HF Spaces plan for better performance
+- Monitor usage to avoid API rate limits
+
+## Support
+
+If you encounter issues:
+1. Check the Space logs in Hugging Face
+2. Verify all environment variables are set
+3. Test locally first to isolate the issue
+4. Check OpenAI API status and quotas 

README.md

@@ -1,12 +1,169 @@
 ---
-title: Deep Research Assistant
-emoji: 😻
-colorFrom: red
-colorTo: indigo
-sdk: gradio
-sdk_version: 5.34.2
+title: Deep_Research_Assistant
 app_file: app.py
-pinned: false
+sdk: gradio
+sdk_version: 5.29.0
+---
+# 🔍 Deep Research Assistant
+
+[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces)
+[![Gradio](https://img.shields.io/badge/Gradio-Interface-orange)](https://gradio.app)
+
+A comprehensive AI-powered research assistant that delivers high-quality, well-researched reports with built-in quality assurance and email delivery capabilities.
+
+## 🚀 Features
+
+### 🤖 Enhanced AI Research System
+- **Quality Evaluation**: Every report is automatically assessed for completeness, accuracy, and clarity
+- **Smart Optimization**: Reports scoring below 7/10 are automatically improved
+- **Multi-Strategy Search**: Uses multiple search approaches for comprehensive coverage
+- **Email Delivery**: Optional email delivery of research reports
+
+### 🎯 Research Modes
+
+1. **🚀 Interactive Research with Clarification** (Recommended)
+   - Generates clarifying questions to focus your research
+   - Provides more targeted and relevant results
+   - Uses the enhanced quality assurance pipeline
+
+2. **🤖 Enhanced Direct Research**
+   - Advanced AI system with automatic quality evaluation
+   - Iterative improvement when needed
+   - Full traceability with OpenAI traces
+
+3. **⚡ Quick Research**
+   - Fast research for simple queries
+   - Legacy compatibility mode
+   - Good for straightforward questions
+
+## 🛠️ Setup
+
+### Environment Variables
+
+You'll need to set up the following environment variables:
+
+```bash
+# Required - OpenAI API for research
+OPENAI_API_KEY=your_openai_api_key_here
+
+# Optional - SendGrid for email delivery
+SENDGRID_API_KEY=your_sendgrid_api_key_here
+SENDGRID_FROM_EMAIL=your_verified_sender_email@example.com
+```
+
+### For Hugging Face Spaces Deployment
+
+1. **Fork this space** or create a new one
+2. **Add your secrets** in the Space settings:
+   - `OPENAI_API_KEY`: Your OpenAI API key
+   - `SENDGRID_API_KEY`: Your SendGrid API key (optional)
+   - `SENDGRID_FROM_EMAIL`: Your verified sender email (optional)
+3. **Deploy** - The space will automatically install dependencies and launch
+
+### For Local Development
+
+1. **Clone the repository**:
+   ```bash
+   git clone <your-repo-url>
+   cd deep_research
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. **Set up environment variables**:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your API keys
+   ```
+
+4. **Run the application**:
+   ```bash
+   python app.py
+   ```
+
+## 📊 Quality Assurance System
+
+Our enhanced research system includes automatic quality evaluation:
+
+### Evaluation Criteria
+- **Completeness**: How thoroughly the query is addressed
+- **Accuracy**: Factual correctness and source reliability  
+- **Clarity**: Writing quality and organization
+- **Depth**: Analysis depth and insight quality
+- **Relevance**: Content alignment with the original query
+
+### Scoring Scale
+- **9-10**: Excellent (no refinement needed)
+- **7-8**: Good (minor improvements)
+- **5-6**: Adequate (refinement recommended)
+- **1-4**: Poor (automatic refinement triggered)
+
+## 🎮 How to Use
+
+1. **Enter Your Research Query**: Describe what you want to research
+2. **Configure Email (Optional)**: Set up email delivery if desired
+3. **Choose Research Mode**:
+   - Click "🚀 Start Research" for interactive clarification mode
+   - Use "🤖 Enhanced Research" for direct advanced research
+   - Use "⚡ Quick Research" for fast results
+
+4. **Get Results**: 
+   - View comprehensive research report
+   - Receive email delivery (if configured)
+   - Access detailed trace logs for transparency
+
+## 🔧 Technical Architecture
+
+Built with:
+- **Frontend**: Gradio for interactive web interface
+- **Backend**: OpenAI Agents framework for modular AI system
+- **Quality Assurance**: Automated evaluation and optimization pipeline
+- **Email**: SendGrid integration for report delivery
+- **Tracing**: OpenAI trace integration for full transparency
+
+### Agent-Based Architecture
+
+The system uses specialized AI agents:
+- **Research Manager**: Orchestrates the entire research process
+- **Planner Agent**: Creates strategic search plans
+- **Search Agent**: Performs web searches
+- **Writer Agent**: Generates comprehensive reports
+- **Evaluator Agent**: Assesses report quality
+- **Optimizer Agent**: Improves reports when needed
+- **Email Agent**: Handles report delivery
+
+## 📝 Example Queries
+
+Try these example research queries:
+
+- "Latest developments in renewable energy storage technology"
+- "Impact of AI on healthcare industry in 2024"
+- "Sustainable urban planning strategies for climate change"
+- "Cybersecurity trends and threats in financial services"
+- "Electric vehicle market analysis and future projections"
+
+## 🤝 Contributing
+
+We welcome contributions! Areas for improvement:
+- Additional research sources and tools
+- Enhanced evaluation criteria
+- New output formats
+- UI/UX improvements
+- Performance optimizations
+
+## 📄 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙋‍♀️ Support
+
+- **Issues**: Report bugs or request features via GitHub Issues
+- **Documentation**: Check out the enhanced README in the repository
+- **Trace Logs**: Use the provided trace IDs to debug research processes
+
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+**Built with ❤️ using OpenAI Agents, Gradio, and modern AI research techniques.** 

app.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python3
+"""
+Deep Research Assistant - Hugging Face Spaces Deployment
+A comprehensive AI-powered research assistant with quality assurance.
+"""
+
+import os
+import gradio as gr
+from dotenv import load_dotenv
+import spaces
+
+# Load environment variables
+load_dotenv(override=True)
+
+# Import the main interface from deep_research.py
+from deep_research import ui
+
+if __name__ == "__main__":
+    # Launch the interface
+    # For Hugging Face Spaces, we don't need inbrowser=True and we want to set share=False
+    ui.launch(
+        server_name="0.0.0.0",  # Required for Hugging Face Spaces
+        server_port=7860,       # Standard port for Gradio on HF Spaces
+        share=False,            # Don't create public links on HF Spaces
+        inbrowser=False         # Don't try to open browser on server
+    ) 

clarifier_agent.py

@@ -0,0 +1,23 @@
+from typing import List
+from pydantic import BaseModel
+from agents import Agent
+
+class ClarificationData(BaseModel):
+    questions: List[str]
+
+CLARIFY_INSTRUCTIONS = """
+You are a Research Clarifier. Given a user's research query, generate exactly 3 clarifying questions 
+that will help focus and refine the research. These questions should help understand:
+1. The specific aspect or angle they want to focus on
+2. The depth or scope of research needed
+3. The intended use or audience for the research
+
+Return your response as JSON matching the ClarificationData model with exactly 3 questions.
+"""
+
+clarifier_agent = Agent(
+    name="ClarifierAgent",
+    instructions=CLARIFY_INSTRUCTIONS,
+    model="gpt-4o-mini",
+    output_type=ClarificationData,
+) 

deep_research.py

@@ -0,0 +1,619 @@
+import gradio as gr
+from dotenv import load_dotenv
+from research_manager import ResearchManager, ResearchManagerAgent
+from agents import Runner, trace, gen_trace_id
+
+load_dotenv(override=True)
+
+async def handle_query_submission(query: str, current_state: dict):
+    """Handle initial query submission - generate clarifying questions with progress"""
+    if not query.strip():
+        return "Please enter a research query.", gr.update(visible=False), gr.update(visible=False), current_state
+    
+    try:
+        # Show progress
+        progress_update = "🔄 **Generating clarifying questions...**\n\nPlease wait while our AI analyzes your query and creates focused questions to improve the research quality."
+        
+        research_manager = ResearchManager()
+        result = await research_manager.run_with_clarification(query)
+        
+        # Format questions for display
+        questions_text = "\n\n".join([f"**{i+1}.** {q}" for i, q in enumerate(result["questions"])])
+        display_text = f"**✅ Clarifying Questions Generated:**\n\n{questions_text}\n\n**Please answer these questions to help focus the research:**"
+        
+        # Update state with query and questions
+        new_state = {
+            "query": query,
+            "questions": result["questions"],
+            "trace_id": result["trace_id"]
+        }
+        
+        return display_text, gr.update(visible=True), gr.update(visible=True), new_state
+        
+    except Exception as e:
+        return f"❌ Error generating clarifying questions: {str(e)}", gr.update(visible=False), gr.update(visible=False), current_state
+
+async def handle_research_with_answers(answers: str, current_state: dict, email_address: str, send_email: bool):
+    """Handle research execution with clarification answers with progress updates"""
+    if not current_state.get("query"):
+        return "Please start by entering a research query first.", current_state
+    
+    if not answers.strip():
+        return "Please provide answers to the clarifying questions.", current_state
+    
+    try:
+        # Show progress
+        progress_message = f"""🔄 **Research in Progress...**
+
+**Original Query:** {current_state['query']}
+
+**Status:** Processing your clarifications and starting comprehensive research...
+
+⏳ This may take 1-2 minutes. We're:
+1. Planning search strategy
+2. Conducting multiple web searches  
+3. Writing initial report
+4. Evaluating quality
+5. Optimizing if needed
+6. Preparing final delivery"""
+        
+        # Use the enhanced manager with email settings
+        from research_manager import create_custom_research_agent
+        
+        # Parse answers (one per line)
+        answer_list = [line.strip() for line in answers.split('\n') if line.strip()]
+        
+        # Format the query with clarifications
+        clarified_query = f"""Original query: {current_state['query']}
+
+Clarifications provided:
+{chr(10).join([f"{i+1}. {answer}" for i, answer in enumerate(answer_list)])}
+
+Please use these clarifications to focus and refine the research approach."""
+        
+        # Create custom agent with email settings
+        custom_agent = create_custom_research_agent(
+            email_address=email_address if send_email else None,
+            send_email=send_email
+        )
+        
+        # Run research with custom agent
+        trace_id = gen_trace_id()
+        with trace("Focused Research with Clarifications", trace_id=trace_id):
+            result = await Runner.run(
+                custom_agent,
+                f"Research Query: {clarified_query}"
+            )
+        
+        email_status = ""
+        if send_email and email_address:
+            email_status = f"\n📧 **Email sent to:** {email_address}"
+        elif send_email and not email_address:
+            email_status = f"\n⚠️ **Email not sent:** No email address provided"
+        else:
+            email_status = f"\n📄 **Report generated:** Email sending disabled"
+        
+        final_report = f"""**✅ Research Complete!**
+
+**🔗 Trace ID:** {trace_id}
+
+**Original Query:** {current_state['query']}
+
+**📊 Enhanced Final Report:**
+
+{result.final_output}
+
+{email_status}
+
+---
+*Research completed using enhanced AI system with quality assurance and your clarifications.*"""
+        
+        return final_report, current_state
+        
+    except Exception as e:
+        return f"❌ Error during research: {str(e)}", current_state
+
+async def run_direct_research(query: str, email_address: str = "", send_email: bool = False):
+    """Run research directly without clarification using the new agent-based system"""
+    if not query.strip():
+        return "Please enter a research query."
+    
+    try:
+        trace_id = gen_trace_id()
+        with trace("Enhanced Research Manager", trace_id=trace_id):
+            print(f"🔗 Starting enhanced research with trace: {trace_id}")
+            
+            # Import the function here to avoid circular imports
+            from research_manager import create_custom_research_agent
+            
+            # Create agent with email settings
+            custom_agent = create_custom_research_agent(
+                email_address=email_address if send_email else None,
+                send_email=send_email
+            )
+            
+            # Use the custom agent
+            result = await Runner.run(
+                custom_agent,
+                f"Research Query: {query}"
+            )
+            
+            email_status = ""
+            if send_email and email_address:
+                email_status = f"\n📧 **Email sent to:** {email_address}"
+            elif send_email and not email_address:
+                email_status = f"\n⚠️ **Email not sent:** No email address provided"
+            else:
+                email_status = f"\n📄 **Report generated:** Email sending disabled"
+            
+            return f"""**✅ Research Complete!**
+
+**🔗 Trace ID:** {trace_id}
+**👀 View Detailed Trace:** https://platform.openai.com/traces/trace?trace_id={trace_id}
+
+**📊 Enhanced Research Report with Quality Assurance:**
+
+{result.final_output}
+
+{email_status}
+
+---
+*🤖 This research was conducted using our enhanced agent-based system with automatic quality evaluation and optimization. Check the trace link above to see the full workflow including planning, searching, writing, evaluation, and optimization steps.*"""
+             
+    except Exception as e:
+        import traceback
+        error_details = traceback.format_exc()
+        print(f"Error details: {error_details}")
+        return f"❌ Error during research: {str(e)}\n\nPlease try the Legacy Quick Research option if this persists."
+
+async def run_legacy_research(query: str, email_address: str, send_email: bool):
+    """Run research using the original ResearchManager class with email options"""
+    if not query.strip():
+        return "Please enter a research query."
+    
+    try:
+        # Use the enhanced system but call it "legacy" for the user
+        trace_id = gen_trace_id()
+        with trace("Quick Research", trace_id=trace_id):
+            from research_manager import create_custom_research_agent
+            
+            # Create agent with email settings
+            custom_agent = create_custom_research_agent(
+                email_address=email_address if send_email else None,
+                send_email=send_email
+            )
+            
+            result = await Runner.run(
+                custom_agent,
+                f"Research Query: {query}"
+            )
+            
+            email_status = ""
+            if send_email and email_address:
+                email_status = f"\n📧 **Email sent to:** {email_address}"
+            elif send_email and not email_address:
+                email_status = f"\n⚠️ **Email not sent:** No email address provided"
+            else:
+                email_status = f"\n📄 **Report generated:** Email sending disabled"
+            
+            return f"""**✅ Quick Research Complete!**
+
+**🔗 Trace ID:** {trace_id}
+
+**📊 Research Report:**
+
+{result.final_output}
+
+{email_status}
+
+---
+*Quick research completed successfully.*"""
+            
+    except Exception as e:
+        return f"❌ Error during research: {str(e)}"
+
+async def run_enhanced_research_with_progress(query: str, email_address: str = "", send_email: bool = False):
+    """Run enhanced research with real-time step-by-step progress updates"""
+    if not query.strip():
+        yield "Please enter a research query."
+        return
+    
+    # Import the new progress function
+    from research_manager import run_research_with_progress
+    
+    try:
+        # Collect all progress updates
+        progress_updates = []
+        async for update in run_research_with_progress(
+            query=query,
+            email_address=email_address if send_email else None,
+            send_email=send_email
+        ):
+            progress_updates.append(update)
+            # Return current progress to update the UI
+            yield "\n\n".join(progress_updates)
+        
+    except Exception as e:
+        import traceback
+        error_details = traceback.format_exc()
+        print(f"Error details: {error_details}")
+        yield f"❌ Error during research: {str(e)}\n\nPlease try a different approach if this persists."
+
+async def run_clarified_research_with_progress(answers: str, current_state: dict, email_address: str, send_email: bool):
+    """Handle research execution with clarification answers and real-time progress"""
+    if not current_state.get("query"):
+        yield "Please start by entering a research query first."
+        return
+    
+    if not answers.strip():
+        yield "Please provide answers to the clarifying questions."
+        return
+    
+    # Import the new progress function
+    from research_manager import run_research_with_progress
+    
+    try:
+        # Parse answers (one per line)
+        answer_list = [line.strip() for line in answers.split('\n') if line.strip()]
+        
+        # Format the query with clarifications
+        clarified_query = f"""Original query: {current_state['query']}
+
+Clarifications provided:
+{chr(10).join([f"{i+1}. {answer}" for i, answer in enumerate(answer_list)])}
+
+Please use these clarifications to focus and refine the research approach."""
+        
+        # Show initial setup
+        yield f"🚀 **Starting Focused Research with Clarifications**\n\n**Original Query:** {current_state['query']}\n\n**Your Clarifications:**\n{chr(10).join([f'• {answer}' for answer in answer_list if answer])}\n\n---\n\n"
+        
+        # Collect all progress updates
+        progress_updates = [f"🚀 **Starting Focused Research with Clarifications**\n\n**Original Query:** {current_state['query']}\n\n**Your Clarifications:**\n{chr(10).join([f'• {answer}' for answer in answer_list if answer])}\n\n---\n\n"]
+        
+        async for update in run_research_with_progress(
+            query=clarified_query,
+            email_address=email_address if send_email else None,
+            send_email=send_email
+        ):
+            progress_updates.append(update)
+            # Return current progress to update the UI
+            yield "\n\n".join(progress_updates)
+        
+    except Exception as e:
+        yield f"❌ Error during research: {str(e)}"
+
+# Custom CSS for better readability and contrast
+custom_css = """
+/* Main container improvements */
+.gradio-container {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif !important;
+}
+
+/* Ensure good contrast for all text inputs */
+.gradio-container input[type="text"],
+.gradio-container textarea {
+    background-color: #4b5563 !important;
+    border: 2px solid #6b7280 !important;
+    border-radius: 8px !important;
+    padding: 12px !important;
+    font-size: 14px !important;
+    color: #f9fafb !important;
+    font-weight: 400 !important;
+    line-height: 1.5 !important;
+    transition: border-color 0.2s ease !important;
+}
+
+.gradio-container input[type="text"]:focus,
+.gradio-container textarea:focus {
+    border-color: #60a5fa !important;
+    box-shadow: 0 0 0 3px rgba(96, 165, 250, 0.2) !important;
+    outline: none !important;
+}
+
+/* Placeholder styling for all inputs */
+.gradio-container input[type="text"]::placeholder,
+.gradio-container textarea::placeholder {
+    color: #9ca3af !important;
+    opacity: 0.8 !important;
+    font-style: italic !important;
+}
+
+/* Simple button styling with good contrast */
+.gradio-container button {
+    border-radius: 8px !important;
+    font-weight: 500 !important;
+    font-size: 14px !important;
+    padding: 8px 16px !important;
+    border: 2px solid transparent !important;
+    transition: all 0.2s ease !important;
+}
+
+/* Primary buttons */
+button[variant="primary"] {
+    background-color: #3b82f6 !important;
+    color: white !important;
+    border-color: #3b82f6 !important;
+}
+
+button[variant="primary"]:hover {
+    background-color: #2563eb !important;
+    border-color: #2563eb !important;
+}
+
+/* Secondary buttons */
+button[variant="secondary"] {
+    background-color: #f8fafc !important;
+    color: #374151 !important;
+    border-color: #d1d5db !important;
+}
+
+button[variant="secondary"]:hover {
+    background-color: #f1f5f9 !important;
+    border-color: #9ca3af !important;
+}
+
+/* Simple section styling */
+.clarification-section {
+    background-color: #374151 !important;
+    border: 2px solid #4b5563 !important;
+    border-radius: 12px !important;
+    padding: 20px !important;
+    margin: 16px 0 !important;
+    color: #ffffff !important;
+}
+
+.clarification-section * {
+    color: #ffffff !important;
+}
+
+.clarification-section h1, 
+.clarification-section h2, 
+.clarification-section h3 {
+    color: #ffffff !important;
+    font-weight: 600 !important;
+}
+
+/* Clean answer box */
+.answer-textbox {
+    background-color: #4b5563 !important;
+    border: 2px solid #6b7280 !important;
+    border-radius: 8px !important;
+    padding: 12px !important;
+    color: #d1d5db !important;
+    line-height: 1.5 !important;
+}
+
+.answer-textbox:focus {
+    border-color: #60a5fa !important;
+    box-shadow: 0 0 0 3px rgba(96, 165, 250, 0.2) !important;
+}
+
+/* Target the actual textarea element inside answer-textbox */
+.answer-textbox textarea {
+    background-color: #4b5563 !important;
+    color: #f9fafb !important;
+    border: 2px solid #6b7280 !important;
+    border-radius: 8px !important;
+    padding: 12px !important;
+    font-size: 14px !important;
+    font-weight: 400 !important;
+    line-height: 1.5 !important;
+}
+
+.answer-textbox textarea:focus {
+    border-color: #60a5fa !important;
+    box-shadow: 0 0 0 3px rgba(96, 165, 250, 0.2) !important;
+}
+
+/* Make sure placeholder text is visible on dark background */
+.answer-textbox textarea::placeholder {
+    color: #9ca3af !important;
+    opacity: 0.8 !important;
+    font-style: italic !important;
+}
+
+/* Make all textareas have proper white text */
+.gradio-container textarea {
+    color: #f9fafb !important;
+}
+
+.answer-textbox::placeholder {
+    color: #9ca3af !important;
+    opacity: 0.9 !important;
+}
+
+/* Results display with better contrast */
+.results-display {
+    background-color: #374151 !important;
+    border: 2px solid #4b5563 !important;
+    border-radius: 8px !important;
+    padding: 16px !important;
+    margin: 12px 0 !important;
+    color: #ffffff !important;
+    line-height: 1.6 !important;
+}
+
+/* Make sure markdown in results display also has white text */
+.results-display * {
+    color: #ffffff !important;
+}
+
+/* Style links in results display for visibility */
+.results-display a {
+    color: #60a5fa !important;
+    text-decoration: underline !important;
+}
+
+.results-display a:hover {
+    color: #93c5fd !important;
+}
+
+/* Accordion improvements */
+.gradio-accordion {
+    border: 1px solid #e5e7eb !important;
+    border-radius: 8px !important;
+    margin: 8px 0 !important;
+}
+
+/* Status indicators with good contrast */
+.status-success {
+    color: #059669 !important;
+    font-weight: 500 !important;
+}
+
+.status-info {
+    color: #0369a1 !important;
+    font-weight: 500 !important;
+}
+
+.status-warning {
+    color: #d97706 !important;
+    font-weight: 500 !important;
+}
+
+/* Simple headers */
+h1, h2, h3 {
+    color: #ffffff !important;
+    font-weight: 600 !important;
+}
+
+/* Remove unnecessary gradients and shadows for simplicity */
+* {
+    box-shadow: none !important;
+}
+
+/* Keep only essential shadows for depth */
+.gradio-container button,
+.gradio-container input,
+.gradio-container textarea {
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1) !important;
+}
+
+.gradio-container button:hover {
+    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15) !important;
+}
+"""
+
+with gr.Blocks(theme=gr.themes.Default(primary_hue="blue"), css=custom_css) as ui:
+    gr.Markdown("# 🔍 Deep Research Assistant")
+    gr.Markdown("**Ask a research question and get comprehensive, AI-powered analysis with quality assurance.**")
+    
+    # State to track the conversation
+    state = gr.State({})
+    
+    # Main Research Configuration Block
+    with gr.Column():
+        query_textbox = gr.Textbox(
+            label="Research Query", 
+            placeholder="What would you like to research? (e.g., 'Latest developments in renewable energy')",
+            lines=2,
+            elem_classes=["main-input"]
+        )
+        
+        # Email Configuration (part of main block)
+        with gr.Accordion("📧 Email Configuration (Optional)", open=False):
+            gr.Markdown("**Configure email delivery for your research reports**")
+            
+            with gr.Row():
+                with gr.Column(scale=3):
+                    email_textbox = gr.Textbox(
+                        label="Email Address", 
+                        placeholder="your.email@example.com",
+                        lines=1
+                    )
+                with gr.Column(scale=1):
+                    send_email_checkbox = gr.Checkbox(
+                        label="Send Email", 
+                        value=False,
+                        info="Check to receive the report via email"
+                    )
+            
+            gr.Markdown("*This email setting will be used for any research option you choose below.*")
+        
+        # Start Research Button (below the main configuration)
+        submit_button = gr.Button("🚀 Start Research", variant="primary", size="lg")
+    
+    # Output area for questions and results
+    output_area = gr.Markdown(
+        label="Research Progress", 
+        elem_classes=["results-display"],
+        value="👋 Enter your research query above and configure email settings if desired, then click Start Research!"
+    )
+    
+    # Clarification answers section (initially hidden)
+    with gr.Column(visible=False, elem_classes=["clarification-section"]) as clarification_row:
+        gr.Markdown("### 💭 Help us focus your research")
+        gr.Markdown("Please answer these questions to get more targeted results:")
+        
+        answers_textbox = gr.Textbox(
+            label="Your Answers", 
+            placeholder="Answer each question on a separate line...\n\nExample:\n1. I'm interested in solar and wind technologies\n2. I need technical details and market analysis\n3. This is for a business presentation",
+            lines=6,
+            elem_classes=["answer-textbox"],
+            show_label=True
+        )
+        
+        research_button = gr.Button(
+            "🔍 Run Focused Research", 
+            variant="primary", 
+            visible=False, 
+            size="lg"
+        )
+    
+    # Research options
+    with gr.Accordion("🤖 Enhanced Research (Recommended)", open=False):
+        gr.Markdown("""
+        **New AI-powered research system featuring:**
+        
+        ✅ **Quality Evaluation** - Each report is automatically assessed  
+        ✅ **Smart Optimization** - Reports are improved if needed  
+        ✅ **Comprehensive Analysis** - Multiple search strategies  
+        
+        *Delivers higher quality research through AI quality assurance.*
+        """)
+        enhanced_button = gr.Button("🤖 Enhanced Research", variant="primary")
+    
+    with gr.Accordion("⚡ Quick Research (Legacy)", open=False):
+        gr.Markdown("*Faster research using the original system - good for quick queries.*")
+        direct_button = gr.Button("⚡ Quick Research", variant="secondary")
+    
+    # Event handlers
+    submit_button.click(
+        fn=handle_query_submission,
+        inputs=[query_textbox, state],
+        outputs=[output_area, clarification_row, research_button, state]
+    )
+    
+    query_textbox.submit(
+        fn=handle_query_submission,
+        inputs=[query_textbox, state],
+        outputs=[output_area, clarification_row, research_button, state]
+    )
+    
+    research_button.click(
+        fn=run_clarified_research_with_progress,
+        inputs=[answers_textbox, state, email_textbox, send_email_checkbox],
+        outputs=[output_area]
+    )
+    
+    answers_textbox.submit(
+        fn=run_clarified_research_with_progress,
+        inputs=[answers_textbox, state, email_textbox, send_email_checkbox],
+        outputs=[output_area]
+    )
+    
+    enhanced_button.click(
+        fn=run_enhanced_research_with_progress,
+        inputs=[query_textbox, email_textbox, send_email_checkbox],
+        outputs=[output_area]
+    )
+    
+    direct_button.click(
+        fn=run_legacy_research,
+        inputs=[query_textbox, email_textbox, send_email_checkbox],
+        outputs=[output_area]
+    )
+
+if __name__ == "__main__":
+    ui.launch(inbrowser=True)
+

email_agent.py

@@ -0,0 +1,37 @@
+import os
+from typing import Dict
+
+import sendgrid
+from sendgrid.helpers.mail import Email, Mail, Content, To
+from agents import Agent, function_tool
+
+@function_tool
+def send_email(subject: str, html_body: str, recipient_email: str = "mallofrench05@gmail.com") -> Dict[str, str]:
+    """ Send an email with the given subject and HTML body to the specified recipient """
+    try:
+        sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
+        from_email = Email("mantomarchi300@outlook.com") # put your verified sender here
+        to_email = To(recipient_email)
+        content = Content("text/html", html_body)
+        mail = Mail(from_email, to_email, subject, content).get()
+        response = sg.client.mail.send.post(request_body=mail)
+        print(f"Email response: {response.status_code}")
+        
+        if response.status_code == 202:
+            return {"status": f"Email sent successfully to {recipient_email}"}
+        else:
+            return {"status": f"Email sending failed with status {response.status_code}"}
+    except Exception as e:
+        print(f"Email sending error: {e}")
+        return {"status": f"Email sending failed: {str(e)}"}
+
+INSTRUCTIONS = """You are able to send a nicely formatted HTML email based on a detailed report.
+You will be provided with a detailed report. You should use your tool to send one email, providing the 
+report converted into clean, well presented HTML with an appropriate subject line."""
+
+email_agent = Agent(
+    name="Email agent",
+    instructions=INSTRUCTIONS,
+    tools=[send_email],
+    model="gpt-4o-mini",
+)

env_example.txt

@@ -0,0 +1,14 @@
+# Copy this file to .env and fill in your actual values
+
+# OpenAI API Configuration (Required)
+OPENAI_API_KEY=your_openai_api_key_here
+
+# SendGrid Email Configuration (Optional)
+SENDGRID_API_KEY=your_sendgrid_api_key_here
+SENDGRID_FROM_EMAIL=your_verified_sender_email@example.com
+
+# OpenAI Organization (Optional)
+OPENAI_ORG_ID=your_openai_org_id_here
+
+# Environment Settings
+ENVIRONMENT=production 

evaluator_agent.py

@@ -0,0 +1,84 @@
+from pydantic import BaseModel
+from typing import List
+from agents import Agent
+
+class EvaluationResult(BaseModel):
+    overall_score: int
+    """Overall quality score from 1-10"""
+    
+    strengths: List[str]
+    """List of report strengths"""
+    
+    weaknesses: List[str]
+    """List of areas needing improvement"""
+    
+    suggestions: List[str]
+    """Specific suggestions for improvement"""
+    
+    needs_refinement: bool
+    """Whether the report needs to be refined"""
+    
+    refined_requirements: str
+    """If refinement needed, what specific requirements should guide it"""
+
+EVALUATION_INSTRUCTIONS = """
+You are a Research Quality Evaluator. Your job is to assess the quality of research reports and determine if they need refinement.
+
+Evaluate reports based on:
+1. **Completeness**: Does it thoroughly address the original query?
+2. **Accuracy**: Are the facts presented accurate and well-sourced?
+3. **Sources & Citations**: Does it include proper source links and references? Is there a "Sources and References" section?
+4. **Clarity**: Is the writing clear and well-structured?
+5. **Depth**: Does it provide sufficient depth and analysis?
+6. **Relevance**: Is all content relevant to the query?
+
+Scoring scale:
+- 9-10: Excellent, no refinement needed
+- 7-8: Good, minor improvements could help
+- 5-6: Adequate, would benefit from refinement
+- 1-4: Poor, definitely needs refinement
+
+CRITICAL: A report without proper source citations should not score above 6, regardless of other qualities.
+
+If needs_refinement is True, provide specific, actionable requirements for improvement.
+"""
+
+evaluator_agent = Agent(
+    name="Research Evaluator",
+    instructions=EVALUATION_INSTRUCTIONS,
+    model="gpt-4o-mini",
+    output_type=EvaluationResult,
+)
+
+
+class OptimizedReport(BaseModel):
+    improved_markdown_report: str
+    """The refined and improved version of the report"""
+    
+    optimization_notes: str
+    """Notes on what was improved and why"""
+
+OPTIMIZER_INSTRUCTIONS = """
+You are a Research Report Optimizer. You receive:
+1. An original research report
+2. Evaluation feedback with specific improvement suggestions
+3. The original query for context
+
+Your job is to create an improved version that addresses all the feedback while maintaining the factual content.
+
+Focus on:
+- Improving structure and flow
+- Adding missing analysis or details
+- Clarifying confusing sections
+- Ensuring complete coverage of the query
+- Enhancing readability and presentation
+
+Keep all factual content accurate - only improve presentation, structure, and completeness.
+"""
+
+optimizer_agent = Agent(
+    name="Research Optimizer", 
+    instructions=OPTIMIZER_INSTRUCTIONS,
+    model="gpt-4o-mini",
+    output_type=OptimizedReport,
+) 

metadata.json

@@ -0,0 +1,22 @@
+{
+  "title": "Deep Research Assistant",
+  "emoji": "🔍",
+  "colorFrom": "blue",
+  "colorTo": "purple",
+  "sdk": "gradio",
+  "sdk_version": "5.22.0",
+  "app_file": "app.py",
+  "pinned": false,
+  "license": "mit",
+  "short_description": "AI-powered research assistant with quality assurance and email delivery",
+  "tags": [
+    "research",
+    "ai",
+    "gradio",
+    "openai",
+    "quality-assurance",
+    "email",
+    "web-search"
+  ],
+  "hardware": "zero-a10g"
+} 

planner_agent.py

@@ -0,0 +1,28 @@
+from pydantic import BaseModel
+from agents import Agent
+
+HOW_MANY_SEARCHES = 3
+
+INSTRUCTIONS = f"You are a helpful research assistant. Given a query, come up with a set of web searches \
+to perform to best answer the query. Output {HOW_MANY_SEARCHES} terms to query for."
+
+
+class WebSearchItem(BaseModel):
+    reason: str
+    "Your reasoning for why this search is important to the query."
+
+    query: str
+    "The search term to use for the web search."
+
+
+class WebSearchPlan(BaseModel):
+    searches: list[WebSearchItem]
+    """A list of web searches to perform to best answer the query."""
+
+
+planner_agent = Agent(
+    name="PlannerAgent",
+    instructions=INSTRUCTIONS,
+    model="gpt-4o-mini",
+    output_type=WebSearchPlan,
+)

requirements.txt

@@ -0,0 +1,11 @@
+gradio>=5.22.0
+openai>=1.68.2
+openai-agents>=0.0.6
+python-dotenv>=1.0.1
+sendgrid>=6.11.0
+requests>=2.32.3
+bs4>=0.0.2
+httpx>=0.28.1
+pydantic>=2.0.0
+typing-extensions>=4.0.0
+spaces>=0.16.0 

research_manager.py

@@ -0,0 +1,506 @@
+from agents import Runner, trace, gen_trace_id, Agent, function_tool
+from search_agent import search_agent
+from planner_agent import planner_agent, WebSearchItem, WebSearchPlan
+from writer_agent import writer_agent, ReportData
+from email_agent import email_agent
+from clarifier_agent import clarifier_agent, ClarificationData
+from evaluator_agent import evaluator_agent, optimizer_agent, EvaluationResult, OptimizedReport
+import asyncio
+from typing import Dict, Any, AsyncGenerator
+
+# Legacy ResearchManager class for backward compatibility
+class ResearchManager:
+
+    async def run_with_clarification(self, query: str):
+        """ Run the clarification step and return clarifying questions """
+        trace_id = gen_trace_id()
+        with trace("Clarification trace", trace_id=trace_id):
+            print(f"View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}")
+            print("Generating clarifying questions...")
+            
+            result = await Runner.run(
+                clarifier_agent,
+                f"Query: {query}",
+            )
+            
+            clarification_data = result.final_output_as(ClarificationData)
+            print(f"Generated {len(clarification_data.questions)} clarifying questions")
+            
+            return {
+                "questions": clarification_data.questions,
+                "trace_id": trace_id
+            }
+
+    async def run_research_with_answers(self, query: str, answers: list[str]):
+        """ Run the full research process with clarification answers """
+        trace_id = gen_trace_id()
+        with trace("Research with clarification trace", trace_id=trace_id):
+            print(f"View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}")
+            print("Starting research with clarifications...")
+            
+            # Use the new manager agent instead
+            clarified_query = self._format_clarified_query(query, answers)
+            
+            result = await Runner.run(
+                ResearchManagerAgent,
+                f"Research Query: {clarified_query}",
+            )
+            
+            return {
+                "report": result.final_output,
+                "trace_id": trace_id
+            }
+
+    def _format_clarified_query(self, original_query: str, answers: list[str]) -> str:
+        """ Format the original query with clarification answers """
+        clarifications = []
+        for i, answer in enumerate(answers, 1):
+            if answer.strip():
+                clarifications.append(f"{i}. {answer.strip()}")
+        
+        if clarifications:
+            clarified_query = f"""Original query: {original_query}
+
+Clarifications provided:
+{chr(10).join(clarifications)}
+
+Please use these clarifications to focus and refine the research approach."""
+        else:
+            clarified_query = original_query
+            
+        return clarified_query
+
+    async def run(self, query: str):
+        """ Run the deep research process, yielding the status updates and the final report"""
+        trace_id = gen_trace_id()
+        with trace("Research trace", trace_id=trace_id):
+            print(f"View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}")
+            yield f"View trace: https://platform.openai.com/traces/trace?trace_id={trace_id}"
+            print("Starting research...")
+            
+            # Use the new manager agent
+            result = await Runner.run(ResearchManagerAgent, f"Research Query: {query}")
+            yield "Research complete"
+            yield result.final_output
+
+# Function tools for the manager agent to orchestrate the research process
+@function_tool
+async def plan_research(query: str) -> Dict[str, Any]:
+    """ Plan the research searches for a given query """
+    print("Planning searches...")
+    result = await Runner.run(planner_agent, f"Query: {query}")
+    search_plan = result.final_output_as(WebSearchPlan)
+    print(f"Will perform {len(search_plan.searches)} searches")
+    return {
+        "searches": [{"query": item.query, "reason": item.reason} for item in search_plan.searches],
+        "plan_ready": True
+    }
+
+@function_tool
+async def perform_search(search_query: str, reason: str) -> str:
+    """ Perform a single web search and return summarized results """
+    print(f"Searching for: {search_query}")
+    input_text = f"Search term: {search_query}\nReason for searching: {reason}"
+    try:
+        result = await Runner.run(search_agent, input_text)
+        return str(result.final_output)
+    except Exception as e:
+        print(f"Search failed for '{search_query}': {e}")
+        return f"Search failed for '{search_query}': {str(e)}"
+
+@function_tool
+async def write_initial_report(query: str, search_results: str) -> Dict[str, Any]:
+    """ Generate an initial research report from search results """
+    print("Writing initial report...")
+    input_text = f"Original query: {query}\nSummarized search results: {search_results}"
+    result = await Runner.run(writer_agent, input_text)
+    report_data = result.final_output_as(ReportData)
+    print("Initial report completed")
+    return {
+        "markdown_report": report_data.markdown_report,
+        "short_summary": report_data.short_summary,
+        "follow_up_questions": report_data.follow_up_questions
+    }
+
+@function_tool
+async def evaluate_report(query: str, report: str) -> Dict[str, Any]:
+    """ Evaluate the quality of a research report """
+    print("Evaluating report quality...")
+    input_text = f"Original Query: {query}\n\nReport to Evaluate:\n{report}"
+    result = await Runner.run(evaluator_agent, input_text)
+    evaluation = result.final_output_as(EvaluationResult)
+    print(f"Evaluation complete - Score: {evaluation.overall_score}/10, Needs refinement: {evaluation.needs_refinement}")
+    return {
+        "score": evaluation.overall_score,
+        "strengths": evaluation.strengths,
+        "weaknesses": evaluation.weaknesses,
+        "suggestions": evaluation.suggestions,
+        "needs_refinement": evaluation.needs_refinement,
+        "refinement_requirements": evaluation.refined_requirements
+    }
+
+@function_tool
+async def optimize_report(query: str, original_report: str, evaluation_feedback: str) -> str:
+    """ Optimize and improve a research report based on evaluation feedback """
+    print("Optimizing report...")
+    input_text = f"""Original Query: {query}
+
+Original Report:
+{original_report}
+
+Evaluation Feedback:
+{evaluation_feedback}
+
+Please improve the report based on this feedback."""
+    
+    result = await Runner.run(optimizer_agent, input_text)
+    optimized = result.final_output_as(OptimizedReport)
+    print("Report optimization complete")
+    return optimized.improved_markdown_report
+
+# Regular function that can be called directly
+async def _send_report_email_to_address(report: str, recipient_email: str) -> Dict[str, str]:
+    """ Send the final research report via email to a specific address """
+    import os
+    import sendgrid
+    from sendgrid.helpers.mail import Email, Mail, Content, To
+    
+    print(f"Sending email to: {recipient_email}")
+    
+    try:
+        sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
+        from_email = Email("mantomarchi300@outlook.com")  # Verified sender
+        to_email = To(recipient_email)  # User-provided email
+        
+        # Create a nice subject line
+        subject = "🔍 Your Research Report is Ready"
+        
+        # Convert markdown to HTML for better email formatting
+        import re
+        
+        # Basic markdown to HTML conversion
+        html_report = report
+        
+        # Convert markdown links to HTML links with styling
+        html_report = re.sub(r'\[([^\]]+)\]\(([^)]+)\)', r'<a href="\2" style="color: #2563eb; text-decoration: none; border-bottom: 1px solid #2563eb;" target="_blank">\1</a>', html_report)
+        
+        # Convert headers
+        html_report = re.sub(r'^### (.*$)', r'<h3 style="color: #2563eb; margin-top: 25px; margin-bottom: 10px;">\1</h3>', html_report, flags=re.MULTILINE)
+        html_report = re.sub(r'^## (.*$)', r'<h2 style="color: #1d4ed8; margin-top: 30px; margin-bottom: 15px;">\1</h2>', html_report, flags=re.MULTILINE)
+        html_report = re.sub(r'^# (.*$)', r'<h1 style="color: #1e40af; margin-top: 35px; margin-bottom: 20px;">\1</h1>', html_report, flags=re.MULTILINE)
+        
+        # Convert bold text
+        html_report = re.sub(r'\*\*(.*?)\*\*', r'<strong style="color: #374151;">\1</strong>', html_report)
+        
+        # Convert numbered lists (for sources)
+        html_report = re.sub(r'^(\d+\.\s)(.*$)', r'<li style="margin-bottom: 8px; list-style-type: decimal;">\2</li>', html_report, flags=re.MULTILINE)
+        
+        # Convert bullet points
+        html_report = re.sub(r'^- (.*$)', r'<li style="margin-bottom: 8px;">\1</li>', html_report, flags=re.MULTILINE)
+        
+        # Wrap consecutive list items in ul/ol tags
+        html_report = re.sub(r'(<li style="margin-bottom: 8px; list-style-type: decimal;">.*?</li>)', r'<ol style="margin: 15px 0; padding-left: 25px;">\1</ol>', html_report, flags=re.DOTALL)
+        html_report = re.sub(r'(<li style="margin-bottom: 8px;">.*?</li>)', r'<ul style="margin: 15px 0; padding-left: 25px;">\1</ul>', html_report, flags=re.DOTALL)
+        
+        # Convert line breaks
+        html_report = html_report.replace('\n\n', '</p><p style="margin-bottom: 15px; line-height: 1.6;">')
+        html_report = '<p style="margin-bottom: 15px; line-height: 1.6;">' + html_report + '</p>'
+        
+        html_content = f"""
+        <!DOCTYPE html>
+        <html lang="en">
+        <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>Your Research Report</title>
+        </head>
+        <body style="font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; line-height: 1.6; color: #374151; background-color: #f9fafb; margin: 0; padding: 20px;">
+            <div style="max-width: 800px; margin: 0 auto; background: #ffffff; border-radius: 12px; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.07); overflow: hidden;">
+                <!-- Header -->
+                <div style="background: linear-gradient(135deg, #2563eb 0%, #1d4ed8 100%); color: white; padding: 30px; text-align: center;">
+                    <h1 style="margin: 0; font-size: 28px; font-weight: 600;">
+                        🔍 Your Research Report
+                    </h1>
+                    <p style="margin: 10px 0 0 0; opacity: 0.9; font-size: 16px;">
+                        Comprehensive AI-powered research analysis
+                    </p>
+                </div>
+                
+                <!-- Content -->
+                <div style="padding: 40px 30px;">
+                    <div style="background: #f8fafc; padding: 30px; border-radius: 8px; border-left: 4px solid #2563eb; margin-bottom: 30px;">
+                        {html_report}
+                    </div>
+                </div>
+                
+                <!-- Footer -->
+                <div style="background: #f8fafc; padding: 25px 30px; border-top: 1px solid #e5e7eb;">
+                    <div style="text-align: center; color: #6b7280; font-size: 14px;">
+                        <p style="margin: 0 0 10px 0;">
+                            <strong>🤖 Generated by Deep Research Assistant</strong>
+                        </p>
+                        <p style="margin: 0;">
+                            This report was created using advanced AI with multi-step quality assurance
+                        </p>
+                        <div style="margin-top: 15px; padding-top: 15px; border-top: 1px solid #d1d5db;">
+                            <p style="margin: 0; font-size: 12px; color: #9ca3af;">
+                                Thank you for using our research service • Generated on {__import__('datetime').datetime.now().strftime('%B %d, %Y at %I:%M %p')}
+                            </p>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </body>
+        </html>
+        """
+        
+        content = Content("text/html", html_content)
+        mail = Mail(from_email, to_email, subject, content).get()
+        response = sg.client.mail.send.post(request_body=mail)
+        
+        print(f"Email response: {response.status_code}")
+        if response.status_code == 202:
+            return {"status": f"Email sent successfully to {recipient_email}"}
+        else:
+            return {"status": f"Email sending failed with status {response.status_code}"}
+            
+    except Exception as e:
+        print(f"Email sending error: {e}")
+        return {"status": f"Email sending failed: {str(e)}"}
+
+@function_tool
+async def send_report_email_to_address(report: str, recipient_email: str) -> Dict[str, str]:
+    """ Send the final research report via email to a specific address """
+    return await _send_report_email_to_address(report, recipient_email)
+
+@function_tool
+async def send_report_email(report: str) -> Dict[str, str]:
+    """ Send the final research report via email (legacy function - uses hardcoded email) """
+    print("Sending email to default address...")
+    result = await Runner.run(email_agent, report)
+    print("Email sent to default address")
+    return {"status": "Email sent successfully to default address"}
+
+# Manager Agent Instructions
+MANAGER_INSTRUCTIONS = """
+You are the Research Manager Agent responsible for orchestrating a comprehensive research process with quality assurance.
+
+Your workflow:
+
+1. **PLAN**: Use plan_research to create a search strategy for the query
+2. **SEARCH**: Use perform_search for each planned search item to gather information
+3. **INITIAL REPORT**: Use write_initial_report to create a first draft from all search results
+4. **EVALUATE**: Use evaluate_report to assess the quality of the initial report
+5. **OPTIMIZE** (if needed): If evaluation shows needs_refinement=True, use optimize_report to improve it
+6. **FINALIZE**: Use send_report_email_to_address to deliver the final report
+
+Quality Standards:
+- Only proceed to email if the report scores 7+ or has been optimized
+- If a report needs refinement, always optimize it before sending
+- Ensure comprehensive coverage of the original query
+- Maintain high standards for accuracy and completeness
+
+Be methodical and ensure each step completes successfully before proceeding to the next.
+"""
+
+# Function to create custom research agent with email options
+def create_custom_research_agent(email_address: str = None, send_email: bool = False):
+    """Create a research manager agent with custom email settings"""
+    
+    if send_email and email_address:
+        # Include email sending in tools
+        tools = [
+            plan_research,
+            perform_search, 
+            write_initial_report,
+            evaluate_report,
+            optimize_report,
+            send_report_email_to_address
+        ]
+        
+        instructions = f"""
+You are the Research Manager Agent responsible for orchestrating a comprehensive research process with quality assurance.
+
+Your workflow:
+
+1. **PLAN**: Use plan_research to create a search strategy for the query
+2. **SEARCH**: Use perform_search for each planned search item to gather information
+3. **INITIAL REPORT**: Use write_initial_report to create a first draft from all search results
+4. **EVALUATE**: Use evaluate_report to assess the quality of the initial report
+5. **OPTIMIZE** (if needed): If evaluation shows needs_refinement=True, use optimize_report to improve it
+6. **FINALIZE**: Use send_report_email_to_address with the report and recipient email "{email_address}" to deliver the final report
+
+Quality Standards:
+- Only proceed to email if the report scores 7+ or has been optimized
+- If a report needs refinement, always optimize it before sending
+- Ensure comprehensive coverage of the original query
+- Maintain high standards for accuracy and completeness
+
+IMPORTANT: When using send_report_email_to_address, you must provide both:
+- The final report text as the first parameter
+- The recipient email address "{email_address}" as the second parameter
+
+Be methodical and ensure each step completes successfully before proceeding to the next.
+The user has requested the report be emailed to: {email_address}
+"""
+    else:
+        # Exclude email sending from tools
+        tools = [
+            plan_research,
+            perform_search, 
+            write_initial_report,
+            evaluate_report,
+            optimize_report
+        ]
+        
+        instructions = """
+You are the Research Manager Agent responsible for orchestrating a comprehensive research process with quality assurance.
+
+Your workflow:
+
+1. **PLAN**: Use plan_research to create a search strategy for the query
+2. **SEARCH**: Use perform_search for each planned search item to gather information
+3. **INITIAL REPORT**: Use write_initial_report to create a first draft from all search results
+4. **EVALUATE**: Use evaluate_report to assess the quality of the initial report
+5. **OPTIMIZE** (if needed): If evaluation shows needs_refinement=True, use optimize_report to improve it
+6. **COMPLETE**: Return the final optimized report (do NOT send email - user chose not to receive email)
+
+Quality Standards:
+- Complete the process when report scores 7+ or has been optimized
+- If a report needs refinement, always optimize it before completing
+- Ensure comprehensive coverage of the original query
+- Maintain high standards for accuracy and completeness
+
+Be methodical and ensure each step completes successfully before proceeding to the next.
+The user has chosen NOT to receive the report via email.
+"""
+
+    return Agent(
+        name=f"Custom Research Manager Agent",
+        instructions=instructions,
+        tools=tools,
+        model="gpt-4o-mini",
+        handoff_description="Orchestrate comprehensive research with quality assurance and optional email delivery"
+    )
+
+# Create the Research Manager Agent with agents-as-tools
+ResearchManagerAgent = Agent(
+    name="Research Manager Agent",
+    instructions=MANAGER_INSTRUCTIONS,
+    tools=[
+        plan_research,
+        perform_search, 
+        write_initial_report,
+        evaluate_report,
+        optimize_report,
+        send_report_email_to_address
+    ],
+    model="gpt-4o-mini",
+    handoff_description="Orchestrate comprehensive research with quality assurance and optimization"
+)
+
+async def run_research_with_progress(query: str, email_address: str = None, send_email: bool = False) -> AsyncGenerator[str, None]:
+    """Run research with step-by-step progress updates"""
+    trace_id = gen_trace_id()
+    
+    yield f"🚀 **Starting Enhanced Research**\n\n**Query:** {query}\n\n**Trace ID:** {trace_id}\n\n---\n\n"
+    
+    try:
+        with trace("Enhanced Research with Progress", trace_id=trace_id):
+            # Step 1: Planning
+            yield "📋 **Step 1/6:** Planning research strategy...\n\n*Analyzing your query and determining the best search approach*"
+            
+            result = await Runner.run(planner_agent, f"Query: {query}")
+            search_plan = result.final_output_as(WebSearchPlan)
+            
+            yield f"✅ **Planning Complete** - Will perform {len(search_plan.searches)} targeted searches\n\n---\n\n"
+            
+            # Step 2: Searching
+            yield "🔍 **Step 2/6:** Conducting web searches...\n\n*Gathering information from multiple sources*"
+            
+            search_results = []
+            for i, search_item in enumerate(search_plan.searches, 1):
+                yield f"🔍 **Search {i}/{len(search_plan.searches)}:** {search_item.query}\n\n*{search_item.reason}*"
+                
+                try:
+                    input_text = f"Search term: {search_item.query}\nReason for searching: {search_item.reason}"
+                    result = await Runner.run(search_agent, input_text)
+                    search_results.append(str(result.final_output))
+                    yield f"✅ **Search {i} Complete**\n\n"
+                except Exception as e:
+                    yield f"⚠️ **Search {i} Failed:** {str(e)}\n\n"
+                    search_results.append(f"Search failed: {str(e)}")
+            
+            yield "✅ **All Searches Complete**\n\n---\n\n"
+            
+            # Step 3: Writing Initial Report
+            yield "✍️ **Step 3/6:** Writing initial research report...\n\n*Analyzing and synthesizing all gathered information*"
+            
+            combined_results = "\n\n".join(search_results)
+            input_text = f"Original query: {query}\nSummarized search results: {combined_results}"
+            result = await Runner.run(writer_agent, input_text)
+            report_data = result.final_output_as(ReportData)
+            
+            yield "✅ **Initial Report Complete**\n\n---\n\n"
+            
+            # Step 4: Evaluating Quality
+            yield "🔍 **Step 4/6:** Evaluating report quality...\n\n*AI quality assessment in progress*"
+            
+            input_text = f"Original Query: {query}\n\nReport to Evaluate:\n{report_data.markdown_report}"
+            result = await Runner.run(evaluator_agent, input_text)
+            evaluation = result.final_output_as(EvaluationResult)
+            
+            yield f"✅ **Evaluation Complete** - Score: {evaluation.overall_score}/10\n\n"
+            
+            final_report = report_data.markdown_report
+            
+            # Step 5: Optimization (if needed)
+            if evaluation.needs_refinement:
+                yield "🔧 **Step 5/6:** Optimizing report quality...\n\n*Improving report based on evaluation feedback*"
+                
+                feedback = f"Score: {evaluation.overall_score}/10\nWeaknesses: {evaluation.weaknesses}\nSuggestions: {evaluation.suggestions}"
+                input_text = f"""Original Query: {query}
+
+Original Report:
+{report_data.markdown_report}
+
+Evaluation Feedback:
+{feedback}
+
+Please improve the report based on this feedback."""
+                
+                result = await Runner.run(optimizer_agent, input_text)
+                optimized = result.final_output_as(OptimizedReport)
+                final_report = optimized.improved_markdown_report
+                
+                yield "✅ **Optimization Complete** - Report quality improved\n\n---\n\n"
+            else:
+                yield "✅ **No Optimization Needed** - Report quality is excellent\n\n---\n\n"
+            
+            # Step 6: Email Delivery (if requested)
+            if send_email and email_address:
+                yield f"📧 **Step 6/6:** Sending report to {email_address}...\n\n*Preparing and delivering your research report*"
+                
+                try:
+                    # Call the regular function directly
+                    result = await _send_report_email_to_address(final_report, email_address)
+                    yield f"✅ **Email Sent Successfully** to {email_address}\n\n---\n\n"
+                except Exception as e:
+                    yield f"❌ **Email Failed:** {str(e)}\n\n---\n\n"
+            else:
+                yield "📄 **Step 6/6:** Finalizing report...\n\n*Email delivery not requested*\n\n---\n\n"
+            
+            # Final result
+            yield f"""🎉 **Research Complete!**
+
+**📊 Final Report:**
+
+{final_report}
+
+**🔗 View Full Trace:** https://platform.openai.com/traces/trace?trace_id={trace_id}
+
+---
+*Enhanced research completed with quality assurance*"""
+            
+    except Exception as e:
+        yield f"❌ **Error during research:** {str(e)}"

search_agent.py

@@ -0,0 +1,23 @@
+from agents import Agent, WebSearchTool, ModelSettings
+
+INSTRUCTIONS = (
+    "You are a research assistant. Given a search term, you search the web for that term and "
+    "produce a concise summary of the results. The summary must be 2-3 paragraphs and less than 300 "
+    "words. Capture the main points. Write succintly, no need to have complete sentences or good "
+    "grammar. This will be consumed by someone synthesizing a report, so it's vital you capture the "
+    "essence and ignore any fluff. "
+    
+    "IMPORTANT: Always preserve and include the source URLs that are provided in the search results. "
+    "When you mention information from a source, include the URL reference in the format: (source.com) "
+    "or [Title](URL). Keep all source links intact in your summary."
+    
+    "Do not include any additional commentary other than the summary itself with preserved source links."
+)
+
+search_agent = Agent(
+    name="Search agent",
+    instructions=INSTRUCTIONS,
+    tools=[WebSearchTool(search_context_size="low")],
+    model="gpt-4o-mini",
+    model_settings=ModelSettings(tool_choice="required"),
+)

writer_agent.py

@@ -0,0 +1,39 @@
+from pydantic import BaseModel
+from agents import Agent
+
+INSTRUCTIONS = (
+    "You are a senior researcher tasked with writing a cohesive report for a research query. "
+    "You will be provided with the original query, and some initial research done by a research assistant.\n"
+    "You should first come up with an outline for the report that describes the structure and "
+    "flow of the report. Then, generate the report and return that as your final output.\n"
+    "The final output should be in markdown format, and it should be lengthy and detailed. Aim "
+    "for 5-10 pages of content, at least 1000 words.\n\n"
+    
+    "IMPORTANT SOURCE HANDLING:\n"
+    "- Preserve all source URLs and references from the research summaries\n"
+    "- Include inline citations throughout your report using the format: [Source Name](URL)\n"
+    "- At the end of your report, create a dedicated '## Sources and References' section\n"
+    "- In the Sources section, list all unique URLs mentioned in the report in a numbered list\n"
+    "- Format sources as: '1. [Website Name/Title](full URL)'\n"
+    "- Ensure no source links are lost during synthesis\n"
+    "- If you cannot find source URLs in the research, note 'Sources: Based on web research summaries'"
+)
+
+
+class ReportData(BaseModel):
+    short_summary: str
+    """A short 2-3 sentence summary of the findings."""
+
+    markdown_report: str
+    """The final report"""
+
+    follow_up_questions: list[str]
+    """Suggested topics to research further"""
+
+
+writer_agent = Agent(
+    name="WriterAgent",
+    instructions=INSTRUCTIONS,
+    model="gpt-4o-mini",
+    output_type=ReportData,
+)