deep-research

What it does

Deep-research implements a multi-step process to generate structured, long-form research reports. It coordinates a main agent with four sub-tasks (Outline, Data collection, Pre-check, Assembly) plus a parallel per-chapter writing routine, producing temporary data in a defined TMPDIR and final reports in a Reviva-managed outputs directory. It supports offline inputs from local files and online sources via multiple search/fetch tools, chosen adaptively. It returns a final assembled report with metadata, citations, and a separate assessment section derived from data and LLM judgments.

How it works

• Offline vs online mode is detected from the topic and local paths. Offline mode uses local files; online mode uses web_search_bing, mcp:exa, mcp:jina-mcp-server, SearXNG, or other tools, depending on availability. The final output is saved to /agents/deep-researcher/outputs/{today}/ and temporary data to /tmp/deep-researcher/{today}/deep-research-{timestamp}/.
• Task 1 analyzes the topic to generate an outline by loading a prompt template and substituting variables; the outline is saved in outline.json.
• Task 2 collects data and builds a structured data pool; on failure, it retries once. It also captures a manifest with counts and engine choices.
• Task 3 distributes chapter writing in parallel, embedding facts with numeric labels, and then collects, verifies, and re-writes any failed chapters sequentially.
• Task 4 runs validation, assembly, and QA steps. It uses Python tools (dr_tools.py) for validation, depth balance checks, citation conversion, currency escaping, QA, and final assembly. It can replace the report in the output directory or write Markdown/HTML directly if tooling is unavailable. It outputs a final report path and a separate assessment, then writes to llm_assessment.txt and inserts it into the report after a translated tag.
• It enforces a strict six-field metadata header, a TOC, and a four-part structure, with a final disclaimer and reference sections. It requires UTF-8 encoding for intermediate files and avoids LaTeX or Math in the text.

When to use it

Use when a user requests a cited long-form research report covering education, industry analysis, policy interpretation, or similar topics, and you need a structured, multi-source synthesis with traceable sources and a comprehensive metadata block. It supports both online searches and offline local-file inputs.

What it can touch

• Tools: file_read, file_write, document_read, kb_search, web_search_bing
• Paths: {TMPDIR}, {PROMPTSDIR}, {TOOLSDIR}, outputs directory, and intermediate chapters under {TMPDIR}/chapters/
• Scripts: python {TOOLSDIR}/dr_tools.py with multiple subcommands (validate-all-chapters, depth-balance, assemble-report, convert-citations, escape-currency, qa-report)

Caveats

• Declared risk: medium
• Requires that exec_command is available for certain steps; otherwise, some steps may fallback to file_write and static generation.
• Final reliability depends on tool availability and network permissions per user setting.
• Output fidelity relies on profiles.json to cap per-chapter length and to determine overall QA thresholds.