Get started

Quick start

Note

Before proceeding, make sure you have a working installation of Docker and a modern Python installation (Python 3.12+).

See also

For more detailed installation instructions, please refer to the Tesseract Core documentation.

1. Install Tesseract-Torch:

   $ pip install tesseract-torch
   

2. Build an example Tesseract:

   $ git clone https://github.com/pasteurlabs/tesseract-torch
   $ tesseract build tesseract-torch/examples/simple/vectoradd_torch
   

3. Use it as part of a PyTorch program:

   import torch
   from tesseract_core import Tesseract
   from tesseract_torch import apply_tesseract
   
   # Load the Tesseract
   t = Tesseract.from_image("vectoradd_torch")
   t.serve()
   
   # Run it with PyTorch tensors
   x = torch.ones(1000, requires_grad=True)
   y = torch.ones(1000)
   
   def vector_sum(x, y):
       res = apply_tesseract(t, {"a": {"v": x}, "b": {"v": y}})
       return res["vector_add"]["result"].sum()
   
   loss = vector_sum(x, y)
   loss.backward()
   print(x.grad)  # gradients via the Tesseract's VJP endpoint
   
   # Forward-mode AD is also supported
   import torch.autograd.forward_ad as fwAD
   with fwAD.dual_level():
       x_dual = fwAD.make_dual(x.detach(), torch.ones_like(x))
       result = apply_tesseract(t, {"a": {"v": x_dual}, "b": {"v": y}})
       _, tangent = fwAD.unpack_dual(result["vector_add"]["result"])
   

Tip

To skip Docker, serve the Tesseract from its source directory in a subprocess instead of building an image:

t = Tesseract.from_source("tesseract-torch/examples/simple/vectoradd_torch/tesseract_api.py")
t.serve()

This builds a virtual environment from the Tesseract’s requirements next to tesseract_api.py on first use (which needs uv), or runs on an existing interpreter passed as python_executable=.... Unlike a container, it is not isolated from your environment and filesystem.

Tip

Now you’re ready to jump into our examples for ways to use Tesseract-Torch.

Sharp edges

• Required endpoints: Using apply_tesseract with reverse-mode AD (.backward(), torch.autograd.grad) requires the Tesseract to define a vector_jacobian_product endpoint. Forward-mode AD (torch.autograd.forward_ad) requires jacobian_vector_product. If these endpoints are not implemented, a NotImplementedError will be raised when the respective AD mode is triggered. The forward pass (apply_tesseract itself) works regardless of which AD endpoints are available.

• Non-differentiable inputs/outputs: Only inputs and outputs marked as Differentiable[...] in the Tesseract schema participate in gradient computation. See the Handling Differentiability page for details.

• Other torch.func transforms are not supported: apply_tesseract works with PyTorch’s standard autograd API (.backward(), torch.autograd.grad, torch.autograd.forward_ad), but not with torch.func transforms (torch.func.vjp, torch.func.jvp, torch.func.grad, torch.func.jacrev, torch.func.jacfwd). These transforms create functionalized tensors that cannot be converted to NumPy arrays, which Tesseract endpoints require. Calling apply_tesseract inside a torch.func transform will raise a RuntimeError.

• No higher-order derivatives: a gradient taken with create_graph=True can be used, but differentiating it again raises a RuntimeError, since the Tesseract’s vector_jacobian_product is opaque to PyTorch. See Troubleshooting.

• torch.vmap needs a vmap_method: pass vmap_method="sequential", "expand_dims" or "broadcast_all" to apply_tesseract to batch it with torch.vmap; without one, torch.vmap raises when a batched tensor reaches apply_tesseract. See Batching with torch.vmap.