Context Specs

Context specs declare the data dependencies for an experiment. They provide a serializable manifest of file paths and configurations that operations can use to load their inputs.

metalab.context_spec

context_spec(cls: type[T]) -> type[T]

context_spec(*, frozen: bool = True) -> Any

context_spec(cls: type[T] | None = None, *, frozen: bool = True) -> type[T] | Any

Decorator that creates a frozen dataclass with automatic fingerprinting.

This decorator: 1. Applies @dataclass(frozen=True) to the class (unless frozen=False) 2. Adds a fingerprint property that computes a stable hash of all fields

The fingerprint is computed lazily on first access and cached.

Parameters:

Name	Type	Description	Default
cls	type[T] | None	The class to decorate (when used without parentheses).	None
frozen	bool	Whether to make the dataclass frozen (default: True).	True

Returns:

Type	Description
type[T] | Any	The decorated class.

Example:

@metalab.context_spec
class MyContextSpec:
    name: str
    version: str = "1.0"
    dataset_path: str = ""

spec = MyContextSpec(name="test", dataset_path="/data/train.csv")
print(spec.fingerprint)  # Auto-computed hash

metalab.FilePath dataclass

FilePath(path: str, hash_path: bool = False)

A file path marker that implements Fingerprintable.

The hash is computed lazily at fingerprint time using file metadata (size, mtime, inode) for O(1) performance regardless of file size.

When used in a context spec, the fingerprint will include the metadata hash, ensuring runs are deduplicated based on file identity.

Parameters:

Name	Type	Description	Default
path	str	Path to the file.	required
hash_path	bool	If True, include the path in the fingerprint (default: False). When False, only file metadata is used - same file at different paths produces the same fingerprint.	False

Example:

@metalab.context_spec
class DataSpec:
    data: FilePath

spec = DataSpec(data=FilePath("./cache/adata.h5ad"))
preprocess(spec)  # File created here
metalab.run(...)  # Hash computed here

__fspath__

__fspath__() -> str

Support os.fspath() and Path() construction.

__str__

__str__() -> str

Return the path (for use in operations).

fingerprint_payload

fingerprint_payload() -> dict[str, Any]

Compute metadata-based hash and return payload for fingerprinting.

metalab.DirPath dataclass

DirPath(path: str, pattern: str = '*', hash_path: bool = False)

A directory path marker that implements Fingerprintable.

The hash is computed lazily at fingerprint time using file metadata (size, mtime, inode) for O(1) performance per file.

When used in a context spec, the fingerprint will include the aggregated metadata hash of all matching files.

Parameters:

Name	Type	Description	Default
path	str	Path to the directory.	required
pattern	str	Glob pattern for files to include (default: "*").	'*'
hash_path	bool	If True, include the path in the fingerprint (default: False).	False

Example:

@metalab.context_spec
class DataSpec:
    raw_data: DirPath

spec = DataSpec(raw_data=DirPath("./data/raw/", pattern="*.csv"))

__fspath__

__fspath__() -> str

Support os.fspath() and Path() construction.

__str__

__str__() -> str

Return the path (for use in operations).

fingerprint_payload

fingerprint_payload() -> dict[str, Any]

Compute metadata-based hash and return payload for fingerprinting.