deep_researcher

Minimal scaffold for a manager-orchestrated, multi-agent research system where each role can run as its own Codex session.

Architecture

• Manager-driven DAG: plan -> retrieve -> extract -> verify -> write
• Role isolation via per-role AGENT.md
• Strict JSON handoffs between stages
• Simple schema checks before accepting agent output

Project Layout

• configs/agents/*/AGENT.md: role instructions for Codex sessions
• schemas/*.json: JSON contracts each role must return
• src/research_system/manager.py: orchestration DAG
• src/research_system/demo.py: local demo with mock workers
• src/research_system/codex_sessions.py: adapter for real Codex role sessions

Quick Start

python -m src.research_system.demo

The demo runs the full workflow with mock outputs and prints the final report JSON.

Wiring Real Codex Sessions

Replace mock workers in src/research_system/demo.py with CodexRoleSession instances. Each role points to its own configs/agents/<role>/AGENT.md, and the manager contract checks remain the same.

Codex CLI End-to-End (No API Service)

This mode runs every role using Codex CLI (codex exec) and writes file-based handoffs under runs/<job_id>/.

Windows PowerShell:

.\run_research.ps1 -Goal "Compare multi-agent research architectures for production reliability"

If Codex CLI is not on PATH in your Python environment:

.\run_research.ps1 -Goal "..." -CodexBin "C:\full\path\to\codex.cmd"

Direct Python command:

python -m src.research_system.run_codex_cli --goal "Compare multi-agent research architectures for production reliability"

Or pass explicit binary:

python -m src.research_system.run_codex_cli --goal "..." --codex-bin "C:\full\path\to\codex.cmd"

Artifacts:

• runs/<job_id>/in/<role>.json: input payload given to each role
• runs/<job_id>/out/<role>.json: role output JSON
• runs/<job_id>/logs/<role>.log: Codex CLI stdout/stderr logs
• runs/<job_id>/final_report.json: final validated report

Long-Running Worker Architecture (Recommended)

This mode is designed for long-running workloads.

1. Start one worker per role:

.\run_workers.ps1

2. Submit a job:

python -m src.research_system.runtime.submit_job --goal "Compare multi-agent research architectures for production reliability" --db runs/runtime.sqlite3

3. Check status:

python -m src.research_system.runtime.status --job-id <job_id> --db runs/runtime.sqlite3

When complete, final_report_path points to runs/<job_id>/final_report.json.

Optional local mock validation

Run full queue orchestration without Codex calls:

python -m src.research_system.runtime.mock_run --goal "test runtime pipeline"

Or run mock workers in separate terminals/windows:

.\run_workers.ps1 -Mock