paper-gap 0.3.1

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
122
123
124
125
126
127
128
129
130
131
132
133
134

# 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 and OpenAlex.
- 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.
- Ranks repository matches with deterministic confidence and matched evidence.
- 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
paper-gap scan --query "symbolic computation" --paper-source openalex
paper-gap scan --category cs.PL --paper-source arxiv
paper-gap scan --query "symbolic computation" --repo-source github
paper-gap inspect --arxiv 2603.21852 --repo-source none
```

OpenAlex handles date-only scans and participates in query scans. Use `--paper-source all|arxiv|openalex` to select paper providers; `all` is the default. Categories are arXiv-only, while date-only scans are OpenAlex-only. Use `--repo-source all|github|gitlab|codeberg|none` to control heuristic repository search; `all` is the default. `none` keeps Papers with Code links and supported official repository evidence without treating disabled search as proof of absence.

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. Set `BRAVE_SEARCH_API_KEY` to use the official Brave Search API; otherwise discovery falls back to DuckDuckGo HTML.

```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 `schema_version`, scan or inspect provenance, underlying papers, code links, repository results, score components, and gap explanations. `paper-gap report` continues to accept pre-0.3 JSON without provenance.

## 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. Provider requests retry once after connection failures, timeouts, HTTP 502/503/504, or HTTP 429. Integer `Retry-After` values are honored up to five seconds; permanent client errors are not retried. If arXiv continues to rate-limit a scan:

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

For broader scholarly metadata, query scans also use OpenAlex. `OPENALEX_EMAIL` is optional and identifies requests to the OpenAlex polite pool.

```sh
export OPENALEX_EMAIL=you@example.org
```

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 optionally uses Brave Search API and otherwise falls back to DuckDuckGo HTML; it remains informational only.
- Repository search is heuristic; reports expose deterministic match confidence and evidence rather than claiming certainty.