# Backend installation and support

This page describes the source API on `main`. Use the source-checkout tab in the installation guide for these extras and portable workflows.

Choose a backend for the components you plan to use. Select it before importing Keras, and use separate processes when switching.

## Start with your backend

Use the `tensorflow` extra for Keras models and TensorFlow-specific data and training paths; use `litert` when you also need conversion.

```python
import os
os.environ["KERAS_BACKEND"] = "tensorflow"
import keras
```

Python 3.12–3.13 is covered by the CI matrix.

Use the `torch` extra for the portable components below. TensorFlow is not required for those paths.

```python
import os
os.environ["KERAS_BACKEND"] = "torch"
import keras
```

Python 3.12–3.14 is covered by the CI matrix. LiteRT export needs the TensorFlow backend: rebuild a Torch-trained model from its params and weights in a process started with `KERAS_BACKEND=tensorflow` (see [Export and quantization](https://ambiqai.github.io/helia-edge/guide/export/)).

## Match the capability to your workflow

| Capability | TensorFlow | PyTorch | Start here |
|---|---|---|---|
| TCN construction | Tested | Tested | [First model](https://ambiqai.github.io/helia-edge/getting-started/first-model/) |
| Portable metrics, EMA quantization | Tested | Tested subset | [Metrics](https://ambiqai.github.io/helia-edge/guide/evaluation/) |
| Normalization1D, FirFilter, RandomGaussianNoise1D | Tested | Tested | [Signal preprocessing](https://ambiqai.github.io/helia-edge/guide/portable-preprocessing/) |
| Masked-autoencoder training | Tested | Tested | [Reconstruction guide](https://ambiqai.github.io/helia-edge/guide/masked-autoencoders/) |
| Grain record pipelines (`helia-edge[grain]`) | `to_tf_dataset` | `to_torch_loader` | [Input pipelines](https://ambiqai.github.io/helia-edge/guide/input-pipeline/) |
| Generator-to-dataset helpers | `tf.data` | No Torch adapter | [Input pipelines](https://ambiqai.github.io/helia-edge/guide/input-pipeline/) |
| Contrastive training | TensorFlow path | Not supported | [Training guide](https://ambiqai.github.io/helia-edge/guide/training/) |
| LiteRT conversion and FLOP counting | TensorFlow path | Not supported | [Export guide](https://ambiqai.github.io/helia-edge/guide/export/) |

Support is component-specific. This table does not certify every architecture, precision, compiled/distributed configuration or export format. The preprocessing contracts describe additional shape, dtype and compilation boundaries.

- [Install your environment](https://ambiqai.github.io/helia-edge/getting-started/): Choose source or release installation and optional extras.
- [Explore preprocessing contracts](https://ambiqai.github.io/helia-edge/guide/preprocessing-contracts/): Check alignment, random state and transform-specific behavior.
Optional dependencies and compatibility with older installs

Base installations provide file and logging helpers without Keras. Plotting and S3 require `plotting` and `aws` respectively; S3 model URLs also need `aws`. Patch extraction does not need plotting, but `PatchLayer2D.show_patched_image` does.

Backend extras retain h5py for Keras serialization. Applications importing plotting, AWS or h5py directly should declare those dependencies themselves. `litert` includes TensorFlow conversion and the LiteRT runtime. `metal` must be combined with `tensorflow`; compatibility has not been validated for the recorded baseline.

Recorded environment and reproducibility limits

The recorded baseline is Linux CPU, Python 3.12.5, Keras 3.15.1, TensorFlow 2.21.0 or Torch 2.14.0+cpu, and LiteRT 2.2.0. To reproduce the CPU Torch environment, install `torch==2.14.0` from `https://download.pytorch.org/whl/cpu` before installing the Torch extra.

The TensorFlow dependency marker excludes Python 3.14 even when its extra is selected. Use Python 3.12–3.13 for TensorFlow or LiteRT. Other platforms, GPU builds and different dependency resolutions need their own validation.

## Loading saved custom objects

Lazy imports no longer register all custom Keras classes as a side effect of
`import helia_edge`. The EDGE model loader registers supported objects explicitly:

```python
from helia_edge.models import load_model
model = load_model('model.keras')
```

Use Keras directly or check serialization limits

For direct Keras loading, import the custom classes used by the model, or register
supported EDGE classes before loading:

```python
import helia_edge
helia_edge.register_keras_serializables()
import keras
model = keras.saving.load_model('model.keras')
```

Registration initializes the selected backend. It does not enable unsafe loading
or make TensorFlow-only custom layers usable on Torch. Fresh-process round trips
cover an EDGE EMA quantizer on both backends and legacy normalization on TF.

## Validation

What the automated checks cover

CI includes a base-only lane and separate backend environments. Import checks
assert the opposite framework is absent. TF runs its applicable suite, including float
and int8 conversion; Torch runs the portable subset and custom-object reloads.
Separate backend-free environments exercise AWS and plotting, followed by
combined backend checks for S3 model loading and patch visualization.
CPU tests set `CUDA_VISIBLE_DEVICES=-1` so installed GPU drivers cannot affect the
CPU export path. Preprocessing uses the public Keras augmentation hierarchy with
CPU TensorFlow and Torch coverage; see the [migration guide](https://ambiqai.github.io/helia-edge/guide/preprocessing-contracts/)
for training, dtype, shape and compilation limits.

## Masked-autoencoder training

See [Masked-autoencoder training](https://ambiqai.github.io/helia-edge/guide/masked-autoencoders/) for the reconstruction contract, native optimization loops and backend parity boundaries.