Package dev.dokimos.core

Interface MatchingStrategy

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface MatchingStrategy
Strategy for determining if a retrieved item matches an expected item.

This abstraction supports various RAG use cases beyond simple document ID matching, including knowledge graph triples, API responses, and semantic matching.

  • Method Details

    • matches

      boolean matches(Object retrieved, Object expected)
      Determines if a retrieved item matches an expected item.
      Parameters:
      retrieved - the item from the retrieval results
      expected - the item from the ground truth
      Returns:
      true if the items match

    • countMatches

      default long countMatches(Collection<?> retrieved, Collection<?> expected)
      Counts how many retrieved items match any expected item.

      Default implementation iterates through all pairs. Implementations may override for better performance with specific data structures.

      Parameters:
      retrieved - the retrieved items
      expected - the expected (ground truth) items
      Returns:
      the number of retrieved items that match at least one expected item

    • byEquality

      static MatchingStrategy byEquality()
      Matches items using Objects.equals(Object, Object).

      Suitable for simple string IDs or objects with proper equals implementation.

    • byIdentifier

      static MatchingStrategy byIdentifier(Function<Object,Object> identifierExtractor)
      Matches items by extracting an identifier and comparing with equality.

      Useful when items are complex objects but have a unique identifier.

      Parameters:
      identifierExtractor - function to extract identifier from an item
      Returns:
      a matching strategy that compares extracted identifiers

    • byField

      static MatchingStrategy byField(String fieldName)
      Matches Map items by comparing a specific field.

      Useful for JSON-like structures where items have an "id" or similar field.

      Parameters:
      fieldName - the field name to compare
      Returns:
      a matching strategy that compares the specified field

    • byFields

      static MatchingStrategy byFields(String... fieldNames)
      Matches Map items by comparing multiple fields.

      Useful for composite keys like knowledge graph triples (subject, predicate, object).

      Parameters:
      fieldNames - the field names that must all match
      Returns:
      a matching strategy that compares all specified fields

    • custom

      static MatchingStrategy custom(BiPredicate<Object,Object> predicate)
      Matches items using a custom predicate.
      Parameters:
      predicate - the matching predicate
      Returns:
      a matching strategy using the predicate

    • caseInsensitive

      static MatchingStrategy caseInsensitive()
      Matches string items case-insensitively.

    • byContainment

      static MatchingStrategy byContainment(boolean normalize)
      Matches string items by checking if one contains the other.

      Useful for partial text matching where retrieved chunks may be substrings or superstrings of expected content.

      Parameters:
      normalize - whether to normalize whitespace and case
      Returns:
      a matching strategy for containment matching

    • llmBased

      static MatchingStrategy llmBased(JudgeLM judge)
      Creates an LLM-based matching strategy.

      Uses an LLM to determine semantic equivalence between items. This is the most flexible but also most expensive option.

      Parameters:
      judge - the LLM judge to use for matching
      Returns:
      a matching strategy using LLM-based comparison

    • anyOf

      static MatchingStrategy anyOf(MatchingStrategy... strategies)
      Creates a composite strategy that matches if ANY of the strategies match.
      Parameters:
      strategies - the strategies to combine
      Returns:
      a strategy that returns true if any sub-strategy matches

    • allOf

      static MatchingStrategy allOf(MatchingStrategy... strategies)
      Creates a composite strategy that matches only if ALL strategies match.
      Parameters:
      strategies - the strategies to combine
      Returns:
      a strategy that returns true only if all sub-strategies match