Revolu Idea • GitHub Pages

CAG Deep Research

A research CLI on LangGraph. It turns a question into a causal graph, has an adversary and a supporter agent search for evidence on each link, judges them, and writes a report. Ports/adapters layout. Experimental.

GitHub repo Demo Quick start Repo tour How it works

Python LangGraph LangChain Tavily / Exa / DDG Reports + audit loop

This is a CLI/backend project (not a web app). This page is just the shareable landing link.

Working demo (simulated)

This demo runs entirely in your browser using prebuilt sample artifacts (no API calls). It previews what a real CLI run produces.

Console output

Click “Run demo” to simulate a run…

Report preview

Open demo report (MD) Open demo report (JSON) Sample causal DAG (Mermaid)

The preview will appear here.

Real run: python main.py "your topic" (requires configuring .env).

Quick start

Clone, install, configure .env, run:

git clone https://github.com/jayhemnani9910/revolu-idea.git
cd revolu-idea
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# copy template, then set LLM_API_KEY
cp .env.example .env

python main.py "What are the latest developments in quantum computing?"

# no-key smoke run
LLM_PROVIDER=mock SEARCH_PROVIDER=mock python main.py "test topic"

How it works

The planner turns the query into a causal DAG. The auditor runs safety checks (loops, depth), the selector picks the next edge, and the adversary and supporter search for evidence on it in parallel. The judge gives a verdict and confidence, then control goes back to the auditor. When no edges are left or max depth is hit, the writer saves output/reports/*.md + .json.

flowchart LR Q["User query"] --> P["Planner
causal DAG"] --> A["Auditor"] --> S["Selector"] --> I["Adversary + Supporter
parallel search"] --> J["Judge"] --> A S -->|"no edges left"| W["Writer"] A -->|"max depth"| W W --> O["output/reports/"]

If the diagram doesn’t render, it’s still readable as text. (Renderer loads from a CDN.)

Providers

LLM: OpenAI-compatible APIs (Groq/DeepSeek/etc) via LLM_BASE_URL.
LLM (no key): LLM_PROVIDER=mock for local smoke runs.
Search: Tavily / Exa (keys) or SEARCH_PROVIDER=duckduckgo (free).
Storage: local filesystem (OUTPUT_DIR).

Settings load from .env (gitignored). Core env vars:

LLM_PROVIDER, LLM_BASE_URL, LLM_MODEL, LLM_API_KEY
SEARCH_PROVIDER (+ TAVILY_API_KEY or EXA_API_KEY if used)
MAX_RECURSION_DEPTH, MAX_INVESTIGATIONS_PER_EDGE
OUTPUT_DIR

Repo tour

main.py — CLI entrypoint (runs the research graph).
container.py — provider wiring (LLM/Search/Storage).
graph/ — LangGraph workflow construction.
agents/ — graph nodes + shared state.
ports/ + adapters/ — interfaces + implementations.
domain/ — core models (citations, evidence, reports, graphs).

Browse code: repo tree

Outputs

Artifacts are written under output/:

output/reports/*.md + *.json — final report

The report includes citations, findings, and verification status.

Key features

LangGraph workflow: planner → selector → adversary + supporter → judge → writer.
One search provider per run: Tavily, Exa, or DuckDuckGo (Wikipedia fallback).
Causal graph: variables and edges, each edge gets a verdict and confidence.
Ports/adapters design so providers can be swapped without touching the core flow.