Python API (`tesseract_core`)¶

class tesseract_core.Tesseract(*args, **kwargs)[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:

RuntimeError – if this Tesseract was not created via from_image() (e.g. from_url() or from_tesseract_api()), or if it is not currently being served (call serve() or use with tess: first).
tesseract_core.sdk.docker_client.NotFound – if the container disappeared between serve() and this call.

Return type:

Container

property current_encoding: RequestedEncoding¶

The encoding calls through this Tesseract request.

The options this Tesseract was created with, overridden by those of with_encoding() for a view (see RequestedEncoding for what None means). To find out which GPU transport to use for GPU arrays, see resolve_gpu_transport().

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', gpu_transport=None, docker_args=None, runtime_config=None, stream_logs=False, skip_health_check=False, startup_timeout=30.0, timeout=None, experimental_binref_pool=False)[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.
gpu_transport (str | None) – GPU transport to enable on the served Tesseract and use for this client’s calls (see with_encoding() to change it per call). none copies GPU arrays to the host, and cuda_ipc passes them by reference, which requires the container to have GPU access and num_workers=1. Independent of output_format, which governs CPU arrays. Resolved against runtime_config with the precedence described in engine.serve.
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.
startup_timeout (float) – How long to wait, in seconds, for the Tesseract to answer a health check. Raise it for one that is slow to initialize, in preference to skipping the check altogether.
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.
experimental_binref_pool (bool) – Opt-in fast path for json+binref that only makes sense when input_path and output_path point at a shared-memory tmpfs (/dev/shm on Linux). Reuses a small pool of pre-faulted, memory-mapped input buffers instead of writing a fresh file per request, and decodes outputs as zero-copy memory-mapped views instead of eager copies. Linux only (raises on other platforms), since elsewhere the container runs in a VM and does not share a page cache with the client.

Return type:

Tesseract

Returns:

A Tesseract instance.

classmethod from_source(tesseract_api, input_path=None, output_path=None, output_format='json+base64', gpu_transport=None, runtime_config=None, stream_logs=False, python_executable=None, startup_timeout=30.0, experimental_binref_pool=False)[source]¶

Create a Tesseract instance from a Tesseract API file, in its own process.

The Tesseract is served by a dedicated tesseract-runtime serve subprocess and reached over HTTP, so it does not share an interpreter, global state or signal handlers with the caller. That matters when sharing them is unsafe (e.g. nesting JAX inside JAX can deadlock) and it lets the Tesseract run in a different environment than the caller (e.g. with conflicting dependencies).

Unlike from_tesseract_api(), which imports the API into this process, this must be used as a context manager or served explicitly, since there is a process to clean up:

>>> with Tesseract.from_source("tesseract_api.py") as tess:
...     tess.apply({"a": 1})

The Tesseract is not isolated the way a container would be. It inherits this process’s environment, working directory, filesystem access and user.

Parameters:

tesseract_api (str | Path) – Path to the tesseract_api.py file. Unlike from_tesseract_api(), an already imported module cannot be used, since it cannot be shared with another process.
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.
gpu_transport (str | None) – GPU transport to enable on the served Tesseract and use for this client’s calls (see with_encoding() to change it per call). none copies GPU arrays to the host, and cuda_ipc passes them by reference, which needs no setup since processes on one host share an IPC namespace. Independent of output_format, which governs CPU arrays. Resolved against runtime_config, an explicit value winning.
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.
python_executable (str | Path | None) – Interpreter to run the Tesseract on. It must have tesseract-core[runtime] and the Tesseract’s requirements installed; pass sys.executable to use the SDK’s own environment. If None, an environment is built from tesseract_config.yaml into .tesseract-venv next to the tesseract_api.py and reused while its requirements are unchanged. This needs uv, or conda for requirements.provider: conda.
startup_timeout (float) – How long to wait, in seconds, for the Tesseract to become healthy before giving up.
experimental_binref_pool (bool) – Opt-in fast path for json+binref that reuses warm memory-mapped buffers instead of allocating a file per call. Only pays off when the binref directory is memory-backed (a tmpfs) and has been observed to negatively affect ordinary disk-backed json+binref on occasion. See Fast same-machine runs with shared-memory binref.

Return type:

Tesseract

Returns:

A Tesseract instance.

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

Create a Tesseract instance from a Tesseract API module.

Unlike from_source() and from_image(), this imports the Tesseract API into the calling process. This is useful for debugging, but requires tesseract-core[runtime] and all of the Tesseract’s dependencies to be installed in the calling environment.

Note: Uses a thread lock internally, so concurrent calls to Tesseracts created via from_tesseract_api will always run sequentially.

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.
gpu_transport (str | None) – Whether the endpoints accept GPU arrays, which only integrations that pass GPU arrays act on (see resolve_gpu_transport()). none means they get GPU inputs copied to the host, and any other transport (such as cuda_ipc) means they get them as they are. Resolved against runtime_config with the precedence described in engine.serve.
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¶

Get the OpenAPI schema of this Tesseract.

Returns:: dictionary with the OpenAPI Schema.

resolve_gpu_transport()[source]¶

Get the GPU transport that calls through this Tesseract should use for GPU arrays.

Integrations that pass GPU arrays, such as Tesseract-JAX and Tesseract-Torch, use this to keep GPU arrays on the device whenever that works and copy them to the host otherwise:

>>> transport = tess.resolve_gpu_transport()
>>> tess.with_encoding(gpu_transport=transport).apply(gpu_inputs)

A GPU transport this Tesseract requests, through with_encoding() or the gpu_transport it was created with, is returned once it is known to work. Otherwise this returns the first transport the server offers that works from this process, in the SDK’s order of preference (which currently holds only cuda_ipc), and none otherwise, with a warning for each offered transport that does not work.

Whether a transport works depends on how both processes are set up (cuda_ipc, for example, needs one host and a GPU visible to both), so it is found out by exchanging a small GPU array with the server once per connection.

In-process Tesseracts created via from_tesseract_api() return the gpu_transport they were created with unless a view requests none.

Return type:

str

Returns:

none, or the name of the GPU transport to use.

Raises:

ValueError – if the requested transport is not enabled on this Tesseract.
RuntimeError – if the requested transport does not work from this process, or the Tesseract answers the exchange with an error.

serve()[source]¶

Serve the Tesseract until it is stopped.

Return type:: None

property server_capabilities: ServerCapabilities | None¶

The encodings this Tesseract’s server accepts, read from its OpenAPI schema.

A listed value can still fail for reasons the server cannot know about. For example, cuda_ipc requires client and server to share a host and a GPU.

Returns:: the advertised capabilities, or None for in-process Tesseracts created via from_tesseract_api(), which do not serialize arrays.

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, or stop the dedicated process serving it.

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.

with_encoding(*, output_format=None, gpu_transport=None, compression=None)[source]¶

Get a view of this Tesseract that requests a different encoding.

The view shares this Tesseract’s connection and stays usable while this Tesseract is served. It only calls endpoints, so serving, logs and container info stay with this Tesseract. Arguments left as None keep this Tesseract’s setting.

>>> with Tesseract.from_image(
...     "my_tesseract", gpu_transport="cuda_ipc"
... ) as t:
...     t.with_encoding(gpu_transport="none").apply(inputs)

In-process Tesseracts created via from_tesseract_api() pass arrays in memory, so only gpu_transport affects them. It is what resolve_gpu_transport() returns, which tells integrations such as Tesseract-JAX whether to hand the endpoints GPU arrays as they are.

Parameters:

output_format (Optional[Literal['json', 'json+base64', 'json+binref']]) – Format for CPU arrays in responses.
gpu_transport (str | None) – How GPU arrays cross the boundary in either direction. none copies them to the host, and any other transport the server offers (such as cuda_ipc) passes them by reference.
compression (Optional[Literal['none', 'lz4']]) – Compression for array buffers in responses (none disables it).

Return type:

Tesseract

Returns:

A Tesseract that uses the requested encoding for every call.

Raises:

ValueError – if the server does not accept a requested value, or runs a runtime too old to be asked for it.

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

Build a container image from a Tesseract source 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.
secrets (list[str] | None) – BuildKit secret specs (e.g. id=name,env=VAR or id=name,src=file) to forward to the build for authenticated package indices. Credentials are mounted, never stored in a layer.
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, debug=False, 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).
debug (bool) – Enable debug mode. This starts a debugpy server in the Tesseract and blocks execution until a debugger attaches to the forwarded port.
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, gpu_transport=None, docker_args=None, runtime_config=None, skip_health_check=False, startup_timeout=30.0)[source]¶

Serve a Tesseract image in a container.

Start the Tesseract listening on an available port 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.
gpu_transport (str | None) – GPU transport the served Tesseract accepts besides none, which copies GPU arrays to the host. cuda_ipc passes them by reference and requires gpus and a shared IPC namespace. Responses only use it for requests that ask for it. Anything but none needs num_workers=1. An explicit value (including none) wins over a gpu_transport in runtime_config, and leaving it unset (None) defers to runtime_config, falling back to none when neither sets it.
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.
startup_timeout (float) – How long to wait for the Tesseract to answer a health check, in seconds. Raise it for one that is slow to initialize, in preference to skipping the check altogether.

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

Python API (tesseract_core)¶

Python API (`tesseract_core`)¶