Struct Identity 

pub struct Identity {
    pub id: IdentityId,
    pub canonical_name: String,
    pub entity_type: Option<TypeLabel>,
    pub kb_id: Option<String>,
    pub kb_name: Option<String>,
    pub description: Option<String>,
    pub embedding: Option<Vec<f32>>,
    pub aliases: Vec<String>,
    pub confidence: f32,
    pub source: Option<IdentitySource>,
}

A global identity: a real-world entity linked to a knowledge base.

The Modal Gap

There’s a fundamental representational gap between:

• Text mentions: Contextual, variable surface forms (“Marie Curie”, “she”, “the scientist”)
• KB entities: Canonical, static representations (Q7186 in Wikidata)

Bridging this gap requires:

1. Learning aligned embeddings (text encoder ↔ KB encoder)
2. Type consistency constraints
3. Cross-encoder re-ranking for hard cases

Design Philosophy

Identities are the “global truth” that tracks point to. They represent:

• A canonical name and description
• A knowledge base reference (if available)
• An embedding in the entity space (for similarity/clustering)

Identities can exist without KB links (for novel entities not in the KB).

Fields

id: IdentityId

Unique identifier

canonical_name: String

Canonical name (the “official” name)

entity_type: Option<TypeLabel>

Entity type/category.

Stored as a TypeLabel to support both core and custom (domain) labels.

kb_id: Option<String>

Knowledge base reference (e.g., “Q7186” for Wikidata)

kb_name: Option<String>

Knowledge base name (e.g., “wikidata”, “umls”)

description: Option<String>

Description from knowledge base

embedding: Option<Vec<f32>>

Entity embedding in the KB/entity space This is aligned with the text encoder space for similarity computation

aliases: Vec<String>

Alias names (other known surface forms)

confidence: f32

Confidence that this identity is correctly resolved

source: Option<IdentitySource>

Source of identity formation (how it was created)

Implementations

impl Identity

pub fn new(id: impl Into<IdentityId>, canonical_name: impl Into<String>) -> Self

Create a new identity.

pub fn from_kb( id: impl Into<IdentityId>, canonical_name: impl Into<String>, kb_name: impl Into<String>, kb_id: impl Into<String>, ) -> Self

Create an identity from a knowledge base entry.

pub fn add_alias(&mut self, alias: impl Into<String>)

Add an alias.

pub const fn id(&self) -> IdentityId

Get the identity’s unique identifier.

pub fn canonical_name(&self) -> &str

Get the canonical name.

pub fn kb_id(&self) -> Option<&str>

Get the KB ID, if linked.

pub fn kb_name(&self) -> Option<&str>

Get the KB name, if linked.

pub fn aliases(&self) -> &[String]

Get the aliases.

pub const fn confidence(&self) -> f32

Get the confidence score.

pub fn set_confidence(&mut self, confidence: f32)

Set the confidence score.

pub fn source(&self) -> Option<&IdentitySource>

Get the identity source.

pub fn with_embedding(self, embedding: Vec<f32>) -> Self

Set the embedding.

pub fn with_type(self, entity_type: impl Into<String>) -> Self

Set the entity type from a string.

For new code, prefer Self::with_type_label which provides type safety.

pub fn with_type_label(self, label: TypeLabel) -> Self

Set the entity type using a type-safe label.

This is the preferred method for new code as it provides type safety and integrates with the core EntityType taxonomy.

pub fn type_label(&self) -> Option<TypeLabel>

Get the entity type as a type-safe label.

This converts the internal string representation to a TypeLabel, attempting to parse it as a core EntityType first.

pub fn with_description(self, description: impl Into<String>) -> Self

Set description.

Trait Implementations

impl Clone for Identity

fn clone(&self) -> Identity

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Identity

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Identity

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Identity

fn eq(&self, other: &Identity) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Identity

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for Identity