Masking

Coalition masking codecs, views, and absence policies.

class nlp_shap.masking.DeletePolicy

Bases: object

Remove absent tokens from the rendered conversation.

property name: str

Return the registered absence-policy identifier.

apply(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → ConversationSnapshot

Drop absent tokens while preserving turn and message structure.

class nlp_shap.masking.MaskBuilder(policy: AbsencePolicy)

Bases: object

Build masked snapshot views without copying the base conversation.

property policy_name: str

Return the configured absence-policy identifier.

view(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → MaskedSnapshot

Create a masked view that shares snapshot across coalitions.

render(masked: MaskedSnapshot) → ConversationSnapshot

Materialize a coalition-specific conversation snapshot.

class nlp_shap.masking.MaskCodec

Bases: object

Encode and decode boolean masks to packed bytes.

static normalize(mask: Sequence[bool] | NDArray[bool]) → NDArray[bool]

Normalize incoming mask to a 1D boolean array.

static pack(mask: Sequence[bool] | NDArray[bool]) → PackedMask

Pack a mask into little-endian bytes.

static unpack(packed: PackedMask) → tuple[bool, ...]

Unpack bytes back to a boolean tuple.

static hash_mask(mask: Sequence[bool] | NDArray[bool]) → int

Return a stable hash over packed mask bytes.

class nlp_shap.masking.MaskSpace(explainable_mask: tuple[bool, ...], target_length: int)

Bases: object

Describe explainable feature positions inside a full coalition mask.

explainable_mask: tuple[bool, ...]

Boolean flags selecting explainable feature positions from the full mask.

target_length: int

Total length of the full coalition mask including fixed positions.

property n_features: int

Return the number of explainable features.

materialize(split: CoalitionMask | Sequence[bool]) → tuple[bool, ...]

Project a split over explainable positions back to the full mask.

class nlp_shap.masking.MaskedSnapshot(base: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask, policy_name: str)

Bases: object

Shared view over a conversation snapshot and coalition mask.

base: ConversationSnapshot

Underlying snapshot shared across coalition evaluations.

players: PlayerSet

Ordered players aligned with the coalition mask.

mask: CoalitionMask

Presence mask selecting which players remain in the coalition.

policy_name: str

Registered absence-policy identifier used to render the view.

property base_snapshot_id: str

Return the shared base snapshot identifier.

property mask_hash: int

Return a stable hash for the coalition mask.

class nlp_shap.masking.NeutralPolicy(fill_char: str = '_')

Bases: object

Replace absent tokens with neutral fillers that preserve token width.

fill_char: str

Single character repeated to match each absent token length.

property name: str

Return the registered absence-policy identifier.

apply(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → ConversationSnapshot

Substitute absent tokens with width-matched neutral fillers.

class nlp_shap.masking.PackedMask(words: bytes, n_bits: int)

Bases: object

Packed bit representation of one boolean mask.

words: bytes

Little-endian packed bytes encoding the boolean mask.

n_bits: int

Original number of bits (mask length) before packing.

class nlp_shap.masking.PadPolicy(placeholder: str = '[MASK]')

Bases: object

Replace absent tokens with a fixed mask placeholder.

placeholder: str

Placeholder text inserted for absent tokens.

property name: str

Return the registered absence-policy identifier.

apply(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → ConversationSnapshot

Substitute absent tokens with placeholder.

class nlp_shap.masking.PrefixTreeStub(enabled: bool = False)

Bases: object

Placeholder type marking the prefix-tree integration point.

enabled: bool

Whether prefix-tree grouping is active.

class nlp_shap.masking.TokenPartitioner

Bases: object

Partition a snapshot into whitespace-delimited text tokens.

property name: str

Return the registered partition identifier.

partition(snapshot: ConversationSnapshot) → PlayerSet

Derive ordered token players from the snapshot text.

Packed bitset encoding and stable hashing for coalition masks.

class nlp_shap.masking.codec.PackedMask(words: bytes, n_bits: int)

Bases: object

Packed bit representation of one boolean mask.

words: bytes

Little-endian packed bytes encoding the boolean mask.

n_bits: int

Original number of bits (mask length) before packing.

class nlp_shap.masking.codec.MaskCodec

Bases: object

Encode and decode boolean masks to packed bytes.

static normalize(mask: Sequence[bool] | NDArray[bool]) → NDArray[bool]

Normalize incoming mask to a 1D boolean array.

static pack(mask: Sequence[bool] | NDArray[bool]) → PackedMask

Pack a mask into little-endian bytes.

static unpack(packed: PackedMask) → tuple[bool, ...]

Unpack bytes back to a boolean tuple.

static hash_mask(mask: Sequence[bool] | NDArray[bool]) → int

Return a stable hash over packed mask bytes.

Mask-space utilities for explainable feature indexing.

class nlp_shap.masking.space.MaskSpace(explainable_mask: tuple[bool, ...], target_length: int)

Bases: object

Describe explainable feature positions inside a full coalition mask.

explainable_mask: tuple[bool, ...]

Boolean flags selecting explainable feature positions from the full mask.

target_length: int

Total length of the full coalition mask including fixed positions.

property n_features: int

Return the number of explainable features.

materialize(split: CoalitionMask | Sequence[bool]) → tuple[bool, ...]

Project a split over explainable positions back to the full mask.

View-based masked snapshots with structural sharing.

class nlp_shap.masking.builder.MaskedSnapshot(base: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask, policy_name: str)

Bases: object

Shared view over a conversation snapshot and coalition mask.

base: ConversationSnapshot

Underlying snapshot shared across coalition evaluations.

players: PlayerSet

Ordered players aligned with the coalition mask.

mask: CoalitionMask

Presence mask selecting which players remain in the coalition.

policy_name: str

Registered absence-policy identifier used to render the view.

property base_snapshot_id: str

Return the shared base snapshot identifier.

property mask_hash: int

Return a stable hash for the coalition mask.

class nlp_shap.masking.builder.MaskBuilder(policy: AbsencePolicy)

Bases: object

Build masked snapshot views without copying the base conversation.

property policy_name: str

Return the configured absence-policy identifier.

view(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → MaskedSnapshot

Create a masked view that shares snapshot across coalitions.

render(masked: MaskedSnapshot) → ConversationSnapshot

Materialize a coalition-specific conversation snapshot.

Absence policies for rendering masked conversation snapshots.

class nlp_shap.masking.policies.DeletePolicy

Bases: object

Remove absent tokens from the rendered conversation.

property name: str

Return the registered absence-policy identifier.

apply(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → ConversationSnapshot

Drop absent tokens while preserving turn and message structure.

class nlp_shap.masking.policies.PadPolicy(placeholder: str = '[MASK]')

Bases: object

Replace absent tokens with a fixed mask placeholder.

placeholder: str

Placeholder text inserted for absent tokens.

property name: str

Return the registered absence-policy identifier.

apply(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → ConversationSnapshot

Substitute absent tokens with placeholder.

class nlp_shap.masking.policies.NeutralPolicy(fill_char: str = '_')

Bases: object

Replace absent tokens with neutral fillers that preserve token width.

fill_char: str

Single character repeated to match each absent token length.

property name: str

Return the registered absence-policy identifier.

apply(snapshot: ConversationSnapshot, players: PlayerSet, mask: CoalitionMask) → ConversationSnapshot

Substitute absent tokens with width-matched neutral fillers.

Player partition plugins for conversation snapshots.

class nlp_shap.masking.partitions.TokenPartitioner

Bases: object

Partition a snapshot into whitespace-delimited text tokens.

property name: str

Return the registered partition identifier.

partition(snapshot: ConversationSnapshot) → PlayerSet

Derive ordered token players from the snapshot text.