tesseract_runtime Python API

The tesseract_runtime Python module contains some useful utilities to create and extend tesseract_api.py files. It is available in all Tesseract container images.

class tesseract_core.runtime.Array(*args, **kwargs)

Generic Pydantic type annotation for a multi-dimensional array with a fixed shape and dtype.

Arrays will be broadcasted to the expected shape and dtype during validation, but dimensions must match exactly.

Polymorphic dimensions are supported by using None in the shape tuple. To indicate a scalar, use an empty tuple.

Arrays of any shape and rank can be represented by using … (ellipsis) as the shape.

Example

>>> class MyModel(BaseModel):
...     int_array: Array[(2, 3), Int32]
...     float_array: Array[(None, 3), Float64]
...     scalar_int: Array[(), Int16]
...     any_shape_array: Array[..., Float32]

You can serialize to (and validate from) different array encodings.

>>> model = MyModel(
...     int_array=np.array([[1, 2, 3], [4, 5, 6]]),
...     float_array=np.array([[1.0, 2.0, 3.0]]),
...     scalar_int=np.int32(42),
...     any_shape_array=np.array([True, False, True]).reshape(1, 1, 3),
... )

>>> model.model_dump_json(context={"array_encoding": "json"})

>>> model.model_dump_json(context={"array_encoding": "base64"})

or to binref:

>>> model.model_dump_json(
...     context={
...         "array_encoding": "binref",
...         "base_dir": "path/to/base",
...         "max_file_size": 10**8,
...     }
... )

In the ‘binref’ case you have to provide a base_dir to save/load binary (.bin) files. The .bin file(s) are written to context[‘base_dir’] / f”{context[‘__binref_uuid’]}.bin”. The ‘__binref_uuid’ is considered an internal variable and should not be modified manually! You can set a ‘max_file_size’ for the binary files. When this file size (in bytes) is reached, a new __binref_uuid (i.e. a new .bin) is created to append array data to.

class tesseract_core.runtime.Differentiable

Type annotation for a differentiable array.

Example

>>> class MyModel(BaseModel):
...     array: Differentiable[Array[(None, 3), Float64]]

pydantic model tesseract_core.runtime.ShapeDType

Data structure describing an array’s shape and data type.

Show JSON schema

{
   "title": "ShapeDType",
   "description": "Data structure describing an array's shape and data type.",
   "type": "object",
   "properties": {
      "shape": {
         "items": {
            "type": "integer"
         },
         "title": "Shape",
         "type": "array"
      },
      "dtype": {
         "enum": [
            "float16",
            "float32",
            "float64",
            "int8",
            "int16",
            "int32",
            "int64",
            "bool",
            "uint8",
            "uint16",
            "uint32",
            "uint64",
            "complex64",
            "complex128"
         ],
         "title": "Dtype",
         "type": "string"
      }
   },
   "required": [
      "shape",
      "dtype"
   ]
}

Config:

• extra: str = ignore

Fields:

• dtype (Literal['float16', 'float32', 'float64', 'int8', 'int16', 'int32', 'int64', 'bool', 'uint8', 'uint16', 'uint32', 'uint64', 'complex64', 'complex128'])

• shape (tuple[int, ...])

field dtype: Literal['float16', 'float32', 'float64', 'int8', 'int16', 'int32', 'int64', 'bool', 'uint8', 'uint16', 'uint32', 'uint64', 'complex64', 'complex128'] [Required]

field shape: tuple[int, ...] [Required]

classmethod from_array_annotation(obj)

Return type:

_AnnotatedAlias

class tesseract_core.runtime.Float16

Float16 scalar array. Equivalent to Array[(), Float16].

class tesseract_core.runtime.Float32

Float32 scalar array. Equivalent to Array[(), Float32].

class tesseract_core.runtime.Float64

Float64 scalar array. Equivalent to Array[(), Float64].

class tesseract_core.runtime.Int8

Int8 scalar array. Equivalent to Array[(), Int8].

class tesseract_core.runtime.Int16

Int16 scalar array. Equivalent to Array[(), Int16].

class tesseract_core.runtime.Int32

Int32 scalar array. Equivalent to Array[(), Int32].

class tesseract_core.runtime.Int64

Int64 scalar array. Equivalent to Array[(), Int64].

class tesseract_core.runtime.UInt8

UInt8 scalar array. Equivalent to Array[(), UInt8].

class tesseract_core.runtime.UInt16

UInt16 scalar array. Equivalent to Array[(), UInt16].

class tesseract_core.runtime.UInt32

UInt32 scalar array. Equivalent to Array[(), UInt32].

class tesseract_core.runtime.UInt64

UInt64 scalar array. Equivalent to Array[(), UInt64].

class tesseract_core.runtime.Bool

Bool scalar array. Equivalent to Array[(), Bool].

class tesseract_core.runtime.Complex64

Complex64 scalar array. Equivalent to Array[(), Complex64].

class tesseract_core.runtime.Complex128

Complex128 scalar array. Equivalent to Array[(), Complex128].

tesseract_core.runtime.experimental

The experimental namespace includes features that are under active development and may not be fully stable. Use these at your own risk, as APIs, behaviors, and implementations can change without notice, or be removed entirely in future releases.

class tesseract_core.runtime.experimental.LazySequence(keys, getter)

Lazy sequence type that loads items from a file handle on access.

This allows users to define a sequence of objects that are lazily loaded from a data source, and validated when accessed.

When used as a Pydantic annotation, lazy sequences accept either a list of objects or a glob pattern to load objects from a file path.

Example

>>> class MyModel(BaseModel):
...     objects: LazySequence[str]
>>> model = MyModel.model_validate({"objects": ["item1", "item2"]})
>>> model.objects[0]
'item1'
>>> model = MyModel.model_validate({"objects": "@/path/to/data/*.json"})
>>> model.objects[1]
'item2'