pixano_inference.schemas.interface

How a deployed model is called: one descriptor per capability.

A capability's Input is the union of what every model of that capability might accept: a SAM2 video model reads keyframes while a ByteTrack model reads classes; Grounding DINO requires classes while a YOLO detector has its own class set. The capability alone does not tell a client how to call a given model, what to show in a model picker, or which class names a closed-vocabulary model knows. A model MAY describe itself with the descriptor of its capability (:attr:pixano_inference.models.InferenceModel.interface); the server publishes it as ModelStatusInfo.interface on GET /v1/models, None when the model declares none.

The descriptors are told apart on the wire by their capability field (:data:ModelInterface).

ModelInterface = Annotated[Union[TrackingInterface, DetectionInterface, SegmentationInterface, VLMInterface, EmbeddingInterface, NERInterface], Field(discriminator='capability')] module-attribute

The descriptor of a model, whichever its capability: a union told apart by capability.

Prompt = Literal['points', 'box', 'mask', 'text'] module-attribute

What a request may carry to name an object.

Threshold = Literal['box', 'text'] module-attribute

A confidence threshold a request may set.

DetectionInterface(**data)

Bases: _BaseModel

How a detection model is called.

Attributes:

Name	Type	Description
capability	Literal['detection']	Always "detection"; tells the descriptors apart on the wire.
classes	Literal['open', 'closed']	"open" when the model detects the class names the request gives (and requires them), "closed" when it has its own class set.
class_names	list[str] | None	The class set of a closed-vocabulary model, None otherwise.
thresholds	list[Threshold]	The confidence thresholds the model reads from the request.
outputs	list[Literal['box', 'score', 'class', 'mask']]	What each detection carries.

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"
            f'See the `model_validator` docs (https://pydantic.dev/docs/validation/{version_short()}/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

EmbeddingInterface(**data)

Bases: _BaseModel

How an embedding model is called.

Attributes:

Name	Type	Description
capability	Literal['embedding']	Always "embedding"; tells the descriptors apart on the wire.
modalities	list[Literal['image', 'text']]	What the model embeds. A model listing both maps them into one shared space.
dim	int | None	Dimensionality of the vectors, None when it is not known before a call.

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"
            f'See the `model_validator` docs (https://pydantic.dev/docs/validation/{version_short()}/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

ImageRange(**data)

Bases: _BaseModel

How many images a request may carry.

Attributes:

Name	Type	Description
min	int	The fewest images a request must carry.
max	int | None	The most images a request may carry; None when there is no limit.

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"
            f'See the `model_validator` docs (https://pydantic.dev/docs/validation/{version_short()}/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

NERInterface(**data)

Bases: _BaseModel

How a named entity recognition model is called.

Attributes:

Name	Type	Description
capability	Literal['ner']	Always "ner"; tells the descriptors apart on the wire.
entity_types	list[str] | None	The labels the model can return, None when they are not known.

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"
            f'See the `model_validator` docs (https://pydantic.dev/docs/validation/{version_short()}/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

SegmentationInterface(**data)

Bases: _BaseModel

How an image segmentation model is called.

Attributes:

Name	Type	Description
capability	Literal['segmentation']	Always "segmentation"; tells the descriptors apart on the wire.
prompts	list[Prompt]	What a request may carry to name what to segment. Empty for a model that segments without a prompt.
multimask	bool	Whether the model can return several candidate masks per prompt.
embeddings	bool	Whether the model returns the image embedding on request and accepts it back, so a client can re-prompt the same image without re-encoding it.
outputs	list[Literal['mask', 'score', 'logits']]	What a prediction carries.

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"
            f'See the `model_validator` docs (https://pydantic.dev/docs/validation/{version_short()}/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

TrackingInterface(**data)

Bases: _BaseModel

How a tracking model is called.

Attributes:

Name	Type	Description
capability	Literal['tracking']	Always "tracking"; tells the descriptors apart on the wire.
prompts	list[Prompt]	What a keyframe may carry to name an object. Empty for a model that takes no prompt.
prompt_free	bool	Whether the model accepts a request that names no object (tracking by detection: the model detects the objects and creates the tracks itself).
classes	Literal['none', 'open', 'closed']	"none" when the model has no notion of class, "open" when it detects the class names the request gives, "closed" when it has its own class set.
class_names	list[str] | None	The class set of a closed-vocabulary model, None otherwise.
thresholds	list[Threshold]	The confidence thresholds the model reads from the request.
interval	bool	Whether the model honours the propagation interval of the request.
outputs	list[Literal['mask', 'box', 'score', 'class']]	What each tracked object carries.

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"
            f'See the `model_validator` docs (https://pydantic.dev/docs/validation/{version_short()}/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )

VLMInterface(**data)

Bases: _BaseModel

How a vision-language model is called.

Attributes:

Name	Type	Description
capability	Literal['vlm']	Always "vlm"; tells the descriptors apart on the wire.
prompt	list[Literal['text', 'messages']]	The prompt forms the model accepts: a text string, or chat messages.
images	ImageRange	How many images a request may carry, in images or embedded in the messages.

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"
            f'See the `model_validator` docs (https://pydantic.dev/docs/validation/{version_short()}/concepts/validators/#model-validators) for more details.',
            stacklevel=2,
        )