SendDeepResearchQuery — Analysis Tool Box

Introduction

A one-line research request is rarely specific enough to produce a genuinely useful report — the gaps in scope, preferred sources, or output format have to get filled in somehow, either by the researcher guessing or by asking first. SendDeepResearchQuery asks first: it runs a three-phase pipeline against OpenAI's Deep Research API that generates clarifying questions for your original query, pauses at the terminal for you to answer them (or skip by pressing Enter), turns your answer into a detailed research brief, and then hands that brief to a deep-research model to actually execute.

Teaching Note

This function automates the workflow of turning a vague research request into a well-scoped one before spending the time and tokens on a full deep-research run. It's useful whenever the cost of researching the wrong thing — the wrong product category, the wrong comparison criteria, the wrong output format — is higher than the cost of a short clarification round-trip. Because it blocks on interactive terminal input during the clarification phase (unless skip_clarification=True), it's best suited to scripts and notebooks run interactively rather than unattended pipelines.

Parameters

Parameter	Type	Default	Description
`query_text`required	`str`	—	The initial research query to investigate (e.g., "Research surfboards for me").
`openai_api_key`	`str`	`None`	OpenAI API key. If None, the function falls back to the OPENAI_API_KEY environment variable; if that is also unset, an error is raised.
`plan_model_name`		`'gpt-5-mini'`	The OpenAI model used to generate the clarifying questions (phase 1) and the detailed research plan (phase 2).
`research_model_name`		`'o4-mini-deep-research'`	The OpenAI Deep Research model used to execute the research plan and produce the final report (phase 3).
`model_name`	`str`	`'o4-mini-deep-research'`	The model name recorded in the returned result's metadata. Does not control which model actually runs the research — that's research_model_name.
`verbose`	`bool`	`True`	Whether to print status messages for each phase as the function runs.
`research_tools`		`[{'type': 'web_search_preview'}]`	List of OpenAI Responses API tool definitions made available to the research model, e.g. web search.
`show_report`	`bool`	`True`	Whether to render the final report as Markdown (via IPython.display.Markdown) in a notebook environment.
`filepath_to_save_report`	`str`	`None`	Path to save the final report as a .md file. Must end in .md if provided.
`filepath_to_save_research_results`	`str`	`None`	Path to save the raw research output text as a .txt file. Must end in .txt if provided.
`skip_clarification`	`bool`	`False`	If True, skips the interactive clarifying-questions phase and proceeds directly to building the research plan from query_text as given.

Returns

A dictionary with the original query, the clarifying_questions asked, any user_additional_info supplied, the enhanced_query, the generated research_plan, the research_results text, a sources mapping of citations, and a metadata dict (model used, token usage, research ID, timestamp, status).

Example

python

from analysistoolbox.llm import SendDeepResearchQuery

# Interactive: prompts for clarifying answers at the terminal
result = SendDeepResearchQuery(
    query_text="Research the best trail running shoes for wide feet",
    openai_api_key="sk-...",
)
print(result['research_results'])

# Non-interactive: skip the clarification round-trip
result = SendDeepResearchQuery(
    query_text="Research the best trail running shoes for wide feet",
    openai_api_key="sk-...",
    skip_clarification=True,
)