Agentic Research

agentic-research-engine-oss

The best $0 research agent that runs on a laptop. Open-source end-to-end, reproducible, privacy-preserving. No cloud dependency by default; no telemetry; every LLM call, every source, and every verification decision is visible.

Table of contents

• TL;DR
• Why use this instead of…
• Quickstart — Mac local
• Quickstart — no install (Google Colab)
• Three ways to drive it
• What ships
• Domain presets
• Bring your own documents
• MCP + Claude plugin
• Plugin / skill loader
• Architecture at a glance
• Repo layout
• Configuration (env vars)
• Testing
• Troubleshooting
• Honest limits
• Status + roadmap
• Contributing
• License

TL;DR

Local-first research agent that verifies its own answers. Runs on Gemma 3 4B + Ollama (3.3 GB on disk) for $0/query; swaps to any OpenAI-compatible endpoint with one env var.

pip install agentic-research-engine

agentic-research ask "what is Anthropic's contextual retrieval?" --domain papers

Why use this instead of…

Honest read: on complex multi-hop reasoning benchmarks, Gemma 3 4B sits 15–25% below 30 B+ open models. We don't claim to beat GPT-5.4 Pro. We claim to be the best $0, runs-on-your-laptop, fully-open research agent in April 2026.

Quickstart — Mac local

Option A — PyPI (fastest)

# 1) Local inference (Ollama + Gemma 3 4B + embedding model — 3.6 GB combined)

brew install ollama ollama pull gemma3:4b nomic-embed-text

2) Self-hosted meta-search (Docker; optional but recommended)

docker run -d --name searxng -p 8888:8080 searxng/searxng

3) The engine itself

pip install agentic-research-engine

4) Go

export OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_API_KEY=ollama export MODEL_SYNTHESIZER=gemma3:4b EMBED_MODEL=nomic-embed-text export SEARXNG_URL=http://localhost:8888 agentic-research ask "what is Anthropic's contextual retrieval?" --domain papers

Option B — from source

# 1) Same local-inference prereqs as Option A (ollama pull + docker run)

2) Clone + install (gives you the CLI, TUI, Web GUI, MCP server, benchmarks, tutorials)

git clone https://github.com/TheAiSingularity/agentic-research-engine-oss cd agentic-research-engine-oss (cd scripts/searxng && docker compose up -d) cd engine && make install make smoke # end-to-end run on the canonical "what is contextual retrieval" question

Expected wall-clock on an M-series Mac: ~45 s for a factoid, ~90 s for multi-hop synthesis. Zero dollars per query.

Higher honesty — cloud-model mode

Gemma 3 4B is surprisingly good at structure (plan, route, verify, compress) but confabulates specific factoids when SearXNG doesn't surface a source containing the right token. Live SimpleQA-mini run on 2026-04-21 (see engine/benchmarks/RESULTS.md) showed gemma3:4b emitting "2023" for *"year Anthropic published Contextual Retrieval"* (gold: 2024) and "LayoutLMv3" for *"which cross-encoder for reranking"* (gold: bge-reranker-v2-m3).

The fix you probably want isn't a smarter synthesizer — it's a more honest one. A 5-question head-to-head on the same retrieval output showed gpt-5-nano + gpt-5-mini refuse to confabulate when evidence was missing (*"The provided evidence does not answer this question"*), where gemma3:4b confidently guessed. Per-claim faithfulness went from 82.9 % → 100 %. Pass rate barely moved (1/5 vs 0/5) because retrieval is the real bottleneck — if SearXNG didn't return a source with the gold token, neither model can produce it.

Swap the whole stack to a cloud endpoint:

# drop the Ollama base URL (fall back to OpenAI cloud)

unset OPENAI_BASE_URL export OPENAI_API_KEY=sk-...

defaults are already cloud-sized: gpt-5-nano for plan/verify, gpt-5-mini for synth.

Explicit override if you want to pin them:

export MODEL_PLANNER=gpt-5-nano export MODEL_SYNTHESIZER=gpt-5-mini # or gpt-5, claude-sonnet-4-5, etc. agentic-research ask "…" --domain papers

Cost is dominated by synthesizer tokens (~5–15 k per query). Full cloud mode with gpt-5-nano + gpt-5-mini runs roughly $0.02–0.05 per research query and is ~2-3× slower than Gemma local (measured: 127 s vs 52 s mean wall on the 5-question subset). Works with any OpenAI-compatible endpoint — Groq, Together, Mistral, DeepSeek, local vLLM — so you can pick a cheap fast model (llama-3.3-70b on Groq ≈ $0.003/query) or a frontier one. Per-node base-URL routing (run gemma3:4b locally for plan/verify AND gpt-5-mini on cloud for synth in the same query) is tracked for 0.2; today the pipeline uses one global OPENAI_BASE_URL.

The bigger accuracy lever is retrieval. Point LOCAL_CORPUS_PATH at an indexed corpus containing your answer and either model will be correct.

Quickstart — no install (Google Colab)

Five runnable notebooks in tutorials/:

1. 01 — Engine API quickstart (mocked, no key) — see how the pipeline works without running inference.
2. 02 — Groq cloud inference (free tier) — real LLM, no local GPU.
3. 03 — Build your own corpus — upload PDFs, index them, query.
4. 04 — MCP server from Python — drive the engine as a tool from another agent.
5. 05 — Domain presets showcase — compare presets on the same question.

Each notebook is self-contained, runs end-to-end on Colab free tier, no credit card required.

Three ways to drive it

CLI

engine ask "what is hybrid retrieval?" --domain papers --memory session

engine reset-memory engine domains list engine version

TUI (Textual — keyboard-driven, SSH-safe)

make tui

Three panes: sources · answer + hallucination flags · trace + memory hits. Press Enter to ask, Ctrl-M to cycle memory mode, Ctrl-L to clear, Ctrl-Q to quit.

Web GUI (FastAPI + HTMX on localhost:8080)

make gui

open http://127.0.0.1:8080 in your browser

No auth. No cloud. No analytics. Dark theme. Streams tokens in place.

What ships

engine/ — the flagship

8-node LangGraph pipeline with 2026-SOTA composition: classify → plan → search → retrieve → fetch_url → compress → synthesize → verify

Every stage is env-toggleable for leave-one-out ablation. Techniques folded in: HyDE, CoVe verification, iterative retrieval, FLARE active retrieval, question classifier router, step critic (ThinkPRM pattern), LongLLMLingua-lite compression, cross-encoder rerank (BAAI/bge-reranker-v2-m3), Anthropic contextual chunking, W6 small- model hardening (three-case synthesize prompt + per-chunk char cap).

core/rag/ — reusable retrieval primitives (v1 stable)

HybridRetriever (BM25 + dense + RRF) · CrossEncoderReranker · contextualize_chunks (Anthropic pattern) · CorpusIndex (bring- your-own-PDFs). 5 exports, used by the engine and the archived recipes.

archive/recipes/ — pre-engine reference recipes

research-assistant, trading-copilot, document-qa, rust-mcp-search-tool. All still work; all tests still pass. The research-assistant/production/main.py is a thin shim over engine.core.pipeline so the cookbook framing is preserved.

Domain presets

Six YAML files in engine/domains/:

Write your own in ~10 lines of YAML — see docs/domains.md.

Bring your own documents

python scripts/index_corpus.py build ~/papers --out ~/papers.idx

export LOCAL_CORPUS_PATH=~/papers.idx engine ask "what do my papers say about contextual retrieval?" --domain personal_docs

Supported formats: PDF (via pypdf), Markdown, plain text, HTML (via trafilatura). The index persists as a directory with a human-readable manifest.json + a pickled index.pkl. Rebuild anytime the docs change.

Details: docs/self-learning.md covers the trajectory + memory model; docs/plugins-skills.md covers external plugins.

MCP + Claude