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 hooks declared in .pre-commit-config.yaml. CI runs the same two stages:

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:

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.