deep_research

Actions

• start_project write

  Create a new research project row in 'planned' status with the user-supplied question. · db.research_tables

  Goal

  Open a new research investigation.

  Inputs

  name (slug), title, question

  Outputs

  research_project_id (uuid)

  Errors

  schema_missing, db_unreachable

  Example

  start_project(name='cholesterol-acm', title='Primary-prevention LDL lowering and all-cause mortality', question='Does pharmacological LDL lowering reduce ACM in strict primary prevention?')

• submit_protocol write idempotent

  Attach the pre-registered protocol JSON to a project and move status to protocol_gated. · db.research_tables

  Goal

  Lock the search/inclusion/effect/analysis plan before any paid searches.

  Inputs

  research_project_id, protocol (PICO + queries + inclusion/exclusion + analysis_plan + gate_thresholds)

  Outputs

  status='protocol_gated', awaiting_human_approval=true

  Errors

  project_not_found, protocol_invalid

  Example

  submit_protocol(research_project_id=..., protocol={...})

• approve_gate write

  Append a human-decision row to gate_log and transition the project to the next phase. · db.research_tables

  Goal

  Record a Gate 1 or Gate 2 decision and advance state.

  Inputs

  research_project_id, gate ('protocol'|'pass2'), decision ('approve'|'revise'|'abort'), notes

  Outputs

  new status

  Errors

  project_not_found, wrong_phase, unknown_gate

  Example

  approve_gate(research_project_id=..., gate='protocol', decision='approve')

• run_pass1 write

  Fan out Scout / Skeptic / Methodologist subagents over the approved protocol. Writes research_searches and research_evidence rows. · net.outbound.scholarly db.research_tables

  Goal

  Build the Pass-1 candidate corpus from abstracts.

  Inputs

  research_project_id

  Outputs

  scout_run, skeptic_run, methodologist_run summaries; corpus rollup

  Errors

  wrong_phase, scholarly_api_unreachable, subagent_cap_exceeded

  Example

  run_pass1(research_project_id=...)

• run_pass2 write

  Retrieve full text for the approved candidate set and stage it for the Synthesizer. · net.outbound.scholarly db.research_tables

  Goal

  Pull OA PDFs and extract to text.

  Inputs

  research_project_id

  Outputs

  n_retrieved, n_paywalled, n_unavailable, candidate ids

  Errors

  wrong_phase, pdf_extract_failed

  Example

  run_pass2(research_project_id=...)

• synthesize write

  Run the Synthesizer subagent. Produces a structured document; enforces verbatim-quote-or-cut on every claim. · db.research_tables

  Goal

  Produce the no-fabrication synthesis document.

  Inputs

  research_project_id

  Outputs

  doc_artifact_id, n_cited, n_supports, n_refutes, n_mixed, complete

  Errors

  wrong_phase, fabrication_detected, doc_build_failed

  Example

  synthesize(research_project_id=...)

Runtime

runtime: python-module · install method: git · entrypoint: python -m deep_research

deep_research is an agent-runtime-agnostic workflow that turns an empirical research question into a citation-grade synthesis. Two human-in-the-loop gates (protocol pre-registration, Pass-2 spend) bracket a four-role subagent crew (Scout / Skeptic / Methodologist / Synthesizer). Every claim a synthesis ships must be backed by a row in the research_evidence table with a verbatim quote_span; claims without their quote get cut. v0.2.0 adds the Python reference implementation: a stdlib-urllib scholar adapter (OpenAlex / Semantic Scholar / PubMed / arXiv / Europe PMC / Crossref / Unpaywall) and a python-docx + matplotlib synthesis builder with pluggable upload. Core stays stdlib-only; the docx builder is gated behind the optional `[viz]` extra.

Tags: researchliterature-reviewmeta-analysisagentssubagent-fan-outno-fabricationskill-bundle

License: Apache-2.0

Last fetched 2026-06-18T09:09:15Z (live)