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:
  # Options marked (images only) are used by `tesseract build` and ignored by
  # `Tesseract.from_source`.

  # Base image for the container, must be Ubuntu or Debian-based (images only)
  # base_image: "debian:bookworm-slim"

  # Platform to build the container for (images only). 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 (images only)
  # extra_packages:
  #  - package_name

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

  # Additional Dockerfile commands to run during the build process (images only)
  # 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. Most only apply to container images, but ``requirements``, ``build_env`` and ``inherit_base_image_packages`` also configure the environment that ``Tesseract.from_source`` builds."
      },
      "env": {
         "additionalProperties": {
            "type": "string"
         },
         "description": "Environment variables to set when serving the Tesseract. Rendered as ``ENV`` lines in the Dockerfile of container images, and passed to the process started by ``Tesseract.from_source``. Example: ``{XLA_PYTHON_CLIENT_PREALLOCATE: 'false'}``",
         "title": "Env",
         "type": "object"
      },
      "metadata": {
         "additionalProperties": true,
         "description": "Arbitrary user-defined metadata. In container images, this is 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 for the Tesseract's environment (e.g., '3.12'), installed via uv if needed. When unset, container images use the base image's system Python. ``Tesseract.from_source`` uses Python 3.11 to match the default base image, unless a ``pylock.toml`` lockfile's ``requires-python`` excludes it.",
               "title": "Python Version"
            },
            "requirements_file": {
               "default": "tesseract_requirements.txt",
               "description": "Name of the dependency file (a bare filename in the Tesseract source directory) to install from. Defaults to a flat ``tesseract_requirements.txt``. A PEP 751 lockfile (``pylock.toml`` or a ``pylock.*.toml`` variant) is also accepted, in which case dependencies are installed with pinned versions and hashes and no build-time resolution. Export one from a ``uv.lock`` with ``uv export --format pylock.toml``.",
               "title": "Requirements File",
               "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. Only applies to container images.",
               "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. Only applies to container images.",
               "title": "Target Platform",
               "type": "string"
            },
            "extra_packages": {
               "default": [],
               "description": "Extra packages to install during build via apt-get. Only applies to container images.",
               "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. Only applies to container images.",
               "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). Only applies to container images. Example: ``[\"RUN echo 'Hello, world!'\"]``",
               "title": "Custom Build Steps"
            },
            "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). With ``Tesseract.from_source``, the environment inherits the packages of the host Python instead. 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,
                  "requirements_file": "tesseract_requirements.txt"
               },
               "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. Only applies to container images. ``Tesseract.from_source`` installs with your own credentials.",
               "items": {
                  "$ref": "#/$defs/HostCredential"
               },
               "title": "Host Credentials",
               "type": "array"
            },
            "build_env": {
               "additionalProperties": {
                  "type": "string"
               },
               "description": "Environment variables to set while building the Tesseract's environment only (not in the final image or the served Tesseract). 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. Only applies to container images.",
               "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. Most only apply to container images, but requirements, build_env and inherit_base_image_packages also configure the environment that Tesseract.from_source builds.

Constraints:

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

field env: dict[Annotated[str, Strict(strict=True)], Annotated[str, Strict(strict=True)]] [Optional]¶: Environment variables to set when serving the Tesseract. Rendered as ENV lines in the Dockerfile of container images, and passed to the process started by Tesseract.from_source. Example: {XLA_PYTHON_CLIENT_PREALLOCATE: 'false'}

field metadata: dict[str, Any] [Optional]¶: Arbitrary user-defined metadata. In container images, this is 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. Only applies to container images.",
         "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. Only applies to container images.",
         "title": "Target Platform",
         "type": "string"
      },
      "extra_packages": {
         "default": [],
         "description": "Extra packages to install during build via apt-get. Only applies to container images.",
         "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. Only applies to container images.",
         "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). Only applies to container images. Example: ``[\"RUN echo 'Hello, world!'\"]``",
         "title": "Custom Build Steps"
      },
      "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). With ``Tesseract.from_source``, the environment inherits the packages of the host Python instead. 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,
            "requirements_file": "tesseract_requirements.txt"
         },
         "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. Only applies to container images. ``Tesseract.from_source`` installs with your own credentials.",
         "items": {
            "$ref": "#/$defs/HostCredential"
         },
         "title": "Host Credentials",
         "type": "array"
      },
      "build_env": {
         "additionalProperties": {
            "type": "string"
         },
         "description": "Environment variables to set while building the Tesseract's environment only (not in the final image or the served Tesseract). 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. Only applies to container images.",
         "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 for the Tesseract's environment (e.g., '3.12'), installed via uv if needed. When unset, container images use the base image's system Python. ``Tesseract.from_source`` uses Python 3.11 to match the default base image, unless a ``pylock.toml`` lockfile's ``requires-python`` excludes it.",
               "title": "Python Version"
            },
            "requirements_file": {
               "default": "tesseract_requirements.txt",
               "description": "Name of the dependency file (a bare filename in the Tesseract source directory) to install from. Defaults to a flat ``tesseract_requirements.txt``. A PEP 751 lockfile (``pylock.toml`` or a ``pylock.*.toml`` variant) is also accepted, in which case dependencies are installed with pinned versions and hashes and no build-time resolution. Export one from a ``uv.lock`` with ``uv export --format pylock.toml``.",
               "title": "Requirements File",
               "type": "string"
            }
         },
         "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)
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. Only applies to container images.

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. Only applies to container images.

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. Only applies to container images.

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. Only applies to container images.

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). Only applies to container images. Example: ["RUN echo 'Hello, world!'"]

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). With Tesseract.from_source, the environment inherits the packages of the host Python instead. Cannot be combined with python_version.

Validated by:

_validate_python_version_provider

field requirements: PipRequirements | CondaRequirements = PipRequirements(provider='uv-pip', python_version=None, requirements_file='tesseract_requirements.txt')¶

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. Only applies to container images. Tesseract.from_source installs with your own credentials.

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 while building the Tesseract’s environment only (not in the final image or the served Tesseract). 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. Only applies to container images.

Validated by:

_validate_python_version_provider

Configuration (tesseract_config.yaml)¶

Example file¶

Schema¶

Configuration (`tesseract_config.yaml`)¶