Deepgraph README

The project's README from github.com/billion-token-one-task/Deepgraph. As one markdown file: README.md.

DeepGraph: an autonomous research agent that improves by being judged by reality

The autonomous research agent of JouleBeat, an open-source RSI lab.
It reads the literature, finds open questions, runs the experiments,
and lets reality decide what is true.

Website · Results · Showcase · Architecture · 中文

MIT Python 3.12+ Harness × Benchmark


Why DeepGraph

JouleBeat builds self-improving AI by letting harnesses and benchmarks evolve together.

How an agent works (its harness: tools, memory, workflow, verification) now moves capability by as much as a model generation, and open source has made harness variants cheap to generate. What is still scarce is the benchmark that tells real progress from a lucky score. So we put both in the loop: harnesses compete under benchmarks, and benchmarks compete on how well they predict results that arrive later.

That loop needs a steady stream of real tasks whose answers can be checked. Computational research is exactly that: a conclusion is confirmed or refuted by rerunnable code, held-out data or an independent recomputation, in minutes to days. DeepGraph is where those tasks come from.

How it works

Step What happens
1 Read Harvests arXiv at scale and extracts claims, methods and results
2 Map Merges them into an evidence graph of entities, relations and contradictions
3 Ask Ten structural detectors find open questions in pure SQL, with no LLM in the path
4 Test Turns a question into a pre-registered, budgeted experiment on CPU or GPU
5 Judge An evidence ladder issues a verdict only when the comparison is fair, and the result updates what gets searched next

Every verdict is auditable, and the system audits itself: in August 2026 it found and retracted 11 of its own conclusions that rested on empty model outputs. A search loop is only as good as the filter that decides what is true. Details in Results.

At a glance

Live production data, August 2026.

Papers 24,407 harvested, 7,005 through the full evidence pipeline
Evidence graph 248,441 entities, 735,913 relations, 238 contradiction clusters
Discovery 25,652 mapped research opportunities
Experiments 150 audited verdicts across six research agendas
Compute 921M LLM tokens invested

The JouleBeat stack

Layer What it is Status
DeepGraph Research agent: real tasks in, checkable conclusions out In service, with paying research groups
Harness × Benchmark libraries Versioned harnesses, and benchmarks scored on how well they predicted later outcomes Harness versioning running; benchmark validation in build
Evolution Kernel The engine: propose, evaluate, accept or roll back Open source, pip install evolution-kernel

Quick start

Python 3.12+ and an LLM API key are the minimum; PostgreSQL enables the full control plane.

python3.12 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env    # set at least DEEPGRAPH_LLM_API_KEY
export $(grep -v '^#' .env | xargs)
python3.12 main.py      # open http://localhost:8080

Full deployment (PostgreSQL, systemd, remote GPU backends): docs/DEPLOY.md.

Learn more

Contributing

Researchers: bring a computational question at deepgraph.joulebeat.com. Developers: issues and pull requests are welcome; contributions are covered by the CLA.

License

MIT

Deepgraph (billion-token-one-task/Deepgraph)

Searching Database…

What is this?DeepGraph is the autonomous research agent of JouleBeat, an open-source AI self-improvement (RSI) lab. It reads scientific literature, finds open questions, runs real experiments, and lets the results decide what is true.
Is this a standalone app or more of a pipeline?It is an end-to-end research pipeline: it harvests arXiv papers into an evidence knowledge graph, detects open questions with pure SQL (no LLM), and turns them into budgeted experiments judged by an evidence ladder.
How do I get it running?The quick start needs Python 3.12+ and an LLM API key; for the full control plane with PostgreSQL, systemd and remote GPU backends, follow the deployment guide at docs/DEPLOY.md.
Do I need a database set up first, or is it optional?PostgreSQL is optional for the minimal quick start but required to unlock the full control plane, systemd deployment, and remote GPU backends.
Is every conclusion it produces trustworthy?The system self-audits rather than guaranteeing correctness on every run: in August 2026 it caught and retracted 11 of its own conclusions that had rested on empty model outputs.
Who is this actually for?It is built for researchers who want checkable computational conclusions, and it doubles as JouleBeat's own R&D loop for evolving agent harnesses and benchmarks.
What is the Evolution Kernel?It is the open-source engine behind the JouleBeat stack that proposes, evaluates, accepts or rolls back changes to harnesses and benchmarks. It is installable separately via pip install evolution-kernel.
How does it find open research questions without an LLM in the loop?Ten structural detectors query the evidence graph using pure SQL to surface open questions, avoiding LLM involvement in that specific step to keep it deterministic and auditable.
What has DeepGraph actually produced so far?As of its August 2026 production data it had harvested 24,407 papers (7,005 fully processed), built a graph of 248,441 entities and 735,913 relations, and issued 150 audited experiment verdicts across six research agendas.
Why did JouleBeat build this instead of just benchmarking models directly?JouleBeat needs a constant stream of real, checkable tasks to judge new agent harnesses and benchmarks against; computational research provides exactly that because conclusions can be confirmed or refuted by rerunning code or data.
Size
85.1 MB
Stars
1K
Age
7mo
Commits · 90 Days