# `Arcana.Search`
[🔗](https://github.com/georgeguimaraes/arcana/blob/main/lib/arcana/search.ex#L1)

Search functionality for Arcana.

Provides vector, keyword, and hybrid search modes with optional
GraphRAG enhancement using Reciprocal Rank Fusion (RRF).

## Mode names

Canonical mode atoms are `:vector`, `:keyword`, and `:hybrid`. The
old names `:semantic` and `:fulltext` are still accepted as aliases
for `:vector` and `:keyword` respectively, with a deprecation warning
logged on use. The old names will be removed in a future release.

# `normalize_mode`

Normalizes a search mode atom. Accepts the canonical `:vector`,
`:keyword`, `:hybrid` or the deprecated aliases `:semantic` and
`:fulltext` (with a one-line warning). Unknown values pass through
unchanged so the caller's validation surfaces them with context.

# `rewrite_query`

Rewrites a query using a provided rewriter function.

Query rewriting can improve retrieval by expanding abbreviations,
adding synonyms, or reformulating the query for better matching.

## Options

  * `:rewriter` - A function that takes a query and returns {:ok, rewritten} or {:error, reason}

# `search`

Searches for chunks similar to the query.

Returns `{:ok, results}` where results is a list of `Arcana.SearchResult`
structs (the same shape for every mode), or `{:error, reason}` on failure.

## Options

  * `:repo` - The Ecto repo to use (required for pgvector backend)
  * `:limit` - Maximum number of results (default: 10)
  * `:source_id` - Filter results to a specific source
  * `:threshold` - Minimum similarity score (default: 0.0)
  * `:mode` - Search mode: `:vector` (default), `:keyword`, or `:hybrid`.
    `:semantic` and `:fulltext` are deprecated aliases.
  * `:collection` - Collection scope as `:all`, a collection name, a list of
    collection names, or `[]` to match nothing
  * `:strict_collections` - When `true`, an unknown collection name
    returns `{:error, {:unknown_collection, name}}` instead of matching
    nothing. Defaults to `config :arcana, strict_collections: false`.
  * `:vector_store` - Override the configured vector store backend
  * `:vector_weight` - Weight for vector scores in hybrid mode (default: 0.5)
  * `:keyword_weight` - Weight for keyword scores in hybrid mode (default: 0.5)

    Both must be non-negative numbers and cannot both be zero. What they mean
    depends on the backend: pgvector multiplies them into a blended score that
    is then compared against `:threshold`, so their magnitudes matter there.
    Every other backend fuses ranks, where only the ratio matters and
    `{0.9, 0.1}` ranks the same as `{9, 1}`.
  * `:reranker` - Reranker module or function. Defaults to `config :arcana, :reranker`.
    Pass `false` to disable a globally configured reranker for this call.
    When set, retrieves `limit * over_fetch` candidates, reranks, returns top `limit`.
  * `:graph_depth` - When graph search is enabled, how many relationship
    hops to expand matched entities before fetching mentioned chunks
    (default: 0, direct mentions only). Chunks reached via traversal are
    down-weighted per hop so direct matches still rank first. The global
    default is `config :arcana, graph: [query_depth: n]`.

Defaults for `:limit`, `:threshold`, and `:mode` can be set globally:

    config :arcana, search: [limit: 10, threshold: 0.0, mode: :vector]

---

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