Skip to content

gracefullight/pkgs / .agents/skills/oma-scholar

oma-scholar

Unverified

Search academic literature and generate, validate, or compare Knows paper sidecars. Use for claim/evidence analysis and literature synthesis.

resources/fallback-providers.md

View on GitHub
# Fallback Provider Cascade

`oma-scholar` queries `knows.academy` first, then falls back to OpenAlex, then
Semantic Scholar for records the platform doesn't have. The fallback is what
makes the skill useful beyond the (currently 2026-only) knows.academy index.

## Coverage Matrix

| Source | Coverage | Gives | Doesn't give |
|--------|----------|-------|--------------|
| **knows.academy** | **2026 only**, mostly arXiv (verified empirically; current counts via `/api/proxy/jobs/stats`) | Full v0.9 sidecar (claims, evidence, relations, methods) | Pre-2026 papers, full text |
| **OpenAlex** | ~240M works, all years | Title, authors, year, venue, DOI, abstract (reconstructed), OA PDF URL, citation count, references | Structured claims/evidence (no sidecar) |
| **Semantic Scholar** | ~214M papers, all years (Ai2) | AI TL;DR, abstract (verbatim), citation + influential-citation counts, arXiv/DOI/CorpusId cross-ids, OA PDF URL | Structured claims/evidence; anonymous access 429s under load |

When a paper is in **both**, prefer knows.academy (richer structure). When a
paper is **only in OpenAlex** (most pre-2026 work), use OpenAlex metadata as
the source for **Mode 1 Generate**, where the host LLM produces a local sidecar from
the abstract.

## Cascade Logic

```
search "query"
   │
   ├─ knows.academy ── any hits? ──► return immediately (sidecars available)
   │     │
   │     no hits
   │     ▼
   ├─ openalex ──── any hits? ────► return metadata + abstract (no sidecar)
   │     │
   │     no hits
   │     ▼
   └─ semanticscholar ───────────► return metadata + TL;DR + citations
                                  ↓
                             user wants deeper? → Mode 1 Generate locally
```

`--always-fallback` includes every tier regardless of earlier hits.

## CLI Reference (`oma scholar`)

### Search both sources

```bash
oma scholar search "vision language action"
```

Returns JSON with:
- `primary`: which source returned hits
- `fallback`: which source was used as fallback (if any)
- `results`: unified list with `source: "knows.academy" | "openalex"` per item

### Get a specific record

```bash
# knows.academy sidecar
oma scholar get "knows:generated/reconvla/1.0.0"

# Partial fetch (saves up to 93% tokens)
oma scholar get --section statements "knows:generated/reconvla/1.0.0"

# OpenAlex by DOI
oma scholar get "10.48550/arXiv.1706.03762"

# OpenAlex by W-id
oma scholar get "W2147144213"

# Semantic Scholar: TL;DR + citation/influential-citation counts
oma scholar get "arXiv:1706.03762"
oma scholar get "CorpusId:13756489"
```

When `oma scholar get` is asked for a `knows:...` id and the platform is
unreachable, the command extracts the slug from the record_id and searches
OpenAlex for the same paper, returning metadata with a `fallback: "openalex"`
marker. The user can then run **Mode 1 Generate** from the abstract.

### Resolve a title across all sources

```bash
oma scholar resolve "Attention Is All You Need"
```

Returns the best match from each source (knows.academy, OpenAlex, Semantic
Scholar) side-by-side, plus a recommendation.

## When Fallback is Needed

Fallback to OpenAlex is the right move when:

- **Pre-2026 papers**: knows.academy doesn't index them
- **Cross-archive coverage**: non-arXiv venues, journals, books
- **Citation counts**: knows.academy doesn't track citations; OpenAlex does
- **Reference resolution**: when a sidecar's `cites` predicate points to a paper not in knows.academy

Fallback is NOT needed for:
- Recent (2026) arXiv papers, since knows.academy has them with rich sidecars
- Full-text reading, since neither source provides full text; fetch the OA PDF and use `oma-pdf`

## Local Generate from Fallback Result

When OpenAlex returns metadata + abstract, but you want a structured sidecar:

```
1. oma scholar get <doi>        → get title, authors, year, venue, abstract
2. (optional) download OA PDF   → oma-pdf to extract full text
3. Mode 1 Generate              → host LLM produces .knows.yaml using sidecar-spec.md
4. oma scholar lint             → validate locally
```

The locally-generated sidecar is **not registered** with knows.academy; it's
yours. If you want it shared, that's a separate publishing flow (out of scope
for this skill).

## Authentication

OpenAlex anonymous use is free up to ~$1/day. For higher limits or polite
pool access, see `setup-openalex.md`. The skill works without any key.

`oma scholar` reads:
- `OPENALEX_API_KEY`: passed as `?api_key=` (recommended)
- `OPENALEX_EMAIL`: passed as `?mailto=` (polite pool, no signup)
- `S2_API_KEY`: Semantic Scholar key, passed as the `x-api-key` header

None are required. Without `S2_API_KEY`, Semantic Scholar uses the shared
anonymous pool, which 429s under load; the CLI retries once after a short
delay, then skips the source. Request a free key via the form at
https://www.semanticscholar.org/product/api (delivered by email; grants a
dedicated 1 req/sec).

## Trust Considerations

- **knows.academy sidecars are AI-generated**: all have `provenance.origin: machine`. Verified `lint_passed: true` is platform-internal; our local `oma scholar lint` finds dangling refs in ~47% (use `--lenient` when consuming)
- **OpenAlex metadata is curated**: generally reliable for title/authors/DOI/year, but venue and abstract can be missing for older works
- **Reconstructed abstracts** from OpenAlex's inverted index are exact (no paraphrasing), but punctuation/formatting may be lossy
- **Semantic Scholar TL;DRs are AI-generated** (Ai2's TLDR model): good `summary` seeds for Mode 1 Generate, but verify against the abstract before citing; citation counts differ from OpenAlex's (different corpora)

## Limitations

- arXiv-only papers without DOI may show `doi: None` in OpenAlex
- Some 2026 papers exist in both sources with slightly different titles; `resolve` does case-insensitive contain matching as a heuristic
- knows.academy proxy can timeout under load; fallback to OpenAlex is automatic
- OpenAlex rate-limits: respect ~10 req/sec courtesy limit
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall