Get started

Quick start

Note

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

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

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.

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