academic-hotspot

academic-hotspot

Track, quantify, and report academic hotspots from public data sources — designed so every reported "hotspot" is cross-source-validated and grounded to a paper id, not noise, single-source bias, or LLM hallucination.

academic-hotspot is a Claude Code plugin (and standalone Python CLI) that pulls incremental paper metadata from arXiv, OpenAlex, Semantic Scholar, DBLP, Hacker News, and Reddit, fuses four trend signals (paper-count acceleration, citation acceleration, multi-source cross-validation, emerging-keyword detection), and produces a weekly Markdown report.

Status: Experimental

The full weekly pipeline runs end-to-end (ingest → score → narrate → render). However, the core promise — the accuracy of which topics get flagged as "hotspots" — has NOT yet been independently human-spot-checked. Treat the output as an experimental signal, not a trusted source for high-stakes decisions. Feedback and validation help are welcome.

Install

Requires Python ≥ 3.11 (3.12 recommended). Install with uv:

uv pip install -e ".[dev]"

After installation, the hotspot command is on your $PATH:

hotspot --help

Configure

1. Copy .env.example to .env (gitignored) and fill in what applies.
2. Required for a production run:
   • OPENALEX_API_KEY — free, ~30 seconds at https://openalex.org/settings/api.
3. Strongly recommended:
   • S2_API_KEY — free but manual review, apply at https://www.semanticscholar.org/product/api (1–14 days).
4. Optional (Reddit signal degrades silently if missing):
   • REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_USER_AGENT — create a "script" app at https://www.reddit.com/prefs/apps.

See .env.example for the full contract.

Subcommands

Command	Purpose
hotspot migrate	Create or upgrade the SQLite schema (idempotent).
hotspot ingest	Incremental fetch across all six sources.
hotspot backfill --weeks 12	One-shot historical fetch.
hotspot show <target>	Query the local store (papers, sources, snapshots).
hotspot score	Score topic clusters from ingested data.
hotspot narrate-prepare / narrate-finalize	Assemble and validate the session-written narrative.
hotspot render	Render the weekly Markdown report.
hotspot weekly	Full pipeline end-to-end.

As a Claude Code plugin it also exposes /hotspot, /hotspot-search, /hotspot-paper, /hotspot-weekly, /hotspot-refresh.

Development

uv pip install -e ".[dev]"
pytest -q          # offline, deterministic (live-network tests are marked `smoke` and skipped)
ruff check .

Tests use pytest-recording VCR cassettes; cassettes are committed for deterministic CI. See CONTRIBUTING.md.

Scheduling (cron)

Shipped as documentation only — there is no packaged scheduler, no /loop, no systemd unit, no cron-related Python in this repo. The entry below is a copy-pasteable recipe for unattended weekly runs.

Prerequisites: uv pip install -e ., chmod +x bin/hotspot, OPENALEX_API_KEY set (backfill hard-fails without it), Claude Code logged in (claude auth login — the narration step uses session auth; no separate ANTHROPIC_API_KEY is required or accepted).

# Every Sunday at 09:00 local — refresh + generate report
0 9 * * 0 cd /path/to/academic-hotspot && claude -p "/hotspot-weekly" --dangerously-skip-permissions >> ~/hotspot-cron.log 2>&1

Security note: --dangerously-skip-permissions bypasses interactive permission prompts. Use only on a trusted single-user machine where unattended execution is intentional.

cron + claude -p is preferred over Claude Code /loop (session-scoped, 7-day recurring expiry) and over Desktop scheduled tasks (need the desktop app). A systemd user timer is an equivalent alternative.

License

MIT — see LICENSE.