paper-gap 0.1.7

Local CLI for finding research papers with missing, weak, or stale public code
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# 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

- Background jobs, local database storage, and a web dashboard are optional future features, not required defaults.
- LLM judgement, subjective preference ranking, and hardware-fit ranking are optional future experiments, not part of the default score.
- Source discovery uses DuckDuckGo HTML best-effort and is informational only.
- Repository search is heuristic; gap scoring explains signals rather than claiming certainty.