1 lightning.finite_horizon.diagnostics.history

lightning.finite_horizon.diagnostics.history

Bounded local metric history for opt-in finite-horizon diagnostic fits.

The JSONL stream is observational: write failures are retained as telemetry status and never propagate into fitting. Each append is one complete encoded line, while readers tolerate only an incomplete final line so interrupted fits remain inspectable without accepting corrupt completed records.

1.1 Classes

Name Description
QhDiagnosticHistory Validated complete prefix of one local diagnostic history.
QhDiagnosticHistoryCallback Observe completed Lightning updates and real validation loops.
QhDiagnosticHistoryIdentity Caller-owned location identities for one diagnostic fit attempt.
QhDiagnosticHistoryStatus Non-authoritative state of the optional telemetry sidecar.
QhDiagnosticHistoryWriter Best-effort append owner whose failures never escape into fitting.

1.1.1 QhDiagnosticHistory

lightning.finite_horizon.diagnostics.history.QhDiagnosticHistory(
    identity,
    events,
    status,
)

Validated complete prefix of one local diagnostic history.

1.1.1.1 Attributes

Name Description
identity Exact identity mapping shared by every admitted event.
events Ordered events with a contiguous zero-based sequence.
status Complete or partial reader status and digest of admitted bytes.

1.1.2 QhDiagnosticHistoryCallback

lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryCallback(writer)

Observe completed Lightning updates and real validation loops.

1.1.2.1 Methods

Name Description
record_final_train_step Emit the exact final loss when observed, otherwise declare it unavailable.
1.1.2.1.1 record_final_train_step
lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryCallback.record_final_train_step(
    optimizer_update,
)

Emit the exact final loss when observed, otherwise declare it unavailable.

1.1.3 QhDiagnosticHistoryIdentity

lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryIdentity(
    cell_id,
    fold_id,
    seed,
)

Caller-owned location identities for one diagnostic fit attempt.

1.1.3.1 Attributes

Name Description
cell_id Stable matrix or experiment cell identity.
fold_id Stable train/validation/test fold identity.
seed Fit seed, duplicated here so a history is self-identifying.

1.1.4 QhDiagnosticHistoryStatus

lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryStatus(
    state,
    path,
    event_count=0,
    content_sha256=None,
    error=None,
)

Non-authoritative state of the optional telemetry sidecar.

1.1.4.1 Attributes

Name Description
state Lifecycle state; only complete proves a terminal event was retained.
path Explicit attempt path outside the fit output directory, when enabled.
event_count Number of complete events successfully appended or admitted by the reader.
content_sha256 Digest of complete admitted JSONL bytes; an incomplete tail is excluded.
error Typed instrumentation failure detail; it is never a fit result.

1.1.5 QhDiagnosticHistoryWriter

lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryWriter(
    path,
    *,
    identity,
    fit_identities,
    dataset_identities,
)

Best-effort append owner whose failures never escape into fitting.

1.1.5.1 Attributes

Name Description
status Return the current telemetry status without changing fit state.

1.1.5.2 Methods

Name Description
record_train_step Retain each 25th completed update and remember the latest for finalization.
record_final_train_step Retain the final completed update when it was not already emitted.
record_validation Retain one realized validation check with its exact horizon reductions.
record_terminal Bind the terminal fit receipt without granting telemetry result authority.
close Close the attempt stream; close failures remain telemetry-only.
record_instrumentation_failure Convert an observer failure into status without interrupting fitting.
1.1.5.2.1 record_train_step
lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryWriter.record_train_step(
    optimizer_update,
    loss,
)

Retain each 25th completed update and remember the latest for finalization.

1.1.5.2.2 record_final_train_step
lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryWriter.record_final_train_step(
    optimizer_update,
)

Retain the final completed update when it was not already emitted.

1.1.5.2.3 record_validation
lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryWriter.record_validation(
    module,
)

Retain one realized validation check with its exact horizon reductions.

1.1.5.2.4 record_terminal
lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryWriter.record_terminal(
    fit_status,
    fit_receipt_sha256,
    completed_optimizer_updates,
)

Bind the terminal fit receipt without granting telemetry result authority.

1.1.5.2.5 close
lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryWriter.close()

Close the attempt stream; close failures remain telemetry-only.

1.1.5.2.6 record_instrumentation_failure
lightning.finite_horizon.diagnostics.history.QhDiagnosticHistoryWriter.record_instrumentation_failure(
    error,
)

Convert an observer failure into status without interrupting fitting.

1.2 Functions

Name Description
read_qh_diagnostic_history Validate a bounded JSONL history, ignoring only an incomplete final line.
validate_qh_diagnostic_fit_receipt Validate the diagnostic fit receipt bound by one complete history.

1.2.1 read_qh_diagnostic_history

lightning.finite_horizon.diagnostics.history.read_qh_diagnostic_history(path)

Validate a bounded JSONL history, ignoring only an incomplete final line.

1.2.2 validate_qh_diagnostic_fit_receipt

lightning.finite_horizon.diagnostics.history.validate_qh_diagnostic_fit_receipt(
    history,
    path,
    *,
    receipt_bytes=None,
)

Validate the diagnostic fit receipt bound by one complete history.

The terminal event binds the exact receipt bytes. The receipt must then reproduce the history’s fit identity: seed, objective, representation, scorer configuration, execution controls, and each realized dataset contract. This prevents a digest-consistent but unrelated JSON document from being promoted as Q_H training evidence.

A null selected loss is admitted only for explicit final-update diagnostics with validation disabled, matching zero actual checkpoint counters and selection-receipt aggregates. It remains unmeasured, not a zero loss.

receipt_bytes permits an acquisition owner to validate the exact bytes already hashed and parsed, without reopening a mutable source. When omitted, the existing path-based read and error behavior are retained.

1.2.2.1 Returns

Name Type Description
str SHA-256 digest of the validated receipt bytes.

1.2.2.2 Raises

Name Type Description
ValueError If the history is incomplete, the receipt is not a diagnostic fit receipt, or any bound identity disagrees.
Back to top