arcana

# Arcana 🔮📚

[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fgeorgeguimaraes%2Farcana%2Fblob%2Fmain%2Flivebooks%2Farcana_tutorial.livemd)

An embeddable RAG library for Elixir and Phoenix. Arcana lets you add vector search, knowledge graphs, and LLM-driven retrieval to any app that already has an Ecto repo, without standing up a separate vector database, indexing service, or orchestration layer.

> [!TIP]
> See [arcana-adept](https://github.com/georgeguimaraes/arcana-adept) for a complete Phoenix app with the Doctor Who corpus pre-ingested and ready to query.

## Why this exists

Most RAG libraries are written in Python and assume you'll bolt them onto your stack via HTTP. That works, but it leaves you running a vector DB you don't otherwise need, juggling two languages, and gluing telemetry together across processes. The BEAM is particularly well-suited to RAG: pgvector is excellent, supervision trees are the right shape for long-running embedders and rerankers, telemetry is built into the platform, and your Phoenix app already has the Repo, the LiveView for the dashboard, and the user session for chat.

Arcana takes that observation seriously. Everything lives inside your app:

- **One Repo.** Documents, chunks, embeddings, and the knowledge graph are tables in your existing Postgres database. No new infrastructure.
- **Local-first by default.** Embeddings run on Bumblebee with EXLA, EMLX (Apple Silicon), or Torchx. The cross-encoder reranker is also local. You can swap to OpenAI/Cohere/whatever, but you don't have to.
- **One process model.** Embedders and rerankers are `Nx.Serving` instances under your supervision tree. Telemetry events are `:telemetry` spans you can already consume. There is no separate "RAG service" to operate.
- **Pluggable, but not abstract.** Every step that can be replaced is a behaviour with a single callback and a sensible default. Custom rerankers, custom searchers, custom answerers — they're all 10-line modules.

## Three modes of operation

Singh et al.'s 2025 [Agentic RAG survey](https://arxiv.org/abs/2501.09136) splits RAG systems into four progressively more flexible patterns. The key axis is **who decides the control flow**:

| Pattern | Flow decided by | What it looks like |
|---|---|---|
| **Naive RAG** | nobody, there is none | embed → retrieve → generate, one shot |
| **Advanced RAG** | author, at code time | naive + query rewriting, reranking, fusion |
| **Modular RAG** | author, at code time | composable pluggable steps you wire together |
| **Agentic RAG** | the LLM, at runtime | LLM picks tools each turn until it can answer |

Arcana ships three usage shapes that map onto the last three slots:

| Arcana surface | Singh slot | When to reach for it |
|---|---|---|
| `Arcana.search/2`, `Arcana.ask/2` | Advanced RAG | The default door. One call, sensible defaults: query rewriting, hybrid search, optional graph fusion, cross-encoder reranki