Python API (tesseract_core)

class tesseract_core.Tesseract(url, server_output_path=None, timeout=None)[source]

A Tesseract.

This class represents a single Tesseract instance, either remote or local, and provides methods to run commands on it and retrieve results.

Communication between a Tesseract and this class is done either via HTTP requests or directly via Python calls to the Tesseract API.

abstract_eval(abstract_inputs)[source]

Run abstract eval endpoint.

Parameters:

abstract_inputs (dict) – a dictionary with the (abstract) inputs.

Return type:

dict

Returns:

dictionary with the results.

apply(inputs, run_id=None)[source]

Run apply endpoint.

Parameters:

  • inputs (dict) – a dictionary with the inputs.

  • run_id (str | None) – a string to identify the run. Run outputs will be located in a directory suffixed with this id.

Return type:

dict

Returns:

dictionary with the results.

property available_endpoints: list[str]

Get the list of available endpoints.

Returns:

a list with all available endpoints for this Tesseract.

container_info()[source]

Retrieve information on the Docker container serving this Tesseract.

Tesseract must be created via from_image and be actively served for this to be available.

Raises:
Return type:

Container

classmethod from_image(image_name, *, host_ip='127.0.0.1', port=None, network=None, network_alias=None, volumes=None, environment=None, gpus=None, num_workers=1, user=None, memory=None, input_path=None, output_path=None, output_format='json+base64', docker_args=None, runtime_config=None, stream_logs=False, skip_health_check=False, timeout=None)[source]

Create a Tesseract instance from a Docker image.

When using this method, the Tesseract will be spawned in a Docker container, serving the Tesseract API via HTTP. To use the Tesseract, you need to call the serve method or use it as a context manager.

Example

>>> with Tesseract.from_image("my_tesseract") as t:
...    # Use tesseract here

This will automatically teardown the Tesseract when exiting the context manager.

Parameters:

  • image_name (str) – Tesseract image name to serve.

  • host_ip (str) – IP address to bind the Tesseracts to.

  • port (str | None) – port or port range to serve each Tesseract on.

  • network (str | None) – name of the network the Tesseract will be attached to.

  • network_alias (str | None) – alias to use for the Tesseract within the network.

  • volumes (list[str] | None) – list of paths to mount in the Tesseract container.

  • environment (dict[str, str] | None) – dictionary of environment variables to pass to the Tesseract.

  • gpus (list[str] | None) – IDs of host Nvidia GPUs to make available to the Tesseracts.

  • num_workers (int) – number of workers to use for serving the Tesseracts.

  • user (str | None) – user to run the Tesseracts as, e.g. ‘1000’ or ‘1000:1000’ (uid:gid). Defaults to the current user.

  • memory (str | None) – Memory limit for the container (e.g., “512m”, “2g”). Minimum allowed is 6m.

  • input_path (str | Path | None) – Input path to read input files from, such as local directory or S3 URI.

  • output_path (str | Path | None) – Output path to write output files to, such as local directory or S3 URI. Required when using json+binref output format.

  • output_format (Literal['json', 'json+base64', 'json+binref']) – Format to use for the output data. json+binref requires output_path to be set. This has no impact on what is returned to Python and only affects the format that is used internally.

  • docker_args (list[str] | None) – Additional arguments to pass to the container runtime (e.g., Docker).

  • runtime_config (dict[str, Any] | None) – Dictionary of runtime configuration options to pass to the Tesseract. These are converted to TESSERACT_* environment variables. For example, {“profiling”: True} enables profiling via TESSERACT_PROFILING=true.

  • stream_logs (bool | Callable[[str], Any]) – If True, stream logs to stdout while endpoints run. If a callable, stream logs to that callable instead.

  • skip_health_check (bool) – If True, skip the startup health check poll. Useful for Tesseracts with slow initialization (e.g., Julia runtime startup, large model loading). The caller is responsible for ensuring readiness, e.g. by calling health(), before calling other endpoints.

  • timeout (float | tuple[float, float] | None) – Request timeout in seconds for HTTP calls to the Tesseract. Can be a float for both connect and read timeouts, or a (connect, read) tuple for separate control. None (the default) disables timeouts. See the requests documentation for details.

Return type:

Tesseract

Returns:

A Tesseract instance.

classmethod from_tesseract_api(tesseract_api, input_path=None, output_path=None, output_format='json+base64', runtime_config=None, stream_logs=False)[source]

Create a Tesseract instance from a Tesseract API module.

Warning: This does not use a containerized Tesseract, but rather imports the Tesseract API directly. This is useful for debugging, but requires a matching runtime environment + all dependencies to be installed locally.

Parameters:

  • tesseract_api (str | Path | ModuleType) – Path to the tesseract_api.py file, or an already imported Tesseract API module.

  • input_path (Path | None) – Path of input directory. All paths in the tesseract payload have to be relative to this path.

  • output_path (Path | None) – Path of output directory. All paths in the tesseract result with be given relative to this path. Required when using json+binref.

  • output_format (Literal['json', 'json+base64', 'json+binref']) – Format to use for the output data. json+binref requires output_path. This has no impact on what is returned to Python and only affects the format that is used internally.

  • runtime_config (dict[str, Any] | None) – Dictionary of runtime configuration options to pass to the Tesseract. For example, {“profiling”: True} enables profiling.

  • stream_logs (bool | Callable[[str], Any]) – If True, stream logs to stdout while endpoints run. If a callable, stream logs to that callable instead.

Return type:

Tesseract

Returns:

A Tesseract instance.

classmethod from_url(url, server_output_path=None, timeout=None)[source]

Create a Tesseract instance from a URL.

This is useful for connecting to a remote Tesseract instance.

Parameters:

  • url (str) – The URL of the Tesseract instance.

  • server_output_path (str | Path | None) – Path where binary output files are stored when using json+binref. Required when the Tesseract is served with –output-format=json+binref. Must be a path accessible from the client machine (e.g., via a shared or mounted filesystem), since the server writes .bin files there and the client reads them from the same path.

  • timeout (float | tuple[float, float] | None) –

    Request timeout in seconds. Can be a float for both connect and read timeouts, or a (connect, read) tuple for separate control. None (the default) disables timeouts. See the requests documentation for details.

Return type:

Tesseract

Returns:

A Tesseract instance.

health()[source]

Check the health of the Tesseract.

Return type:

dict

Returns:

dictionary with the health status.

jacobian(inputs, jac_inputs, jac_outputs, run_id=None)[source]

Calculate the Jacobian of (some of the) outputs w.r.t. (some of the) inputs.

Parameters:

  • inputs (dict) – a dictionary with the inputs.

  • jac_inputs (list[str]) – Inputs with respect to which derivatives will be calculated.

  • jac_outputs (list[str]) – Outputs which will be differentiated.

  • run_id (str | None) – a string to identify the run. Run outputs will be located in a directory suffixed with this id.

Return type:

dict

Returns:

dictionary with the results.

jacobian_vector_product(inputs, jvp_inputs, jvp_outputs, tangent_vector, run_id=None)[source]

Calculate the Jacobian Vector Product (JVP) of (some of the) outputs w.r.t. (some of the) inputs.

Parameters:

  • inputs (dict) – a dictionary with the inputs.

  • jvp_inputs (list[str]) – Inputs with respect to which derivatives will be calculated.

  • jvp_outputs (list[str]) – Outputs which will be differentiated.

  • tangent_vector (dict) – Element of the tangent space to multiply with the Jacobian.

  • run_id (str | None) – a string to identify the run. Run outputs will be located in a directory suffixed with this id.

Return type:

dict

Returns:

dictionary with the results.

property openapi_schema: dict[source]

Get the OpenAPI schema of this Tesseract.

Returns:

dictionary with the OpenAPI Schema.

serve()[source]

Serve the Tesseract until it is stopped.

Return type:

None

server_logs()[source]

Get the logs of the Tesseract server.

Return type:

str

Returns:

logs of the Tesseract server.

teardown()[source]

Teardown the Tesseract.

This will stop and remove the Tesseract container.

Return type:

None

test(test_spec)[source]

Run a regression test, raising AssertionError on failure.

Works in LocalClient, HTTPClient and remote if served in debug mode.

Parameters:

  • test_spec (dict) – Test specification dict with keys: - endpoint: Name of endpoint (e.g., “apply”, “jacobian”) - payload: Input data dict - expected_outputs: Expected output data dict (if no exception expected) - expected_exception: Optional exception type or name (e.g., ValueError or “ValueError”) - expected_exception_regex: Optional regex pattern for exception message - atol: Optional absolute tolerance (default 1e-8) - rtol: Optional relative tolerance (default 1e-5)

  • expected_exception. (Must provide exactly one of expected_outputs or)

Raises:

  • AssertionError – If test fails (outputs don’t match or wrong exception)

  • RuntimeError – If test encounters unexpected error

Return type:

None

Example

>>> tess = Tesseract.from_tesseract_api("path/to/tesseract_api.py")
>>> tess.test(
...     {
...         "endpoint": "apply",
...         "payload": {"a": [1, 2], "b": [3, 4]},
...         "expected_outputs": {"result": [4, 6]},
...     }
... )
vector_jacobian_product(inputs, vjp_inputs, vjp_outputs, cotangent_vector, run_id=None)[source]

Calculate the Vector Jacobian Product (VJP) of (some of the) outputs w.r.t. (some of the) inputs.

Parameters:

  • inputs (dict) – a dictionary with the inputs.

  • vjp_inputs (list[str]) – Inputs with respect to which derivatives will be calculated.

  • vjp_outputs (list[str]) – Outputs which will be differentiated.

  • cotangent_vector (dict) – Element of the cotangent space to multiply with the Jacobian.

  • run_id (str | None) – a string to identify the run. Run outputs will be located in a directory suffixed with this id.

Return type:

dict

Returns:

dictionary with the results.

tesseract_core.build_tesseract(src_dir, image_tag, build_dir=None, inject_ssh=False, config_override=None, generate_only=False, stream_logs=False)[source]

Build a new Tesseract from a context directory.

Parameters:

  • src_dir (str | Path) – path to the Tesseract project directory, where the tesseract_api.py and tesseract_config.yaml files are located.

  • image_tag (str | None) – name to be used as a tag for the Tesseract image.

  • build_dir (Path | None) – directory to be used to store the build context. If not provided, a temporary directory will be created.

  • inject_ssh (bool) – whether or not to forward SSH agent when building the image.

  • config_override (dict[tuple[str, ...], Any] | None) – overrides for configuration options in the Tesseract.

  • generate_only (bool) – only generate the build context but do not build the image.

  • stream_logs (Callable[[str], Any] | bool) – if True, stream build logs to stderr. If a callable is provided, it will be called with each log line.

Return type:

Image | Path

Returns:

Image object representing the built Tesseract image, or path to build directory if generate_only is True.

tesseract_core.run_tesseract(image, command, args, volumes=None, gpus=None, ports=None, environment=None, network=None, user=None, memory=None, input_path=None, output_path=None, output_format=None, output_file=None, docker_args=None, stream_logs=False)[source]

Start a Tesseract and execute a given command.

Parameters:

  • image (str) – string of the Tesseract to run.

  • command (str) – Tesseract command to run, e.g. “apply”.

  • args (list[str]) – arguments for the command.

  • volumes (list[str] | None) – list of paths to mount in the Tesseract container.

  • gpus (list[int | str] | None) – list of GPUs, as indices or names, to passthrough the container.

  • ports (dict[str, str] | None) – dictionary of ports to bind to the host. Key is the host port, value is the container port.

  • environment (dict[str, str] | None) – list of environment variables to set in the container, in Docker format: key=value.

  • network (str | None) – name of the Docker network to connect the container to.

  • user (str | None) – user to run the Tesseract as, e.g. ‘1000’ or ‘1000:1000’ (uid:gid). Defaults to the current user.

  • memory (str | None) – Memory limit for the container (e.g., “512m”, “2g”). Minimum allowed is 6m.

  • input_path (str | Path | None) – Input path to read input files from, such as local directory or S3 URI.

  • output_path (str | Path | None) – Output path to write output files to, such as local directory or S3 URI.

  • output_format (Optional[Literal['json', 'json+base64', 'json+binref']]) – Format of the output.

  • output_file (str | None) – If specified, the output will be written to this file within output_path instead of stdout.

  • docker_args (list[str] | None) – Additional arguments to pass to the container runtime (e.g., Docker).

  • stream_logs (bool | Callable[[str], None]) – If set, stream logs in real-time. Can be True (streams to stderr) or a callable that accepts a string (e.g., logger.info).

Return type:

tuple[str, str]

Returns:

Tuple with the stdout and stderr of the Tesseract.

tesseract_core.serve(image_name, *, host_ip='127.0.0.1', port=None, network=None, network_alias=None, volumes=None, environment=None, gpus=None, debug=False, num_workers=1, user=None, memory=None, input_path=None, output_path=None, output_format=None, docker_args=None, runtime_config=None, skip_health_check=False)[source]

Serve one or more Tesseract images.

Start the Tesseracts listening on an available ports on the host.

Parameters:

  • image_name (str) – Tesseract image name to serve.

  • host_ip (str) – IP address to bind the Tesseracts to.

  • port (str | None) – port or port range to serve each Tesseract on.

  • network (str | None) – name of the network the Tesseract will be attached to.

  • network_alias (str | None) – alias to use for the Tesseract within the network.

  • volumes (list[str] | None) – list of paths to mount in the Tesseract container.

  • environment (dict[str, str] | None) – dictionary of environment variables to pass to the Tesseract.

  • gpus (list[str] | None) – IDs of host Nvidia GPUs to make available to the Tesseracts.

  • debug (bool) – Enable debug mode. This will propagate full tracebacks to the client and start a debugpy server in the Tesseract. WARNING: This may expose sensitive information, use with caution (and never in production).

  • num_workers (int) – number of workers to use for serving the Tesseracts.

  • user (str | None) – user to run the Tesseracts as, e.g. ‘1000’ or ‘1000:1000’ (uid:gid). Defaults to the current user.

  • memory (str | None) – Memory limit for the container (e.g., “512m”, “2g”). Minimum allowed is 6m.

  • input_path (str | Path | None) – Input path to read input files from, such as local directory or S3 URI.

  • output_path (str | Path | None) – Output path to write output files to, such as local directory or S3 URI.

  • output_format (Optional[Literal['json', 'json+base64', 'json+binref']]) – Output format to use for the results.

  • docker_args (list[str] | None) – Additional arguments to pass to the container runtime (e.g., Docker).

  • runtime_config (dict[str, Any] | None) – Dictionary of runtime configuration options to pass to the Tesseract. These are converted to TESSERACT_* environment variables. For example, {"profiling": True} sets TESSERACT_PROFILING=1.

  • skip_health_check (bool) – If True, skip the startup health check poll. Useful for Tesseracts with slow initialization (e.g., Julia runtime startup, large model loading). The caller is responsible for ensuring readiness, e.g. by polling /health, before calling other endpoints.

Return type:

tuple

Returns:

A tuple of the Tesseract container name and the port it is serving on.

tesseract_core.teardown(container_ids=None, tear_all=False)[source]

Teardown Tesseract container(s).

Parameters:

  • container_ids (Collection[str] | None) – List of container IDs to teardown.

  • tear_all (bool) – boolean flag to teardown all Tesseract containers.

Return type:

None