`tesseract` 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)[source]¶

Run apply endpoint.

Parameters:: inputs (dict) – a dictionary with the inputs.
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, *, volumes=None, gpus=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 (str) – The Docker image to use.
volumes (list[str] | None) – List of volumes to mount.
gpus (list[str] | None) – List of GPUs to use.

Return type:

Tesseract

Returns:

A Tesseract instance.

classmethod from_tesseract_api(tesseract_api)[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.
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.

property input_schema: dict[source]¶

Get the input schema of this Tessseract.

Returns:: dictionary with the input schema.

jacobian(inputs, jac_inputs, jac_outputs)[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.

Return type:

dict

Returns:

dictionary with the results.

jacobian_vector_product(inputs, jvp_inputs, jvp_outputs, tangent_vector)[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.

Return type:

dict

Returns:

dictionary with the results.

property openapi_schema: dict[source]¶

Get the OpenAPI schema of this Tessseract.

Returns:: dictionary with the OpenAPI Schema.

property output_schema: dict[source]¶

Get the output schema of this Tessseract.

Returns:: dictionary with the output schema.

serve(port=None)[source]¶

Serve the Tesseract.

Parameters:: port (str | None) – Port to serve the Tesseract on.
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)[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.

Return type:

dict

Returns:

dictionary with the results.

tesseract_core.build_tesseract(src_dir, image_tag, build_dir=None, inject_ssh=False, config_override=(), 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 (tuple[tuple[list[str], str], ...]) – 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)[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.

Return type:

tuple[str, str]

Returns:

Tuple with the stdout and stderr of the Tesseract.

tesseract_core.serve(images, ports=None, volumes=None, gpus=None, debug=False)[source]¶

Serve one or more Tesseract images.

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

Parameters:

images (list[str]) – a list of Tesseract image IDs as strings.
ports (list[str] | None) – port or port range to serve each Tesseract on.
volumes (list[str] | None) – list of paths to mount in the Tesseract container.
gpus (list[str] | None) – IDs of host Nvidia GPUs to make available to the Tesseracts.
debug (bool) – whether to enable debug mode.

Return type:

str

Returns:

A string representing the Tesseract Project ID.

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

Teardown Tesseract image(s) running in a Docker Compose project.

Parameters:

project_ids (Sequence[str] | None) – List of Docker Compose project IDs to teardown.
tear_all (bool) – boolean flag to teardown all Tesseract projects.

Return type:

None

tesseract Python API¶

`tesseract` Python API¶