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"
      },
      "HostCredential": {
         "additionalProperties": false,
         "description": "Credentials for authenticating HTTPS access to a host during the build.\n\nThe credential is keyed by host and applies to everything fetched from that\nhost at build time -- package indices (``--extra-index-url``), PEP 508 direct\nreferences (``pkg @ https://host/...whl``), conda channels, and\n``git+https://host/...`` dependencies alike. The token is supplied\nout-of-band via a build secret and assembled into netrc and git-credential\nentries inside the build stage; it never lands in the config or an image layer.",
         "properties": {
            "host": {
               "description": "Host the credential authenticates against (e.g. ``pkgs.dev.azure.com`` or ``github.com``). Just the host, not a full URL.",
               "title": "Host",
               "type": "string"
            },
            "secret_id": {
               "description": "ID of the build secret carrying the token/password for this host, matching the ``id`` of a ``tesseract build --secret id=<id>,env=<VAR>`` (or ``,src=<file>``).",
               "title": "Secret Id",
               "type": "string"
            },
            "username": {
               "default": "__token__",
               "description": "Username paired with the secret. Defaults to ``__token__``, which suits PAT-style tokens; set it for hosts that require a real username.",
               "title": "Username",
               "type": "string"
            }
         },
         "required": [
            "host",
            "secret_id"
         ],
         "title": "HostCredential",
         "type": "object"
      },
      "PipRequirements": {
         "additionalProperties": false,
         "description": "Configuration options for Python environments built via uv.",
         "properties": {
            "provider": {
               "const": "uv-pip",
               "title": "Provider",
               "type": "string"
            },
            "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"
            }
         },
         "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": "Deprecated alias for ``build_config.requirements.python_version``. Kept for backwards compatibility; set the version under the provider settings instead. Removed in Tesseract 1.13.0.",
               "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": "uv-pip",
                  "python_version": null
               },
               "title": "Requirements"
            },
            "host_credentials": {
               "default": [],
               "description": "Credentials for authenticated hosts accessed during the build. Each entry maps a host to a build secret supplied out-of-band at build time (see ``HostCredential`` and ``tesseract build --secret``). Applies to package indices, direct-reference wheels, conda channels, and ``git+https`` dependencies on that host.",
               "items": {
                  "$ref": "#/$defs/HostCredential"
               },
               "title": "Host Credentials",
               "type": "array"
            },
            "build_env": {
               "additionalProperties": {
                  "type": "string"
               },
               "description": "Environment variables to set during the build stage only (not in the final image). Useful for configuring the package resolver, e.g. ``{UV_INDEX_STRATEGY: unsafe-best-match}``. Do not put secrets here: values are written into the build context. Use ``tesseract build --secret`` for credentials instead.",
               "title": "Build Env",
               "type": "object"
            },
            "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, Strict(strict=True)] [Required]¶

Name of the Tesseract.

Constraints:

min_length = 1
strict = True

field version: Annotated[str, Strict(strict=True)] = 'unknown'¶

Version of the Tesseract.

Constraints:

min_length = 1
max_length = 128
strict = True

Validated by:

validate_version

field description: Annotated[str, Strict(strict=True)] = ''¶

Free-text description of what the Tesseract does.

Constraints:

strict = True

field build_config: <lambda>, json_schema_input_type=PydanticUndefined)] [Optional]¶

Configuration options for building the Tesseract.

Constraints:

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

field env: dict[Annotated[str, Strict(strict=True)], Annotated[str, Strict(strict=True)]] [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": "Deprecated alias for ``build_config.requirements.python_version``. Kept for backwards compatibility; set the version under the provider settings instead. Removed in Tesseract 1.13.0.",
         "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": "uv-pip",
            "python_version": null
         },
         "title": "Requirements"
      },
      "host_credentials": {
         "default": [],
         "description": "Credentials for authenticated hosts accessed during the build. Each entry maps a host to a build secret supplied out-of-band at build time (see ``HostCredential`` and ``tesseract build --secret``). Applies to package indices, direct-reference wheels, conda channels, and ``git+https`` dependencies on that host.",
         "items": {
            "$ref": "#/$defs/HostCredential"
         },
         "title": "Host Credentials",
         "type": "array"
      },
      "build_env": {
         "additionalProperties": {
            "type": "string"
         },
         "description": "Environment variables to set during the build stage only (not in the final image). Useful for configuring the package resolver, e.g. ``{UV_INDEX_STRATEGY: unsafe-best-match}``. Do not put secrets here: values are written into the build context. Use ``tesseract build --secret`` for credentials instead.",
         "title": "Build Env",
         "type": "object"
      },
      "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"
      },
      "HostCredential": {
         "additionalProperties": false,
         "description": "Credentials for authenticating HTTPS access to a host during the build.\n\nThe credential is keyed by host and applies to everything fetched from that\nhost at build time -- package indices (``--extra-index-url``), PEP 508 direct\nreferences (``pkg @ https://host/...whl``), conda channels, and\n``git+https://host/...`` dependencies alike. The token is supplied\nout-of-band via a build secret and assembled into netrc and git-credential\nentries inside the build stage; it never lands in the config or an image layer.",
         "properties": {
            "host": {
               "description": "Host the credential authenticates against (e.g. ``pkgs.dev.azure.com`` or ``github.com``). Just the host, not a full URL.",
               "title": "Host",
               "type": "string"
            },
            "secret_id": {
               "description": "ID of the build secret carrying the token/password for this host, matching the ``id`` of a ``tesseract build --secret id=<id>,env=<VAR>`` (or ``,src=<file>``).",
               "title": "Secret Id",
               "type": "string"
            },
            "username": {
               "default": "__token__",
               "description": "Username paired with the secret. Defaults to ``__token__``, which suits PAT-style tokens; set it for hosts that require a real username.",
               "title": "Username",
               "type": "string"
            }
         },
         "required": [
            "host",
            "secret_id"
         ],
         "title": "HostCredential",
         "type": "object"
      },
      "PipRequirements": {
         "additionalProperties": false,
         "description": "Configuration options for Python environments built via uv.",
         "properties": {
            "provider": {
               "const": "uv-pip",
               "title": "Provider",
               "type": "string"
            },
            "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"
            }
         },
         "required": [
            "provider"
         ],
         "title": "PipRequirements",
         "type": "object"
      }
   },
   "additionalProperties": false
}

Fields:

base_image (str)
build_env (dict[str, str])
custom_build_steps (tuple[str, ...] | None)
extra_packages (tuple[str, ...])
host_credentials (tuple[tesseract_core.sdk.api_parse.HostCredential, ...])
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, Strict(strict=True)] = '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, Strict(strict=True)] = '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, Strict(strict=True)], ...] = ()¶

Extra packages to install during build via apt-get.

Validated by:

_validate_python_version_provider

field package_data: tuple[tuple[Annotated[str, AfterValidator(func=assert_relative_path)], Annotated[str, Strict(strict=True)]], ...] | 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, Strict(strict=True)], ...] | 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: Annotated[str, Strict(strict=True)] | None = None¶

Deprecated alias for build_config.requirements.python_version. Kept for backwards compatibility; set the version under the provider settings instead. Removed in Tesseract 1.13.0.

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='uv-pip', python_version=None)¶

Validated by:

_validate_python_version_provider

field host_credentials: tuple[HostCredential, ...] = ()¶

Credentials for authenticated hosts accessed during the build. Each entry maps a host to a build secret supplied out-of-band at build time (see HostCredential and tesseract build --secret). Applies to package indices, direct-reference wheels, conda channels, and git+https dependencies on that host.

Validated by:

_validate_python_version_provider

field build_env: dict[Annotated[str, Strict(strict=True)], Annotated[str, Strict(strict=True)]] [Optional]¶

Environment variables to set during the build stage only (not in the final image). Useful for configuring the package resolver, e.g. {UV_INDEX_STRATEGY: unsafe-best-match}. Do not put secrets here: values are written into the build context. Use tesseract build --secret for credentials instead.

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`)¶