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 the base search-papers capability 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 also exposes sciatlas through uv tool install.

Package-only alternatives are also supported.

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 SCIATLAS_LLM_TIMEOUT=30
export SCIATLAS_LLM_TEMPERATURE=0
export SCIATLAS_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. SciAtlas will use built-in keyword extraction, and normal search, review, idea, trend, and researcher workflows still run.

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.

Runtime variables:

4. Test

sciatlas health
sciatlas config

5. Run a Paper Search

sciatlas search-papers \
  --query "open world agent" \
  --keyword "high:open world agent" \
  --top-k 10

🔑 API Token

SciAtlas uses personal API tokens for public access.

Browser Registration

Visit:

http://sciatlas.openkg.cn/register

Steps:

1. enter your name, email, organization, and use case;
2. clic