add clarifier

src/clarifier.py

@@ -0,0 +1,24 @@
+from agents import Agent
+from pydantic import BaseModel, Field
+
+INSTRUCTIONS = (
+    "You are a domain expert who wants to fully understand the research intent behind a user's high-level query. "
+    "Return a concise list (max 3) of the most important clarifying questions you would ask the user to narrow the scope "
+    "and make the subsequent research more targeted and useful. Output only the questions - no additional commentary."
+)
+
+
+class ClarifyingQuestions(BaseModel):
+    """A list of clarifying questions to present to the user before starting the research."""
+
+    questions: list[str] = Field(
+        description="The clarifying questions that should be asked of the user before planning the research."
+    )
+
+
+clarifier_agent = Agent(
+    name="ClarifierAgent",
+    instructions=INSTRUCTIONS,
+    model="gpt-4o-mini",
+    output_type=ClarifyingQuestions,
+)

src/main.py

@@ -6,21 +6,73 @@ from research_manager import ResearchManager
 load_dotenv()
 
 
-async def run(query: str):
-    async for chunk in ResearchManager().run(query):
+async def ask_clarifications(query: str) -> tuple[str, list[str]]:
+    """Generate clarifying questions for *query* and return both a nicely formatted string and the raw list."""
+    manager = ResearchManager()
+    questions = await manager.get_clarifying_questions(query)
+
+    if not questions:
+        return (
+            "No clarifying questions were generated. You can proceed to run the research.",
+            [],
+        )
+
+    formatted = "\n".join(f"{idx+1}. {q}" for idx, q in enumerate(questions))
+    return formatted, questions
+
+
+async def run_research(query: str, answers: str, questions: list[str]):
+    """Run the complete research pipeline and stream the markdown report."""
+    clarifications_block = ""
+
+    answer_lines = [line.strip() for line in answers.split("\n")]
+    while len(answer_lines) < len(questions):
+        answer_lines.append("")
+
+    q_and_a = []
+    for idx, question in enumerate(questions):
+        answer = answer_lines[idx]
+        q_and_a.append(f"Q{idx+1}: {question}\nA{idx+1}: {answer}")
+
+    clarifications_block = "\n".join(q_and_a)
+
+    async for chunk in ResearchManager().run(query, clarifications_block):
         yield chunk
 
 
 with gr.Blocks(theme=gr.themes.Default(primary_hue="yellow")) as ui:
     gr.Markdown("# Deep Research")
-    query_textbox = gr.Textbox(
-        label="What topic would you like to research?",
-        value="e.g. How to create a Deep Research Agent?",
+
+    with gr.Row():
+        query_textbox = gr.Textbox(
+            label="What topic would you like to research?",
+            placeholder="e.g. How to create a Deep Research Agent?",
+        )
+        ask_button = gr.Button("Ask clarifying questions")
+
+    clarifying_questions_state = gr.State([])
+    clarifications_markdown = gr.Markdown(label="Clarifying questions will appear here")
+
+    clarification_answers_box = gr.Textbox(
+        label="Your answers to the clarifying questions (one per line)",
+        placeholder="Answer 1\nAnswer 2\n...",
+        lines=3,
     )
-    run_button = gr.Button("Run", variant="primary")
+
+    run_button = gr.Button("Run research", 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)
+    ask_button.click(
+        fn=ask_clarifications,
+        inputs=query_textbox,
+        outputs=[clarifications_markdown, clarifying_questions_state],
+    )
+
+    run_button.click(
+        fn=run_research,
+        inputs=[query_textbox, clarification_answers_box, clarifying_questions_state],
+        outputs=report,
+    )
 
-ui.launch()
+if __name__ == "__main__":
+    ui.launch()

src/research_manager.py

@@ -2,6 +2,7 @@ import asyncio
 
 from agents import Runner, gen_trace_id, trace
 
+from clarifier import ClarifyingQuestions, clarifier_agent
 from planner import WebSearchItem, WebSearchPlan, planner_agent
 from report_generator import ReportData, writer_agent
 from web_search import search_agent
@@ -9,16 +10,29 @@ from web_search import search_agent
 
 class ResearchManager:
 
-    async def run(self, query: str):
-        """Run the deep research process, yielding the status updates and the final report"""
+    async def run(self, query: str, clarifications: str | None = None):
+        """Run the deep research process, yielding status updates and the final report.
+
+        If *clarifications* are provided (the user's answers to the clarifying questions), we will use them to
+        augment the planning and reporting stages. Otherwise this behaves exactly like the previous implementation.
+        """
         trace_id = gen_trace_id()
         with trace("Research trace", trace_id=trace_id):
             print("Starting research...")
-            search_plan = await self.plan_searches(query)
+
+            # Combine the original query with any clarification the user has supplied.
+            if clarifications:
+                combined_query = (
+                    f"Original query: {query}\n\nUser clarifications:\n{clarifications}"
+                )
+            else:
+                combined_query = query
+
+            search_plan = await self.plan_searches(combined_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)
+            report = await self.write_report(combined_query, search_results)
             yield report.markdown_report
 
     async def plan_searches(self, query: str) -> WebSearchPlan:
@@ -63,7 +77,7 @@ class ResearchManager:
     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}"
+        input = f"{query}\nSummarized search results: {search_results}"
         result = await Runner.run(
             writer_agent,
             input,
@@ -71,3 +85,13 @@ class ResearchManager:
 
         print("Finished writing report")
         return result.final_output_as(ReportData)
+
+    async def get_clarifying_questions(self, query: str) -> list[str]:
+        """Generate clarifying questions for a given query."""
+        print("Generating clarifying questions...")
+        result = await Runner.run(clarifier_agent, f"Query: {query}")
+        questions_model: ClarifyingQuestions = result.final_output_as(
+            ClarifyingQuestions
+        )
+        print(f"Generated {len(questions_model.questions)} clarifying questions")
+        return questions_model.questions