research-agent

Self-improving deep research agent for the terminal.
Built-in eval suite. GEPA self-improvement loop. Single file.

$ pip install git+https://github.com/bigknoxy/research-agent.git

Features

Deep Research

Multi-step web search with DDG, Wikipedia, and SearXNG backends. Cross-source contradiction detection. Structured report synthesis.

Eval-Driven

Built-in evaluation suite with 3 research tasks and 12 deterministic quality checks. Run with --eval. Regression-proof your prompts.

Self-Improving

GEPA loop evolves prompt strategies across generations. Mutates, evaluates, and selects winners by accuracy. Discovers what works.

Self-Patching

Generates _self_patch.py with learned prompt improvements. Apply with one command. Version bumped automatically.

Local LLM Grading

Auto-detects Ollama models for quality scoring. Falls back to heuristic grading when no GPU is available.

Single File

Zero infrastructure. One Python file. pip install from GitHub. No API keys, no databases, no containers.

Quick Start

# Install
pip install git+https://github.com/bigknoxy/research-agent.git

# Run a research query
research-agent "What are the latest developments in RAG?"

# Run the eval suite
research-agent --eval --eval-runs 1

# Self-improvement loop
research-agent --gepa --gepa-generations 3

# Full dogfood pipeline
research-agent --dogfood

# Apply learned improvements
python _self_patch.py

# Update to latest
pip install --upgrade git+https://github.com/bigknoxy/research-agent.git
research-agent --self-update

# Uninstall
pip uninstall research-agent

How It Works

research-agent is built around a pipeline of specialized modules, each guided by prompt strategies that the GEPA loop evolves over time:

Query → TaskPlanner → WebCrawler → ContradictionEngine → ReportSynthesizer → Report
         ↑              ↑            ↑                     ↑
         └─── Prompt strategies evolved by GEPA loop ──────┘

The GEPA loop evaluates prompt strategy variants against the test suite, selects winners by accuracy, and mutates them to discover better strategies. All improvements self-patch into the script.

Read the full design doc →

Philosophy

Most AI research tools are closed-source, require API keys, or depend on heavy infrastructure. research-agent is free, private, self-improving, and auditable. It runs entirely on your machine, gets better with every run, and is a single file you can read end-to-end.