Scholar RAG Agent

Scholar RAG Agent is a production-grade, local-first Agentic RAG system for scientific literature. It ingests papers from PDFs, arXiv, arXiv HTML abs abstracts, Semantic Scholar search and recommendations, OpenAlex, OpenAlex authors, OpenAlex author works, OpenAlex concepts, OpenAlex concepts ancestors, OpenAlex institutions, OpenAlex sources/venues, OpenAlex source hierarchies, OpenAlex sources host org, PubMed MeSH, OpenAlex topics hierarchy, Semantic Scholar bulk, OpenAlex publishers, OpenAlex funders, OpenAlex keywords, OpenAlex topics, PubMed, PubMed Central (PMC), PMC OA packages, Crossref, Crossref types filter, Crossref members, Crossref relations, Crossref Funder Registry, Crossref works-by-funder, Crossref works-by-license, Crossref works type+license, Crossref works ISSN+type, Crossref works-by-ISBN, Crossref Event Data, Crossref journals, Europe PMC, Europe PMC grants, DOAJ, DBLP, HAL, OpenAIRE, OpenAIRE projects, Zenodo, Figshare, CORE, bioRxiv/medRxiv, bioRxiv/medRxiv collections, NASA ADS, DataCite, DataCite related identifiers, DataCite reports, DataCite DOIs-by-prefix, DataCite Event Data, OpenCitations, OSF, ORCID, ORCID works filter, ORCID works summaries, ORCID education, Unpaywall, Dryad, Wikidata scholarly entities, SSRN preprints, OpenAlex retraction alerts, and ClinicalTrials.gov; builds hybrid dense, sparse, and entity-relationship retrieval indexes; and answers research questions with multi-hop reasoning and citation-backed evidence.

Scholar RAG Agent supports reproducible scientific knowledge synthesis, helping researchers accelerate literature review, hypothesis validation, and grounded comparison across large corpora while preserving source provenance.

Why Researchers Need This

Most literature workflows break down when the corpus grows beyond a few papers:

• Issue: keyword search misses papers that use different terminology. Scholar RAG Agent combines dense semantic retrieval, BM25 sparse search, HyDE expansion, and RRF fusion so a query can match both exact terms and related scientific phrasing.

• Issue: fused results are dominated by near-duplicate passages that waste the context window. An optional Maximal Marginal Relevance (MMR) re-ranker balances relevance against novelty, dropping redundant chunks so the model sees complementary evidence.

• Issue: single-hop RAG retrieves isolated snippets but misses evidence chains. The GraphRAG layer extracts entities and relationships, then follows bounded multi-hop paths to connect methods, datasets, findings, and limitations across papers.

• Issue: generated summaries sound plausible but are hard to audit. Every answer is mapped back to retrieved chunk IDs, and unsupported claims are flagged with [UNGROUNDED] instead of being silently trusted.

• Issue: research questions often need a plan, not just one search call. The Observe -> Decide -> Act runtime classifies intent, decomposes the query into retrieval sub-tasks, and persists a JSON rationale trace for every decision.

• Issue: teams need reproducible evidence trails for reviews, grants, and publications. The SQLite event log records state transitions, timestamps, agent IDs, run IDs, plans, retrieval payloads, and final answer provenance.

Example Use Cases

• Systematic literature review: ingest a folder of PDFs plus arXiv IDs, ask for the strongest themes, and receive cited claims grouped by supporting chunks.

• Research and grant evidence synthesis: collect papers around a research question or contribution, assess novelty claims, and export citation-backed reasoning traces showing the evidence for each claim.

• Hypothesis validation: ask whether the literature supports or refutes a hypothesis, then inspect supporting and counter-evidence retrieval tasks separately.

• Method comparison: compare approaches such as GraphRAG, dense retrieval, and BM25 across papers while preserving the source chunks behind each contrast.

• Research onboarding: give a new lab member a paper corpus and let them ask grounded factual, synthesis, comparison, and hypothesis questions without manually reading every PDF first.

• Prior-art triage: search Semantic Scholar and arXiv records, expand a trusted seed through Semantic Scholar recommendations, ingest abstracts, then identify overlapping methods, datasets, and claims before deeper manual review.

• Citation QA for drafts: paste draft claims as questions and flag statements that are not supported by the ingested source chunks.

• Multi-provider LLM evaluation: route reasoning, speed, cost, and default tasks to different adapters while keeping output validation and citation grounding consistent.

Demo Gallery

                 +---------------------------+
                 | Observe: Query Analyzer   |
                 +-------------+-------------+
                               |
                               v
+---------+      +-------------+-------------+      +-------------------+
| Papers  +----->| Decide: Planner           +----->| Act: Executor     |
+---------+      +-------------+-------------+      +---------+---------+
 PDF/arXiv/S2                  |                              |
                               v                              v
                   +-----------+-----------+       +----------+----------+
                   | SQLite Durable Events |       | Hybrid Retrieval    |
                   +-----------------------+       | Dense + BM25 + RRF  |
                                                   +----------+----------+
                                                              |
                                                              v
                                                   +----------+----------+
                                                   | GraphRAG Multi-hop  |
                                                   +----------+----------+
                                                              |
                                                              v
                                                   +----------+----------+
                                                   | LLM Router + Guard  |
                                                   +----------+----------+
                                                              |
                                                              v
                                                   Citation-backed answer

Install In 3 Commands

git clone https://github.com/Francis1998/scholar-rag-agent.git
cd scholar-rag-agent && uv sync --extra dev
uv run pytest tests/ -v

Local Demo

uv run python scripts/demo_local.py
uv run uvicorn api.main:app --reload

The deterministic demo ingests a small fixture paper, executes an Observe -> Decide -> Act run, prints the planner trace, and returns a cited answer. A generated demo asset is available at docs/assets/demo.gif.

Additional GIFs in docs/assets/ show the problem-to-solution flow, planner trace, and citation grounding guard.

Documentation

Provider Keys

All live providers are optional. Without keys the system uses deterministic fakes for tests and demos. Configure keys in .env or your shell:

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GEMINI_API_KEY=...
export MOONSHOT_API_KEY=...
export [email protected]

When enabled, downstream synthesis can route through GPT-5.5, Claude Sonnet 4.6, Gemini 3.x, and Kimi K2 while deterministic connectors such as Unpaywall keep source lookup reproducible. For downstream synthesis and evaluation, the preferred frontier model families are GPT-5.5, Claude Sonnet 4.6, Gemini 3.x, and Kimi K2. Gemini 3.x, and Kimi K2 while deterministic connectors such as Unpaywall and retraction checks keep source lookup reproducible.

Quality Gates

uv run ruff check . && uv run ruff format --check .
uv run mypy src/
uv run pytest tests/ -v --cov=src --cov-fail-under=70

License

Apache-2.0. See LICENSE.