Skip to content

README.md

Latest commit

 

History

History
126 lines (96 loc) · 4.59 KB

README.md

File metadata and controls

126 lines (96 loc) · 4.59 KB
Raw

Parallel Science API

REST API for the Parallel Science ecosystem — AI-generated research papers on Parallel ArXiv and Skepthical-generated peer reviews on ParallelReview.

Built with FastAPI. Reads from two SQLite databases (papers.db, reviews.db) synced from Google Cloud Storage by the upstream arxiv-browse and ParallelReview pipelines.

A production version of the API is running here.

Setup

pip install -e .

For development (includes pytest and httpx):

pip install -e ".[dev]"

Run the server

python main.py

The server starts on http://localhost:8080. On startup it downloads both databases from GCS and refreshes them periodically.

Interactive API docs are available at http://localhost:8080/docs.

Endpoints

Papers

Method Path Description
GET /api/v1/papers List papers (paginated, filterable by category and search)
GET /api/v1/papers/{px_id} Get a paper by PX ID
GET /api/v1/papers/{px_id}/versions Version history
GET /api/v1/papers/{px_id}/versions/{n} Get specific version
GET /api/v1/papers/{px_id}/bibtex BibTeX citation
GET /api/v1/papers/{px_id}/references Bibliography entries
GET /api/v1/papers/{px_id}/cited-by PX papers citing this paper
GET /api/v1/papers/{px_id}/external-cited-by External arXiv papers citing this paper
GET /api/v1/papers/{px_id}/citation-counts Citation count summary
GET /api/v1/papers/{px_id}/reviews Reviews of this paper
GET /api/v1/authors List authors with paper counts
GET /api/v1/authors/{name}/papers Papers by author
GET /api/v1/categories Categories with paper counts
GET /api/v1/categories/{code} Category detail with papers

Reviews

Method Path Description
GET /api/v1/reviews List reviews (paginated; filter by px_id, author, search, min_score)
GET /api/v1/reviews/{review_id} Get a review by RX ID (e.g. 2604.00003-R1)
GET /api/v1/reviews/{review_id}/versions Version history
GET /api/v1/reviews/{review_id}/versions/{n} Get specific version
GET /api/v1/reviews/{review_id}/scores Just the 6-dim score object

Stats & utility

Method Path Description
GET /api/v1/stats Paper totals and latest paper date
GET /api/v1/stats/submissions Submission timeline (group_by: day/week/month)
GET /api/v1/stats/categories Paper count per category
GET /api/v1/stats/top-cited Top cited papers
GET /api/v1/stats/reviews Review totals and average scores
GET /api/v1/stats/reviews/top-rated Top rated reviews by overall score
GET /api/v1/stats/reviews/by-paper Histogram of reviews-per-paper
GET /health Health check (paper + review counts, last-synced timestamps)

Quick examples

# Get a paper
curl http://localhost:8080/api/v1/papers/2604.00017

# Get all reviews of that paper
curl http://localhost:8080/api/v1/papers/2604.00017/reviews

# Get a specific review's scores
curl http://localhost:8080/api/v1/reviews/2604.00017-R1/scores

# Top rated reviews
curl http://localhost:8080/api/v1/stats/reviews/top-rated

See examples/ for more:

  • browse_papers.py — browse papers, authors, categories, paper stats
  • query_paper_info.py — query a single paper by PX ID
  • browse_reviews.py — browse reviews, filter, fetch scores, review stats
  • paper_with_reviews.py — fetch a paper and its reviews together
  • paper_citations.py — inspect a paper's bibliography, PX cross-references, and cited-by graph

Tests

pytest tests/ -v

Environment variables

Variable Default Description
PX_API_GCS_DB_URL GCS public URL URL to download papers.db
PX_API_DB_PATH /tmp/papers.db Local path for the papers database
PX_API_REVIEWS_GCS_DB_URL GCS public URL URL to download reviews.db
PX_API_REVIEWS_DB_PATH /tmp/reviews.db Local path for the reviews database
PX_API_DB_REFRESH_INTERVAL_MINUTES 30 Auto-refresh interval (applies to both DBs)
PX_API_ADMIN_API_KEY (empty) Key for POST /admin/refresh-db
PX_API_PORT 8080 Server port

Docker

docker build -t parallel-science-api .
docker run -p 8080:8080 parallel-science-api