> ## Documentation Index
> Fetch the complete documentation index at: https://rapidreview.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Searching the corpus

> Which command answers which question, and how to read results honestly.

Direct commands answer from the indexes in about a second and are free. Chat-backed commands create a model turn — slower, usage-tracked. Compose direct commands first; reach for the agent when you need judgment.

## Which command

| You want                                 | Run                                                                                           |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| Papers about a topic                     | `nisa search` with 3–5 phrasings (below)                                                      |
| Papers *like* a description              | `nisa semantic-search "…"`                                                                    |
| Everything about one paper               | `nisa paper <id>` → `nisa excerpts <id> --query "…"` → `nisa related <id>` → `nisa cite <id>` |
| "From paper X, what else should I read?" | `nisa related <id> --n 15`                                                                    |
| Who builds on X                          | `nisa search "<X's coined term>"`, then `nisa excerpts <hit> --query "<term>"` to verify      |
| Compare A and B at claim level           | `nisa paper A`, `nisa paper B`, `nisa excerpts` on both                                       |
| Rank, pick, decide among N               | `nisa ask --schema '…'` — chat-backed                                                         |
| A long synthesis                         | `nisa exec` — chat-backed, multi-turn                                                         |

## Several phrasings, one call

```bash theme={"theme":{"light":"github-light","dark":"dark-plus"}}
nisa search \
  --query "mechanistic interpretability diffusion" \
  --query "concept unlearning diffusion" \
  --query "SAE diffusion" \
  --max-results 25 \
  | jq '.papers | map(select(.year >= 2024))'
```

Parallel fan-out, deduplicated by `arxiv_id`, re-sorted. Caps: 8 queries for `search`, 4 for `semantic-search`; the server returns at most 50 results per call — paginate with `--offset` (clamped at 500; 200 for `semantic-search`). In list mode you lose which query found which paper.

## Read the ranking honestly

<AccordionGroup>
  <Accordion title="search — recency is under-ranked">
    BM25 blended with citation counts: a recent, low-citation paper ranks far below an older, well-cited one. An empty recency window is a ranking artifact, not proof of absence. Every response carries `index_latest_pub_month` — check it before concluding a paper doesn't exist.
  </Accordion>

  <Accordion title="related — run without --min-score first">
    Hybrid citation-graph proximity + content similarity, read from a precomputed table. `similarity_score` is an open-ended absolute value, not a percentage — a famous paper's neighbours score in the thousands, a recent or niche paper's far lower. Look at the distribution before you threshold.
  </Accordion>

  <Accordion title="excerpts — zero hits ≠ absence">
    Tokenized OR matching (quoted phrases exact). Check `matched_terms`, `missing_terms`, `doc_found`, `full_text_indexed` before treating zero excerpts as absence.
  </Accordion>

  <Accordion title="Two indexes, different freshness">
    Full-text (`search`, `excerpts`) and embeddings (`semantic-search`) are refreshed on different schedules and can differ. There's no published cadence — use `index_latest_pub_month`.
  </Accordion>
</AccordionGroup>

## Filters and formats

`search`: `--date-from 2024-06 --date-to 2025` (month precision; a bare year in `--date-to` means December), `--author "Vaswani"`. `semantic-search`: `--year-min`, `--year-max`. `--format json|bibtex|csv` on `search`, `semantic-search`, `related`, `list-papers`. `--envelope` wraps direct-command JSON as `{meta, data}` for scripts. [CLI reference](/docs/nisa/reference/cli)