Package com.tnsai.context.entity

Interface EntityResolver

public interface EntityResolver
Interface for resolving entities across multiple sources.

EntityResolver implementations are responsible for:

  • Finding entities by ID or attributes across registered sources
  • Merging entity data from multiple sources
  • Detecting and handling duplicate entities
  • Managing entity sources

Usage Example


 EntityResolver resolver = new InMemoryEntityResolver();

 // Register sources
 resolver.registerSource(salesforceSource);
 resolver.registerSource(slackSource);

 // Resolve by ID
 Optional<Entity> entity = resolver.resolve("customer-123");

 // Resolve by attributes
 EntityResolutionResult result = resolver.resolveByAttributes(Map.of(
     "email", "john@example.com",
     "company", "Acme Corp"
 ));

  • Method Details

    • resolve

      Optional<Entity> resolve(String entityId)
      Resolves an entity by its identifier.
      Parameters:
      entityId - entity identifier
      Returns:
      Optional containing the resolved entity if found

    • resolveByAttributes

      EntityResolutionResult resolveByAttributes(Map<String,Object> attributes)
      Resolves an entity by matching attributes.

      This method searches for entities that match the provided attributes and returns a resolution result with confidence score.

      Parameters:
      attributes - map of attribute name to expected value
      Returns:
      resolution result with entity, confidence, and alternatives

    • resolveByAttributes

      default EntityResolutionResult resolveByAttributes(Map<String,Object> attributes, EntityType type)
      Resolves an entity by matching attributes with type constraint.
      Parameters:
      attributes - map of attribute name to expected value
      type - expected entity type
      Returns:
      resolution result

    • registerSource

      void registerSource(EntitySource source)
      Registers a new entity source.
      Parameters:
      source - the source to register

    • unregisterSource

      boolean unregisterSource(String sourceId)
      Unregisters an entity source.
      Parameters:
      sourceId - source identifier to unregister
      Returns:
      true if source was removed

    • getSources

      List<EntitySource> getSources()
      Gets all registered sources.
      Returns:
      list of registered sources

    • getSource

      Optional<EntitySource> getSource(String sourceId)
      Gets a specific source by ID.
      Parameters:
      sourceId - source identifier
      Returns:
      Optional containing the source if found

    • store

      void store(Entity entity)
      Stores or updates an entity.
      Parameters:
      entity - entity to store

    • store

      void store(Entity entity, String sourceId)
      Stores an entity from a specific source.
      Parameters:
      entity - entity to store
      sourceId - source identifier

    • delete

      boolean delete(String entityId)
      Deletes an entity.
      Parameters:
      entityId - entity identifier
      Returns:
      true if entity was deleted

    • mergeEntities

      Entity mergeEntities(List<Entity> candidates, ConflictResolution strategy)
      Merges multiple entities that represent the same real-world entity.
      Parameters:
      candidates - entities to merge
      strategy - conflict resolution strategy
      Returns:
      merged entity

    • findPotentialDuplicates

      List<Entity> findPotentialDuplicates(Entity entity, double similarityThreshold)
      Finds potential duplicates for an entity.
      Parameters:
      entity - entity to find duplicates for
      similarityThreshold - minimum similarity score (0.0-1.0)
      Returns:
      list of potential duplicate entities

    • listByType

      List<Entity> listByType(EntityType type)
      Lists all entities of a specific type.
      Parameters:
      type - entity type
      Returns:
      list of entities

    • listBySource

      List<Entity> listBySource(String sourceId)
      Lists all entities from a specific source.
      Parameters:
      sourceId - source identifier
      Returns:
      list of entities

    • searchByAttribute

      List<Entity> searchByAttribute(String attributeName, Object attributeValue)
      Searches entities by attribute value.
      Parameters:
      attributeName - attribute to search
      attributeValue - value to match
      Returns:
      list of matching entities

    • getStatistics

      EntityResolver.ResolverStatistics getStatistics()
      Gets statistics about the resolver.
      Returns:
      resolver statistics