kempnerpulse.reader.base¶

Layer 1 (Read) — backend contract and raw records.

This layer acquires raw data from one source and emits a stream of opaque RawRecord objects keyed by the source’s own field names. By design, this layer:

never coerces an N/A reading to 0.0 (it uses None);

never looks up field meanings — naming, units, and missing-value policy are Layer 2’s responsibility;

never blocks on user input or installs signal handlers (that belongs to the cross-cutting tier).

Its runtime dependencies are the standard library only.

Classes

`Backend`	Layer 1 contract.
`BackendCaps`	What a backend can produce.
`BackendKind`	Which Layer-1 source produced a record.
`RawRecord`	One reading for one entity (a GPU or MIG slice), in the source's vocabulary.
`ReaderConfig`	Minimal Layer-1 configuration.

Exceptions

`DcgmStreamError`	The `dcgmi dmon` streaming subprocess failed or exited unexpectedly.
`ExporterCollisionDetected`	`dcgm-exporter` already holds the profiling watch; recommend `--backend prometheus`.
`HostEngineUnavailableError`	`nv-hostengine` is not reachable on the local socket.
`ReaderError`	Base for Layer-1 read failures.
`ReservationDeniedError`	Could not acquire the requested DCGM watch fields without dropping another consumer.

class kempnerpulse.reader.base.BackendKind[source]¶

Bases: Enum

Which Layer-1 source produced a record.

DCGMI = 'dcgmi'¶

PROMETHEUS = 'prometheus'¶

REPLAY = 'replay'¶

NVML_DIRECT = 'nvml_direct'¶

class kempnerpulse.reader.base.RawRecord[source]¶

Bases: object

One reading for one entity (a GPU or MIG slice), in the source’s vocabulary.

fields carries the source’s raw key/values for this entity — metric values (typically float) and any source labels (str). A value is None when the source reported N/A; it is never silently coerced to 0. Assigning meaning to these keys (canonical names, units, identity) is Layer 2’s job.

timestamp: float¶

wallclock: float¶

entity_id: str¶

fields: Mapping[str, Any | None]¶

source: str¶

source_version: str¶

error: str | None = None¶

__init__(timestamp, wallclock, entity_id, fields, source, source_version, error=None)¶

Parameters:

timestamp (float)
wallclock (float)
entity_id (str)
fields (Mapping[str, Any | None])
source (str)
source_version (str)
error (str | None)

Return type:

None

class kempnerpulse.reader.base.BackendCaps[source]¶

Bases: object

What a backend can produce.

fields is the set of source field names this backend can emit. Layer 2 uses it to decide which canonical metrics are available for a given source.

kind: BackendKind¶

fields: frozenset[str]¶

__init__(kind, fields=<factory>)¶

Parameters:

kind (BackendKind)
fields (frozenset[str])

Return type:

None

class kempnerpulse.reader.base.ReaderConfig[source]¶

Bases: object

Minimal Layer-1 configuration.

A deliberately small, self-contained slice of configuration so that Layer 1 can be constructed and tested on its own. The cross-cutting configuration tier supplies these values from parsed CLI arguments.

backend: BackendKind = 'dcgmi'¶

poll_seconds: float = 0.1¶

source: str = 'http://localhost:9400/metrics'¶

gpu_ids: tuple[str, ...] | None = None¶

all_gpus: bool = False¶

timeout: float = 5.0¶

__init__(backend=BackendKind.DCGMI, poll_seconds=0.1, source='http://localhost:9400/metrics', gpu_ids=None, all_gpus=False, timeout=5.0)¶

Parameters:

backend (BackendKind)
poll_seconds (float)
source (str)
gpu_ids (tuple[str, ...] | None)
all_gpus (bool)
timeout (float)

Return type:

None

class kempnerpulse.reader.base.Backend[source]¶

Bases: Protocol

Layer 1 contract. Implementations: dcgmi, prometheus, replay.

open(config)[source]¶

Acquire the source (spawn dcgmi, open the HTTP scrape, open the replay file).

Backends that contend for a shared resource (dcgmi profiling watch) run their preflight here and raise a typed ReaderError with remediation on failure.