pixano_inference.configs.base

Core typed config classes and model params registry.

BaseModelParams(**data)

Bases: BaseModel

Base class for typed model parameters.

All models require at least a path (HuggingFace model ID or local checkpoint). Extra fields are forbidden so that typos are caught at config-creation time.

Attributes:

Name	Type	Description
path	str	HuggingFace model ID or local checkpoint path.

Source code in pydantic/main.py

def __init__(self, /, **data: Any) -> None:
    """Create a new model by parsing and validating input data from keyword arguments.

    Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
    validated to form a valid model.

    `self` is explicitly positional-only to allow `self` as a field name.
    """
    # `__tracebackhide__` tells pytest and some other tools to omit this function from tracebacks
    __tracebackhide__ = True
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
    if self is not validated_self:
        warnings.warn(
            'A custom validator is returning a value other than `self`.\n'
            "Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.\n"
            'See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

DeploymentConfig(**data)

Bases: BaseModel

User-facing deployment settings.

Merges resource, autoscaling, and batch settings into a single flat class for convenience in Python config files.

Attributes:

Name	Type	Description
num_gpus	float	Number of GPUs per replica.
num_cpus	float	Number of CPUs per replica.
memory_mb	int | None	Memory limit in MB.
min_replicas	int	Minimum number of replicas (0 for scale-to-zero).
max_replicas	int	Maximum number of replicas.
target_num_ongoing_requests_per_replica	int	Target ongoing requests per replica before scaling up.
downscale_delay_s	float	Delay in seconds before scaling down.
upscale_delay_s	float	Delay in seconds before scaling up.
max_batch_size	int	Maximum batch size for inference.
batch_wait_timeout_s	float	Timeout for waiting to fill batch.

Source code in pydantic/main.py

def __init__(self, /, **data: Any) -> None:
    """Create a new model by parsing and validating input data from keyword arguments.

    Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
    validated to form a valid model.

    `self` is explicitly positional-only to allow `self` as a field name.
    """
    # `__tracebackhide__` tells pytest and some other tools to omit this function from tracebacks
    __tracebackhide__ = True
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
    if self is not validated_self:
        warnings.warn(
            'A custom validator is returning a value other than `self`.\n'
            "Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.\n"
            'See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

ModelConfig(**data)

Bases: BaseModel

Full model configuration with typed validation.

This class resolves the model capability from the configured model class and resolves model_params through the ModelParamsRegistry when a schema is registered for the given model_class.

Accepts both strings and typed Python objects so config files can keep IDE support while still allowing concise string-based declarations.

Attributes:

Name	Type	Description
name	str | None	Unique model name. Optional for HuggingFace models (auto-derived from path).
model_class	str | type	Registered model class name or class type (e.g. "Sam2ImageModel" or Sam2ImageModel).
model_module	str | None	Python module path to import before resolving model_class.
model_params	dict[str, Any] | BaseModelParams	Typed params or raw dict, auto-resolved via registry.
deployment	DeploymentConfig	Deployment settings.

Source code in pydantic/main.py

def __init__(self, /, **data: Any) -> None:
    """Create a new model by parsing and validating input data from keyword arguments.

    Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
    validated to form a valid model.

    `self` is explicitly positional-only to allow `self` as a field name.
    """
    # `__tracebackhide__` tells pytest and some other tools to omit this function from tracebacks
    __tracebackhide__ = True
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
    if self is not validated_self:
        warnings.warn(
            'A custom validator is returning a value other than `self`.\n'
            "Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.\n"
            'See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

capability property

Capability derived from the configured model class.

model_class_name property

Registered name of the configured model class.

resolved_name property

Resolved deployment name for the configured model.

model_post_init(__context)

Resolve and validate the configured model class.

Source code in pixano_inference/configs/base.py

def model_post_init(self, __context: Any) -> None:
    """Resolve and validate the configured model class."""
    self._resolved_model_class = self._resolve_model_class()
    infer_http_capability(self._resolved_model_class)

to_deployment_config()

Convert to the internal ModelDeploymentConfig used by Ray Serve.

Returns:

Type	Description
ModelDeploymentConfig	A ModelDeploymentConfig instance.

Source code in pixano_inference/configs/base.py

def to_deployment_config(self) -> ModelDeploymentConfig:
    """Convert to the internal ``ModelDeploymentConfig`` used by Ray Serve.

    Returns:
        A ``ModelDeploymentConfig`` instance.
    """
    dep = self.deployment
    if isinstance(self.model_params, BaseModel):
        model_params = self.model_params.model_dump()
    else:
        model_params = self.model_params
    return ModelDeploymentConfig(
        name=self.resolved_name,
        capability=self.capability,
        model_class=self.model_class_name,
        model_module=self.model_module,
        model_params=model_params,
        resources=ResourceConfig(
            num_gpus=dep.num_gpus,
            num_cpus=dep.num_cpus,
            memory_mb=dep.memory_mb,
        ),
        autoscaling=AutoscalingConfig(
            min_replicas=dep.min_replicas,
            max_replicas=dep.max_replicas,
            target_num_ongoing_requests_per_replica=dep.target_num_ongoing_requests_per_replica,
            downscale_delay_s=dep.downscale_delay_s,
            upscale_delay_s=dep.upscale_delay_s,
        ),
        max_batch_size=dep.max_batch_size,
        batch_wait_timeout_s=dep.batch_wait_timeout_s,
    )

ModelParamsRegistry

Registry mapping model class names to their params Pydantic schemas.

This lightweight registry allows validation of model_params without importing heavy ML dependencies.

get(name) classmethod

Get the params schema for a model class, or None if not registered.

Parameters:

Name	Type	Description	Default
name	str	The model class name.	required

Returns:

Type	Description
type[BaseModelParams] | None	The params Pydantic model class, or None.

Source code in pixano_inference/configs/base.py

@classmethod
def get(cls, name: str) -> type[BaseModelParams] | None:
    """Get the params schema for a model class, or None if not registered.

    Args:
        name: The model class name.

    Returns:
        The params Pydantic model class, or None.
    """
    return cls._registry.get(name)

has(name) classmethod

Check if a params schema is registered.

Parameters:

Name	Type	Description	Default
name	str	The model class name.	required

Returns:

Type	Description
bool	True if registered.

Source code in pixano_inference/configs/base.py

@classmethod
def has(cls, name: str) -> bool:
    """Check if a params schema is registered.

    Args:
        name: The model class name.

    Returns:
        True if registered.
    """
    return name in cls._registry

list_all() classmethod

List all registered params schemas.

Returns:

Type	Description
dict[str, type[BaseModelParams]]	Dictionary of model class name to params schema.

Source code in pixano_inference/configs/base.py

@classmethod
def list_all(cls) -> dict[str, type[BaseModelParams]]:
    """List all registered params schemas.

    Returns:
        Dictionary of model class name to params schema.
    """
    return cls._registry.copy()

register(name) classmethod

Decorator to register a params schema for a model class.

Parameters:

Name	Type	Description	Default
name	str	The model class name (e.g. "Sam2ImageModel").	required

Returns:

Type	Description
Callable[[type[BaseModelParams]], type[BaseModelParams]]	The decorator function.

Source code in pixano_inference/configs/base.py

@classmethod
def register(cls, name: str) -> Callable[[type[BaseModelParams]], type[BaseModelParams]]:
    """Decorator to register a params schema for a model class.

    Args:
        name: The model class name (e.g. ``"Sam2ImageModel"``).

    Returns:
        The decorator function.
    """

    def decorator(params_cls: type[BaseModelParams]) -> type[BaseModelParams]:
        if name in cls._registry:
            raise ValueError(f"Model params schema '{name}' already registered.")
        cls._registry[name] = params_cls
        return params_cls

    return decorator

ServerConfig(**data)

Bases: BaseModel

Top-level typed server configuration.

Attributes:

Name	Type	Description
host	str	Host to bind to.
port	int	Port to serve on.
num_cpus	int | None	Total CPUs available to Ray. None means auto-detect.
num_gpus	int | None	Total GPUs available to Ray. None means auto-detect.
pip_packages	list[str] | None	Pip packages for Ray workers runtime environment.
working_dir	str | None	Working directory for Ray workers.
models	list[ModelConfig]	List of model configurations.

Source code in pydantic/main.py

def __init__(self, /, **data: Any) -> None:
    """Create a new model by parsing and validating input data from keyword arguments.

    Raises [`ValidationError`][pydantic_core.ValidationError] if the input data cannot be
    validated to form a valid model.

    `self` is explicitly positional-only to allow `self` as a field name.
    """
    # `__tracebackhide__` tells pytest and some other tools to omit this function from tracebacks
    __tracebackhide__ = True
    validated_self = self.__pydantic_validator__.validate_python(data, self_instance=self)
    if self is not validated_self:
        warnings.warn(
            'A custom validator is returning a value other than `self`.\n'
            "Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.\n"
            'See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

to_ray_serve_config()

Convert to the internal RayServeConfig.

Returns:

Type	Description
RayServeConfig	A RayServeConfig instance with all models converted.

Source code in pixano_inference/configs/base.py

def to_ray_serve_config(self) -> RayServeConfig:
    """Convert to the internal ``RayServeConfig``.

    Returns:
        A ``RayServeConfig`` instance with all models converted.
    """
    return RayServeConfig(
        host=self.host,
        port=self.port,
        num_cpus=self.num_cpus,
        num_gpus=self.num_gpus,
        pip_packages=self.pip_packages,
        working_dir=self.working_dir,
        models=[m.to_deployment_config() for m in self.models],
    )

register_model_params(name)

Convenience decorator for registering model params schemas.

Parameters:

Name	Type	Description	Default
name	str	The model class name to register under.	required

Returns:

Type	Description
Callable[[type[BaseModelParams]], type[BaseModelParams]]	The decorator function.

Source code in pixano_inference/configs/base.py

def register_model_params(name: str) -> Callable[[type[BaseModelParams]], type[BaseModelParams]]:
    """Convenience decorator for registering model params schemas.

    Args:
        name: The model class name to register under.

    Returns:
        The decorator function.
    """
    return ModelParamsRegistry.register(name)