Configuration (`tesseract_config.yaml`)¶

The tesseract_config.yaml file contains a Tesseract’s metadata, such as its name, description, version, and build configuration.

Example file¶

name: "helloworld"
version: "1.0.0"
description: "A sample Python app"

build_config:
  # Base image to use for the container, must be Ubuntu or Debian-based
  # base_image: "debian:bookworm-slim"

  # Platform to build the container for. In general, images can only be executed
  # on the platform they were built for.
  # target_platform: "native"

  # Additional packages to install in the container (via apt-get)
  # extra_packages:
  #  - package_name

  # Data to copy into the container, relative to the project root
  # package_data:
  #  - [path/to/source, path/to/destination]

  # Additional Dockerfile commands to run during the build process
  # custom_build_steps:
  #  - |
  #   RUN echo "Hello, World!"

Schema¶

The TesseractConfig class is used to define the schema for the tesseract_config.yaml file. It contains the following fields:

pydantic model tesseract_core.sdk.api_parse.TesseractConfig[source]¶

Configuration options for Tesseracts. Defines valid options in tesseract_config.yaml.

Show JSON schema

{
   "title": "TesseractConfig",
   "description": "Configuration options for Tesseracts. Defines valid options in ``tesseract_config.yaml``.",
   "type": "object",
   "properties": {
      "name": {
         "description": "Name of the Tesseract.",
         "minLength": 1,
         "title": "Name",
         "type": "string"
      },
      "version": {
         "default": "unknown",
         "description": "Version of the Tesseract.",
         "maxLength": 128,
         "minLength": 1,
         "title": "Version",
         "type": "string"
      },
      "description": {
         "default": "",
         "description": "Free-text description of what the Tesseract does.",
         "title": "Description",
         "type": "string"
      },
      "build_config": {
         "$ref": "#/$defs/TesseractBuildConfig",
         "description": "Configuration options for building the Tesseract."
      },
      "env": {
         "additionalProperties": {
            "type": "string"
         },
         "description": "Environment variables to set in the Docker image. Rendered as ``ENV`` lines in the Dockerfile. Example: ``{XLA_PYTHON_CLIENT_PREALLOCATE: 'false'}``",
         "title": "Env",
         "type": "object"
      },
      "metadata": {
         "additionalProperties": true,
         "description": "Arbitrary user-defined metadata. This will be stored as a Docker label (ai.pasteurlabs.tesseract.metadata).",
         "title": "Metadata",
         "type": "object"
      }
   },
   "$defs": {
      "CondaRequirements": {
         "additionalProperties": false,
         "description": "Configuration options for Python environments built via conda.",
         "properties": {
            "provider": {
               "const": "conda",
               "title": "Provider",
               "type": "string"
            }
         },
         "required": [
            "provider"
         ],
         "title": "CondaRequirements",
         "type": "object"
      },
      "PipRequirements": {
         "additionalProperties": false,
         "description": "Configuration options for Python environments built via pip.",
         "properties": {
            "provider": {
               "const": "python-pip",
               "title": "Provider",
               "type": "string"
            }
         },
         "required": [
            "provider"
         ],
         "title": "PipRequirements",
         "type": "object"
      },
      "TesseractBuildConfig": {
         "additionalProperties": false,
         "description": "Configuration options for building a Tesseract.",
         "properties": {
            "base_image": {
               "default": "debian:bookworm-slim",
               "description": "Base Docker image for the build. Must be Debian-based.",
               "title": "Base Image",
               "type": "string"
            },
            "target_platform": {
               "default": "native",
               "description": "Target platform for the Docker build. Must be a valid Docker platform, or 'native' to build for the host platform. In general, images built for one platform will not run on another.",
               "title": "Target Platform",
               "type": "string"
            },
            "extra_packages": {
               "default": [],
               "description": "Extra packages to install during build via apt-get.",
               "items": {
                  "type": "string"
               },
               "title": "Extra Packages",
               "type": "array"
            },
            "package_data": {
               "anyOf": [
                  {
                     "items": {
                        "maxItems": 2,
                        "minItems": 2,
                        "prefixItems": [
                           {
                              "type": "string"
                           },
                           {
                              "type": "string"
                           }
                        ],
                        "type": "array"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": [],
               "description": "Additional files to copy into the Docker image, in the format ``(source, destination)``. Source paths are relative to the directory containing `tesseract_api.py`. Destination paths are relative or absolute paths within the Docker image (e.g., ``/app/shared_code.py``) and must be unique.",
               "title": "Package Data"
            },
            "custom_build_steps": {
               "anyOf": [
                  {
                     "items": {
                        "type": "string"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": [],
               "description": "Custom steps to run during ``docker build`` (after everything else is installed). Example: ``[\"RUN echo 'Hello, world!'\"]``",
               "title": "Custom Build Steps"
            },
            "python_version": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Python version to use inside the Tesseract (e.g., '3.12'). When set, ``uv python install`` is used to install the specified version, decoupling the Python version from the base image. When unset, the system Python from the base image is used.",
               "title": "Python Version"
            },
            "inherit_base_image_packages": {
               "default": false,
               "description": "If True, create the Python virtual environment with --system-site-packages so it inherits Python packages pre-installed in the base image (e.g. Firedrake, FEniCS, OpenFOAM). Cannot be combined with python_version.",
               "title": "Inherit Base Image Packages",
               "type": "boolean"
            },
            "requirements": {
               "anyOf": [
                  {
                     "$ref": "#/$defs/PipRequirements"
                  },
                  {
                     "$ref": "#/$defs/CondaRequirements"
                  }
               ],
               "default": {
                  "provider": "python-pip"
               },
               "title": "Requirements"
            },
            "skip_checks": {
               "default": false,
               "description": "If True, skip build-time checks of Tesseract API module. This can be useful when such a check cannot succeed (e.g. when building for a different platform), but may lead to runtime errors if the Tesseract API is not valid.",
               "title": "Skip Checks",
               "type": "boolean"
            }
         },
         "title": "TesseractBuildConfig",
         "type": "object"
      }
   },
   "additionalProperties": false,
   "required": [
      "name"
   ]
}

Fields:

build_config (tesseract_core.sdk.api_parse.TesseractBuildConfig)
description (str)
env (dict[str, str])
metadata (dict[str, Any])
name (str)
version (str)

Validators:

validate_version » version

field name: Annotated[str] [Required]¶

Name of the Tesseract.

Constraints:

min_length = 1
strict = True

field version: Annotated[str] = 'unknown'¶

Version of the Tesseract.

Constraints:

min_length = 1
max_length = 128
strict = True

Validated by:

validate_version

field description: Annotated[str] = ''¶

Free-text description of what the Tesseract does.

Constraints:

strict = True

field build_config: Annotated[TesseractBuildConfig] [Optional]¶

Configuration options for building the Tesseract.

Constraints:

func = <function <lambda> at 0x70ce6a9940e0>
json_schema_input_type = PydanticUndefined

field env: dict[Annotated[str], Annotated[str]] [Optional]¶: Environment variables to set in the Docker image. Rendered as ENV lines in the Dockerfile. Example: {XLA_PYTHON_CLIENT_PREALLOCATE: 'false'}

field metadata: dict[str, Any] [Optional]¶: Arbitrary user-defined metadata. This will be stored as a Docker label (ai.pasteurlabs.tesseract.metadata).

validator validate_version » version[source]¶

Validate that the version string is a valid semantic version.

Return type:: str

pydantic model tesseract_core.sdk.api_parse.TesseractBuildConfig[source]¶

Configuration options for building a Tesseract.

Show JSON schema

{
   "title": "TesseractBuildConfig",
   "description": "Configuration options for building a Tesseract.",
   "type": "object",
   "properties": {
      "base_image": {
         "default": "debian:bookworm-slim",
         "description": "Base Docker image for the build. Must be Debian-based.",
         "title": "Base Image",
         "type": "string"
      },
      "target_platform": {
         "default": "native",
         "description": "Target platform for the Docker build. Must be a valid Docker platform, or 'native' to build for the host platform. In general, images built for one platform will not run on another.",
         "title": "Target Platform",
         "type": "string"
      },
      "extra_packages": {
         "default": [],
         "description": "Extra packages to install during build via apt-get.",
         "items": {
            "type": "string"
         },
         "title": "Extra Packages",
         "type": "array"
      },
      "package_data": {
         "anyOf": [
            {
               "items": {
                  "maxItems": 2,
                  "minItems": 2,
                  "prefixItems": [
                     {
                        "type": "string"
                     },
                     {
                        "type": "string"
                     }
                  ],
                  "type": "array"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": [],
         "description": "Additional files to copy into the Docker image, in the format ``(source, destination)``. Source paths are relative to the directory containing `tesseract_api.py`. Destination paths are relative or absolute paths within the Docker image (e.g., ``/app/shared_code.py``) and must be unique.",
         "title": "Package Data"
      },
      "custom_build_steps": {
         "anyOf": [
            {
               "items": {
                  "type": "string"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "default": [],
         "description": "Custom steps to run during ``docker build`` (after everything else is installed). Example: ``[\"RUN echo 'Hello, world!'\"]``",
         "title": "Custom Build Steps"
      },
      "python_version": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Python version to use inside the Tesseract (e.g., '3.12'). When set, ``uv python install`` is used to install the specified version, decoupling the Python version from the base image. When unset, the system Python from the base image is used.",
         "title": "Python Version"
      },
      "inherit_base_image_packages": {
         "default": false,
         "description": "If True, create the Python virtual environment with --system-site-packages so it inherits Python packages pre-installed in the base image (e.g. Firedrake, FEniCS, OpenFOAM). Cannot be combined with python_version.",
         "title": "Inherit Base Image Packages",
         "type": "boolean"
      },
      "requirements": {
         "anyOf": [
            {
               "$ref": "#/$defs/PipRequirements"
            },
            {
               "$ref": "#/$defs/CondaRequirements"
            }
         ],
         "default": {
            "provider": "python-pip"
         },
         "title": "Requirements"
      },
      "skip_checks": {
         "default": false,
         "description": "If True, skip build-time checks of Tesseract API module. This can be useful when such a check cannot succeed (e.g. when building for a different platform), but may lead to runtime errors if the Tesseract API is not valid.",
         "title": "Skip Checks",
         "type": "boolean"
      }
   },
   "$defs": {
      "CondaRequirements": {
         "additionalProperties": false,
         "description": "Configuration options for Python environments built via conda.",
         "properties": {
            "provider": {
               "const": "conda",
               "title": "Provider",
               "type": "string"
            }
         },
         "required": [
            "provider"
         ],
         "title": "CondaRequirements",
         "type": "object"
      },
      "PipRequirements": {
         "additionalProperties": false,
         "description": "Configuration options for Python environments built via pip.",
         "properties": {
            "provider": {
               "const": "python-pip",
               "title": "Provider",
               "type": "string"
            }
         },
         "required": [
            "provider"
         ],
         "title": "PipRequirements",
         "type": "object"
      }
   },
   "additionalProperties": false
}

Fields:

base_image (str)
custom_build_steps (tuple[str, ...] | None)
extra_packages (tuple[str, ...])
inherit_base_image_packages (bool)
package_data (tuple[tuple[str, str], ...] | None)
python_version (str | None)
requirements (tesseract_core.sdk.api_parse.PipRequirements | tesseract_core.sdk.api_parse.CondaRequirements)
skip_checks (bool)
target_platform (str)

Validators:

_validate_python_version_provider » all fields

field base_image: Annotated[str] = 'debian:bookworm-slim'¶

Base Docker image for the build. Must be Debian-based.

Constraints:

strict = True

Validated by:

_validate_python_version_provider

field target_platform: Annotated[str] = 'native'¶

Target platform for the Docker build. Must be a valid Docker platform, or ‘native’ to build for the host platform. In general, images built for one platform will not run on another.

Constraints:

strict = True

Validated by:

_validate_python_version_provider

field extra_packages: tuple[Annotated[str], ...] = ()¶

Extra packages to install during build via apt-get.

Validated by:

_validate_python_version_provider

field package_data: tuple[tuple[Annotated[str], Annotated[str]], ...] | None = ()¶

Additional files to copy into the Docker image, in the format (source, destination). Source paths are relative to the directory containing tesseract_api.py. Destination paths are relative or absolute paths within the Docker image (e.g., /app/shared_code.py) and must be unique.

Validated by:

_validate_python_version_provider

field custom_build_steps: tuple[Annotated[str], ...] | None = ()¶

Custom steps to run during docker build (after everything else is installed). Example: ["RUN echo 'Hello, world!'"]

Validated by:

_validate_python_version_provider

field python_version: Optional[Annotated[str]] = None¶

Python version to use inside the Tesseract (e.g., ‘3.12’). When set, uv python install is used to install the specified version, decoupling the Python version from the base image. When unset, the system Python from the base image is used.

Validated by:

_validate_python_version_provider

field inherit_base_image_packages: bool = False¶

If True, create the Python virtual environment with –system-site-packages so it inherits Python packages pre-installed in the base image (e.g. Firedrake, FEniCS, OpenFOAM). Cannot be combined with python_version.

Validated by:

_validate_python_version_provider

field requirements: PipRequirements | CondaRequirements = PipRequirements(provider='python-pip')¶

Validated by:

_validate_python_version_provider

field skip_checks: bool = False¶

If True, skip build-time checks of Tesseract API module. This can be useful when such a check cannot succeed (e.g. when building for a different platform), but may lead to runtime errors if the Tesseract API is not valid.

Validated by:

_validate_python_version_provider

Configuration (tesseract_config.yaml)¶

Example file¶

Schema¶

Configuration (`tesseract_config.yaml`)¶