SAM Pydantic Base Classes

These are the base Pydantic models used as the foundations for all Smarter API Manifest (SAM) models.

Pydantic models for Smarter API Manifests.

class smarter.lib.manifest.models.AbstractSAMBase(*, apiVersion: str, kind: str, metadata: AbstractSAMMetadataBase, spec: AbstractSAMSpecBase, status: AbstractSAMStatusBase | None = None)[source]

Bases: SmarterBasePydanticModel, ABC

Abstract base class for all Smarter API Manifest (SAM) models.

This class serves as the foundational Pydantic model for representing Smarter API manifests. It is intended to be subclassed by concrete manifest classes that define specific resource types within the Smarter API ecosystem.

The AbstractSAMBase class provides a strongly-typed structure for manifest data, ensuring that all manifests adhere to a consistent schema and validation logic. It includes built-in validation for core manifest fields and supports structured access to manifest data.

Subclasses should implement or extend this class to define the specific data and behaviors required for their respective manifest types. This design promotes code reuse, type safety, and robust validation across all Smarter API manifests.

The class also provides methods for validating manifest data and for representing the manifest as a string for debugging or logging purposes.

Note

Do not instantiate this class directly. Instead, create subclasses that define the required fields and any additional validation or methods specific to your manifest type.

apiVersion: str
kind: str
metadata: AbstractSAMMetadataBase
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}

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

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Return type:

None

Parameters:

  • self – The BaseModel instance.

  • context – The context.

spec: AbstractSAMSpecBase
status: AbstractSAMStatusBase | None
classmethod validate_apiVersion(v)[source]

Validates the apiVersion field for a manifest.

This method ensures that the apiVersion attribute is present and matches one of the supported API versions defined in SmarterApiVersions. If the value is missing or invalid, a SAMValidationError is raised.

Parameters:

v (str) – The value of the apiVersion field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If the value is missing or not a supported version.

Returns:

The validated apiVersion string.

Return type:

str

classmethod validate_metadata(v)[source]

Validates the metadata field for a manifest.

This method ensures that the metadata attribute is an instance of AbstractSAMMetadataBase. If a dictionary is provided, it will be coerced into an AbstractSAMMetadataBase object. This guarantees that the manifest metadata is always properly structured and validated.

Parameters:

v (dict or AbstractSAMMetadataBase) – The value of the metadata field to validate.

Returns:

The validated metadata object.

Return type:

AbstractSAMMetadataBase

class smarter.lib.manifest.models.AbstractSAMMetadataBase(*, name: str, description: str | None, version: str | None, tags: List[str] | None = <factory>, annotations: List[dict[str, str | int | float | bool | ~datetime.date | ~datetime.datetime | ~decimal.Decimal | ~uuid.UUID | bytes | list | dict]] | None=<factory>)[source]

Bases: SmarterBasePydanticModel, ABC

Abstract base class for manifest metadata in the Smarter API.

This class defines the required structure and validation logic for metadata associated with Smarter API manifests. It is designed to be subclassed by concrete manifest metadata classes, which may extend or customize the metadata fields as needed for specific resource types.

The AbstractSAMMetadataBase enforces strong typing and validation for core metadata fields, such as resource name, description, version, tags, and annotations. It ensures that all metadata adheres to expected formats and constraints, promoting consistency and reliability across all manifest definitions.

Subclasses should inherit from this class to implement metadata for their specific manifest types. This approach encourages code reuse, enforces validation, and provides a unified interface for working with manifest metadata throughout the Smarter API ecosystem.

Note

This class is abstract and should not be instantiated directly. Instead, create subclasses that define any additional fields or validation required for your manifest’s metadata.

annotations: List[dict[str, str | int | float | bool | date | datetime | Decimal | UUID | bytes | list | dict]] | None
classmethod coerce_annotations_to_list(v)[source]

Pre-validator to coerce stringified JSON lists to Python lists for annotations. This ensures that if the input is a string (e.g., ‘[{“key”: “value”}]’), it is parsed as a list before type validation.

description: str | None
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}

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

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Return type:

None

Parameters:

  • self – The BaseModel instance.

  • context – The context.

name: str
tags: List[str] | None
classmethod validate_annotations(v)[source]

Validates the annotations field for a manifest. Accepts a list of dicts, where each dict can be a single key-value pair or a flat dict with multiple key-value pairs. Supports multi-line string values (YAML block scalars). Ensures each annotation key is URL-friendly and each value is a string or scalar (including multi-line strings). Raises SAMValidationError if invalid.

Parameters:

v (Optional[List[dict[str, Any]]]) – The value of the annotations field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If any annotation is invalid.

Returns:

The validated list of annotations.

Return type:

Optional[List[dict[str, Union[str, int, float, bool, date, datetime, Decimal, UUID, bytes, list, dict]]]]

classmethod validate_description(v)[source]

Validates the description field for a manifest. This method ensures that the description attribute is present. If the value is missing, a SAMValidationError is raised.

Parameters:

v (str) – The value of the description field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If the value is missing.

Returns:

The validated description string.

Return type:

Optional[str]

classmethod validate_name(v)[source]

Validates the name field for a manifest.

Ensures the value is a string, present, and meets all constraints. Raises if not a string.

Return type:

str

classmethod validate_tags(v)[source]

Validates the tags field for a manifest. This method ensures that each tag in the tags list adheres to URL-friendly character rules. If any tag is invalid, a SAMValidationError is raised.

Parameters:

v (Optional[List[str]]) – The value of the tags field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If any tag is invalid.

Returns:

The validated list of tags.

Return type:

Optional[List[str]]

classmethod validate_version(v)[source]

Validates the version field for a manifest. This method ensures that the version attribute is present and follows semantic versioning rules. If the value is missing or invalid, a SAMValidationError is raised

Parameters:

v (str) – The value of the version field to validate.

Raises:

smarter.lib.manifest.exceptions.SAMValidationError – If the value is missing or invalid.

Returns:

The validated version string.

Return type:

Optional[str]

version: str | None
class smarter.lib.manifest.models.AbstractSAMSpecBase[source]

Bases: SmarterBasePydanticModel, ABC

Pydantic Spec base class. Expected to be subclassed by specific manifest classes.

model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}

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

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Return type:

None

Parameters:

  • self – The BaseModel instance.

  • context – The context.

class smarter.lib.manifest.models.AbstractSAMStatusBase(*, recordLocator: str, created: datetime, modified: datetime)[source]

Bases: SmarterBasePydanticModel, ABC

Pydantic Status base class. Expected to be subclassed by specific manifest classes.

created: datetime
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}

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

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Return type:

None

Parameters:

  • self – The BaseModel instance.

  • context – The context.

modified: datetime
recordLocator: str
class smarter.lib.manifest.models.SmarterBasePydanticModel[source]

Bases: BaseModel, SmarterHelperMixin

Smarter API Base Pydantic Model.

__init__(**data)[source]

Add support for passing a ‘user’ argument when initializing the model, which will be stored in a private attribute.

classmethod coerce_none_strings(data)[source]
model_config: ClassVar[ConfigDict] = {'arbitrary_types_allowed': True, 'from_attributes': True, 'frozen': True}

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

model_post_init(context, /)

This function is meant to behave like a BaseModel method to initialize private attributes.

It takes context as an argument since that’s what pydantic-core passes when calling it.

Return type:

None

Parameters:

  • self – The BaseModel instance.

  • context – The context.

property user: User | None

Get the user associated with this manifest, if any.

property user_profile: UserProfile | None

Get the user profile associated with this manifest, if any.

smarter.lib.manifest.models.VALID_ANNOTATION_VALUE_TYPES_SET = (<class 'str'>, <class 'int'>, <class 'float'>, <class 'bool'>, <class 'datetime.date'>, <class 'datetime.datetime'>, <class 'decimal.Decimal'>, <class 'uuid.UUID'>, <class 'bytes'>, <class 'list'>, <class 'dict'>)

Types allowed for annotation values in manifest metadata.

(
    <class 'str'>,
    <class 'int'>,
    <class 'float'>,
    <class 'bool'>,
    <class 'datetime.date'>,
    <class 'datetime.datetime'>,
    <class 'decimal.Decimal'>,
    <class 'uuid.UUID'>,
    <class 'bytes'>,
    <class 'list'>,
    <class 'dict'>,
)