How to Add a Custom Reranker Using the RerankingModel Interface in Dat

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 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 – 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 – 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 (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 – 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:

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.

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<String> ENDPOINT =
            ConfigOptions.key("endpoint")
                    .stringType()
                    .noDefaultValue()
                    .withDescription("HTTP endpoint of the custom reranking service.");

    @Override
    public String factoryIdentifier() {
        return IDENTIFIER;
    }

    @Override
    public Set<ConfigOption<?>> requiredOptions() {
        return Collections.singleton(ENDPOINT);
    }

    @Override
    public Set<ConfigOption<?>> 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().

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:

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) 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:

dat yaml template

Inspect the output for the rerankings section. Your custom provider should appear in the list:

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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}