QuantumAtlas

README

QuantumAtlas

A paper collection, multi-paradigm search, and registry database for quantum algorithm research.

📚 Documentation is the Sphinx/Furo site served by qatlasd at /doc (user guide) and /devdoc (developer guide). The current internal instance is https://qatlas.hfnl.app.chenzhaoyun.com/doc/. It is not published to Read the Docs.

QuantumAtlas collects quantum-algorithm papers from arXiv, parses them into structured assets, registers every paper and asset in a PostgreSQL database, and answers queries through a single search endpoint that fans out across multiple paradigms — the local catalog, arXiv, OpenAlex, and (optionally) semantic vector retrieval via Qdrant.

The core idea is simple: collect once, register everything, search everywhere. Raw assets (PDF / Markdown / images) live in S3-compatible object storage, the paper registry in PostgreSQL tracks metadata, identities, and asset state, and the search engine queries across all of it without making you pick a paradigm up front.

arXiv / user uploads
    -> Object storage      Immutable raw assets (PDF / MD / images, per-kind buckets)
    -> Postgres registry   Papers, identities, asset state (goose-migrated at boot)
    -> Search engine       POST /api/search: catalog + arxiv + openalex (+ qdrant)

What it does

• Fetch papers from arXiv and parse PDFs into Markdown (MinerU pipeline).
• Register every paper, identity (arXiv ID / DOI), and asset in a PostgreSQL paper registry — queryable with plain SQL.
• Search across paradigms from one endpoint (POST /api/search): local catalog, arxiv.org, OpenAlex, and optional Qdrant hybrid vector retrieval (dense+sparse, RRF + rerank).
• Ingest lazily: assets are fetched and converted on demand, with server-side dedupe and LRO-style status polling.
• Mirror the OpenAlex works corpus into Postgres for citation context and batch analysis.
• Collaborate remotely through the Web API, CLI, and share links — no server login required for contributors.

Installation

QuantumAtlas has two independently maintained components:

• qatlasd (Go server with PocketBase + SQLite) — precompiled releases embed the complete UI; go install automatically fetches and caches the same UI from its exact version's GitHub Release on first start
• qatlas (Python CLI, qatlas-cli package) — the daily-driver client, maintained and released in IAI-USTC-Quantum/qatlas-cli

Install the server (qatlasd)

Choose a published tag using the new release format. vX.Y.Z below is a placeholder, not an existing release; this change does not reissue v0.34.0.

TAG=vX.Y.Z # replace with the selected published release tag
# Download the installer from that SAME tag, review it, then run it.
curl -fL --proto '=https' --proto-redir '=https' \
  "https://raw.githubusercontent.com/IAI-USTC-Quantum/QuantumAtlas/$TAG/cmd/qatlasd/install-qatlasd.sh" \
  -o install-qatlasd.sh
sh install-qatlasd.sh --version "$TAG" # optionally: --dir /opt/qatlas/bin

The installer verifies the default GoReleaser tar.gz checksum and executable version before atomic replacement. Supported precompiled platforms: linux/{amd64,arm64} + darwin/arm64. They include the entire UI and documentation and need no first-run UI download. An old running server's /install-qatlasd.sh does not understand the new archive format; use the tag-pinned script during migration.

Alternatively, with Go matching go.mod (no Node or Sphinx required):

go install "github.com/IAI-USTC-Quantum/QuantumAtlas/cmd/qatlasd@$TAG"
# Ensure $(go env GOPATH)/bin (or GOBIN) is on PATH.

On first serve, a source-installed binary downloads qatlasd_<version>_web.zip and the checksum list from its exact Release, validates them and atomically caches the bundle under the OS user cache directory's qatlas/ui/v<version>. Later starts use the verified cache offline; upgrades fetch a separate version. Download, validation and unsupported dev/pseudo-version errors stop startup—never silently fall back to latest. Both installation methods use the same Web service once resources are ready. See installation and recovery.

Prepare normal server configuration, then start or explicitly register a service (the installer does neither):

qatlasd --version
qatlasd config init # ~/.qatlas/config.yaml; refuses to overwrite an existing file
# Edit the YAML for your backing services and credentials.
qatlasd serve
# Or register the background service explicitly:
qatlasd service install --mode user --config "$HOME/.qatlas/config.yaml" --force

Install the client (qatlas CLI)

Old package retirement: the final quantum-atlas 0.21.0 has been published as a metadata-only migration notice. It contains no qatlas module, parser library, console entry point, or runtime dependencies, and does not automatically install qatlas-cli. There will be no further legacy releases. This repository is not a Python distribution and does not provide the qatlas command. For a new installation, choose one command below. Existing quantum-atlas users must migrate first.

# Recommended: uv global tool (isolated env + easy upgrades)
uv tool install qatlas-cli

# or pipx
pipx install qatlas-cli

# or plain pip
pip install qatlas-cli

qatlas --help

The qatlas CLI points at a remote server via its YAML config (qatlas config set). See docs/client/cli-qatlas.md.

Migrate from quantum-atlas

Choose only the installer you originally used, in the same environment:

# uv tool users
uv tool uninstall quantum-atlas
uv tool install qatlas-cli

# OR pipx users
pipx uninstall quantum-atlas
pipx install qatlas-cli

# OR pip users (activate the original virtual environment first, if used)
pip uninstall quantum-atlas
pip install qatlas-cli

If both packages were already installed, uninstalling the old package can remove shared module or command paths. Reinstall qatlas-cli after uninstalling quantum-atlas, even if the installer says the new package is already present:

# Choose the matching installer again
uv tool install --reinstall qatlas-cli
# OR
pipx reinstall qatlas-cli
# OR
pip install --force-reinstall qatlas-cli

qatlas --help

Do not delete ~/.config/qatlas (or the corresponding platform config directory): keep your existing configuration and credentials. The old package's remaining Python helpers are retired, not a supported library API in this repo.

Quickstart

Run the server locally

For a checkout (including unreleased commits), first build the complete UI using the pinned development instructions, then:

CGO_ENABLED=0 go build -tags embedui -o build/qatlasd ./cmd/qatlasd
./build/qatlasd config init
# Edit ~/.qatlas/config.yaml, e.g. postgres.dsn and GitHub OAuth settings.
./build/qatlasd serve --http=127.0.0.1:4200

Plain go build and go test work without any generated frontend files. Local build info may contain a tag, pseudo-version, or +dirty marker; dev is the fallback when usable version metadata is absent. A binary without a corresponding public Release needs embedui to serve UI. Git stores only source; never commit web/dist, generated docs, caches or release archives.

Default entry points:

• Home / SPA: http://localhost:4200
• PocketBase admin UI: http://localhost:4200/_/
• PAT management: http://localhost:4200/pat (CLI bearer tokens use PATs, with finer scope/expiry/audit)

Or with Docker — Compose starts qatlasd and optional app profiles; PostgreSQL and object storage remain external:

cd deploy
cp .env.docker.example .env   # pin image versions only; app config is ~/.qatlas/config.yaml
docker compose up -d

Production deployment, systemd install, reverse proxy, and the auth boundary are covered in docs/server/.

Common commands

# Install the client (qatlas CLI) as a global tool — from PyPI (recommended).
# Note: the package moved to `qatlas-cli` (repo IAI-USTC-Quantum/qatlas-cli);
# `quantum-atlas` no longer ships the CLI.
uv tool install qatlas-cli
# or install the qatlas-cli repo checkout in editable mode (for contributors)
# uv tool install /path/to/qatlas-cli --editable --force
qatlas --help

# Paper asset contribution (authenticated PDF upload)
qatlas contrib pdf quant-ph/9508027v1 --pdf paper.pdf

# Parse locally with your own MinerU token, then push to the server
qatlas contrib mineru 2501.00010v1 --push-pdf

# Fetch a paper's PDF / Markdown from the server
qatlas paper get pdf 2501.00010v1 -o paper.pdf
qatlas paper get markdown 2501.00010v1 -o paper.md

Collaboration model

QuantumAtlas leans toward "research infrastructure" rather than a static archive. Configuration is split in two:

• Client (Python qatlas CLI): YAML-only (~/.config/qatlas/config.yaml on Linux, resolved via platformdirs). A template is auto-created on first run; manage it with qatlas config set.
• Server (Go qatlasd): YAML-only (~/.qatlas/config.yaml, env-var configuration is rejected at startup). Initialise with qatlasd config init, inspect with qatlasd config show; see config.example.yaml for the full schema.

Content contribution has two parallel paths:

1. Server-side lazy ingestion: when a search hits a paper the registry has never seen (e.g. an unknown arXiv ID), the server mints a paper_id and fetches the PDF in the background — no client action needed.
2. Authenticated direct upload (qatlas contrib pdf → POST /api/papers/{arxiv_id}/upload-pdf), or local MinerU with your own token pushed back to the server (qatlas contrib mineru).

Full CLI options, auth details (PAT scopes / bearer tokens), and the recommended collaboration cadence are in docs/client/contribute-content.md.

Documentation map

User docs live in docsite/ (Sphinx + Furo). Component docs are collected from pinned SHAs in docsite/components.lock.json. Build with uv run --locked --script .github/scripts/build_docs.py; deploy the content image with deploy/update-docs.sh.

• docsite/guide/: user guide (Web, CLI, API, search, admin)
• docsite/manual/: platform reference, operations, and ADRs
• docsite/dev/: developer/release docs (served at /devdoc)
• docsite/manual/contributing.md: contribution and server release process

Repository overview

QuantumAtlas/
├── cmd/                   Go server entry point
├── internal/              Go server internals (registry, search, ingest, objstore, ...)
├── web/                   React SPA frontend
├── deploy/                docker-compose templates
├── scripts/               bootstrap and maintenance scripts
├── tests/                 test suite
├── docs/                  historical Markdown sources (Sphinx copies live in docsite/manual/)
├── go.mod / go.sum        Go module, pinned dependencies and tool declarations
└── docsite/               Sphinx/Furo user and developer documentation source

State directories (raw/, data/, pb_data/) are not in the repo — they default to ${XDG_DATA_HOME:-$HOME/.local/share}/qatlasd/ or can be overridden via YAML paths.* to a mounted disk / /var/lib/.... See docs/server/migration-storage-layout.md.

Current status

The project is in alpha, and recently repositioned around three pillars:

• Paper collection — arXiv fetch, MinerU parsing, authenticated uploads.
• Multi-paradigm search — one endpoint over catalog / arXiv / OpenAlex / Qdrant providers.
• Registry database — PostgreSQL as the central store (paper registry + OpenAlex corpus).

It is best understood as "extensible research infrastructure", not a productized platform.

Agent application direction

• Users / auth are handled by the Go server's embedded PocketBase (GitHub OAuth + PAT); both the CLI and the SPA call write endpoints with Authorization: Bearer <token>. The QuantumAtlas backend centrally provides the API and build-artifact hosting; all page design lives in the Vite + React workbench under web/.

Development docs

The developer guide is the Sphinx site at /devdoc (sources in docsite/dev/). Start with development, versioning, release, and contributing. User-facing pages remain at /doc.

This Go repository is tag-only: maintainers choose an unpublished SemVer vX.Y.Z[-rc.N], push that annotated tag, and CI runs GoReleaser to publish GitHub archives, checksums, the UI zip, and GHCR images. There is no version file and no bump tooling here. Companion Python repos (qatlas-cli, qatlas-search, qatlas-rag) manage their own PEP 440 versions in their own repositories and publish on tag push. qatlasd and qatlas-cli are compatible when (major, minor) match; the prerelease spellings differ on purpose.

Contributing

Contributions welcome in these areas:

• Improving parsing, ingestion, search providers, and the API.
• Tests, documentation fixes, and collaboration UX.

Please use Conventional Commits (feat:, fix:, docs:, refactor:, test:, chore:); they do not automatically bump versions. All official main-repository versions come solely from Git tags: maintainers choose an unpublished SemVer, check/commit/review the candidate source, create an annotated vX.Y.Z[-rc.N] tag on the approved SHA, and push only that tag to the existing CI/GoReleaser workflow. No root version file, version-only bump commit, or Go source version edit is required. Use standard vX.Y.Z[-rc.N] tags, not PEP 440 or +build labels: removing the custom gate does not remove Go module, UI, or Docker tag constraints. Releases publish only server Go/GitHub/Docker artifacts, never PyPI packages. This workflow change does not publish a new release or alter historical v0.34.0. CLI development and releases belong in qatlas-cli. See docs/contributing.md for the server release process.

GoReleaser owns GitHub and dual-architecture GHCR publication after reusable checks pinned to the event's github.sha, with native Git/SemVer validation, default warning-only preflight and native Summary. New GitHub Releases start as drafts and become public automatically after all attachments upload; there is no custom promotion gate or external smoke prerequisite. After GoReleaser publishes, official actions/attest steps register signed build attestations in GitHub for subsequent releases, verifiable with gh attestation verify; already-published v0.35.0-rc.1 is not re-attested. Versioned qatlasd_<version>_checksums.txt names stay unchanged: SHA256 integrity is not a provenance signature, and neither proves code is bug-free. Each stable, non-snapshot image publication still updates GHCR latest; prereleases do not. GitHub/GHCR/attestations are not atomic: an attestation failure may follow a public Release. Default uploads do not overwrite same-named attachments, and publishing to an immutable Release is rejected; inspect actual remote state before any rerun. For a local snapshot without Docker builds, use goreleaser release --snapshot --clean --skip=docker after preparing the UI; real images still need separate validation.

The final quantum-atlas 0.21.0 release is complete. Its immutable historical tag retains the package metadata, one-time checker/tests, and publishing workflow for audit. They are not an ongoing main-branch workflow. The root Python/Pixi manifests and obsolete wiki batch tools have been removed; Python remains only for documentation and small CI helpers. GoReleaser explicitly ignores that historical Python tag, and no further legacy package versions will be published.

Acknowledgements

QuantumAtlas builds on the Go, PocketBase, PostgreSQL, React, and arXiv / OpenAlex open ecosystems.

Full open-source credits, inspiration sources, and the maintainer list are in Credits.

Data sources & attribution

QuantumAtlas's paper catalog builds on these open scholarly data sources:

• Paper metadata (titles / authors / DOIs / citations) from OpenAlex and Crossref, both CC0 1.0 public domain.
• Paper records from arXiv, metadata mirrored per the arXiv ToU. We do not hold or redistribute paper PDF bytes — the public server exposes no PDF / Markdown download API; users fetch PDFs from arxiv.org themselves.

Full license / attribution / takedown process: License & Attribution; terms of use: Terms of Service.

License

Apache-2.0 License (code + documentation)

GitHub: https://github.com/IAI-USTC-Quantum/QuantumAtlas

Collect the papers, register everything, search everywhere.