Domain types

Conversation and explanation enumerations for the text MVP.

class nlp_shap.domain.enums.Role(*values)

Bases: StrEnum

Participant role attached to a message or token.

USER = 'user'

End-user or human-provided input.

ASSISTANT = 'assistant'

Model-generated output.

SYSTEM = 'system'

System-level instruction or steering text.

class nlp_shap.domain.enums.SystemRolesSetup(*values)

Bases: StrEnum

How system-role tokens participate in explainability.

NONE = 'none'

All tokens, including system tokens, are explainable.

SYSTEM = 'system'

System tokens are excluded from explainability.

SYSTEM_ASSISTANT = 'system_assistant'

System and assistant tokens are excluded from explainability.

class nlp_shap.domain.enums.EmbeddingMode(*values)

Bases: StrEnum

Whether value functions use static or contextual embeddings.

STATIC = 'static'

Embeddings computed from final generated tokens only.

CONTEXTUAL = 'contextual'

Embeddings derived from model internal states.

Immutable conversation snapshots without backend or IO.

class nlp_shap.domain.conversation.Message(role: Role, text: str)

Bases: object

A single explainable text unit with an attached role.

role: Role

Participant role for this text unit.

text: str

Token or span text included in the explainability input.

class nlp_shap.domain.conversation.Turn(messages: tuple[Message, ...])

Bases: object

One conversational turn composed of ordered messages.

messages: tuple[Message, ...]

Ordered messages that make up this turn.

class nlp_shap.domain.conversation.ConversationSnapshot(turns: tuple[Turn, ...], snapshot_id: str)

Bases: object

Frozen conversation state used as the explainability input.

turns: tuple[Turn, ...]

Ordered turns that define the conversation under study.

snapshot_id: str

Stable identifier used for deduplication and run archives.

classmethod from_turns(turns: tuple[Turn, ...]) → ConversationSnapshot

Build a snapshot with a stable content-derived identifier.

Player indexing for cooperative-game explainability.

class nlp_shap.domain.players.PlayerSet(player_ids: tuple[str, ...])

Bases: object

Ordered explainability players aligned with coalition masks.

player_ids: tuple[str, ...]

Stable player identifiers in coalition-mask order.

property num_players: int

Return the number of players in the set.

Coalition masks over explainability players.

class nlp_shap.domain.coalition.CoalitionMask(present: tuple[bool, ...])

Bases: object

Boolean presence mask aligned with a player set.

present: tuple[bool, ...]

Presence flags aligned with PlayerSet order.

classmethod from_sequence(present: Sequence[bool]) → CoalitionMask

Build a mask from any boolean sequence.

coalition_size() → int

Return the number of present players.

validate_against(player_set: PlayerSet) → None

Ensure the mask length matches the player set.

Cooperative-game domain types.

class nlp_shap.domain.game.CooperativeGame(player_set: PlayerSet, empty_value: float = 0.0)

Bases: object

Player set and reference values for a characteristic function.

player_set: PlayerSet

Ordered explainability players that define the game.

empty_value: float

Reference payoff \(v(\emptyset)\) for the characteristic function.

Estimand labels for attribution outputs and archive manifests.

nlp_shap.domain.estimands.EstimandWire

Wire values used in manifests and configuration payloads.

alias of Literal[‘shapley’, ‘banzhaf’]

class nlp_shap.domain.estimands.Estimand(*values)

Bases: StrEnum

Supported cooperative-game value formulations.

SHAPLEY = 'shapley'

Shapley value with coalition weights k!(n-k-1)!/n!.

BANZHAF = 'banzhaf'

Banzhaf index with uniform coalition weights 1/2^(n-1).

nlp_shap.domain.estimands.estimand_to_wire(estimand: Estimand) → Literal['shapley', 'banzhaf']

Serialize an estimand enum member to its wire value.