tesseract_core Python API

class tesseract_core.Tesseract(url)[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.

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, input_path=None, output_path=None, output_format='json')[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.

  • 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 (Literal['json', 'json+base64', 'json+binref']) – Format to use for the output data.

Return type:

Tesseract

Returns:

A Tesseract instance.

classmethod from_tesseract_api(tesseract_api, input_path=None, output_path=None, output_format='json')[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.

  • output_format (Literal['json', 'json+base64', 'json+binref']) – Format to use for the output data.

Return type:

Tesseract

Returns:

A Tesseract instance.

classmethod from_url(url)[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.

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

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)[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.

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, input_path=None, output_path=None, output_format=None, output_file=None)[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.

  • 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.

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, input_path=None, output_path=None, output_format=None)[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.

  • 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.

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