Upload folder using huggingface_hub

.env.exampe

@@ -0,0 +1,3 @@
+OPENAI_API_KEY=YOUR_OPENAI_API_KEY
+SENDGRID_API_KEY=YOUR_SENDGRID_API_KEY
+SENDGRID_SENDER_EMAIL=YOUR_SENDGRID_SENDER_EMAIL

README.md

@@ -1,12 +1,27 @@
----
-title: Deep Research
-emoji: 📚
-colorFrom: indigo
-colorTo: red
-sdk: gradio
-sdk_version: 5.49.1
-app_file: app.py
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+---
+title: deep_research
+app_file: deep_research.py
+sdk: gradio
+sdk_version: 5.34.2
+---
+
+# 🧠 Deep Research Agent (Modular)
+
+This project is a modular and extended version of the deep research agent. Instead of running the entire research process in a single step, this system breaks it down into reusable **tool-like stages**, orchestrated by a central **Research Manager Agent**. This creates a more natural and interactive experience, similar to tools like ChatGPT.
+
+---
+
+## 🚀 What's different
+
+- Each research stage is implemented as a standalone tool.
+- Generates clarifying questions.
+- A **manager agent** controls the flow and selects tools dynamically.
+- Enables a **more conversational** research experience.
+- Rather than hardcoding the user's email address in the script, the agent dynamically prompts the user for their address and uses SendGrid to send the report to that input
+
+---
+
+## 🛠️ Usage
+
+- Just make sure you've defined the environment variables listed in the `.env.example` file.
+- If you want to send emails to any address, you need to have a verified domain in SendGrid and use an email address from that domain in the SENDGRID_SENDER_EMAIL variable. Otherwise, you can use your verified single sender email address, but you may encounter issues when sending emails to recipients other than the sender address.

deep_research.py

@@ -0,0 +1,45 @@
+import gradio as gr
+from dotenv import load_dotenv
+from agents import Runner
+from manager_agent import manager_agent
+
+load_dotenv(override=True)
+
+
+async def run_chat(user_message: str, chat_history: list):
+    chat_history.append({"role": "user", "content": user_message})
+
+    chat_history.append({"role": "assistant", "content": "Pensando..."})
+    yield chat_history, ""
+
+    messages = [{"role": message["role"], "content": message["content"]} for message in chat_history[:-1]]
+
+    result = await Runner.run(
+        manager_agent,
+        messages,
+    )
+
+    chat_history[-1] = {"role": "assistant", "content": result.final_output}
+    yield chat_history, ""
+
+
+with gr.Blocks() as ui:
+    chat = gr.Chatbot(type="messages", label="Agente de investigación profunda")
+    chat_history = gr.State([])
+    
+    txt = gr.Textbox(placeholder="Escribe aquí…", show_label=False)
+    btn = gr.Button("Enviar")
+    
+    btn.click(
+        fn=run_chat,
+        inputs=[txt, chat_history],
+        outputs=[chat, txt],
+    )
+    txt.submit(
+        fn=run_chat,
+        inputs=[txt, chat_history],
+        outputs=[chat, txt],
+    )
+
+ui.launch(inbrowser=True)
+

email_agent.py

@@ -0,0 +1,30 @@
+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, email_address: str) -> Dict[str, str]:
+    """ Send an email with the given subject and HTML body """
+    sg = sendgrid.SendGridAPIClient(api_key=os.environ.get('SENDGRID_API_KEY'))
+    from_email = Email(os.environ.get("SENDGRID_SENDER_EMAIL")) # put your verified sender here
+    to_email = To(email_address) # put your recipient here
+    content = Content("text/html", html_body)
+    mail = Mail(from_email, to_email, subject, content).get()
+    print(f"Sending email from {os.environ.get('SENDGRID_SENDER_EMAIL')} to {email_address}")
+    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",
+)

manager_agent.py

@@ -0,0 +1,37 @@
+from research_tools import plan_searches, perform_searches, write_report, send_email, generate_questions
+from agents import Agent
+
+INSTRUCTIONS = (
+    "You are a dedicated **Research Manager Agent**, designed to conduct in-depth research for users. "
+    "Your primary goal is to provide comprehensive and accurate reports based on their queries. "
+    "Follow these steps to manage the research process effectively:\n\n"
+    
+    "1. **Clarify the Query:** When you receive a new query, your first step is to ensure full understanding. "
+    "   **Generate precisely 5 specific clarification questions** to help refine the user's request. "
+    "   Politely ask the user to answer these questions so you can perform the best possible search.\n\n"
+    
+    "2. **Conduct Research:** Once the user has provided answers to your questions, proceed with the core research. "
+    "   **Plan the necessary web searches, then execute them, and finally, synthesize your findings into a comprehensive research report.**\n\n"
+    
+    "3. **Deliver and Offer Email:** After generating the report, present it to the user. "
+    "   **Crucially, ask the user if they would like to receive this report via email.** "
+    "   If they agree, politely request their email address and then send the report to that address. "
+    "   If they decline the email, conclude the interaction gracefully without further action regarding email.\n"
+    
+    "**Remember:** You are equipped with the following tools to accomplish these tasks: `generate_questions`, `plan_searches`, `perform_searches`, `write_report`, and `send_email`."
+)
+
+manager_tools = [
+    generate_questions,
+    plan_searches,
+    perform_searches,
+    write_report,
+    send_email,
+]
+
+manager_agent = Agent(
+    name="ManagerAgent",
+    instructions=INSTRUCTIONS,
+    tools=manager_tools,
+    model="gpt-4o-mini",
+)

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,
+)

questions_generator_agent.py

@@ -0,0 +1,10 @@
+from agents import Agent
+
+INSTRUCTIONS = f"You are a helpful research assistant. Given a query, come up with a set of questions \
+    that can help you understand the query better and plan your research. Output a list of 5 questions."
+
+questions_generator_agent = Agent(
+    name="QuestionsGeneratorAgent",
+    instructions=INSTRUCTIONS,
+    model="gpt-4o-mini",
+)

research_tools.py

@@ -0,0 +1,102 @@
+from agents import Runner, trace, gen_trace_id
+from search_agent import search_agent
+from planner_agent import planner_agent, WebSearchItem, WebSearchPlan
+from questions_generator_agent import questions_generator_agent
+from writer_agent import writer_agent, ReportData
+from email_agent import email_agent
+import asyncio
+from agents import function_tool
+
+"""
+    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_result = await self.plan_searches(query)
+            search_plan = search_plan_result.searches
+            user_email = search_plan_result.user_email
+            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, user_email)
+            yield "Email sent, research complete"
+            yield report.markdown_report
+"""
+
+@function_tool
+async def generate_questions(query: str) -> str:
+    """ Generate 5 questions to answer for the query """
+    print("Generating questions...")
+    result = await Runner.run(
+        questions_generator_agent,
+        f"Query: {query}",
+    )
+    print(f"Generated 5 questions...")
+    return result.final_output
+
+@function_tool
+async def plan_searches(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)
+
+@function_tool
+async def perform_searches(search_plan: WebSearchPlan) -> list[str]:
+    """ Perform the searches to perform for the query """
+    print("Searching...")
+    num_completed = 0
+    tasks = [asyncio.create_task(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(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
+
+@function_tool
+async def write_report(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)
+    
+@function_tool
+async def send_email(report: ReportData, user_email: str) -> None:
+    print("Writing email...")
+    result = await Runner.run(
+        email_agent,
+        f"Report: {report.markdown_report}\nUser email: {user_email}",
+    )
+    print("Email sent")
+    return report

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"),
+)

writer_agent.py

@@ -0,0 +1,28 @@
+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."
+    "If the query includes an email address, please ignore it."
+)
+
+
+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,
+)