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. |
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. |
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. |
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. |
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. |
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
ServiceLoaderorder 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.
Related
- RAG: the
@Knowledgeand@Searchmembers these providers serve. - Embeddings: installing an embedding provider.
- Retrieval strategies: which strategies need which provider.
- RAG diagnostics: what a Role resolved.