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

RAG (Retrieval Augmented Generation) question answering.

This module handles the core ask workflow:
1. Search for relevant context chunks
2. Build a prompt with the context
3. Call the LLM for an answer

## Usage

    {:ok, answer, context} = Arcana.ask("What is X?",
      repo: MyApp.Repo,
      llm: "openai:gpt-4o-mini"
    )

# `ask`

Asks a question using retrieved context from the knowledge base.

Performs a search to find relevant chunks, then passes them along with
the question to an LLM for answer generation.

## Options

  * `:repo` - The Ecto repo to use (required)
  * `:llm` - Any type implementing the `Arcana.LLM` protocol (required)
  * `:limit` - Maximum number of context chunks to retrieve (default: 5)
  * `:source_id` - Filter context to a specific source. Chunks, matched
    entities, and relationships are scoped to it; community summaries
    are collection-level artifacts and may describe entities beyond the
    source. Use collections (see `:strict_collections`) for isolation.
  * `:threshold` - Minimum similarity score for context (default: 0.0)
  * `:mode` - Search mode: `:vector` (default), `:keyword`, or `:hybrid`.
    `:semantic` and `:fulltext` are deprecated aliases and log a warning.
  * `:collection` - Collection scope as `:all`, a collection name, a list of
    collection names, or `[]` to match nothing
  * `:prompt` - Custom prompt function. Supports arity 2 `(question, context)` or
    arity 3 `(question, context, graph_context)`
  * `:reranker` - Reranker module/function (passed through to search)
  * `:rewriter` - Query rewriter (passed through to search)
  * `:graph` - Enable/disable GraphRAG (default: global config)
  * `:graph_depth` - When GraphRAG is enabled, how many relationship hops
    to expand matched entities (default: 0). Affects both retrieval (chunks
    mentioning neighbor entities are pulled in, down-weighted per hop) and
    the prompt's relationship context, which then includes edges from
    matched entities to their expanded neighbors. The global default is
    `config :arcana, graph: [query_depth: n]`.

Defaults for `:limit` can be set globally:

    config :arcana, ask: [limit: 5]

## Examples

    # Basic usage
    {:ok, answer, context} = Arcana.ask("What is Elixir?",
      repo: MyApp.Repo,
      llm: "openai:gpt-4o-mini"
    )

    # With custom prompt
    {:ok, answer, _} = Arcana.ask("Summarize the docs",
      repo: MyApp.Repo,
      llm: my_llm,
      prompt: fn question, context ->
        "Be concise. Question: #{question}"
      end
    )

---

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