The Problem

Deep search agents—systems that must browse the web across many steps to answer a question—need large amounts of high-quality, multi-turn training data. Hand-labeling thousands of long-horizon browsing trajectories is expensive and doesn't scale. DeepDive automates the data generation step: it synthesizes difficult QA pairs from knowledge graphs via random walks, then uses those pairs for multi-turn reinforcement learning.

What This Does

DeepDive is a research codebase (forked from THUDM/DeepDive) implementing a two-stage pipeline. Stage 1 is automated data synthesis: qa_synthetic/random_walk_kilt.py walks a knowledge graph to build entity paths, obfuscates them with an LLM, and filters for difficulty using a frontier model. Stage 2 is multi-turn RL training with GRPO, described in the README but not yet implemented in code—the repository currently contains only the data-synthesis pipeline.

The core logic lives in qa_synthetic/ with four Python files. random_walk_kilt.py orchestrates graph traversal and LLM-based question generation; kilt_query.py provides a KILT knowledge-graph client; generate_qa.py is the CLI entry point that ties everything together; prompt.py holds prompt templates.

How It Is Wired

Execution starts at main in qa_synthetic/generate_qa.py:178, which reaches 9 functions. The traced path from entry point to external effect is short: main -> merge_jsonl, which writes to the filesystem via os.makedirs. The pipeline also calls an LLM for inference from 4 functions (call_llm, query_llm, and two others), so a run makes network calls to a model API and writes JSONL output files.

The most-connected functions form the hub of the system: _normalize_title is called from 6 places, and _retry from 3. custom_random_walk is the orchestration core, calling query_relations, query_text, and cut_see_also_and_filter_anchors. KiltClient wraps the knowledge-graph API with retry logic.

File-by-file map: random_walk_kilt.py (13 functions, 1 class) owns the graph-walking and LLM querying; generate_qa.py (10 functions) owns CLI parsing, prompt rendering, and output merging; kilt_query.py (10 functions, 1 class) owns KILT API access with retry and title normalization.

How To Use It

Setup: Install dependencies from qa_synthetic/requirements.txt with pip.

pip install -r qa_synthetic/requirements.txt

Configuration: The pipeline requires an LLM API key (likely OpenAI-compatible, given the GPT-4o reference in the README), but no .env file or config template exists in the repo. You'll need to inspect generate_qa.py for the expected environment variable or CLI argument.

Running it: Invoke the CLI:

python qa_synthetic/generate_qa.py --help

The README doesn't document concrete run commands, so you'll need to read generate_qa.py's argument parser to determine required flags.

Real-World Use

A research team building a web-browsing agent would run the synthesis pipeline to generate training data, then use the resulting JSONL files for SFT or RL fine-tuning. The pipeline is designed to produce only questions that frontier models fail on, ensuring the training set contains genuinely hard, multi-step search tasks rather than trivial lookups.

Code Health & Issues

Static analysis found 5 issues across the codebase. One high-severity finding: deep nesting in qa_synthetic/kilt_query.py and qa_synthetic/random_walk_kilt.py (max indentation depth 11), making control flow hard to follow—fix with early returns and extraction. Three medium-severity findings: broad exception handling in generate_qa.py, kilt_query.py, and random_walk_kilt.py that swallows errors indiscriminately.

SDLC observations from the structure: no test files, no CI/CD pipeline, no license file, and dependencies declared without a lockfile. This is a research prototype, not production software.

The Bottom Line

The data-synthesis pipeline is functional and the approach is sound for research purposes, but the code needs refactoring before reuse. The RL training half of the paper isn't in the repo yet. Suitable for researchers reproducing the data-generation method; not ready for production deployment.