# Install retrieval providers

Declarative retrieval finds optional components through Java `ServiceLoader`. To add one, put a public implementation with a no-argument constructor on the classpath and list its fully qualified class name in `META-INF/services/<interface FQCN>`.

Some interfaces have a bundled implementation in `tnsai-rag`; others ship none, and an annotation that needs one fails at binding initialization until you install it.

## Provider interfaces

| Service file (interface) | What it does | Bundled | Selection |
|---|---|---|---|
| `com.tnsai.memory.advanced.EmbeddingFunction` | Turns text into vectors for vector-backed strategies | None; a hash embedding is the fallback | One provider is used. More than one fails. See [Embeddings](embedding-prefixes.md). |
| `com.tnsai.intelligence.rag.Reranker` | Re-scores candidates for `@Search(rerank = true)` | None | Exactly one provider must support `rerankerModel`. |
| `com.tnsai.intelligence.rag.QueryExpander` | Rewrites one query into several for `@Search(queryExpansion = ...)` | None | Exactly one provider must support the mode and `queryExpansionModel`. `NONE` is not a mode to resolve. |
| `com.tnsai.intelligence.rag.TreeNavigator` | Chooses branches for tree descent, using `navigatorModel` | None | Exactly one provider must support the model. See [Vectorless retrieval](vectorless.md). |
| `com.tnsai.rag.ChunkContextGenerator` | Writes per-chunk context at ingest for `@Knowledge(chunkContext = ...)` | None | Exactly one provider must support `chunkContextModel`. |
| `com.tnsai.intelligence.rag.graph.GraphStoreProvider` | Opens the graph store behind GRAPH sources | In-memory, KnowledgeTools and Neo4j adapters | An explicit adapter beats the framework default; two non-default claimants fail. See [Graph stores](graph-stores.md). |
| `com.tnsai.intelligence.rag.binding.SourceLoader` | Loads one `Knowledge.Type` of source when a Role's binding is built | FILE and URL | One loader per type. See [Source loaders](#source-loaders). |
| `com.tnsai.rag.ContentExtractor` | Turns file bytes into text for one or more formats | Structured text and office documents | An explicit extractor beats the framework default. See [File formats](file-formats.md). |
| `com.tnsai.rag.RetrievalEngineProvider` | Creates the retrieval engine for an agent or Role's sources | The default engine | The first provider in `ServiceLoader` order. |

When no provider matches, or more than one does, the error names the providers that are installed. Turning the feature off also clears it: `rerank = false`, no `queryExpansion`, or `chunkContext = NONE`.

## Source loaders

A `SourceLoader` declares the type it serves with `handles()` and returns documents from `load(source)`. `load` runs once, when a Role's binding is built; the framework indexes what it returns and searches that index afterwards. The returned order is the ingest order, so return a deterministic list.

- TnsAI bundles FILE and HTTP/HTTPS URL loaders. DATABASE has no bundled loader; your application supplies one.
- MEMORY and GRAPH sources load nothing. Registering a loader for either type fails.
- A source whose type has no loader is skipped with a warning, and the binding builds from the sources that did load. Binding fails only when every enabled source is unloadable, so read the warning.
- If two loaders handle the same type, the later one in `ServiceLoader` order replaces the earlier and a warning names both. Your own URL loader always wins over the bundled one.

A corpus that must be queried per request, such as a remote search API, cannot be a `SourceLoader`. Serve it through a `RetrievalEngineProvider`, which is called per retrieval. For vectors in Qdrant or pgvector, see [Remote vector stores](remote-vector-stores.md).

## Related

- [RAG](index.md): the `@Knowledge` and `@Search` members these providers serve.
- [Embeddings](embedding-prefixes.md): installing an embedding provider.
- [Retrieval strategies](retrieval-strategies.md): which strategies need which provider.
- [RAG diagnostics](diagnostics.md): what a Role resolved.