Interactive sessions#

Session `dataclass` #

Session(yaml_path: Path | None = None, _base: Mapping[str, Any] = (lambda: MappingProxyType({}))(), _overrides: Mapping[str, Any] = (lambda: MappingProxyType({}))())

Immutable, branchable configuration for interactive HPX operations.

Sessions retain unresolved configuration overrides so YAML values and board-derived defaults are resolved by the same validation path as the CLI. Every with_* method returns an independent session.

from_yaml `classmethod` #

from_yaml(path: str | Path) -> Self

Create a session from an immutable snapshot of an HPX YAML config.

from_dict `classmethod` #

from_dict(intent: Mapping[str, Any]) -> Self

Create a session from unresolved configuration intent.

load `classmethod` #

load(path: str | Path) -> Self

Load a versioned unresolved-intent snapshot from JSON.

intent_dict #

intent_dict() -> dict[str, Any]

Return JSON-safe unresolved intent without expanding defaults.

resolved_dict #

resolved_dict(model: str | Path | None = None) -> dict[str, Any]

Return the fully resolved and validated configuration snapshot.

save #

save(path: str | Path) -> Path

Persist unresolved intent as a versioned JSON snapshot.

with_overrides #

with_overrides(overrides: Mapping[str, Any]) -> Self

Return a session with advanced raw configuration overrides merged in.

with_options #

with_options(*, verbose: int | None = None, frozen: bool | None = None, work_dir: str | Path | None = None, clean: bool | None = None) -> Self

Return a session with top-level run options.

resolve #

resolve(model: str | Path | None = None) -> ProfileConfig

Resolve and validate this session as a complete profile config.

profile #

profile(model: str | Path | None = None, *, progress_sink: Callable[[ProgressUpdate], None] | None = None) -> ProfileResult

Run a profile using this session's resolved configuration.

analyze #

analyze(model: str | Path | None = None) -> ModelAnalysis

Analyze the configured model without building or flashing firmware.

compare #

compare(baseline: str | Path | ProfileResult, candidate: str | Path | ProfileResult, *, output_dir: str | Path | None = None, profile: str | Path | ComparisonProfile | None = None) -> CompareResult

Compare two completed profiles and optionally write diff artifacts.

doctor #

doctor() -> DoctorResult

Return structured host dependency checks.

show #

show(value: Any, *, console: Console | None = None) -> Any

Pretty-print a typed interactive value and return it unchanged.

boards #

boards() -> tuple[BoardDef, ...]

Return boards visible to this session's platform registry.

engines #

engines() -> tuple[EngineType, ...]

Return supported inference engine identifiers.

counter_groups #

counter_groups() -> tuple[str, ...]

Return registered PMU counter group names.

counters #

counters(group: str | None = None) -> tuple[PmuCounter, ...]

Return registered PMU counters, optionally filtered by group.

probes #

probes() -> tuple[JLinkProbe, ...]

Return connected J-Link probes.

inspect_probes #

inspect_probes(board: str | None = None) -> tuple[JLinkProbeMatch, ...]

Inspect the target core visible through each connected probe.

match_probe #

match_probe(board: str | None = None, *, serial: str | None = None) -> str

Resolve the J-Link serial matching a board target.

ports #

ports(*, include_all: bool = False) -> tuple[SerialPortInfo, ...]

Return host serial ports relevant to HPX transports.

reset #

reset(board: str | None = None, *, serial: str | None = None, kind: Literal['debug', 'swpoi'] = 'debug') -> None

Reset the configured target through its J-Link probe.

examples #

Packaged assets for examples, smoke tests, and tutorials.

tiny_cnn #

tiny_cnn() -> Path

Materialize the packaged tiny CNN and return its stable cache path.

Create a session, retain typed results, and render them as Rich tables when working in a terminal, IPython, or notebook:

import helia_profiler as hpx

session = hpx.Session().with_target(board="apollo510_evb")

doctor = session.show(session.doctor())
probes = session.show(session.probes())
matches = session.show(session.inspect_probes())

Session.show() returns the original value unchanged, so pretty-printing does not replace the typed result or prevent later programmatic use.

Persisting intent#

Session snapshots store unresolved user intent, not environment-derived defaults. Relative model and module paths remain relative strings:

session = (
    hpx.Session()
    .with_model("models/model.tflite")
    .with_target(board="apollo510_evb")
)
session.save("experiment.session.json")

restored = hpx.Session.load("experiment.session.json")
assert restored.intent_dict() == session.intent_dict()

Use resolved_dict() when a fully validated configuration snapshot is needed for inspection or provenance. Loading a resolved snapshot as intent is deliberately not automatic because doing so would freeze defaults that may be board-, environment-, or version-dependent.

Session.profile() and the top-level profile() function are silent by default. Pass progress_sink=updates.append to receive typed ProgressUpdate events without enabling terminal presentation. The hpx CLI owns Rich progress and final result rendering.

The versioned envelope is described by the packaged permissive schema helia_profiler/data/session_intent.schema.v1.json.

For a newcomer-oriented walkthrough of discovery, immutable experiment branches, profiling, filtering, comparisons, overlays, and power, see Interactive Python.

Interactive result types#

ModelAnalysis `dataclass` #

ModelAnalysis(layers: list[LayerOps], total_macs: int, total_ops: int, num_parameters: int, engine: str = 'tflite')

Full model analysis result.

num_parameters `instance-attribute` #

num_parameters: int

Approximate parameter count (weights + biases).

engine `class-attribute` `instance-attribute` #

engine: str = 'tflite'

Engine/interpreter that produced this analysis ('tflite', 'helia-rt', 'helia-aot').

CompareResult `dataclass` #

CompareResult(baseline: RunArtifacts, candidate: RunArtifacts, config_rows: list[ConfigDiffRow], metrics: list[MetricDiff], layer_rows: list[LayerDiffRow], warnings: list[str] = list(), comparability: ComparabilityAssessment = ComparabilityAssessment(), verdict: ComparisonVerdict | None = None)

Full comparison between two profile runs.

DoctorCheck `dataclass` #

DoctorCheck(label: str, name: str, available: bool, path: str | None = None, required: bool = True, hint: str | None = None)

Availability result for one required or optional host dependency.

DoctorResult `dataclass` #

DoctorResult(checks: tuple[DoctorCheck, ...])

Structured host-readiness result returned by the programmatic API.

missing_required `property` #

missing_required: tuple[DoctorCheck, ...]

Required dependencies that are unavailable.

BoardDef `dataclass` #

BoardDef(name: str, soc: str, channel: str, psram_kb: int | None = None, default_sync_gpio_pin: int = DEFAULT_SYNC_GPIO_PIN, default_state_gpio_pin: int = DEFAULT_STATE_GPIO_PIN, default_go_gpio_pin: int = DEFAULT_GO_GPIO_PIN, starter_profile_board: str | None = None, description: str = '', ble_reset_gpio_pin: int | None = None)

Definition of an evaluation board.

profile_source_board `property` #

profile_source_board: str

Board name used to derive starter-profile-owned NSX metadata.

power_capture `property` #

power_capture: PowerCaptureCapabilities

Power-capture wiring defaults (sync/state/go GPIO pins) for this board.

PmuCounter `dataclass` #

PmuCounter(name: str, event_id: int, group: str, description: str = '')

A single PMU event that the hardware can count.

JLinkProbe `dataclass` #

JLinkProbe(serial: str, product: str = '', connection: str = 'USB')

JLinkProbeMatch `dataclass` #

JLinkProbeMatch(probe: JLinkProbe, detected_core: CoreArch | None)

SerialPortInfo `dataclass` #

SerialPortInfo(device: str, kind: str, description: str = '', manufacturer: str = '', product: str = '', serial_number: str = '', interface: str = '', hwid: str = '')

Description of one host serial port relevant to HPX transports.