An auditable, multi-source pipeline for high-quality academic literature discovery
面向研究问题的自动化学术文献检索、分层筛选、质量评估、引文扩展与报告生成系统
Scholattice turns a natural-language research question into a ranked and traceable set of academic papers. Instead of relying on a single search API or a single relevance score, it combines query decomposition, six academic sources, semantic screening, LLM-assisted review, metadata quality signals, and citation expansion in one reproducible CLI workflow.
cd literature_agent
python main.py \
--rq "How can retrieval-augmented generation reduce hallucinations?" \
--config config/config.yaml \
--output-dir output/rag_hallucination \
--verboseThe run produces a readable literature report, structured paper records, a BibTeX bibliography, diagnostics, logs, and resumable checkpoints. PDF download is available when explicitly enabled.
View the text-rendered architecture
flowchart LR
RQ[Research Question] --> KP[Knowledge Primer]
KP --> QU[Query Understanding]
QU --> SR[Multi-source Retrieval]
SR --> S2[Semantic Scholar]
SR --> OA[OpenAlex]
SR --> AX[arXiv]
SR --> CR[Crossref]
SR --> DB[DBLP]
SR --> CO[CORE]
S2 --> PRE[Seed Injection<br/>Deduplication<br/>Language Filter]
OA --> PRE
AX --> PRE
CR --> PRE
DB --> PRE
CO --> PRE
PRE --> L1[L1 Semantic Filter]
L1 --> L2[L2 Relevance Review]
L2 --> L3[L3 Calibrated Scoring]
L3 --> MQ[Metadata Enrichment<br/>Quality Scoring]
MQ --> CE[Citation Expansion]
CE --> OUT[Ranking<br/>Clustering<br/>Exports]
The pipeline stores intermediate checkpoints and diagnostics so decisions can be inspected and long searches can recover from partial failures.
| Feature | Implementation | Why It Matters |
|---|---|---|
| Research-question decomposition | LLM-assisted query understanding and query generation | Searches multiple formulations instead of one literal query |
| Knowledge priming | Domain context, terminology, and candidate seed discovery | Improves query coverage before retrieval begins |
| Multi-source retrieval | Semantic Scholar, OpenAlex, arXiv, Crossref, DBLP, optional CORE | Reduces dependence on one index and one ranking policy |
| Seed injection | Curated seeds and automatically discovered seeds | Preserves known landmark papers when configured |
| Layered deduplication | Identifier, normalized-title, author-overlap, and title-similarity checks | Consolidates duplicate records across providers |
| L1 semantic screening | SPECTER2 embeddings with cache support and TF-IDF fallback | Removes obvious mismatches before expensive LLM review |
| L2 relevance review | Batched LLM classification, cache support, and rescue rules | Adds contextual relevance judgments with failure recovery |
| L3 calibrated scoring | Multi-dimensional scoring, soft thresholds, and borderline rescoring | Distinguishes strong, borderline, and weak candidates |
| Quality scoring | Venue, citation, author, institution, recency, and peer-review signals | Separates topical relevance from research quality |
| Citation expansion | Reference and citation traversal with relevance gates and OpenAlex fallback | Finds important papers missed by keyword retrieval |
| Auditable outputs | Exclusion records, diagnostics, checkpoints, and run metadata | Makes filtering and ranking decisions inspectable |
| Resilience controls | Retry policies, circuit breakers, budget tracking, and graceful degradation | Keeps partial provider failures from invalidating the run |
| Source | Primary Role | Credentials |
|---|---|---|
| Semantic Scholar | Semantic paper search, paper lookup, references, citations | Optional API key |
| OpenAlex | Broad scholarly search, metadata enrichment, citation fallback | Optional API key |
| arXiv | Preprint discovery | No key required |
| Crossref | DOI and publication metadata | Contact email recommended |
| DBLP | Computer-science publication metadata | No key required |
| CORE | Open-access discovery and optional PDF fallback | API key required when enabled |
Providers can be enabled or disabled in config/config.yaml. Only configure services you intend
to use.
The agent extracts the research scope, decomposes the question, generates search queries, and can prime the run with domain concepts and candidate seed papers.
Search requests run across the enabled academic sources. Provider-specific responses are mapped to a shared paper model before seed injection, cross-source deduplication, and language filtering.
Raw candidates
-> L1: embedding similarity and adaptive semantic threshold
-> L2: contextual relevance classification and rescue rules
-> L3: calibrated topic, method, and survey-fitness scoring
Early stages reduce cost; later stages spend more computation on the papers that remain plausible.
The pipeline enriches paper metadata, computes independent quality signals, and expands references and citations under strict relevance and convergence limits.
Final ranking combines relevance and quality evidence. The output stage groups related papers and writes both human-readable and machine-readable artifacts.
git clone https://github.com/Zhouyang66639/Scholattice.git
cd Scholattice/literature_agent
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
cp config/config.yaml.example config/config.yamlWindows PowerShell:
git clone https://github.com/Zhouyang66639/Scholattice.git
Set-Location Scholattice\literature_agent
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
Copy-Item config\config.yaml.example config\config.yamlThe embedding stack includes PyTorch and Transformers. Installation size and first-run model download time depend on the selected platform and model cache.
Keep real credentials in environment variables or the ignored local config/config.yaml.
export LLM_API_KEY="your-llm-key"
export SEMANTIC_SCHOLAR_API_KEY="your-s2-key"
export OPENALEX_API_KEY="your-openalex-key"
export CROSSREF_MAILTO="your-email@example.com"
export CORE_API_KEY="your-core-key"The LLM layer supports OpenAI-compatible endpoints through the provider and base-URL settings in the configuration file.
python main.py \
--rq "What methods improve factuality in retrieval-augmented generation?" \
--config config/config.yaml \
--output-dir output/factuality_review
| Option | Required | Description |
|---|---|---|
--rq, --research-question |
Yes | Natural-language research question |
--output-dir |
No | Output directory; defaults to output/ |
--config |
No | Configuration path; defaults to config/config.yaml |
--verbose, -v |
No | Enable detailed terminal and file logs |
python main.py --helpA run can create the following artifacts beneath the selected output directory:
output/<run>/
|-- report.md # grouped literature report
|-- papers.json # normalized papers, scores, and metadata
|-- references.bib # BibTeX bibliography
|-- checkpoints/ # resumable intermediate results and run metadata
|-- logs/ # terminal logs and diagnostic artifacts
|-- excluded/ # auditable exclusion records
`-- pdfs/ # optional downloaded papers
Exact diagnostic filenames depend on the enabled stages and providers.
Generated output can contain the research question, bibliographic metadata, model responses, and provider error details. Review run artifacts before sharing them outside your environment.
The example configuration groups controls for:
- source enablement, per-query limits, and circuit breakers;
- semantic, L2, and L3 filtering thresholds;
- seed injection and citation-expansion budgets;
- embedding and LLM caches;
- LLM provider, model, endpoint, timeout, and concurrency settings;
- venue, citation, author, institution, recency, and peer-review weights;
- retry and degradation behavior;
- optional PDF download.
Start from literature_agent/config/config.yaml.example; never commit the populated
config/config.yaml.
Scholattice/
|-- README.md
|-- .gitignore
`-- literature_agent/
|-- main.py
|-- requirements.txt
|-- config/
| |-- config.yaml.example
| |-- calibration_examples.json
| |-- seed_papers.yaml
| |-- top_institutions.json
| `-- venue_tiers.json
|-- src/
| |-- api_clients/ # academic provider clients
| |-- filters/ # L1, L2, and L3 relevance stages
| |-- quality/ # metadata enrichment and quality scoring
| |-- resilience/ # retry, circuit breaker, and budget controls
| |-- pipeline.py # end-to-end orchestration
| `-- output_generator.py # reports and structured exports
`-- tests/ # offline unit and integration tests
Private development notes, generated runs, caches, local configuration, and downloaded documents are intentionally excluded from the public tree.
The offline suite covers data models, configuration, API clients, query understanding, parsing, deduplication, L1/L2/L3 filtering, citation expansion, quality scoring, output generation, resilience, and pipeline integration.
cd literature_agent
python -m unittest discover -s tests -vLive API and LLM behavior still depends on provider availability, credentials, rate limits, and the configured models.
The tracked configuration file is a template and must contain placeholders only. The repository's ignore rules exclude local configuration, environment files, generated output, caches, logs, virtual environments, and private development documents.
Before publishing a fork or changing repository visibility:
- inspect the complete Git history, not only the current working tree;
- scan tracked files and staged changes for secrets and machine-local paths;
- remove generated reports, checkpoints, logs, PDFs, databases, and model caches;
- rotate any credential that has ever been committed;
- verify the README against the exact code revision being released.
This repository is a research prototype and command-line application. Search quality and runtime vary with the research question, enabled sources, metadata coverage, LLM behavior, model loading, network conditions, and available compute. Rankings support literature review; they do not replace expert screening or systematic-review methodology.
- Multi-source academic retrieval
- Knowledge priming and query decomposition
- Layered deduplication and language filtering
- L1/L2/L3 relevance pipeline
- Metadata quality scoring and citation expansion
- Markdown, JSON, and BibTeX export
- Checkpoints, diagnostics, and resilience controls
- Public benchmark and reproducible evaluation report
- Continuous integration across supported Python versions
- Installable package and versioned releases
- Optional web interface
This project builds on the public APIs and metadata provided by Semantic Scholar, OpenAlex, arXiv, Crossref, DBLP, and CORE, together with the open-source Python, PyTorch, and Hugging Face ecosystems.