Classes
class	Row

class	RowsError

class	Source

Functions
Any	loads_strict (str text)

Row	validate_row (dict raw, int source_index)

None	check_unique_ids (Iterable[Row] rows)

Source	read_source (Any source, int index=0)

str	canonical_space (dict space)

dict	common_space (Iterable[Source] sources, Any passed_space=None)

None	check_context (Iterable[Row] rows)

str	vector_key (dict parameters, dict space)

Variables
tuple	KINDS

tuple	STATUSES

Detailed Description

Shared reader for finished HPO trial rows.

One reader serves the post-hoc analysis modules. A source is a complete result
object, a rows JSONL file or a list of rows, and every row is checked the way
``continuation`` checks warm-start rows. Each refusal is a ``RowsError`` whose
``kind`` names the rule that failed. Nothing here evaluates a trial, writes a
file or keeps state: the only side effect is reading the one file named to
``read_source``.

Function Documentation

◆ canonical_space()

str pineforge_hpo._rows.canonical_space ( dict space )

Canonical v1 JSON of a recorded space (the form of continuation.py:143-181).

Definition at line 518 of file _rows.py.

◆ check_context()

None pineforge_hpo._rows.check_context ( Iterable[Row] rows )

Refuse rows whose scoring context visibly differs (necessary, not sufficient).

Among rows with status ``ok`` that carry a ``backtest`` object, the tuple
(input_bars_processed, script_bars_processed, input_tf_seconds,
script_tf_seconds) must be equal; every row that carries a ``space_hash`` must
carry the same one. Equal counters and hashes do not prove the same data,
window, fixed inputs or strategy (study-spec.md:1018-1020). The refusal names
the rows as (source_index, trial_id) pairs, starting from the lowest pair.

Definition at line 611 of file _rows.py.

◆ check_unique_ids()

None pineforge_hpo._rows.check_unique_ids ( Iterable[Row] rows )

Refuse a trial id that repeats inside one source (continuation.py:358-359).

Rows are keyed by (source_index, trial_id), so rows of several sources may be
passed together; the repeated ids are plain trial ids when every row belongs
to one source and (source_index, trial_id) pairs otherwise.

Definition at line 294 of file _rows.py.

◆ common_space()

dict pineforge_hpo._rows.common_space	(	Iterable[Source]	sources,
		Any	passed_space = `None`
	)

Return the one recorded space shared by every row and result of ``sources``.

A row's own ``space`` and a result's ``space`` must all have the same canonical
form (which includes the objective, its direction and its constraints), else
``space_mismatch`` naming the dimensions that differ and the offending rows.
When nothing records a space, ``passed_space`` (a recorded-space dict or a
StudySpec) is used; with none passed the call is refused as ``space_missing``.
A passed space is not compared with recorded ones. Rows or sources that record
no space are not checked against it.

Definition at line 552 of file _rows.py.

◆ loads_strict()

Any pineforge_hpo._rows.loads_strict ( str text )

``json.loads`` refusing duplicate keys, NaN/Infinity tokens and overflow.

Float tokens that overflow to infinity, and integer tokens too large for a
binary64, raise ``RowsError("input_invalid")`` like every other defect.

Definition at line 178 of file _rows.py.

◆ read_source()

Source pineforge_hpo._rows.read_source	(	Any	source,
		int	index = `0`
	)

Read one source into a Source whose rows are validated and in file order.

``source`` is a path to a result JSON or a rows JSONL, an already-parsed
result dict, or an already-parsed list of rows. A result must keep every
trial (``trials_out`` all or absent) and its counts must agree with its rows,
else ``rows_incomplete``. A JSONL file holds one row object per non-blank line;
a bad line is refused with its 1-based line number. A source with no rows is
returned empty. Rows from several sources are told apart by ``index``.

Definition at line 493 of file _rows.py.

◆ validate_row()

Row pineforge_hpo._rows.validate_row	(	dict	raw,
		int	source_index
	)

Check one row object (continuation.py:352-371) and return it as a Row.

Definition at line 234 of file _rows.py.

◆ vector_key()

str pineforge_hpo._rows.vector_key	(	dict	parameters,
		dict	space
	)

Canonical JSON key of a parameter vector (continuation.py:112-140, 363).

Each value becomes a typed scalar by its dimension's kind in ``space``; reals
are binary64 hex with -0.0 taken as +0.0 and an int in a real dimension taken
as the same real. Equality is exact: no tolerance and no lattice snapping.

Definition at line 693 of file _rows.py.

Variable Documentation

◆ KINDS

tuple pineforge_hpo._rows.KINDS

Initial value:

=  (
    "input_invalid",
    "rows_incomplete",
    "space_missing",
    "space_mismatch",
    "context_mismatch",
)

Definition at line 44 of file _rows.py.

◆ STATUSES

tuple pineforge_hpo._rows.STATUSES