Skip to main content

agrag.common.data_models.entity.Entity

Bases: DataPoint

A permanent mention-level node, never destroyed once written.

Each Entity is one raw record. Exact-match accumulation only folds a new mention into the existing node for its normalized name. Fuzzy, embedding, and LLM matches never absorb a node. They persist as MATCHES edges with a derived ResolvedEntity instead, so both raw records and their relationships survive resolution.

Attributes:

  • label (str) – The EntityType label this entity was resolved as.
  • name (str) – The canonical resolved surface form. It is field-resolved the same way any property is, but it stays as its own field rather than inside properties, since every entity has one regardless of EntityType.properties schema. It is what gets embedded (embedding_text).
  • properties (dict[str, object]) – Field-resolved property values, keyed by the schema declared property names (for example "dosage" or "description", whatever EntityType.properties for this label declares). Never holds name.
  • embedding (list[float] | None) – The entity's dense vector, once populated by the storage stage. None before that point.
  • merge_count (int) – The total number of source mentions this entity's data was assembled from. Starts at 1.
  • source_chunk_ids (list[UUID]) – Ids of every Chunk a mention contributing to this entity's data came from. Each also backs one MENTIONED_IN edge from that Chunk to this Entity.

Functions:

created_at​

created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))

embedding​

embedding: list[float] | None = None

embedding_text​

embedding_text: str

Return the text this entity's embedding is computed from.

Name alone, or name plus a "description" property when the schema declares one. Decided once, here, so every embedding call site (resolution's future embedding tier, storage-stage population, Graph.consolidate()) embeds the same text for the same entity.

id​

id: UUID

label​

label: str

merge_count​

merge_count: int = 1

merge_key​

merge_key: str

Return this entity's global exact-match lookup key.

The key is (label, normalized name). It uses the same identity that ExactMatch already uses in-batch, applied to a persisted store lookup. A derived value, not stored redundantly anywhere else on this model. to_node_record() computes it fresh from label and name on every write, so it can never drift from what the fields it's derived from actually say.

metadata​

metadata: dict[str, Any] = Field(default_factory=dict)

name​

name: str

properties​

properties: dict[str, object] = Field(default_factory=dict)

source_chunk_ids​

source_chunk_ids: list[UUID] = Field(default_factory=list)

to_node_record​

to_node_record() -> NodeRecord

Return this entity as a GraphStore write record.

Name, merge_key, merge_count, and source_chunk_ids are flattened into properties as plain JSON-safe values. GraphStore has no reason to know these fields are special.