Pipeline configuration

Explain pipeline configuration schema.

class nlp_shap.pipeline.config.BackendConfig(*, kind: str, model_id: str, api_host: str | None = None)

Bases: BaseModel

Backend selection and connection parameters.

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

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

kind: str

Registered backend plugin identifier.

model_id: str

Model name or repository id passed to the backend.

api_host: str | None

Optional API host for HTTP-compatible backends.

class nlp_shap.pipeline.config.GenerationConfig(*, max_new_tokens: int = 128, temperature: float = 0.0, top_k: int = 1, precompute_base: bool = True)

Bases: BaseModel

Generation parameters for the base and coalition evaluations.

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

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

max_new_tokens: int

Maximum tokens generated per coalition evaluation.

temperature: float

Sampling temperature for model generation.

top_k: int

Top-k sampling cutoff for model generation.

precompute_base: bool

Whether to generate the grand-coalition reference before explaining.

class nlp_shap.pipeline.config.BudgetConfig(*, fraction: Annotated[float, Gt(gt=0.0), Le(le=1.0)] = 1.0)

Bases: BaseModel

Estimator budget controls replacing standard/limited split configs.

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

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

fraction: float

Fraction of the full coalition budget used by the estimator.

class nlp_shap.pipeline.config.ArchiveConfig(*, path: str = './runs/{run_id}', flush_every: Annotated[int, Ge(ge=1)] = 50)

Bases: BaseModel

Run archive persistence options.

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

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

path: str

Filesystem path template for persisted run archives.

flush_every: int

Number of coalition records between archive flushes.

class nlp_shap.pipeline.config.DedupConfig(*, enabled: Literal['auto', 'on', 'off'] = 'auto')

Bases: BaseModel

Coalition deduplication options.

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

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

enabled: Literal['auto', 'on', 'off']

Deduplication mode for repeated coalition evaluations.

class nlp_shap.pipeline.config.KvCacheConfig(*, enabled: bool = True)

Bases: BaseModel

Prefix cache options for supported backends.

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

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

enabled: bool

Whether prefix/KV cache reuse is enabled when supported.

class nlp_shap.pipeline.config.ExplanationConfig(*, use_v2: bool = True, estimand: Estimand = Estimand.SHAPLEY, estimator: str = 'neyman_cc', value_fn: str = 'tfidf_cosine', normalizer: str = 'identity', players: str = 'tokens', absence_policy: str = 'delete', budget: BudgetConfig = BudgetConfig(fraction=1.0), include_minimal_masks: bool = False, max_inflight: Annotated[int, Ge(ge=1)] = 2, archive: ArchiveConfig = ArchiveConfig(path='./runs/{run_id}', flush_every=50), dedup: DedupConfig = DedupConfig(enabled='auto'), kv_cache: KvCacheConfig = KvCacheConfig(enabled=True), embedding_mode: EmbeddingMode = EmbeddingMode.STATIC, seed: int = 42)

Bases: BaseModel

Explanation algorithm and runtime controls.

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

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

use_v2: bool

Whether the v2 explain pipeline is active.

estimand: Estimand

Cooperative-game value targeted by aggregation.

estimator: str

Registered estimator plugin used to sample coalitions.

value_fn: str

Registered value-function plugin used to score outputs.

normalizer: str

Registered normalizer applied after estimand aggregation.

players: str

Registered partition plugin that defines explainability players.

absence_policy: str

Registered absence policy used to render masked snapshots.

budget: BudgetConfig

Estimator budget controls.

include_minimal_masks: bool

Whether minimal coalitions are included in estimator sampling.

max_inflight: int

Maximum concurrent coalition evaluations.

archive: ArchiveConfig

Run archive persistence settings.

dedup: DedupConfig

Coalition deduplication settings.

kv_cache: KvCacheConfig

Prefix cache settings for supported backends.

embedding_mode: EmbeddingMode

Embedding mode used by embedding-based value functions.

seed: int

Random seed for reproducible coalition sampling.

class nlp_shap.pipeline.config.ExplainConfig(*, backend: BackendConfig, generation: GenerationConfig = GenerationConfig(max_new_tokens=128, temperature=0.0, top_k=1, precompute_base=True), explanation: ExplanationConfig = ExplanationConfig(use_v2=True, estimand=<Estimand.SHAPLEY: 'shapley'>, estimator='neyman_cc', value_fn='tfidf_cosine', normalizer='identity', players='tokens', absence_policy='delete', budget=BudgetConfig(fraction=1.0), include_minimal_masks=False, max_inflight=2, archive=ArchiveConfig(path='./runs/{run_id}', flush_every=50), dedup=DedupConfig(enabled='auto'), kv_cache=KvCacheConfig(enabled=True), embedding_mode=<EmbeddingMode.STATIC: 'static'>, seed=42))

Bases: BaseModel

Top-level explain pipeline configuration.

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

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

backend: BackendConfig

Backend selection and connection parameters.

generation: GenerationConfig

Generation parameters for base and coalition evaluations.

explanation: ExplanationConfig

Explanation algorithm and runtime controls.

nlp_shap.pipeline.config.explain_config_from_yaml(text: str) → ExplainConfig

Parse YAML text into a validated ExplainConfig.

nlp_shap.pipeline.config.explain_config_to_yaml(config: ExplainConfig) → str

Serialize a config to YAML with stable key ordering within sections.

Explain pipeline result types.

class nlp_shap.pipeline.result.ExplainResult(estimand: Estimand, values: tuple[float, ...])

Bases: object

Attribution output for a single explain run.

estimand: Estimand

Estimand used to aggregate coalition samples.

values: tuple[float, ...]

Per-player attribution values.

Run archive manifest schema stubs.

class nlp_shap.pipeline.manifest.RunManifestPayload

Bases: TypedDict

JSON-compatible manifest payload persisted with a run archive.

estimand: Literal['shapley', 'banzhaf']

Estimand label recorded for every attribution output.

run_id: str

Stable identifier for the explain run.

class nlp_shap.pipeline.manifest.RunManifest(estimand: Estimand, run_id: str)

Bases: object

Top-level metadata persisted alongside a run archive.

estimand: Estimand

Estimand label recorded for every attribution output.

run_id: str

Stable identifier for the explain run.

to_dict() → RunManifestPayload

Serialize manifest fields to JSON-compatible primitives.

nlp_shap.pipeline.manifest.parse_manifest(payload: RunManifestPayload) → RunManifest

Parse a typed manifest payload into a run manifest.