# How to Add a Custom Reranker Using the RerankingModel Interface in Dat > Learn to add a custom reranker in Dat by implementing the ScoringModelFactory interface and configuring dat.yaml. Enhance your search relevance with custom logic. - Repository: [Junjie.M/dat](https://github.com/junjiem/dat) - Tags: how-to-guide - Published: 2026-03-05 --- **To add a custom reranker in Dat, implement the `ScoringModelFactory` interface, register it via Java SPI in `META-INF/services/ai.dat.core.factories.ScoringModelFactory`, and reference the provider identifier in your [`dat.yaml`](https://github.com/junjiem/dat/blob/main/dat.yaml) configuration.** The open-source Dat project (junjiem/dat) provides a pluggable reranking architecture that allows developers to integrate custom scoring models into the retrieval pipeline. Whether you need to call a remote reranking API or embed a local ONNX model, the framework exposes a clean factory pattern through the `ScoringModelFactory` interface. This guide walks through the complete implementation process using the actual source architecture from the Dat repository. ## Understanding the Reranking Plug-in Architecture Dat treats reranking as a **scoring operation** implemented through LangChain4j's `ScoringModel` interface. The framework discovers and instantiates these models using a factory pattern managed by two core classes. ### Core Architectural Components The reranking subsystem relies on the following key files: - **[`dat-core/src/main/java/ai/dat/core/factories/ScoringModelFactory.java`](https://github.com/junjiem/dat/blob/main/dat-core/src/main/java/ai/dat/core/factories/ScoringModelFactory.java)** – Defines the contract that every custom reranker must implement, including the `factoryIdentifier()` method and configuration options. - **[`dat-core/src/main/java/ai/dat/core/factories/ScoringModelFactoryManager.java`](https://github.com/junjiem/dat/blob/main/dat-core/src/main/java/ai/dat/core/factories/ScoringModelFactoryManager.java)** – An SPI-based registry that discovers all factories at runtime and maps them to their string identifiers (e.g., `onnx`, `xinference`). - **[`dat-core/src/main/java/ai/dat/core/utils/FactoryUtil.java`](https://github.com/junjiem/dat/blob/main/dat-core/src/main/java/ai/dat/core/utils/FactoryUtil.java)** (lines 76-84) – Contains `createScoringModel()`, the helper method that content stores call to instantiate the reranker with validated configuration. - **[`dat-sdk/src/main/java/ai/dat/core/data/project/RerankingConfig.java`](https://github.com/junjiem/dat/blob/main/dat-sdk/src/main/java/ai/dat/core/data/project/RerankingConfig.java)** – The YAML data model that stores the provider identifier and model-specific settings. ### The Boot Process Flow When a project starts with a `reranking` block in [`dat.yaml`](https://github.com/junjiem/dat/blob/main/dat.yaml): 1. The YAML parser creates a `DatProject` instance via `DatProjectUtil.datProject()`. 2. The system reads `project.reranking.provider` and looks up the matching `ScoringModelFactory` via `ScoringModelFactoryManager`. 3. `FactoryUtil.createScoringModel()` validates the config and invokes `factory.create()` to produce a `ScoringModel`. 4. The `ContentStore` receives this model and uses it to reorder candidate fragments via `ContentStore.rerank()`. ## Step 1 – Implement the ScoringModelFactory Interface Create a new class that implements `ScoringModelFactory` from `dat-core`. This factory acts as the entry point for your custom reranking logic. ```java package com.example.dat.reranker.mycustom; import ai.dat.core.configuration.ConfigOption; import ai.dat.core.configuration.ConfigOptions; import ai.dat.core.configuration.ReadableConfig; import ai.dat.core.factories.ScoringModelFactory; import ai.dat.core.utils.FactoryUtil; import dev.langchain4j.model.scoring.ScoringModel; import java.util.Collections; import java.util.Set; /** * Factory for a custom reranker that delegates to a remote scoring service. */ public class MyCustomScoringModelFactory implements ScoringModelFactory { /** Unique identifier referenced in dat.yaml */ public static final String IDENTIFIER = "mycustom"; /** Required configuration: the HTTP endpoint of the reranking service */ public static final ConfigOption ENDPOINT = ConfigOptions.key("endpoint") .stringType() .noDefaultValue() .withDescription("HTTP endpoint of the custom reranking service."); @Override public String factoryIdentifier() { return IDENTIFIER; } @Override public Set> requiredOptions() { return Collections.singleton(ENDPOINT); } @Override public Set> optionalOptions() { return Collections.emptySet(); } @Override public ScoringModel create(ReadableConfig config) { // Validates that all required options are present FactoryUtil.validateFactoryOptions(this, config); String endpoint = config.get(ENDPOINT); // Return your concrete ScoringModel implementation here return new MyCustomScoringModel(endpoint); } } ``` **Key implementation details:** - **`factoryIdentifier()`** must return a unique string (e.g., `mycustom`) that users will reference in YAML. - **`requiredOptions()`** declares `ConfigOption` keys that must be present in the configuration. - **`create()`** instantiates your concrete `ScoringModel`. Use `FactoryUtil.validateFactoryOptions()` to ensure required keys exist before access. ## Step 2 – Register via Java SPI Dat uses the Java Service Provider Interface (SPI) to discover factories at runtime. You must register your implementation by creating a service descriptor file. Create the file: `src/main/resources/META-INF/services/ai.dat.core.factories.ScoringModelFactory` Add a single line containing the fully-qualified class name: ``` com.example.dat.reranker.mycustom.MyCustomScoringModelFactory ``` The `ServiceLoader` mechanism in `ScoringModelFactoryManager` scans these files automatically when the JAR is on the classpath, making your reranker available without explicit registration code. ## Step 3 – Configure in dat.yaml Reference your custom reranker in the project configuration using the identifier defined in `factoryIdentifier()`. ```yaml reranking: provider: mycustom configuration: endpoint: "https://my-rerank.api/v1/rerank" ``` To enable reranking in a content store, set `rerank-mode: true` and optionally specify the provider: ```yaml content_stores: default: provider: default configuration: rerank-mode: true reranking: mycustom # Optional if set globally above ``` The `RerankingConfig` class ([`dat-sdk/src/main/java/ai/dat/core/data/project/RerankingConfig.java`](https://github.com/junjiem/dat/blob/main/dat-sdk/src/main/java/ai/dat/core/data/project/RerankingConfig.java)) binds these YAML properties to the runtime configuration object used by `FactoryUtil.createScoringModel()`. ## Step 4 – Verify Discovery After compiling and packaging your module, verify that Dat recognizes the new provider using the CLI template generator. Run the following command: ```bash dat yaml template ``` Inspect the output for the `rerankings` section. Your custom provider should appear in the list: ```yaml rerankings: - provider: mycustom display: true configuration: | # Configuration options for mycustom... ``` The `DatProjectUtil.yamlTemplate()` method ([`dat-sdk/src/main/java/ai/dat/core/utils/DatProjectUtil.java`](https://github.com/junjiem/dat/blob/main/dat-sdk/src/main/java/ai/dat/core/utils/DatProjectUtil.java), lines 88-94) generates this list by querying `ScoringModelFactoryManager` for all registered identifiers. ## Summary - **Implement `ScoringModelFactory`** in `dat-core` to define your reranker's configuration schema and instantiation logic. - **Register via SPI** by adding your factory class name to `META-INF/services/ai.dat.core.factories.ScoringModelFactory` for automatic discovery. - **Configure in YAML** using the identifier returned by `factoryIdentifier()`, placing settings under the `reranking.configuration` block. - **Enable reranking** in your content store by setting `rerank-mode: true` to activate the scoring pipeline. ## Frequently Asked Questions ### What interface must I implement to add a custom reranker in Dat? You must implement **`ai.dat.core.factories.ScoringModelFactory`**, which produces a `dev.langchain4j.model.scoring.ScoringModel`. While the conceptual model is a reranker, Dat implements this through the LangChain4j scoring abstraction, requiring you to provide both a factory and a concrete scoring model implementation. ### How does Dat discover custom reranker implementations at runtime? Dat uses Java's **Service Provider Interface (SPI)** mechanism. The `ScoringModelFactoryManager` scans all JARs on the classpath for files named `META-INF/services/ai.dat.core.factories.ScoringModelFactory`, loading each listed class to build the registry of available rerankers. ### Where do I specify the configuration options for my custom reranker? Configuration options are defined in your `ScoringModelFactory` implementation using **`ConfigOption`** constants (declared in `requiredOptions()` or `optionalOptions()`). Users then provide values in [`dat.yaml`](https://github.com/junjiem/dat/blob/main/dat.yaml) under the `reranking.configuration` map, which `FactoryUtil.createScoringModel()` validates and passes to your `create()` method. ### Can I deploy multiple custom rerankers in a single Dat instance? Yes. Each reranker requires its own `ScoringModelFactory` implementation with a unique `factoryIdentifier()`. Register each factory via separate lines in the SPI service file or across multiple JARs. `ScoringModelFactoryManager` maintains all discovered factories and selects the appropriate one based on the `provider` value in the YAML configuration.