# `Arcana.Reranker.ColBERT`
[🔗](https://github.com/georgeguimaraes/arcana/blob/main/lib/arcana/reranker/colbert.ex#L1)

ColBERT-style neural reranker using per-token embeddings and MaxSim scoring.

Uses the Stephen library to rerank chunks with fine-grained semantic matching.
Unlike single-vector embeddings, ColBERT maintains one embedding per token,
enabling more nuanced relevance scoring.

## Requirements

Add stephen to your dependencies:

    {:stephen, "~> 0.1"}

## Usage

    # With Arcana.Pipeline
    ctx
    |> Pipeline.search()
    |> Pipeline.rerank(reranker: Arcana.Reranker.ColBERT)
    |> Pipeline.answer()

    # With custom encoder
    ctx
    |> Pipeline.search()
    |> Pipeline.rerank(reranker: {Arcana.Reranker.ColBERT, encoder: my_encoder})
    |> Pipeline.answer()

    # Directly
    {:ok, reranked} = Arcana.Reranker.ColBERT.rerank(
      "What is Elixir?",
      chunks,
      threshold: 0.5
    )

## Options

  * `:encoder` - Pre-loaded Stephen encoder. If not provided, loads the default
    encoder on first use (cached for subsequent calls).
  * `:threshold` - Minimum score to keep (default: 0.0). ColBERT scores are
    typically in the range 0-30+ depending on query/document length.
  * `:top_k` - Maximum number of results to return (default: all above threshold)

## Score Interpretation

ColBERT scores are the sum of maximum similarities between query tokens and
document tokens. Higher is better, but the scale depends on query length:
- Short queries (2-3 words): scores typically 5-15
- Medium queries (5-10 words): scores typically 10-25
- Long queries (10+ words): scores typically 20-40+

Consider using `:top_k` rather than `:threshold` for most use cases.

---

*Consult [api-reference.md](api-reference.md) for complete listing*