# paper-gap

`paper-gap` is a local, on-demand Rust CLI for finding research papers that appear to lack useful public code, or only have weak/prototype/stale implementations.

It is not a recommender. It does not rank by user preference, hardware fit, or subjective interest.

## What it does

- Fetches papers from arXiv.
- Normalizes paper metadata.
- Checks Papers with Code for known code links.
- Searches public code forges:
  - GitHub
  - GitLab
  - Forgejo/Gitea, with Codeberg enabled by default
- Produces markdown or JSON reports.
- Explains the transparent additive implementation-gap score.
- Lists configured and discoverable sources.

## Install / run

Build and install `paper-gap` so it is on your `PATH`:

```sh
cargo build --release
install -Dm755 target/release/paper-gap ~/.local/bin/paper-gap
```

Then run:

```sh
paper-gap --help
```

## Examples

Scan recent or queried papers:

```sh
paper-gap scan --query "symbolic computation" --since 30d
paper-gap scan --category cs.PL --since 90d
paper-gap scan --category math.NA --limit 50
paper-gap scan --from 2026-06-01 --to 2026-06-29
```

Inspect one arXiv paper:

```sh
paper-gap inspect --arxiv 2603.21852
```

Write JSON, then render a markdown report later:

```sh
paper-gap scan --category cs.PL --limit 5 --format json --output scan.json
paper-gap report --input scan.json --format markdown
```

List sources:

```sh
paper-gap sources
paper-gap sources --papers
paper-gap sources --repos
paper-gap sources --check
```

Discover possible new sources, informational only:

```sh
paper-gap sources discover --kind papers
paper-gap sources discover --kind repos
paper-gap sources discover --kind all
```

## Output

Reports are written to stdout unless `--output` is supplied. Progress messages go to stderr so stdout can be piped safely.

Markdown reports are ranked by `implementation_gap_score`. JSON reports include the underlying papers, code links, repository results, score components, and gap explanations.

## Scoring

The score is additive and intentionally simple:

```text
implementation_gap_score =
    no_code_score
  + prototype_only_score
  + stale_repo_score
  + packaging_gap_score
  + docs_gap_score
  + tests_gap_score
  + license_gap_score
  + reproducibility_gap_score
  + ecosystem_gap_score
```

Each non-zero score should have an explanation in the report.

## API notes and rate limits

`paper-gap` is local and only runs when you invoke it, but it still calls public APIs. arXiv may rate-limit repeated scans. If that happens:

- wait a few minutes;
- retry with a smaller `--limit`;
- prefer targeted `--category`, `--query`, or date ranges.

Repository searches can also hit anonymous rate limits. Optional tokens are supported via environment variables:

```sh
export GITHUB_TOKEN=...
export GITLAB_TOKEN=...
```

## Current MVP limits

- No background jobs.
- No required local database.
- No web dashboard.
- No LLM judgement.
- No subjective preference or hardware-fit ranking.
- Source discovery uses DuckDuckGo HTML best-effort and is informational only.
- Repository search can return noisy false positives; gap scoring explains signals rather than claiming certainty.
