Value functions

Coalition utility scoring plugins.

@domain value @see [[knowledge/architecture/value]]

Frozen-corpus TF-IDF cosine value function.

@domain value @see [[knowledge/architecture/value]] @tested-by [[tests/value/test_tfidf.py]]

class mllm_shap.value.tfidf.TfIdfCosineValue(context: PluginContext | None = None)

Bases: object

Score generations with cosine similarity of frozen TF-IDF vectors.

options_model

Accepts no explanation.plugin_options.

alias of PluginOptions

property name: str

Return the registered value-function identifier.

fit(corpus: Sequence[GenerationRecord]) → None

Freeze inverse document frequency weights from corpus.

score(base: GenerationResult, candidate: GenerationResult) → float

Return TF-IDF cosine similarity between candidate and base.

Embedding-based value functions.

@domain value @see [[knowledge/architecture/value]] @tested-by [[tests/value/test_embedding.py]]

class mllm_shap.value.embedding.EmbeddingValue(context: PluginContext | None = None, embedding_mode: EmbeddingMode = EmbeddingMode.STATIC, provider: EmbeddingProvider | None = None)

Bases: ABC

Similarity between static or contextual embedding vectors.

options_model

Accepts no explanation.plugin_options.

alias of PluginOptions

registered_name: ClassVar[str]

Registered value-function identifier.

property name: str

Return the registered value-function identifier.

property needs_embeddings: bool

Always true; scoring reads the records’ embedding vectors.

score(base: GenerationResult, candidate: GenerationResult) → float

Return the similarity of the two embedding vectors.

class mllm_shap.value.embedding.CosineEmbeddingValue(context: PluginContext | None = None, embedding_mode: EmbeddingMode = EmbeddingMode.STATIC, provider: EmbeddingProvider | None = None)

Bases: EmbeddingValue

Cosine similarity between static or contextual embeddings (U1/U2).

registered_name: ClassVar[str] = 'embedding_cosine'

Registered value-function identifier.

class mllm_shap.value.embedding.EuclideanEmbeddingValue(context: PluginContext | None = None, embedding_mode: EmbeddingMode = EmbeddingMode.STATIC, provider: EmbeddingProvider | None = None)

Bases: EmbeddingValue

Similarity 1 / (1 + distance) between embeddings (U4).

registered_name: ClassVar[str] = 'embedding_euclidean'

Registered value-function identifier.

Logprob-based value function.

@domain value @see [[knowledge/architecture/value]] @tested-by [[tests/value/test_logprob.py]]

class mllm_shap.value.logprob.LogprobValue(context: PluginContext | None = None)

Bases: object

Score a coalition by the model’s confidence in its own generation.

v(S) is the mean natural-log probability of the tokens the backend generated for coalition S (its GenerationRecord.logprobs), so it lies in (-inf, 0]; an empty generation scores 0. The base generation is not read: v(N) is the base generation’s own mean logprob.

options_model

Accepts no explanation.plugin_options.

alias of PluginOptions

property name: str

Return the registered value-function identifier.

property needs_logprobs: bool

Always true; scoring reads GenerationRecord.logprobs.

score(base: GenerationResult, candidate: GenerationResult) → float

Return the mean token logprob of candidate.

Raises:

LogprobsUnavailableError – If candidate carries no logprobs.

Word error rate against a reference text as a coalition value.

@domain value @see [[knowledge/architecture/value]] @tested-by [[tests/value/test_wer.py]]

mllm_shap.value.wer.word_error_rate(reference: str, hypothesis: str) → float

Return word-level edit distance over the reference’s word count.

Words are lowercased runs of letters, digits, _ and ', so case and punctuation do not count. An empty reference gives 0 for an empty hypothesis and 1 otherwise.

class mllm_shap.value.wer.ReferenceWerOptions(*, reference: str | None = None)

Bases: PluginOptions

Options of the reference_wer value function.

reference: str | None

Target text, such as a transcript; None uses the full coalition’s answer.

model_config = {'extra': 'forbid', 'frozen': True, 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class mllm_shap.value.wer.ReferenceWerValue(context: PluginContext | None = None)

Bases: object

Score 1 - min(1, WER) of a coalition’s answer against a reference.

With reference set, v(S) measures how correct the answer is (a transcription task); without it, how close it stays to the full answer. Values lie in [0, 1].

options_model

Options accepted from explanation.plugin_options.

alias of ReferenceWerOptions

reference

Target text; None scores against the base generation.

property name: str

Return the registered value-function identifier.

score(base: GenerationResult, candidate: GenerationResult) → float

Return 1 - min(1, WER) of candidate against the target.

Build generation records from generated text for value-function scoring.

@domain value @see [[knowledge/architecture/value]] @tested-by [[tests/value/test_generation_records.py]]

mllm_shap.value.generation_records.EMBED_DIM: Final[int] = 8

Dimension of the deterministic hash embedding used by mock and archive paths.

mllm_shap.value.generation_records.generation_record_from_text(text: str, context_id: str | None = None) → GenerationRecord

Build a record whose token rows and embeddings derive from text only.

explain and reanalyze both score records built here, so a value function sees the same inputs whether the text came from a backend or an archive. contextual_embedding hashes text with a separator so it differs from embedding; it takes no prompt or snapshot id, which a backend sees for the rendered coalition and reanalyze never sees.

Parameters:

• text – Generated text.

• context_id – Deprecated and ignored; passing it emits a DeprecationWarning. It salted contextual_embedding until 0.1.18, which made backend records differ from reanalyze.

mllm_shap.value.generation_records.stable_token_id(token: str) → int

Return a process-independent 56-bit id for token.

mllm_shap.value.generation_records.hash_embedding(payload: str) → tuple[float, ...]

Map payload to a fixed-size float vector in [-1, 1] via SHA-256.