Research CLI

Python CLI that researches any question on the live web and writes a detailed cited markdown brief.

Flow: detect entity/intent → plan queries → search/rank/filter → fetch → grounded evidence → detailed synthesis.

Setup

cd ~/research-cli
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env   # optional

Defaults: Ollama at http://127.0.0.1:11434/v1, model llama3.2.

Usage

source .venv/bin/activate

research-cli "What is RAG and when should I use it?"
research-cli what is youtube --depth deep
research-cli                  # interactive

Interactive: type a question, or help / history / clear / exit.

Flags

Flag	Default	Meaning
--depth	normal	fast (quick) / normal / deep (more sources)
--max-sources	depth default	Cap pages to read
--out-dir	briefs	Where markdown briefs are saved

How it works

1. Detect — intent + domain persona (e.g. CS → senior SWE at Meta; ML → senior ML engineer)
2. Plan — LLM proposes 2–4 entity-locked search queries
3. Search — DuckDuckGo; dedupe, rank, drop junk hosts
4. Fetch — extract main text from top pages
5. Evidence — extract claim-checked [n] fact lines
6. Synthesize — detailed brief in the domain persona’s voice; falls back to a deterministic draft if citations break

Domains: computer_science, machine_learning, biology, finance, physics, product, general.

Prompt engineering

Progressive PE harness lives in scripts/pe_cycle.py (stages S0→S5) with verify in scripts/pe_verify.py.

python scripts/pe_cycle.py                  # full progressive cycle
python scripts/pe_verify.py                 # score current S5 prompts

Latest verify (eval_out/pe-verify-20260809-000427): 100% pass, mean quality 110 on DuckDuckGo + RAG + hash map.

Hardening with winning prompts: domain personas in {persona} slots, acronym expansion, entity aliases (hash map ↔ hash table), nested-query parsing, single-sentence evidence, stricter citation validation.

Env vars

Variable	Default
OPENAI_BASE_URL	http://127.0.0.1:11434/v1
OPENAI_API_KEY	ollama
RESEARCH_MODEL	llama3.2