SciAtlas

✨ Overview

SciAtlas is a research map you can use from the command line. Give it a topic, an idea, an author, or a paper trail, and it helps you look up literature, gather graph-backed evidence, and turn the result into readable reports and reusable JSON artifacts.

Behind that simple workflow is a large scientific knowledge graph. SciAtlas connects papers, authors, institutions, venues, keywords, citations, and a four-level research taxonomy from domains down to topics. That means a search is not limited to matching words: it can follow how research areas, people, concepts, and papers relate to one another.

This repository packages that capability as a lightweight SciAtlas client. New users can install it with pip, register an API token, and start running literature-grounded research tasks without setting up Neo4j, maintaining graph data, or touching backend infrastructure.

With the client, SciAtlas becomes a practical research assistant for:

• graph-aware paper search: combine keywords, semantic matching, title anchors, references, and graph propagation instead of stopping at plain keyword matching;
• research workflow automation: run literature review, idea grounding, idea evaluation, idea generation, trend analysis, related-author retrieval, and researcher profiling;
• agent-friendly outputs: keep reproducible machine-readable artifacts such as request.json and response.json, plus user-facing summary.txt and report.md;
• editable CLI skills: inspect, copy, modify, and rerun common downstream workflows as reusable JSON skills;
• portable Agent Skill pack: use agent-skill/ to migrate SciAtlas retrieval and the current literature-review, automated-review, and idea-generation workflows into end-to-end downstream tasks for tools such as Codex, Claude Code, and other coding agents.

📑 Table of Contents

• ✨ Overview
• 🚀 Quick Start
• 🔑 API Token
• 🧩 Supported Tasks
• 🛠️ CLI-First Workflow
• 🧰 Editable Skills
• 🖊Agent Skill
• 🐍 Python SDK
• 📦 Outputs and Artifacts
• 📂 Repository Layout
• 🧯 Troubleshooting
• 📝 TODO
• ✍️ Citation
• 📄 License

🚀 Quick Start

1. Install

Recommended one-command download and install with uv:

Linux / macOS:

curl -LsSf https://raw.githubusercontent.com/zjunlp/SciAtlas/main/scripts/install-sciatlas-uv.sh | sh

Windows PowerShell:

powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/zjunlp/SciAtlas/main/scripts/install-sciatlas-uv.ps1 | iex"

The installer downloads the full repository to ~/SciAtlas, creates a uv virtual environment, installs the SciAtlas CLI and workflow dependencies, and also exposes an editable sciatlas command through uv tool install.

Package-only alternatives are supported for the core CLI: health checks, configuration, plans, and hosted paper/author retrieval. They do not ship the repository-level literature-review, idea-evaluate, or idea-generate workflows.

Install directly from GitHub:

pip install "git+https://github.com/zjunlp/SciAtlas.git#subdirectory=sciatlas"

For isolated CLI usage:

pipx install "git+https://github.com/zjunlp/SciAtlas.git#subdirectory=sciatlas"

After installation:

sciatlas -h

2. Register an API Token

Open:

http://sciatlas.openkg.cn/register

Complete email verification and copy your personal token.

Quick link: 🔑 API Token.

3. Configure

At minimum, configure the hosted SciAtlas API endpoint and your personal token.

Linux / macOS:

export SCIATLAS_API_BASE_URL="http://sciatlas.openkg.cn"
export SCIATLAS_API_KEY="your-personal-sciatlas-token"
export SCIATLAS_TIMEOUT=900
export SCIATLAS_RUNS_DIR="./runs"

Windows CMD:

set SCIATLAS_API_BASE_URL=http://sciatlas.openkg.cn
set SCIATLAS_API_KEY=your-personal-sciatlas-token
set SCIATLAS_TIMEOUT=900
set SCIATLAS_RUNS_DIR=.\runs

📕 Optional: use your own LLM for keyword extraction

export LLM_PROVIDER="chat_completions"
export LLM_API_KEY="your-provider-api-key"
export LLM_BASE_URL="https://your-provider-or-gateway.example/v1"
export LLM_MODEL="your-model-name"
# Optional when your provider uses a custom endpoint or auth header:
# export LLM_CHAT_COMPLETIONS_URL="https://your-provider-or-gateway.example/v1/chat/completions"
# export LLM_AUTH_HEADER="x-api-key: your-provider-api-key"
export LLM_TIMEOUT=180
export LLM_TEMPERATURE=0.7
export LLM_MAX_TOKENS=512

This step is optional. Configure it only when you want SciAtlas to use your LLM API to turn a free-form query into better search keywords.

Keep LLM_PROVIDER=chat_completions, then replace LLM_API_KEY, LLM_BASE_URL, and LLM_MODEL with your provider values. If your provider gives a full chat-completions endpoint, set LLM_CHAT_COMPLETIONS_URL; if it requires a custom auth header, set LLM_AUTH_HEADER.

Leave the LLM values empty if you do not need this. The core retrieval CLI will use built-in keyword extraction. Dedicated literature-review, idea-evaluate, and idea-generate workflows have their own credential requirements; see Workflow prerequisites and the relevant workflow section before running them.

User-editable template: .env.example. Set these variables only if you want LLM-assisted keyword extraction.

🖊 Optional: OpenAlex metadata support

export OA_API_KEY=""
export OPENALEX_MAILTO=""

OpenAlex is useful when you want extra metadata or PDF-related support. It is not required for the main CLI examples in this README. If you leave these variables empty, normal SciAtlas retrieval still works.

User-editable template: .env.example. Set these only if you want OpenAlex-assisted metadata support.

🖌 Optional: GROBID for local PDF workflows

GROBID is only needed when you process local PDF files. It reads scientific PDFs and extracts titles, authors, abstracts, and references. If you are only running the text-based CLI commands above, you can skip this section.

Start GROBID locally:

docker pull lfoppiano/grobid:latest
docker run -d --rm --name grobid -p 8070:8070 lfoppiano/grobid:latest
curl http://127.0.0.1:8070/api/isalive

Then set:

export GROBID_BASE_URL="http://127.0.0.1:8070"

Windows CMD:

set GROBID_BASE_URL=http://127.0.0.1:8070

User-editable template: .env.example. Leave GROBID_BASE_URL empty unless you process local PDFs.

🧪 Required: embedding / rerank models for idea evaluation

The idea-evaluate rubric branch and the grounding stage need two local models: bge-large-en-v1.5 (embedding) and bge-reranker-large (reranking). Download them once into <repo>/models/ (~1.3GB each) — the workflow auto-detects them there, no environment variables required:

pip install -r requirements-rubric.txt
export HF_ENDPOINT=https://hf-mirror.com   # mainland-China mirror; omit when huggingface.co is reachable
huggingface-cli download BAAI/bge-large-en-v1.5 --local-dir models/bge-large-en-v1.5
huggingface-cli download BAAI/bge-reranker-large --local-dir models/bge-reranker-large
python scripts/download_rubric_assets.py   # precomputed NC-paper artifacts + FAISS index (~160MB)
python scripts/check_rubric_setup.py       # pre-flight check; prints fixes for anything missing
python run_rubric.py --idea "your research idea"

The directory names must be exactly models/bge-large-en-v1.5 and models/bge-reranker-large — the FAISS index in the asset pack was built with bge-large-en-v1.5 (1024 dims), so other embedding models will not match. Models stored els