vertebrae.config

Public configuration objects for vertebrae.

Classes

OverlapScoringConfig	Configuration for MiniBatchKMeans-backed OverlapIndex scoring.
ContinuousOverlapScoringConfig	Configuration for MiniBatchKMeans-backed ContinuousOverlapIndex scoring.
RetrievalConfig	Configuration for exact, training-free query--gallery retrieval scoring.
ZeroShotConfig	Configuration for exact, training-free zero-shot semantic alignment.
SeparatixConfig	Configuration for optional Separatix complexity diagnostics.
StabilityConfig	Configuration for prototype or subsample stability analysis.
LabelViewConfig	Configuration for optional hierarchical label-view benchmarking.
TargetViewConfig	Configuration for optional named target-view benchmarking.
CacheConfig	Artifact cache settings.
EmbeddingConfig	Configuration for embedding generation and materialization.
ExecutionConfig	Artifact-backed benchmark execution settings.
SegmentationConfig	Configuration for dense spatial segmentation evaluation.
EmbeddingCompressionConfig	Configuration for optional embedding compression.
MemoryConfig	Memory budget and admission-control settings.
ResourceProfilingConfig	Opt-in measurement of extraction cost and representation footprint.

Functions

overlap_scoring_config_recipe(config)

Serialize overlap configuration with semantic classification keys.

Module Contents

class vertebrae.config.OverlapScoringConfig

Configuration for MiniBatchKMeans-backed OverlapIndex scoring.

k

Global k, class-to-k mapping, or “auto” for per-class resolution.

min_k

Lower target used by automatic k resolution.

max_k

Maximum k allowed for any class.

min_samples_per_cluster

Minimum class samples expected per prototype.

kmeans_kwargs

Extra keyword arguments passed to MiniBatchKMeans.

offline_chunk_size

Chunk size forwarded to OverlapIndex.fit_offline.

normalize_embeddings

Whether to L2-normalize embeddings before scoring.

max_dense_bytes

Fallback dense-operation limit for downstream diagnostics.

exclude_classes

Reporting-only classes omitted from global aggregation.

class vertebrae.config.ContinuousOverlapScoringConfig

Configuration for MiniBatchKMeans-backed ContinuousOverlapIndex scoring.

vertebrae.config.overlap_scoring_config_recipe(config)

Serialize overlap configuration with semantic classification keys.

Typed class labels are valid configuration values but are not ordinary JSON scalars. Recipes use their canonical semantic keys so local and distributed scoring protocols share one portable representation.

Parameters:

config (Any)

Return type:

Optional[Dict[str, Any]]

class vertebrae.config.RetrievalConfig

Configuration for exact, training-free query–gallery retrieval scoring.

class vertebrae.config.ZeroShotConfig

Configuration for exact, training-free zero-shot semantic alignment.

Zero-shot evaluation compares frozen sample embeddings with frozen text prompt prototypes. It intentionally has no learned calibration, prompt search, or fitted classification head. sample_batch_size bounds the exact sample-to-class score block, while max_dense_bytes caps the estimated scorer working set.

class vertebrae.config.SeparatixConfig

Configuration for optional Separatix complexity diagnostics.

enabled

Whether Separatix diagnostics should run.

overlap_threshold

Minimum classification overlap score required to run.

regression_overlap_threshold

Minimum regression overlap score required to run.

random_state

Seed forwarded to Separatix.

budget

Optional Separatix diagnostic budget.

max_samples

Optional Separatix sample cap.

densify_policy

Behavior when a dense-only diagnostic receives sparse data.

max_dense_bytes

Optional sparse densification memory limit in bytes.

n_jobs

Optional parallelism hint forwarded to Separatix.

mlp_probes

Whether conditional Separatix MLP probes should be enabled.

mlp_device

Requested Separatix MLP execution device.

mlp_trigger_skill_threshold

Skill threshold that suppresses MLP execution.

mlp_min_improvement

Minimum improvement required for an MLP override.

mlp_max_parameters

Optional hard cap for MLP parameter count.

class vertebrae.config.StabilityConfig

Configuration for prototype or subsample stability analysis.

enabled

Whether stability analysis should run.

mode

Stability mode: “prototype”, “subsample”, or “none”.

repeats

Number of repeated scoring runs.

interval_level

Percentile interval level reported in summaries.

subsample_fraction

Fraction sampled for subsample stability.

random_state

Seed used to generate repeat seeds and subsamples.

class vertebrae.config.LabelViewConfig

Configuration for optional hierarchical label-view benchmarking.

enabled

Whether hierarchy-derived label views should be evaluated.

hierarchy_levels

Sequence of hierarchy levels to evaluate. Each level may be an integer index or a named level present in dataset metadata.

output_levels

Mapping from extractor output names to hierarchy levels.

skip_invalid_levels

Whether invalid or unavailable levels should be skipped with a warning instead of raising.

class vertebrae.config.TargetViewConfig

Configuration for optional named target-view benchmarking.

enabled

Whether named target views should be evaluated.

views

Explicit target-view names to evaluate. When empty and enabled, all registered target views are evaluated.

output_views

Mapping from extractor output names to target-view names.

skip_invalid_views

Whether unavailable views should be skipped with a warning instead of raising.

class vertebrae.config.CacheConfig

Artifact cache settings.

enabled

Whether embedding artifacts should be cached.

cache_dir

Local cache directory or artifact-store URI.

force_recompute

Whether to ignore cache hits and recompute embeddings.

storage_options

Provider-specific store options such as S3 endpoint URLs.

metadata

Additional user metadata to preserve with cache settings.

class vertebrae.config.EmbeddingConfig

Configuration for embedding generation and materialization.

batch_size

Number of samples to pass to streaming-safe extractors.

streaming_enabled

Whether streaming-safe extractors should be embedded batch-by-batch instead of in one full transform call.

class vertebrae.config.ExecutionConfig

Artifact-backed benchmark execution settings.

Parameters:

• total_shards – Requested number of deterministic embedding shards.

• dispatch_stages – Stages submitted through the configured backend. Omitted stages use the same artifact jobs synchronously on the driver.

• retain_intermediate_artifacts – Whether to retain shard and run-scoped artifacts after result construction.

class vertebrae.config.SegmentationConfig

Configuration for dense spatial segmentation evaluation.

class vertebrae.config.EmbeddingCompressionConfig

Configuration for optional embedding compression.

enabled

Whether compression should run.

method

Compression method name.

n_components

Target dimension for projection-based compressors.

preserve_variance

PCA variance target in (0, 1).

precision

Quantization precision such as “float16” or “int8”.

assume_matryoshka

Whether prefix truncation should be treated as a matryoshka-style dimension shortening workflow.

random_state

Seed for stochastic compressors.

whiten

Whether PCA outputs should be whitened.

dtype

Optional real floating-point output dtype such as “float32”.

algorithm_kwargs

Extra method-specific keyword arguments.

class vertebrae.config.MemoryConfig

Memory budget and admission-control settings.

max_memory_bytes

Explicit process memory budget. When None, the budget is derived from current available memory using psutil.

reserve_system_bytes

Memory to leave available for the OS and other processes. When None, a conservative reserve is selected.

max_fraction

Maximum fraction of currently available memory to use.

allow_disk_spill

Whether large embedding artifacts may be streamed to disk.

fail_fast

Whether to raise before expensive work when estimates exceed the configured budget.

probe_batch_size

Number of samples used to infer unknown embedding shape.

model_memory_bytes

Optional model memory hint included in admission checks.

raw_batch_memory_bytes

Optional raw batch memory hint included in checks.

subsample_rate

Fraction of samples to keep before embedding and scoring. A value of 1.0 disables user-requested subsampling.

subsample_random_state

Seed used for deterministic stratified subsampling.

min_subsample_samples_per_class

Minimum retained samples per class when class sizes allow it.

auto_subsample_on_memory_exceeded

Whether to warn and select the largest fitting stratified subsample instead of raising when a full embedding artifact would exceed memory.

class vertebrae.config.ResourceProfilingConfig

Opt-in measurement of extraction cost and representation footprint.

Resource profiles are descriptive measurements for the current benchmark protocol. They do not participate in quality scoring or ranking.