Identity

domain.enrichment.entity.identity

Identity helpers for entity enrichment: text normalization, entity id derivation, candidate canonicalization, and entity state payload construction.

build_entity(
    name: str,
    entity_type: str = "merchant",
    entity_logo: str | None = None,
) -> dict

Build the entity payload spread into pipeline state.

Parameters:

Name	Type	Description	Default
`name`	`str`	Entity display name.	required
`entity_type`	`str`	Entity type, defaults to `"merchant"`.	`'merchant'`
`entity_logo`	`str \| None`	Logo URL/path, or `None`.	`None`

Returns:

Name	Type	Description
`dict`	`dict`	A payload mapping the `entity.*` keys accepted by
	`dict`	`dagpipe` state forks.

canonicalize_candidate(candidate: str | None) -> str | None

Canonicalize a candidate value for comparisons.

Parameters:

Name	Type	Description	Default
`candidate`	`str \| None`	Raw candidate string.	required

Returns:

Type	Description
`str \| None`	str \| None: The normalized candidate key, or `None` for falsy
`str \| None`	input.

normalize_key(text: str | None) -> str | None

Normalize arbitrary text to a comparison key.

Applies NFKC unicode normalization, lower-cases, and strips surrounding whitespace.

Parameters:

Name	Type	Description	Default
`text`	`str \| None`	Text to normalize; `None` passes through.	required

Returns:

Type	Description
`str \| None`	str \| None: The normalized key, or `None` for `None` input.

to_entity_id(name: str | None) -> str | None

Derive a stable slug id from a name.

Empty/falsy names yield None. Non-alphanumeric runs are replaced with a single underscore and edge underscores are trimmed.

Parameters:

Name	Type	Description	Default
`name`	`str \| None`	Entity name to slugify.	required

Returns:

Type	Description
`str \| None`	str \| None: The slug id, or `None` when `name` is falsy.