Package com.tnsai.context.entity

Class Entity

java.lang.Object
com.tnsai.context.entity.Entity
public final class Entity extends Object
Represents a unified entity resolved from multiple sources.

Entities aggregate information from different systems (CRM, Slack, Email) into a single coherent view, tracking the provenance of each attribute. This enables the Context Graph to maintain a complete picture of real-world entities across organizational boundaries.

Design Principles

  • Immutable core state for thread-safety
  • Provenance tracking for every attribute
  • Conflict detection and resolution support
  • Merge capability for entity deduplication

Usage Example


 Entity customer = Entity.builder()
     .id("customer-123")
     .type(EntityType.CUSTOMER)
     .attribute("name", "Acme Corp", "salesforce", 0.95)
     .attribute("email", "contact@acme.com", "email-system", 0.99)
     .source(salesforceSource)
     .build();

 // Check for conflicts
 if (customer.hasConflict("email")) {
     List<EntityAttribute> emails = customer.getConflictingValues("email");
 }

 // Merge with another entity
 Entity merged = customer.merge(otherCustomer, ConflictResolution.HIGHEST_CONFIDENCE);

  • Method Details

    • builder

      public static Entity.Builder builder()
      Creates a new builder.

    • of

      public static Entity of(String id, EntityType type)
      Creates a simple entity with ID and type.

    • getId

      public String getId()

    • getType

      public EntityType getType()

    • getCreatedAt

      public Instant getCreatedAt()

    • getLastUpdatedAt

      public Instant getLastUpdatedAt()

    • getSpec

      public Map<String,Object> getSpec()

    • getSources

      public List<EntitySource> getSources()

    • getAttributeNames

      public Set<String> getAttributeNames()
      Gets all attribute names.

    • getAttribute

      public Optional<EntityAttribute> getAttribute(String name)
      Gets an attribute by name.
      Parameters:
      name - attribute name
      Returns:
      Optional containing the attribute if present

    • getAttributeValue

      public Optional<Object> getAttributeValue(String name)
      Gets an attribute value by name.
      Parameters:
      name - attribute name
      Returns:
      Optional containing the value if present

    • getAttributeValue

      public <T> Optional<T> getAttributeValue(String name, Class<T> type)
      Gets an attribute value as a specific type.
      Parameters:
      name - attribute name
      type - expected type
      Returns:
      Optional containing the typed value if present and castable

    • hasConflict

      public boolean hasConflict(String attributeName)
      Returns true if this entity has conflicting values for an attribute.
      Parameters:
      attributeName - attribute to check
      Returns:
      true if there are conflicts

    • hasAnyConflicts

      public boolean hasAnyConflicts()
      Returns true if this entity has any conflicts.

    • getConflictingValues

      public List<EntityAttribute> getConflictingValues(String attributeName)
      Gets all conflicting values for an attribute.
      Parameters:
      attributeName - attribute to get conflicts for
      Returns:
      list of conflicting attributes, empty if no conflicts

    • getAllConflicts

      public Map<String,List<EntityAttribute>> getAllConflicts()
      Gets all attributes that have conflicts.

    • merge

      public Entity merge(Entity other, ConflictResolution strategy)
      Merges this entity with another, using the specified conflict resolution strategy.
      Parameters:
      other - entity to merge with
      strategy - conflict resolution strategy
      Returns:
      new merged entity

    • withAttribute

      public Entity withAttribute(EntityAttribute attribute)
      Creates a new entity with an updated attribute.
      Parameters:
      attribute - new or updated attribute
      Returns:
      new Entity with the attribute updated

    • withoutAttribute

      public Entity withoutAttribute(String attributeName)
      Creates a new entity with an attribute removed.
      Parameters:
      attributeName - attribute to remove
      Returns:
      new Entity without the attribute

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object