# Development

Python 3.12.3 is the minimum. TensorFlow is tested on 3.12–3.13 and Torch on
3.12–3.14. Python 3.15's native lazy-import syntax is outside that matrix;
`from __future__ import annotations` postpones annotations, not module imports.

## Package boundaries

- Helpers and sampling policies must import without Keras or a training backend.
- Portable tensor computation uses public Keras APIs. Gradient steps and export
  adapters may use their selected backend explicitly.
- KITs own dataset meaning, preprocessing policy and release criteria. Add shared
  abstractions only when real consumers establish the contract.
- Keep temporary profiling scripts, investigation notes and run results outside
  the repository. Track tooling only when it has an ongoing maintenance purpose.

## Repository layout

- `helia_edge/`: installed library and public type declarations.
- `tests/`: regression tests, with supporting code beside the tests it serves;
  fixed datasets in `tests/fixtures/` and static contracts in `tests/typing/`.
- `astro-site/`: authored site pages, API generation, search and browser checks.
- `docs/guides/`: notebook sources rendered into the site; every other page is authored in `astro-site/`.
- `.github/workflows/`: CI orchestration. Generated files belong in the runner's
  temporary directory and are uploaded as artifacts when needed.

The MAE parity fixture and comparison helper live in `tests/trainers/`. CI uses
them to check forward values, gradients and optimizer updates across isolated
backends. They are regression infrastructure, not performance measurements.
`tests/export/cross_backend_export.py` trains models with the Torch backend and
exports them with the TensorFlow backend; CI runs its two halves in separate jobs.
Run both locally with `python tests/export/cross_backend_export.py run
--torch-python <torch env python> --tensorflow-python <tensorflow env python>`.

## API conventions

Public lazy exports are declared once in adjacent `__init__.pyi` files.
`lazy-loader` uses those declarations at runtime; type checkers read the same
files. Package the stubs and `py.typed` marker when building distributions.
Keep import errors actionable and test base-only/TF-only/Torch-only environments.

Use enums for closed choices, dataclasses for internal records, and Pydantic for
validated external configuration. Named tuples suit structured tensor outputs
that must remain compatible with Keras trees and tuple unpacking. Dictionaries
remain appropriate for keyed collections and framework-defined serialization.
Keep comments about constraints or reasoning; put usage and architecture in docs.

## Checks and git hooks

Checks run through [prek](https://github.com/j178/prek) hooks declared in
`.pre-commit-config.yaml`. CI runs the same two stages:

```sh
uv sync --locked --all-extras --group ci
uv run prek install                                  # once per clone
uv run prek run --all-files --hook-stage pre-commit  # ruff format, ruff check, uv lock
uv run prek run --all-files --hook-stage pre-push    # ty, fast pytest set
```

The pre-commit stage needs only the `ci` group. The pre-push stage needs both
backends to resolve annotations, so run it from the full environment above; CI
installs CPU-only Torch for it. ruff, ty and prek are pinned exactly in the `ci`
group, which `dev` includes. pre-commit reads the same configuration if prek is
unavailable. The `dev` group's `parity` tools install `helia-model-zoo` from git; set
`GIT_LFS_SKIP_SMUDGE=1` when syncing to skip the zoo's model files, which those tests do not need.

Runtime isolation is tested separately. Base, plotting-only, AWS-only and backend
environments each run their applicable tests; combined environments cover model
retrieval and visualization. Do not install every extra to qualify a base install.

`tool.ty.src.include` lists the current gate: lazy public exports, modernized
sampling/helpers, patch layers, masked-autoencoder and backend parity helpers.
Static contract checks verify that public re-exports retain their types.
Legacy model families and augmentation implementations still contain
typing debt and are outside this initial gate. There are no global rule
suppressions; extend coverage as those modules are corrected.

To inspect the remaining package debt, run `uv run ty check helia_edge`.

## Update documentation and API contracts

Edit task guides in `astro-site/src/content/docs/`. Update public Python docstrings with parameter shapes, units, return values and error behavior when an API changes. Public re-exports belong in the adjacent `__init__.pyi` file as well.

The API generator reads source statically with Griffe, including lazy exports. Do not edit generated reference pages. To regenerate and validate the site with Node 24:

```sh
cd astro-site
npm ci
npm run check
npm run build
npm run check:output
npx playwright install chromium
npm test
```

These checks cover types, internal links, exported API contracts, search, navigation and responsive layouts. The backend CI matrix also executes the introductory examples in `tests/test_docs_examples.py`. Add executable coverage when a guide introduces a new runnable workflow. Notebook pages render committed cells and saved outputs; the site build does not execute their training runs.