Add initial implementation of deep research agents and email functionality

- Created app.py for user interface with Gradio, allowing users to input research queries and receive reports via email.
- Implemented deep_research_agents including:
- email_agent.py for sending formatted HTML emails using SendGrid.
- planner_agent.py for generating search plans based on user queries.
- research_manager.py to orchestrate the research process, including planning searches, performing them, writing reports, and sending emails.
- search_agent.py for summarizing search results.
- writer_agent.py for generating detailed reports from research findings.
- Integrated dotenv for environment variable management.
- Added support for dynamic email recipients in research reports.
- Established a cohesive flow for research tasks and email notifications.

app.py

@@ -0,0 +1,66 @@
+import gradio as gr
+from dotenv import load_dotenv
+from deep_research_agent.research_manager import ResearchManager
+import sendgrid
+from sendgrid.helpers.mail import Email, Mail, Content, To
+import os
+import ssl
+ssl._create_default_https_context = ssl._create_unverified_context
+
+load_dotenv(override=True)
+
+# Custom email sender to use the user's email
+async def send_email_to_user(subject: str, html_body: str, user_email: str):
+    sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
+    from_email = Email("liorsolomon.solid@gmail.com")  # put your verified sender here
+    to_email = To(user_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("Email response", response.status_code)
+    return {"status": "success"}
+
+# Patch the ResearchManager to allow dynamic recipient email
+def make_research_manager_with_email(user_email):
+    class PatchedResearchManager(ResearchManager):
+        async def send_email(self, report):
+            subject = "Your Deep Research Report"
+            html_body = report.markdown_report.replace('\n', '<br>')
+            await send_email_to_user(subject, html_body, user_email)
+            return report
+    return PatchedResearchManager()
+
+async def run_research(query: str, user_email: str):
+    manager = make_research_manager_with_email(user_email)
+    yield "<b>🔍 Research started! Please wait while we process your request...</b>"
+    async for chunk in manager.run(query):
+        # Show step-by-step progress to the user
+        if chunk.startswith("View trace: "):
+            yield f"<i>Trace available: <a href='{chunk[11:]}' target='_blank'>{chunk[11:]}</a></i>"
+        elif chunk.lower().startswith("searches planned"):
+            yield "<b>📝 Searches planned. Starting to search the web...</b>"
+        elif chunk.lower().startswith("searches complete"):
+            yield "<b>✅ Searches complete. Writing the report...</b>"
+        elif chunk.lower().startswith("report written"):
+            yield "<b>🖊️ Report written. Sending the report to your email...</b>"
+        elif chunk.lower().startswith("email sent"):
+            yield "<b>📧 Email sent! Research complete. See your inbox for the full report.</b>"
+        elif chunk.strip().startswith('#'):
+            yield chunk
+        else:
+            yield f"<i>{chunk}</i>"
+
+with gr.Blocks(theme=gr.themes.Default(primary_hue="sky")) as ui:
+    gr.Markdown("# Deep Research Chatbot\nEnter your email and research topic. You'll receive a detailed report by email!")
+    with gr.Row():
+        email_box = gr.Textbox(label="Your Email", type="text", placeholder="your@email.com")
+        query_box = gr.Textbox(label="Research Query", lines=3, placeholder="What would you like to research?")
+    run_btn = gr.Button("Run Deep Research", variant="primary")
+    report_md = gr.Markdown(label="Report Preview (sent to your email)")
+
+    run_btn.click(run_research, inputs=[query_box, email_box], outputs=report_md)
+    query_box.submit(run_research, inputs=[query_box, email_box], outputs=report_md)
+    email_box.submit(run_research, inputs=[query_box, email_box], outputs=report_md)
+
+if __name__ == "__main__":
+    ui.launch(inbrowser=True)

deep_research_agents/deep_research.py

@@ -0,0 +1,23 @@
+import gradio as gr
+from dotenv import load_dotenv
+from .research_manager import ResearchManager
+
+load_dotenv(override=True)
+
+
+async def run(query: str):
+    async for chunk in ResearchManager().run(query):
+        yield chunk
+
+
+with gr.Blocks(theme=gr.themes.Default(primary_hue="sky")) as ui:
+    gr.Markdown("# Deep Research")
+    query_textbox = gr.Textbox(label="What topic would you like to research?")
+    run_button = gr.Button("Run", variant="primary")
+    report = gr.Markdown(label="Report")
+    
+    run_button.click(fn=run, inputs=query_textbox, outputs=report)
+    query_textbox.submit(fn=run, inputs=query_textbox, outputs=report)
+
+ui.launch(inbrowser=True)
+

deep_research_agents/email_agent.py

@@ -0,0 +1,46 @@
+import os
+from typing import Dict
+
+import sendgrid
+from sendgrid.helpers.mail import Email, Mail, Content, To
+from agents import Agent, function_tool
+import markdown2
+
+@function_tool
+def send_email(subject: str, html_body: str) -> Dict[str, str]:
+    """ Send an email with the given subject and HTML body (markdown supported) """
+    sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
+    from_email = Email("liorsolomon.solid@gmail.com") # put your verified sender here
+    to_email = To("liorsolomon.solid@gmail.com") # put your recipient here
+    # Convert markdown to HTML and wrap in a basic template
+    html_content = markdown2.markdown(html_body)
+    html_template = f"""
+    <html>
+      <head>
+        <style>
+          body {{ font-family: Arial, sans-serif; margin: 2em; }}
+          h1, h2, h3 {{ color: #0074D9; }}
+          p {{ line-height: 1.6; }}
+        </style>
+      </head>
+      <body>
+        {html_content}
+      </body>
+    </html>
+    """
+    content = Content("text/html", html_template)
+    mail = Mail(from_email, to_email, subject, content).get()
+    response = sg.client.mail.send.post(request_body=mail)
+    print("Email response", response.status_code)
+    return {"status": "success"}
+
+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",
+)

deep_research_agents/planner_agent.py

@@ -0,0 +1,23 @@
+from pydantic import BaseModel, Field
+from agents import Agent
+
+HOW_MANY_SEARCHES = 5
+
+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 = Field(description="Your reasoning for why this search is important to the query.")
+    query: str = Field(description="The search term to use for the web search.")
+
+
+class WebSearchPlan(BaseModel):
+    searches: list[WebSearchItem] = Field(description="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,
+)

deep_research_agents/research_manager.py

@@ -0,0 +1,84 @@
+from agents import Runner, trace, gen_trace_id
+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
+import asyncio
+
+class ResearchManager:
+
+    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...")
+            search_plan = await self.plan_searches(query)
+            yield "Searches planned, starting to search..."     
+            search_results = await self.perform_searches(search_plan)
+            yield "Searches complete, writing report..."
+            report = await self.write_report(query, search_results)
+            yield "Report written, sending email..."
+            await self.send_email(report)
+            yield "Email sent, research complete"
+            yield report.markdown_report
+        
+
+    async def plan_searches(self, query: str) -> WebSearchPlan:
+        """ Plan the searches to perform for the query """
+        print("Planning searches...")
+        result = await Runner.run(
+            planner_agent,
+            f"Query: {query}",
+        )
+        print(f"Will perform {len(result.final_output.searches)} searches")
+        return result.final_output_as(WebSearchPlan)
+
+    async def perform_searches(self, search_plan: WebSearchPlan) -> list[str]:
+        """ Perform the searches to perform for the query """
+        print("Searching...")
+        num_completed = 0
+        tasks = [asyncio.create_task(self.search(item)) for item in search_plan.searches]
+        results = []
+        for task in asyncio.as_completed(tasks):
+            result = await task
+            if result is not None:
+                results.append(result)
+            num_completed += 1
+            print(f"Searching... {num_completed}/{len(tasks)} completed")
+        print("Finished searching")
+        return results
+
+    async def search(self, item: WebSearchItem) -> str | None:
+        """ Perform a search for the query """
+        input = f"Search term: {item.query}\nReason for searching: {item.reason}"
+        try:
+            result = await Runner.run(
+                search_agent,
+                input,
+            )
+            return str(result.final_output)
+        except Exception:
+            return None
+
+    async def write_report(self, query: str, search_results: list[str]) -> ReportData:
+        """ Write the report for the query """
+        print("Thinking about report...")
+        input = f"Original query: {query}\nSummarized search results: {search_results}"
+        result = await Runner.run(
+            writer_agent,
+            input,
+        )
+
+        print("Finished writing report")
+        return result.final_output_as(ReportData)
+    
+    async def send_email(self, report: ReportData) -> None:
+        print("Writing email...")
+        result = await Runner.run(
+            email_agent,
+            report.markdown_report,
+        )
+        print("Email sent")
+        return report

deep_research_agents/search_agent.py

@@ -0,0 +1,17 @@
+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 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 its vital you capture the "
+    "essence and ignore any fluff. Do not include any additional commentary other than the summary itself."
+)
+
+search_agent = Agent(
+    name="Search agent",
+    instructions=INSTRUCTIONS,
+    tools=[WebSearchTool(search_context_size="low")],
+    model="gpt-4o-mini",
+    model_settings=ModelSettings(tool_choice="required"),
+)

deep_research_agents/writer_agent.py

@@ -0,0 +1,27 @@
+from pydantic import BaseModel, Field
+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."
+)
+
+
+class ReportData(BaseModel):
+    short_summary: str = Field(description="A short 2-3 sentence summary of the findings.")
+
+    markdown_report: str = Field(description="The final report")
+
+    follow_up_questions: list[str] = Field(description="Suggested topics to research further")
+
+
+writer_agent = Agent(
+    name="WriterAgent",
+    instructions=INSTRUCTIONS,
+    model="gpt-4o-mini",
+    output_type=ReportData,
+)