Agentic Research README

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 plugin

engine/mcp/server.py is a Python MCP server exposing:

• research(question, domain?, memory?) → structured {answer, verified_claims, unverified_claims, sources, trace, totals, memory_hits}
• reset_memory()
• memory_count()

Bundled Claude plugin at engine/mcp/claude_plugin/ — four skills (/research, /cite-sources, /verify-claim, /set-domain), ready to submit to the Anthropic marketplace.

Register in Claude Desktop:

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "engine": {
      "command": "python",
      "args": ["-m", "engine.mcp.server"],
      "env": {
        "OPENAI_BASE_URL": "http://localhost:11434/v1",
        "OPENAI_API_KEY":  "ollama",
        "MODEL_SYNTHESIZER": "gemma3:4b",
        "SEARXNG_URL":    "http://localhost:8888"
      }
    }
  }
}

Plugin / skill loader

Install third-party Claude plugins or Hermes (agentskills.io) skills:

engine plugins install gh:owner/some-research-plugin@v1
engine plugins install file:./my-local-plugin
engine plugins install https://example.com/marketplace.json
engine plugins list
engine plugins uninstall some-plugin

Safety: every install runs a forbidden-symbols scan (eval(, exec(, os.system(, …) — rejects plugins that would execute arbitrary code. Registry lives at ~/.agentic-research/plugins/, fully inspectable, wipable.

Full docs: docs/plugins-skills.md.

Architecture at a glance

                ┌─────────────┐
                │   question  │
                └──────┬──────┘
                       ▼
           ┌─────────────────────────┐   T4.3 router  — route by question type
           │  classify               │
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T1 decompose · T2 HyDE · T4.1 critic
           │  plan                   │   T4.5 refine-on-reject
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   SearXNG parallel × N
           │  search                 │   + W5 local corpus (optional)
           │  (+ T4.1 critic)        │   + T4.1 coverage critic
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T1 hybrid BM25 + dense + RRF
           │  retrieve               │   W4.1 cross-encoder rerank (opt-in)
           │  (+ W4.1 rerank)        │
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   W4.2 trafilatura clean-text
           │  fetch_url              │   skips corpus:// URLs
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T4.4 LLM distillation
           │  compress               │   + W6.2 per-chunk char cap
           │  (+ W6.2 cap)           │
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T2 synth · T4.2 FLARE on hedges
           │  synthesize             │   W6.1 three-case anti-hallucinate
           │  (+ FLARE + stream)     │   W7 streaming
           └──────────┬──────────────┘
                      ▼
           ┌─────────────────────────┐   T2 CoVe — decompose + verify
           │  verify                 │
           └────────┬────────────────┘
                    │
              verified? ── yes ──▶ END
                    │
                    no
                    │
           ◀────── re-search unverified claims ──── loop (bounded by MAX_ITERATIONS)

Every stage has an ENABLE_* flag so you can leave-one-out ablate. Deep spec: docs/architecture.md.

Repo layout

agentic-research-engine-oss/
├── engine/                        the flagship research engine
│   ├── core/                      pipeline · models · trace · memory
│   │   ├── pipeline.py              · compaction · domains · plugins
│   │   ├── models.py
│   │   ├── trace.py
│   │   ├── memory.py
│   │   ├── compaction.py
│   │   ├── domains.py
│   │   └── plugins.py
│   ├── interfaces/
│   │   ├── cli.py                 rich stdout CLI with subcommands
│   │   ├── tui.py                 Textual TUI
│   │   └── web/                   FastAPI + HTMX localhost GUI
│   ├── mcp/
│   │   ├── server.py              Python FastMCP server
│   │   └── claude_plugin/         submittable Claude plugin bundle
│   ├── domains/                   6 YAML presets
│   ├── examples/                  5 worked research examples
│   ├── benchmarks/                mini SimpleQA + BrowseComp fixtures + runner
│   └── tests/                     pytest suite (all mocked, zero-network)
├── core/rag/                      shared retrieval primitives (stable v1)
├── archive/                       pre-engine recipes (kept for reference)
├── tutorials/                     5 Google Colab notebooks
│   ├── 01_engine_api_quickstart.ipynb
│   ├── 02_groq_cloud_inference.ipynb
│   ├── 03_build_your_own_corpus.ipynb
│   ├── 04_mcp_server_from_python.ipynb
│   └── 05_domain_presets_showcase.ipynb
├── scripts/
│   ├── searxng/                   self-hosted meta-search (docker-compose)
│   ├── setup-local-mac.sh         Ollama + Docker + SearXNG one-liner
│   ├── setup-vm-gpu.sh            Linux + vLLM/SGLang setup
│   └── index_corpus.py            build a CorpusIndex from PDFs/md/txt
├── docs/
│   ├── architecture.md            deep technical spec
│   ├── plugins-skills.md          write + install plugins
│   ├── domains.md                 write a new preset
│   ├── self-learning.md           trajectory logging + memory
│   ├── progress.md                wave-by-wave build log
│   ├── how-it-works.md            elevator pitches + SOTA comparison
│   ├── launch-checklist.md        go-live sequence
│   └── launch-copy.md             drafted HN / Reddit / Twitter copy
├── .github/
│   ├── workflows/
│   │   └── engine-tests.yml       CI: mocked suite on every PR
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── LICENSE                        MIT
└── README.md                      you're reading it

Configuration (env vars)

Full list in engine/core/pipeline.py header. Most-common knobs:

Full list: docs/architecture.md env-vars section.

Testing

cd engine && make test     # 120+ mocked tests in engine/tests/
# or repo-wide:
PYTHONPATH=$(pwd) .venv/bin/python -m pytest core/rag recipes engine/tests -q

All tests are mocked — no network, no API key, no model downloads. Live integration smokes are separate (make smoke).

CI runs on every push / PR touching engine / core / recipes — see .github/workflows/engine-tests.yml.

Troubleshooting

Still stuck? Open an issue with the bug_report template — include ollama list, engine version, and the error.

Honest limits

• Gemma 4B ≠ GPT-5.4 Pro. 15–25 % below 30 B+ open models on hard multi-hop. We position as "best $0 local", not "SOTA."
• Gemma 3 4B confabulates specific factoids when SearXNG doesn't return a source that contains the right token. Measured on SimpleQA-mini: 0/20 strict pass rate (see engine/benchmarks/RESULTS.md — verified_ratio 85.5 %, zero must_not_contain hits; the model isn't emitting banned strings, it's picking wrong ones). Mitigations: (a) swap the whole stack to a cloud endpoint (see "Higher factoid accuracy" above — $0.02–0.05/query with gpt-5-nano + gpt-5-mini), (b) give the engine a LOCAL_CORPUS_PATH so your own docs become retrieval targets, (c) set ENABLE_RERANK=1 to bias retrieval toward the right sources.
• CoVe confirms internal consistency, not ground truth. Every synthesized claim is checked against retrieved evidence; claims don't get verified by the world. If retrieval misses, CoVe will still happily verify a confidently-wrong answer. The engine will never fabricate citations, but it can confidently repeat wrong information that was in its evidence pool.
• No LoRA fine-tuning in v1. Trajectory data is collected; actual model training deferred until GPU access + data volume.
• No hosted SaaS. Local-first is the entire v1 positioning.
• Team / multi-user features. Out of scope for v1.
• General web crawler / own search index. Not shipping. SearXNG stays. A curated research-focused index may land in v2.
• Mobile. Not in scope.

Status + roadmap

• 0.1.3 — public alpha (current). Features listed above; on PyPI + the official MCP registry + the Anthropic plugin marketplace. See CHANGELOG.md.
• 0.2 — specialist tool wiring (tools_enabled field in presets finally activates), first LoRA run if GPU arrives, plugin catalog in docs/.
• 0.3 — team-collab features (shared memory, PR-driven domain presets), desktop app packaging via Tauri.
• 0.4+ — open-work tracked in GitHub Issues.

Contributing

Good first issues: CONTRIBUTING.md. RFCs for anything pipeline-scope. Plugin + domain-preset submissions welcome.

No Co-Authored-By trailers; author-as-written-by.

License

MIT. See LICENSE.

Related (sibling projects)

• HermesClaw — the secure runtime these recipes can run inside
• NVIDIA/OpenShell — kernel-level agent sandbox
• NousResearch/hermes-agent — self-improving agent (whose agentskills.io skill format we interoperate with)

MCP registry ownership

This PyPI package is the official source of the MCP server registered at https://registry.modelcontextprotocol.io. The line below is the ownership marker the registry validates — do not remove when editing this README.

mcp-name: io.github.TheAiSingularity/agentic-research