YannAhlgrim
96 lines
2.4 KiB
Markdown
96 lines
2.4 KiB
Markdown
# Linked Papers
|
|
|
|
A lightweight, self-hosted web app for exploring academic paper reference graphs. Search for a paper and see an interactive graph of the papers it cites. Node size is proportional to citation count.
|
|
|
|
## Features
|
|
|
|
- Search by paper title, DOI, or arXiv ID
|
|
- Interactive force-directed graph (vis-network)
|
|
- Node size based on citation count
|
|
- Click a node to see details; double-click to re-center the graph
|
|
- File-based JSON cache (survives container restarts)
|
|
- Works offline for previously cached graphs
|
|
- Uses OpenAlex for all paper data
|
|
- Shows only outgoing references (papers the seed paper cites)
|
|
- Dockerized
|
|
|
|
## Data Source
|
|
|
|
- **OpenAlex API:** https://openalex.org/
|
|
|
|
OpenAlex is free. Anonymous usage has rate limits; if you hit them often, get a free API key and set it in a `.env` file (see below).
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# (Optional) Add your OpenAlex API key
|
|
cp .env.example .env
|
|
# edit .env with your OA_API_KEY and OA_EMAIL
|
|
|
|
# Build and run
|
|
docker-compose up -d --build
|
|
|
|
# Open locally
|
|
# http://127.0.0.1:5000
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Edit `docker-compose.yml` to tune these environment variables:
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `CACHE_TTL_DAYS` | 30 | Days before cached graph is refreshed |
|
|
| `SEARCH_LIMIT` | 20 | Number of search results, sorted by citation count |
|
|
| `REFERENCE_LIMIT` | 100 | Top N papers cited by the seed paper (outgoing) |
|
|
| `OA_API_KEY` | (from `.env`) | OpenAlex API key (higher rate limits) |
|
|
| `OA_EMAIL` | (from `.env`) | Email for OpenAlex polite pool (recommended) |
|
|
|
|
### Getting an API key (optional but recommended)
|
|
|
|
- **OpenAlex:** https://openalex.org/rest-api
|
|
|
|
Set it in `.env` and restart:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# edit .env with your OA_API_KEY and OA_EMAIL
|
|
docker-compose up -d
|
|
```
|
|
|
|
## Cache
|
|
|
|
Cached graphs are stored as JSON files in `./cache/`. To clear the cache:
|
|
|
|
```bash
|
|
rm -f cache/*.json
|
|
```
|
|
|
|
You can also inspect the cache files directly — they are plain JSON.
|
|
|
|
## Troubleshooting
|
|
|
|
### 429 / "Too Many Requests" or 503 from OpenAlex
|
|
|
|
The public IP you are running from has hit OpenAlex's rate limit. Set `OA_API_KEY` and `OA_EMAIL` for higher limits.
|
|
|
|
### Offline mode
|
|
|
|
If the APIs are unreachable but a cached graph exists, the app returns the cached graph automatically.
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
# View logs
|
|
docker-compose logs -f
|
|
|
|
# Restart
|
|
docker-compose restart
|
|
|
|
# Stop
|
|
docker-compose down
|
|
|
|
# Rebuild after code changes
|
|
docker-compose up -d --build
|
|
```
|