Tesseract Hackathon Template

A ready-to-use template for building projects with Tesseract Core and Tesseract-JAX, featuring two interacting tesseracts that demonstrate vector scaling and similarity computation. Intended as a starting point for participants of the [Tesseract Hackathon](link TODO).

Warning

Using this template is not required to participate in the Hackathon. You may use any tools at your disposal, including Tesseract Core, Tesseract-JAX, and Tesseract-Streamlit — or composing Tesseracts via docker run calls in a glorified shell script. Your imagination is the limit!

See also

• Tesseract Core Documentation
• Tesseract-JAX Documentation
• Tesseract showcase
• Get help @ Tesseract User Forums

Overview

This template demonstrates how to:

1. Define Tesseracts (tesseracts/*).
2. Build them locally (buildall.sh).
3. Serve Tesseracts locally, and compose them into a (differentiable) pipeline via the Tesseract Core SDK and Tesseract-JAX (main.py).

Included Tesseracts

Example Tesseracts are minimal and meant as starting point for you to build upon.

1. scaler (tesseracts/scaler)
   • Scales input vectors by a given factor.
   • Implements a vector-Jacobian product by hand for autodiff.
2. dotproduct (tesseracts/dotproduct)
   • Computes dot product between two vectors.
   • Calculates cosine similarity.
   • Uses the Tesseract JAX recipe to enable automatic differentiation.

Pipeline Demo

The example script main.py demonstrates two ways to compose Tesseracts into pipelines.

Path 1: Calling Tesseracts manually

• Call Tesseracts via Tesseract Core SDK.

Path 2: Composing Tesseracts with Tesseract-JAX

• Wrap Tesseract calls in a differentiable JAX function using Tesseract-JAX.

Get Started

Prerequisites

• Python 3.10 or higher, ideally with a virtual environment (e.g. via venv, conda, or uv).
• Working Docker setup for the current user (Docker Desktop recommended).

Quickstart

1. Create a new repository off this template and clone it

   $ git clone <your-repo-url>
   $ cd <myrepo>

2. Set up virtual environment (if not done already). uv or conda can also be used.

   $ python3 -m venv .venv
   $ source .venv/bin/activate

3. Install dependencies

   $ pip install -r requirements.txt

4. Build Tesseracts

   $ ./buildall.sh

5. Run the example pipeline

   $ python main.py

Now go and build your own!

Some pointers to get you started:

1. Change Tesseract definitions.
   • Just update the code in tesseracts/*. You can add / remove Tesseracts at will, and buildall.sh will... build them all.
   • Make sure to check out the Tesseract docs to learn how to adapt existing configuration and define Tesseracts from scratch.
2. Use gradients to perform optimization.
   • Exploit that Tesseract pipelines with AD endpoints are end-to-end differentiable.
   • Check showcases for inspiration, e.g. the Rosenbrock optimization showcase for a minimal demo.
3. Deploy Tesseracts anywhere.
   • Since built Tesseracts are just Docker images, you can deploy them virtually anywhere.
   • This includes HPC clusters via SLURM.
   • Have a look at Tesseract Streamlit that can turn Tesseracts into web apps.
   • Show us how and where you run Tesseracts over the local network, on clusters, or in the cloud!
4. Happy Hacking! 🚀
   • Don't let these pointers constrain you. We're looking for creative solutions, so thinking out of the box is always appreciated.
   • Have fun, and reach out if you need help.

License

Licensed under Apache License 2.0.

All submissions must use the Apache License 2.0 to be eligible for the Tesseract Hackathon. See LICENSE file for details.