vertebrae.extractors.base

Feature extractor protocols and shared multi-output types.

Classes

`EmbeddingOutputSpec`	Declarative description of one named extractor output.
`EmbeddingOutput`	Materialized embedding output from one extractor pass.
`FeatureExtractor`	Protocol implemented by all vertebrae feature extractors.
`MultiOutputFeatureExtractor`	Optional protocol for extractors that can emit multiple embedding matrices.
`RetrievalCapableExtractor`	Optional protocol for independent query/gallery branch encoding.
`ResourceProfileAdapter`	Optional extractor-owned hooks for framework-specific resource data.

Functions

`normalize_optional_output_integer`(value, name)	Validate an optional signed integer without lossy coercion.
`normalize_output_metadata`(value, name)	Copy deterministic, finite metadata without coercing its typed content.

Module Contents

class vertebrae.extractors.base.EmbeddingOutputSpec[source]: Declarative description of one named extractor output.

class vertebrae.extractors.base.EmbeddingOutput[source]: Materialized embedding output from one extractor pass.

class vertebrae.extractors.base.FeatureExtractor[source]

Bases: Protocol

Protocol implemented by all vertebrae feature extractors.

name[source]: User-facing extractor name.

modality[source]: Input modality handled by the extractor.

extractor_type[source]: Extractor family metadata.

fit(X, y=None)[source]

Fit extractor state when applicable.

Parameters:

X (Any) – Input samples.
y (Any) – Optional labels.

Returns:

The fitted extractor.

Return type:

FeatureExtractor

transform(X)[source]

Transform inputs into embeddings.

Parameters:: X (Any) – Input samples.
Returns:: Dense or sparse numeric embedding matrix.
Return type:: numpy.ndarray

fit_transform(X, y=None)[source]

Fit the extractor and transform inputs into embeddings.

Parameters:

X (Any) – Input samples.
y (Any) – Optional labels.

Returns:

Dense or sparse numeric embedding matrix.

Return type:

numpy.ndarray

recipe()[source]

Return a serializable extractor recipe.

Returns:: JSON-compatible recipe used for cache keys and reports.
Return type:: Dict[str, Any]

class vertebrae.extractors.base.MultiOutputFeatureExtractor[source]

Bases: Protocol

Optional protocol for extractors that can emit multiple embedding matrices.

output_specs()[source]

Return the named outputs this extractor can materialize.

Return type:: List[EmbeddingOutputSpec]

transform_many(X)[source]

Transform inputs into multiple named embedding outputs.

Parameters:: X (Any)
Return type:: List[EmbeddingOutput]

class vertebrae.extractors.base.RetrievalCapableExtractor[source]

Bases: Protocol

Optional protocol for independent query/gallery branch encoding.

encode_retrieval(X, *, branch, modality)[source]

Encode one declared endpoint branch into a numeric embedding matrix.

Parameters:

X (Any)
branch (str)
modality (str)

Return type:

Any

class vertebrae.extractors.base.ResourceProfileAdapter[source]

Bases: Protocol

Optional extractor-owned hooks for framework-specific resource data.

metadata()[source]

Return backend, device, dtype, and synchronization metadata.

Return type:: vertebrae.profiling.ResourceAdapterMetadata

synchronize()[source]

Synchronize asynchronous device work when supported.

Return type:: vertebrae.profiling.AdapterOperationResult

reset_peak_device_memory()[source]

Reset allocator peak counters when supported.

Return type:: vertebrae.profiling.AdapterOperationResult

peak_device_memory()[source]

Return allocator memory and availability metadata.

Return type:: vertebrae.profiling.DeviceMemoryMeasurement

model_footprint()[source]

Return parameter and buffer counts/bytes when available.

Return type:: vertebrae.profiling.ModelFootprintMeasurement

deployment_artifacts()[source]

Return explicit local model/checkpoint artifact paths.

Return type:: Sequence[vertebrae.profiling.DeploymentArtifact]

vertebrae.extractors.base.normalize_optional_output_integer(value, name)[source]

Validate an optional signed integer without lossy coercion.

Parameters:

value (Any)
name (str)

Return type:

Optional[int]

vertebrae.extractors.base.normalize_output_metadata(value, name)[source]

Copy deterministic, finite metadata without coercing its typed content.

Parameters:

value (Any)
name (str)

Return type:

Dict[str, Any]