(tr-quickstart)=

# Get Started

## Quick install

```{note}
This requires Docker and Python 3.10+. See the [installation guide](installation.md) for detailed setup instructions.
```

```bash
$ pip install tesseract-core
```

## Hello Tesseract

The [`tesseract` CLI](../api/tesseract-cli.md) builds Tesseracts as Docker containers from `tesseract_api.py` files. Here, we'll build and invoke a simple Tesseract that greets you by name.

### Build your first Tesseract

Download the {download}`Tesseract examples </downloads/examples.zip>` and run the following command from where you unpacked the archive:

```bash
$ tesseract build examples/helloworld
 [i] Building image ...
 [i] Built image sha256:95e0b89e9634, ['helloworld:latest']
```

```{tip}
Having trouble? Check [common issues](#installation-issues) for solutions.
```

Your first Tesseract is now available as a Docker image on your system.

### Run your Tesseract

You can interact with any built Tesseract via the CLI, the REST API, or the [Python SDK](../api/tesseract-api.md):

::::{tab-set}
:::{tab-item} CLI
:sync: cli

```bash
$ tesseract run helloworld apply '{"inputs": {"name": "Osborne"}}'
{"greeting":"Hello Osborne!"}
```

:::
:::{tab-item} REST API
:sync: http

```bash
$ tesseract serve -p 8080 helloworld
 [i] Waiting for Tesseract containers to start ...
 [i] Container ID: 2587deea2a2efb6198913f757772560d9c64cf8621a6d1a54aa3333a7b4bcf62
 [i] Name: tesseract-uum375qt6dj5-sha256-9by9ahsnsza2-1
 [i] Entrypoint: ['tesseract-runtime', 'serve']
 [i] View Tesseract: http://127.0.0.1:56489/docs
 [i] Docker Compose Project ID, use it with 'tesseract teardown' command: tesseract-u7um375qt6dj5
{"project_id": "tesseract-u7um375qt6dj5", "containers": [{"name": "tesseract-uum375qt6dj5-sha256-9by9ahsnsza2-1", "port": "8080"}]}%

$ # The port at which your Tesseract will be served is random if `--port` is not specified;
$ # specify the one you received from `tesseract serve` output in the next command.
$ curl -d '{"inputs": {"name": "Osborne"}}' \
       -H "Content-Type: application/json" \
       http://127.0.0.1:8080/apply
{"greeting":"Hello Osborne!"}

$ tesseract teardown tesseract-u7um375qt6dj5
 [i] Tesseracts are shutdown for Project name: tesseract-u7um375qt6dj5
```

:::
:::{tab-item} Python SDK
:sync: python

```python
>>> from tesseract_core import Tesseract
>>>
>>> with Tesseract.from_image("helloworld") as helloworld:
>>>     helloworld.apply({"name": "Osborne"})
{'greeting': 'Hello Osborne!'}
```

:::
::::

```{tip}
For faster iteration during development, you can run Tesseracts without building containers. See [Debugging and Development](../misc/debugging.md) for details.
```

Each Tesseract auto-generates CLI and REST API docs. To view them:

::::{tab-set}
:::{tab-item} CLI
:sync: cli

```bash
$ tesseract run helloworld --help
```

:::
:::{tab-item} REST API
:sync: http

```bash
$ tesseract apidoc helloworld
 [i] Waiting for Tesseract containers to start ...
 [i] Serving OpenAPI docs for Tesseract helloworld at http://127.0.0.1:59569/docs
 [i]   Press Ctrl+C to stop
```

:::
::::

```{figure} /img/apidoc-screenshot.png
:scale: 33%

The OpenAPI docs for the `helloworld` Tesseract, documenting its endpoints and valid inputs / outputs.
```

(getting-started)=

## Under the hood

The folder passed to `tesseract build` contains three files:

```bash
$ tree examples/helloworld
examples/helloworld
├── tesseract_api.py
├── tesseract_config.yaml
└── tesseract_requirements.txt
```

These are all that's needed to define a Tesseract.

### `tesseract_api.py`

This file defines the Tesseract's input and output schemas, along with the endpoint functions: `apply`, `abstract_eval`, `jacobian`, `jacobian_vector_product`, and `vector_jacobian_product` (see [endpoints](../api/endpoints.md)). Only `apply` is required.

```{literalinclude} ../../../examples/helloworld/tesseract_api.py
:pyobject: InputSchema
```

```{literalinclude} ../../../examples/helloworld/tesseract_api.py
:pyobject: OutputSchema
```

```{literalinclude} ../../../examples/helloworld/tesseract_api.py
:pyobject: apply
```

```{tip}
For a Tesseract that has all optional endpoints implemented, check out the [Univariate example](../examples/building-blocks/univariate.md).
```

(quickstart-tr-config)=

### `tesseract_config.yaml`

Contains metadata such as the Tesseract's name, description, version, and build configuration.

```{literalinclude} ../../../examples/helloworld/tesseract_config.yaml

```

### `tesseract_requirements.txt`

Lists the Python packages needed to build and run the Tesseract, in [pip requirements file format](https://pip.pypa.io/en/stable/reference/requirements-file-format/).

```{note}
This file is optional. `tesseract_api.py` can invoke functions written in any language. In that case, use the `build_config` section in [`tesseract_config.yaml`](quickstart-tr-config) to provide data files and install dependencies.
```

```{literalinclude} ../../../examples/helloworld/tesseract_requirements.txt

```

## Features and limitations

::::{tab-set}
:::{tab-item} Features

- **Self-documenting** — Tesseracts announce their interfaces, so users can inspect them without reading source code and perform static validation without running the code.
- **Auto-validating** — Input data is automatically validated against the schema, so internal logic can assume the data is in the expected format.
- **Autodiff-native** — Tesseracts support [differentiable programming](../misc/differentiable-programming.md) and integrate as native operations in PyTorch and JAX — but exposing derivatives is _strictly optional_.
- **Batteries included** — Every Tesseract ships with a containerized runtime, a CLI, a REST API, and a Python SDK.

:::
:::{tab-item} Limitations

- **Python as glue** — Tesseracts may use any software under the hood, but they always use Python as glue between the runtime and the wrapped functionality. Support for Python projects is more mature than other languages.
- **Single entrypoint** — Each Tesseract has a single `apply` entrypoint. To expose N functions, create N Tesseracts.
- **Context-free** — Tesseracts are not aware of outer-loop orchestration or runtime details.
- **Runtime overhead** — Tesseracts are designed for compute kernels that run at least several seconds, so they may not suit very low-latency workloads.

:::
::::

## Next steps

Depending on your needs:

- [](../creating-tesseracts/create.md) — define schemas, implement endpoints, and build Tesseracts
- [](../using-tesseracts/use.md) — invoke Tesseracts and work with their outputs

Or jump into end-to-end tutorials:

- [JAX Rosenbrock function minimization](https://si-tesseract.discourse.group/t/jax-based-rosenbrock-function-minimization/48)
- [PyTorch Rosenbrock function minimization](https://si-tesseract.discourse.group/t/pytorch-based-rosenbrock-function-minimization/44)
- [JAX RBF fitting with autodiff](https://si-tesseract.discourse.group/t/jax-auto-diff-templates-gaussian-radial-basis-function-fitting/51)