Metadata-Version: 2.4
Name: helia-profiler
Version: 0.1.1
Summary: Profile LiteRT models on Ambiq Apollo hardware
License-Expression: Apache-2.0
Project-URL: Documentation, https://ambiqai.github.io/helia-profiler/
Project-URL: Issues, https://github.com/AmbiqAI/helia-profiler/issues
Project-URL: Repository, https://github.com/AmbiqAI/helia-profiler
Keywords: ambiq,apollo,embedded,joulescope,litert,profiling
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Embedded Systems
Requires-Python: <3.13,>=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
License-File: src/helia_profiler/vendor/segger_rtt/LICENSE.md
Requires-Dist: Jinja2>=3.1
Requires-Dist: PyYAML>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: pyserial>=3.5
Requires-Dist: pylink-square>=0.14.0
Requires-Dist: neuralspotx<0.8.0,>=0.7.8
Requires-Dist: numpy<3,>=2.1
Requires-Dist: pyjoulescope-driver<2.3.0,>=2.2.12; python_version < "3.12"
Requires-Dist: pyjoulescope-driver<3,>=2.3.2; python_version >= "3.12"
Requires-Dist: pydantic<3,>=2.7
Requires-Dist: typer>=0.16
Requires-Dist: click>=8.2
Provides-Extra: aot
Requires-Dist: helia-aot>=0.18.0; extra == "aot"
Requires-Dist: ai-edge-litert<2.2,>=2.1.6; extra == "aot"
Requires-Dist: backports-strenum<1.3; extra == "aot"
Provides-Extra: analysis
Requires-Dist: ai-edge-litert<2.2,>=2.1.6; extra == "analysis"
Requires-Dist: backports-strenum<1.3; extra == "analysis"
Requires-Dist: flatbuffers>=24.0; extra == "analysis"
Dynamic: license-file

# heliaPROFILER

**`hpx`** profiles LiteRT (`.tflite`) models on real Ambiq Apollo silicon —
one command builds temporary firmware, flashes it, and returns per-layer PMU
counter breakdowns plus optional Joulescope power/energy per inference.

> **Alpha.** heliaPROFILER is pre-1.0. Breaking changes may land on **minor**
> versions until v1.0. Pin an exact version in production pipelines.

📖 Full docs: **https://ambiqai.github.io/helia-profiler/**

## Why hpx

- **Per-layer PMU breakdowns** — cycles, instructions, cache, and (on
  Cortex-M55 boards) MVE and memory counter groups, one row per layer.
- **Power & energy per inference** — GPIO-gated Joulescope capture
  (JS110/JS220) isolates the inference window from setup/teardown noise.
- **Three engines** — `tflm` (vanilla TFLM baseline), `helia-rt` (Ambiq's
  optimized TFLM interpreter), and `helia-aot` (Ambiq's ahead-of-time model
  compiler), selected explicitly
  per run.
- **Multiple toolchains** — `arm-none-eabi-gcc`, `armclang`, and ATfE, so you
  can compare build/runtime trade-offs without changing your model.
- **Memory placement control** — pin the tensor arena and model weights to
  TCM, SRAM, MRAM, or PSRAM independently.
- **Model Explorer overlays** — export per-layer metrics as JSON overlays
  for [Model Explorer](https://github.com/google-ai-edge/model-explorer).
- **Config-file driven** — a frozen, immutable `hpx.yml` schema merges with
  CLI flags, with strict validation and did-you-mean suggestions for typos.
- **Multi-board** — Apollo3, Apollo4, and Apollo5-family EVBs. Run
  `hpx boards` for the exact list your install supports.

## Install

```bash
pip install helia-profiler
# or
uv tool install helia-profiler
```

Extras: `helia-profiler[aot]` adds the heliaAOT compiler;
`helia-profiler[analysis]` enables model compute/parameter analysis without
hardware.

Hardware prerequisites (ARM toolchain, SEGGER J-Link, and optional
Joulescope drivers) are covered step by step in
[Getting Started](https://ambiqai.github.io/helia-profiler/getting-started/).

## Quick taste

```bash
hpx doctor                                   # check toolchain + dependencies
hpx profile model.tflite                     # profile with defaults
hpx profile model.tflite --power             # add Joulescope power capture
hpx profile --config hpx.yml                 # reproducible, config-driven run
```

```text
  Layer  Op                  ARM_PMU_CPU_CYCLES  ARM_PMU_INST_RETIRED
  0      CONV_2D                        123,456                98,765
  1      DEPTHWISE_CONV_2D               45,678                34,567
  ...
  Power:  1.234 mA avg   12.345 mW avg   x.xxx µJ / inference
```

*(Illustrative sample only — see
[Getting Started](https://ambiqai.github.io/helia-profiler/getting-started/)
for a real walkthrough.)*

## Development

```bash
uv sync --locked --all-groups
uv run ruff check src tests tools
uv run pytest -q
uv run mkdocs build --strict
```

Repository workflows use the committed `uv.lock` for reproducibility. PyPI
installations continue to resolve the compatible dependency ranges published in
`pyproject.toml`.

## License

Apache-2.0
