ArXiv Pulse

ArXiv Pulse is a local-first research inbox for arXiv papers. It fetches daily papers, ranks and enriches them, and serves an interactive FastAPI + frontend workspace for triage, review, and synthesis.

Highlights

• Daily arXiv fetch + local library storage (SQLite)
• Search modes: local keyword, semantic/vector, and global arXiv search
• Triage states (new, liked, dismissed, bookmarks) with inbox automation
• AI-assisted workflows (structure extraction, synthesis, digests, ranking support)
• Reading plan, follow-ups, alerts, and unified inbox views
• Export/share utilities and version-update tracking

Tech Stack

• Backend: Python, FastAPI, Uvicorn
• Storage: SQLite
• Frontend: Vanilla JS/CSS/HTML
• ML/AI utilities: scikit-learn + local/remote AI service integrations in arxivc/ai_service.py

Quick Start

1. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies:

pip install -r requirements.txt

3. Start the app:

./run_server.sh

Alternative:

.venv/bin/uvicorn arxivc.server:app --reload --host 0.0.0.0 --port 8001

4. Open:

http://localhost:8001

Personal Config (Private)

Use this pattern to keep personal paths/tokens out of Git:

• config.json is the public/shared base config.
• config.local.json is your private override (git-ignored).
• The app loads config.json, then overrides with config.local.json.
• UI Settings saves to config.local.json by default.

Create your local file:

cp config.example.json config.local.json

Then edit config.local.json with your local values (e.g. Obsidian vault path, Notion token/db id).

Optional: set ARXIVC_LOCAL_CONFIG_FILE if you want the private override file in a custom path.

Validation Commands

• Smoke checks:

make smoke

• Full validation (Python compile + JS syntax + smoke):

make validate

• Hot-path profiling:

make profile

Project Layout

arxivc/                 # Backend services, API routes, storage, ranking, exports
frontend/               # Web UI (app.js, style.css, index.html)
scripts/                # Smoke tests and profiling scripts
run_server.sh           # Local dev server launcher
Makefile                # Smoke/profile/validate helpers

CI

GitHub Actions is configured in .github/workflows/ci.yml to run on push and pull requests to main:

• dependency install
• Python compile checks
• frontend JS syntax check
• API smoke suite

License

MIT. See LICENSE.