helia_profiler

The entry points of the heliaPROFILER Python API: one call, one session, and the progress stream they report through.

Every name on this page is imported from helia_profiler.

API tier: stable

Generated from the src/helia_profiler tree f38e378c801d34438affb680257217e0b58d2cd1.

Re-exports

Name	Source
ProfileConfig	`helia_profiler.ProfileConfig`
ModelConfig	`helia_profiler.ModelConfig`
EngineConfig	`helia_profiler.EngineConfig`
TargetConfig	`helia_profiler.TargetConfig`
ProfilingConfig	`helia_profiler.ProfilingConfig`
OutputConfig	`helia_profiler.OutputConfig`
BuildConfig	`helia_profiler.BuildConfig`
HeartbeatConfig	`helia_profiler.HeartbeatConfig`
TimeoutsConfig	`helia_profiler.TimeoutsConfig`
ClockSelection	`helia_profiler.ClockSelection`
OutputFormat	`helia_profiler.OutputFormat`
FrozenRun	`helia_profiler.FrozenRun`
FrozenModel	`helia_profiler.FrozenModel`
FrozenRuntime	`helia_profiler.FrozenRuntime`
LocalInput	`helia_profiler.LocalInput`
ToolchainIdentity	`helia_profiler.ToolchainIdentity`
build	`helia_profiler.build`
load_build	`helia_profiler.load_build`
run_build	`helia_profiler.run_build`
load_run	`helia_profiler.load_run`
hpx_cache_root	`helia_profiler.hpx_cache_root`
CompiledBuild	`helia_profiler.CompiledBuild`
RunResult	`helia_profiler.RunResult`
RunResultRecord	`helia_profiler.RunResultRecord`
RunResultError	`helia_profiler.RunResultError`
Lifecycle	`helia_profiler.Lifecycle`
TypedFixture	`helia_profiler.TypedFixture`
FixtureIO	`helia_profiler.FixtureIO`
FixtureOutput	`helia_profiler.FixtureOutput`
FixtureRole	`helia_profiler.FixtureRole`
FixtureFile	`helia_profiler.FixtureFile`
FixtureTensor	`helia_profiler.FixtureTensor`
PerTensorQuantization	`helia_profiler.PerTensorQuantization`
PerAxisQuantization	`helia_profiler.PerAxisQuantization`
FixtureDType	`helia_profiler.FixtureDType`
FixtureMethod	`helia_profiler.FixtureMethod`
FixtureTimingScope	`helia_profiler.FixtureTimingScope`
FixtureStatePolicy	`helia_profiler.FixtureStatePolicy`
analyze_run_model	`helia_profiler.analyze_run_model`
analyze_run_model_for_engine	`helia_profiler.analyze_run_model_for_engine`
TypedFixtureModelAnalysis	`helia_profiler.TypedFixtureModelAnalysis`
FixtureCaptureGuard	`helia_profiler.FixtureCaptureGuard`
OperatorGuard	`helia_profiler.OperatorGuard`
FixtureTarget	`helia_profiler.FixtureTarget`
FixturePowerGuard	`helia_profiler.FixturePowerGuard`
FixtureRailPowerRequest	`helia_profiler.FixtureRailPowerRequest`
FixtureBoardPowerRequest	`helia_profiler.FixtureBoardPowerRequest`
FixtureCaptureResult	`helia_profiler.FixtureCaptureResult`
FixtureTiming	`helia_profiler.FixtureTiming`
FixtureMemory	`helia_profiler.FixtureMemory`
FixturePowerSync	`helia_profiler.FixturePowerSync`
FixtureRailEnergy	`helia_profiler.FixtureRailEnergy`
FixtureBatchCompletion	`helia_profiler.FixtureBatchCompletion`
FixturePsramObservation	`helia_profiler.FixturePsramObservation`
PreparedUpstreamRuntime	`helia_profiler.PreparedUpstreamRuntime`
VerifiedPreparedRuntime	`helia_profiler.VerifiedPreparedRuntime`
PreparedRuntimeManifest	`helia_profiler.PreparedRuntimeManifest`
RuntimeABI	`helia_profiler.RuntimeABI`
RuntimeHeader	`helia_profiler.RuntimeHeader`
RuntimeProvider	`helia_profiler.RuntimeProvider`
ResolverPlan	`helia_profiler.ResolverPlan`
FixtureKernelSource	`helia_profiler.FixtureKernelSource`
FixtureRuntimeSource	`helia_profiler.FixtureRuntimeSource`
EngineSource	`helia_profiler.EngineSource`
FixtureBuild	`helia_profiler.FixtureBuild`
MemoryPlan	`helia_profiler.MemoryPlan`
ToolchainInfo	`helia_profiler.ToolchainInfo`
FixturePsramWeights	`helia_profiler.FixturePsramWeights`
FixturePsramPayload	`helia_profiler.FixturePsramPayload`
capabilities	`helia_profiler.capabilities`
FixtureCapabilities	`helia_profiler.FixtureCapabilities`
QualifiedFixtureTarget	`helia_profiler.QualifiedFixtureTarget`
EngineDTypeCapability	`helia_profiler.EngineDTypeCapability`
FixtureCapability	`helia_profiler.FixtureCapability`
RunIdentity	`helia_profiler.RunIdentity`
RunFacts	`helia_profiler.RunFacts`
EnergyFacts	`helia_profiler.EnergyFacts`
BuildFacts	`helia_profiler.BuildFacts`
RuntimeIdentity	`helia_profiler.RuntimeIdentity`
KernelIdentity	`helia_profiler.KernelIdentity`
CanonicalEngine	`helia_profiler.CanonicalEngine`
CanonicalKernel	`helia_profiler.CanonicalKernel`
Unknown	`helia_profiler.Unknown`
SemanticHash	`helia_profiler.SemanticHash`
canonical_engine	`helia_profiler.canonical_engine`
canonical_kernel	`helia_profiler.canonical_kernel`
PowerConfig	`helia_profiler.PowerConfig`
EngineType	`helia_profiler.EngineType`
Toolchain	`helia_profiler.Toolchain`
Transport	`helia_profiler.Transport`
Placement	`helia_profiler.Placement`
ResetStrategy	`helia_profiler.ResetStrategy`
CompatibilityBaseline	`helia_profiler.CompatibilityBaseline`
CompatibilityResolution	`helia_profiler.CompatibilityResolution`
QualificationState	`helia_profiler.QualificationState`
load_compatibility_baseline	`helia_profiler.load_compatibility_baseline`
DependencyLockProvenance	`helia_profiler.DependencyLockProvenance`
read_dependency_lock_provenance	`helia_profiler.read_dependency_lock_provenance`
qualification	`helia_profiler.qualification`
Qualification	`helia_profiler.Qualification`
RuntimeQualification	`helia_profiler.RuntimeQualification`
runtimes	`helia_profiler.runtimes`
RuntimeRecord	`helia_profiler.RuntimeRecord`
RuntimeSource	`helia_profiler.RuntimeSource`
QualifiedTarget	`helia_profiler.QualifiedTarget`
ProfileResult	`helia_profiler.ProfileResult`
PmuResult	`helia_profiler.PmuResult`
PresetResult	`helia_profiler.PresetResult`
LayerResult	`helia_profiler.LayerResult`
FirmwareMeta	`helia_profiler.FirmwareMeta`
RunMetadata	`helia_profiler.RunMetadata`
ResultManifest	`helia_profiler.ResultManifest`
ResultArtifact	`helia_profiler.ResultArtifact`
ResultIssue	`helia_profiler.ResultIssue`
ResultValidity	`helia_profiler.ResultValidity`
RunStatus	`helia_profiler.RunStatus`
load_result_manifest	`helia_profiler.load_result_manifest`
PowerMode	`helia_profiler.PowerMode`
PowerResult	`helia_profiler.PowerResult`
PowerObservation	`helia_profiler.PowerObservation`
PowerTerminalRecord	`helia_profiler.PowerTerminalRecord`
OnDevicePowerSummary	`helia_profiler.OnDevicePowerSummary`
PowerMetadata	`helia_profiler.PowerMetadata`
MeasurementScope	`helia_profiler.MeasurementScope`
ObservationMode	`helia_profiler.ObservationMode`
PowerIntegrity	`helia_profiler.PowerIntegrity`
CompareResult	`helia_profiler.CompareResult`
assess_comparability	`helia_profiler.assess_comparability`
ComparabilityAssessment	`helia_profiler.ComparabilityAssessment`
ComparabilityIssue	`helia_profiler.ComparabilityIssue`
ComparabilitySeverity	`helia_profiler.ComparabilitySeverity`
ComparisonProfile	`helia_profiler.ComparisonProfile`
evaluate_comparison_profile	`helia_profiler.evaluate_comparison_profile`
ComparisonVerdict	`helia_profiler.ComparisonVerdict`
MetricPolicy	`helia_profiler.MetricPolicy`
MetricDirection	`helia_profiler.MetricDirection`
MetricVerdict	`helia_profiler.MetricVerdict`
MissingMetricPolicy	`helia_profiler.MissingMetricPolicy`
VerdictStatus	`helia_profiler.VerdictStatus`
evaluate_run	`helia_profiler.evaluate_run`
RunEvaluation	`helia_profiler.RunEvaluation`
Expect	`helia_profiler.Expect`
Tolerance	`helia_profiler.Tolerance`
compare_fixture_outputs	`helia_profiler.compare_fixture_outputs`
compare_outputs	`helia_profiler.compare_outputs`
host_reference	`helia_profiler.host_reference`
Verification	`helia_profiler.Verification`
TensorComparison	`helia_profiler.TensorComparison`
ReferenceOutputs	`helia_profiler.ReferenceOutputs`
ReferenceOrigin	`helia_profiler.ReferenceOrigin`
ModelAnalysis	`helia_profiler.ModelAnalysis`
section_inventory	`helia_profiler.section_inventory`
SectionInventory	`helia_profiler.SectionInventory`
ElfSection	`helia_profiler.ElfSection`
LoadSegment	`helia_profiler.LoadSegment`
SupportBundleOptions	`helia_profiler.SupportBundleOptions`
collect_support_bundle	`helia_profiler.collect_support_bundle`
write_support_bundle	`helia_profiler.write_support_bundle`
verify_support_bundle	`helia_profiler.verify_support_bundle`
SupportBundleManifest	`helia_profiler.SupportBundleManifest`
SupportBundleSection	`helia_profiler.SupportBundleSection`
HpxError	`helia_profiler.HpxError`
ConfigError	`helia_profiler.ConfigError`
PlatformError	`helia_profiler.PlatformError`
EngineError	`helia_profiler.EngineError`
FirmwareError	`helia_profiler.FirmwareError`
BuildError	`helia_profiler.BuildError`
DependencyError	`helia_profiler.DependencyError`
VersionError	`helia_profiler.VersionError`
LockError	`helia_profiler.LockError`
NetworkError	`helia_profiler.NetworkError`
CaptureError	`helia_profiler.CaptureError`
DeterministicCaptureError	`helia_profiler.DeterministicCaptureError`
PowerError	`helia_profiler.PowerError`
ReportError	`helia_profiler.ReportError`

Machine-readable model

__version__attributeAPI tier: stable
profilefunctionRun a full profiling session.
ProgressUpdateclassUser-meaningful progress within a pipeline stage.
SessionclassImmutable, branchable configuration for interactive HPX operations.

__version__ = '0.4.1'

API tier: stable

profile(config: ProfileConfig, *, progress_sink: ProgressSink | None = None) -> ProfileResult

Run a full profiling session.

This is the main programmatic entry point. It builds the default pipeline, executes all stages, and returns a typed :class:ProfileResult.

The result includes the stored report evaluation, whose payload retains the experimental :class:RunEvaluation contract. Invalid evaluations are returned normally, including when output.fail_on_invalid is set; that exit policy belongs to the CLI.

Raises :class:HpxError (or a subclass) on failure.

API tier: stable

ProgressUpdate(
    message: str,
    kind: Literal['status', 'checkpoint'] = 'status',
    completed: int | None = None,
    total: int | None = None,
    unit: str | None = None,
    eta_s: float | None = None,
    min_verbosity: int = 0,
) -> None

dataclass

User-meaningful progress within a pipeline stage.

API tier: stable

message: str

kind: Literal['status', 'checkpoint'] = 'status'

completed: int | None = None

total: int | None = None

unit: str | None = None

eta_s: float | None = None

min_verbosity: int = 0

Session(
    yaml_path: Path | None = None,
    _base: Mapping[str, Any] = lambda : ...(),
    _overrides: Mapping[str, Any] = lambda : ...(),
) -> None

dataclass

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.

API tier: stable

yaml_path: Path | None = None

from_yaml(path: str | Path) -> Self

classmethod

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

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

classmethod

Create a session from unresolved configuration intent.

load(path: str | Path) -> Self

classmethod

Load a versioned unresolved-intent snapshot from JSON.

intent_dict() -> dict[str, Any]

Return JSON-safe unresolved intent without expanding defaults.

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

Return the fully resolved and validated configuration snapshot.

save(path: str | Path) -> Path

Persist unresolved intent as a versioned JSON snapshot.

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

Return a session with advanced raw configuration overrides merged in.

with_model(path: str | Path, **options: Any = {}) -> Self

with_engine(engine: Any, **options: Any = {}) -> Self

with_target(**options: Any = {}) -> Self

with_profiling(**options: Any = {}) -> Self

with_power(**options: Any = {}) -> Self

with_output(**options: Any = {}) -> Self

with_build(**options: Any = {}) -> Self

with_timeouts(**options: Any = {}) -> Self

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(model: str | Path | None = None) -> ProfileConfig

Resolve and validate this session as a complete profile config.

freeze(model: str | Path | None = None) -> FrozenRun

Resolve this session into a replayable :class:FrozenRun plan.

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

Run a profile using this session’s resolved configuration.

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

Analyze the configured model without building or flashing firmware.

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(*, include_versions: bool = False) -> DoctorResult

Return structured host dependency checks.

Set include_versions to also compare installed tool and package versions against the HPX compatibility baseline.

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

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

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

Return boards visible to this session’s platform registry.

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

Return supported inference engine identifiers.

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

Return registered PMU counter group names.

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

Return registered PMU counters, optionally filtered by group.

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

Return connected J-Link probes.

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

Inspect the target core visible through each connected probe.

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

Resolve the J-Link serial matching a board target.

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

Return host serial ports relevant to HPX transports.

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

Reset the configured target through its J-Link probe.

Machine-readable: helia_profiler.json · helia_profiler.md, complete and lossless.