Skip to main content

Development

What counts as development in this repo​

This repository owns the Neural Technology target plus the NX-oriented backend path. Development here often crosses target profiles, estimator configuration, conversion integration, and resource files used by the analysis flow.

Local setup​

Use uv to create and sync the development environment:

uv sync --group dev

If you only need the test stack:

uv sync --group test

Common commands​

Run the quick CI-aligned test suite:

uv run pytest -m "not slow" tests/

Run the full test suite:

uv run pytest tests/

Run repository checks:

uv run pre-commit run --all-files

Build the package:

uv build

PyTorch converter and ETDump compatibility​

CI installs the executorch extra and the test dependency group in one environment, checks the installed requirements, and runs both converter and profiling regression tests. Reproduce the installation with:

uv sync --extra executorch --group test
uv pip check

Run the combined integration test separately from the TensorFlow test fixtures:

MLIA_REQUIRE_PYTORCH_E2E=1 uv run --no-sync pytest -o addopts="" --noconftest tests/test_executorch_converter_integration.py

The test exports a real PyTorch module through the converter plugin, executes its portable PTE, and verifies standardized MLIA output from the generated ETRecord and a serialized ETDump containing controlled timing samples. Runtime wheel builds do not need on-device event tracing enabled. Missing converter packages fail the CI test; outside this job, the optional test can be skipped. The existing quick test job continues to enforce the repository coverage target.

What usually changes together​

When you update one of these areas, review the adjacent layers as well:

  • Target profiles and target logic.
  • Estimator configuration parsing.
  • Conversion backend integration.
  • Resource files under src/mlia/resources/.
  • Output, provenance, and troubleshooting docs for estimator and measured-data workflows.

Good review questions​

Before you consider a change complete, ask:

  • Does the target still appear correctly through mlia target list?
  • Do backend-specific CLI options still behave as documented?
  • Did estimator config changes affect the documented examples?
  • If conversion is involved, does the end-to-end workflow still make sense?
  • Do estimator and measured-data results retain compatible entities, aggregations, totals, and warnings?

Runtime boundary actions​

Application code must not directly launch external processes, invoke registered model transformers, perform runtime network access, install packages, or mutate the filesystem. Neural Technology-specific actions must go through a gateway in mlia.nx_utils.boundaries, using Core mlia.utils.boundaries gateways where appropriate.

Notice-worthy actions such as model transformation and converter or estimator execution must call log_boundary_action() immediately before the action. Documented user-requested output, temporary resources, and derived output beneath an already-announced operation still use a boundary gateway but do not need a separate notice.

To add a runtime boundary operation, add an intention-revealing gateway and tests for its behavior. Reviewers must manually verify, with LLM assistance where useful, that runtime effects remain inside the boundary package and required notices execute before their actions on every path. Build hooks, CI workflows, pre-commit tooling, and tests are outside this runtime policy.

Documentation expectations​

When profiles, input formats, backend options, capture schemas, or provenance rules change, update this repo's docs so estimator and measured-data behaviour remain understandable on their own.