1 rollouts.presentation.reports

rollouts.presentation.reports

Deterministic pandas projections and JSON bundles for rollout evidence.

The module is a read-only adapter over aria_nbv.rollouts.inspection. It gives Streamlit, thesis authoring, and offline analysis one stable table contract without reimplementing rollout statistics or parsing Zarr arrays in presentation code. Heavy candidate rows remain in the rollout store.

1.1 Attributes

Name	Description
ANALYSIS_FACT_SIDECAR_VERSION	Schema version for sidecars that promote analysis outputs into facts.
THESIS_REPORT_BUNDLE_ROLE	Semantic role required by submission-facing Typst report consumers.
THESIS_REPORT_BUNDLE_VERSION	Schema version for compact thesis-report JSON bundles.
THESIS_REPORT_TABLE_COLUMNS	Stable table names and column order consumed by the thesis bundle.

1.2 Classes

Name	Description
RolloutCorpusAcquisition	Complete report evidence acquired from one selected rollout shard.
RolloutCorpusSummary	Safe additive evidence across explicitly selected rollout stores.

1.2.1 RolloutCorpusAcquisition

rollouts.presentation.reports.RolloutCorpusAcquisition(
    selected_path,
    included_store,
    frames,
    q_h_row,
    excluded_store,
)

Complete report evidence acquired from one selected rollout shard.

The acquisition is the cacheable seam between immutable shard I/O and corpus-wide reduction. Exactly one of frames or excluded_store is populated. Valid acquisitions retain the original report frames and deep Q_H row so corpus reducers recompute statistics from unchanged source rows; per-shard quantiles are never merged.

1.2.1.1 Attributes

Name	Description
selected_path	Canonical selected shard path.
included_store	Validated identity and persisted compatibility contract.
frames	Complete canonical report frames for a valid shard.
q_h_row	Complete deep-Q_H evidence for a valid shard.
excluded_store	Canonical path and exact acquisition error for an invalid shard.

1.2.2 RolloutCorpusSummary

rollouts.presentation.reports.RolloutCorpusSummary(
    verdict,
    selected_paths,
    included_stores,
    excluded_stores,
    totals,
    candidate_support,
    endpoints,
    failure_counts,
    q_h_stores,
    temporal_source=pd.DataFrame(),
    budget_coverage=pd.DataFrame(),
    temporal_summary=pd.DataFrame(),
    target_admission=pd.DataFrame(),
    feasibility=pd.DataFrame(),
    contract_totals=pd.DataFrame(),
)

Safe additive evidence across explicitly selected rollout stores.

1.2.2.1 Attributes

Name	Description
verdict	Whether every selected store contributed validated evidence.
selected_paths	Normalized requested store paths in deterministic order.
included_stores	Validated store identities and profiles included in all totals.
excluded_stores	Selected stores excluded with exact validation or projection reasons.
totals	Additive store, rollout, storage, and complete deep-Q_H counts.
candidate_support	Additive candidate support grouped by exact generation cohort and family.
endpoints	Store-qualified diagnostic endpoint rows, preserving profile, policy, and horizon.
failure_counts	Failure counts grouped only by kind and severity.
q_h_stores	Per-store deep Q_H counts and any explicit unavailability reason.
temporal_source	Complete validated store-qualified rows available for temporal queries.
budget_coverage	Factual remaining-budget support reduced once from the validated source.
temporal_summary	Factual finite-only depth summaries, separated by persisted contract.
target_admission	Additive target-admission counts across validated stores.
feasibility	Additive collision and clearance availability evidence by exact cohort.
contract_totals	Deterministic additive totals faceted by persisted compatibility contract.

1.3 Functions

Name	Description
acquire_rollout_corpus_store	Acquire complete report and deep-Q_H evidence for one rollout shard.
build_rollout_corpus_summary	Build a safe corpus summary while preserving the public path interface.
build_thesis_report_frames	Build deterministic named DataFrames from rollout stores and sidecars.
candidate_benchmark_report_frames	Project an immutable benchmark bundle into report-owned data frames.
reduce_rollout_corpus_acquisitions	Reduce independently acquired shards into one safe corpus summary.
serialize_thesis_report_bundle	Serialize report frames as strict, compact, byte-stable JSON.
summarize_temporal_population	Summarize a filtered temporal population for descriptive exploration.
write_thesis_report_bundle	Atomically write a thesis-report bundle and return its SHA-256 digest.

1.3.1 acquire_rollout_corpus_store

rollouts.presentation.reports.acquire_rollout_corpus_store(store_path)

Acquire complete report and deep-Q_H evidence for one rollout shard.

Persistence I/O, decoding, and value-validation failures are returned as explicit exclusions so an invalid selected shard remains visible without contributing scientific rows. Unexpected programming errors propagate; they must not silently shrink the reported population.

1.3.2 build_rollout_corpus_summary

rollouts.presentation.reports.build_rollout_corpus_summary(store_paths)

Build a safe corpus summary while preserving the public path interface.

1.3.3 build_thesis_report_frames

rollouts.presentation.reports.build_thesis_report_frames(
    store_paths,
    *,
    sidecar_paths=(),
    evidence_status,
    table_names=None,
)

Build deterministic named DataFrames from rollout stores and sidecars.

1.3.3.1 Parameters

Name	Type	Description	Default
store_paths	Iterable[Path | str]	Current-schema rollout Zarr stores. Every store is fully validated before its facts enter the report.	required
sidecar_paths	Iterable[Path | str]	Optional caller-selected JSON or JSONL evidence files. Selected paths are required to exist; missing files never disappear silently from provenance.	()
evidence_status	Literal['pilot', 'confirmatory']	Explicit scientific status for all projected facts. Callers must choose pilot or confirmatory; file names and paths never determine this status.	required
table_names	Iterable[str] | None	Optional output dependency closure. None preserves the complete report-v1 projection. The bounded stores/facts reporting path may stop before unrelated target, tree, depth, and Q_H diagnostics while retaining full store admission.	None

1.3.3.2 Returns

Name	Type	Description
	dict[str, pd.DataFrame]	Mapping whose keys and columns exactly match
	dict[str, pd.DataFrame]	data:THESIS_REPORT_TABLE_COLUMNS. Config values, statistics, and
	dict[str, pd.DataFrame]	sidecar leaves use typed long-form rows so missing values remain
	dict[str, pd.DataFrame]	distinguishable from zero or an empty string.

1.3.4 candidate_benchmark_report_frames

rollouts.presentation.reports.candidate_benchmark_report_frames(
    path,
    *,
    expected_binding,
)

Project an immutable benchmark bundle into report-owned data frames.

The bundle reader remains the sole authority for validation and DTO decoding. This adapter is intentionally small so Typst/report exports consume exactly the same canonical records as the Streamlit inspector.

1.3.5 reduce_rollout_corpus_acquisitions

rollouts.presentation.reports.reduce_rollout_corpus_acquisitions(acquisitions)

Reduce independently acquired shards into one safe corpus summary.

Every store first crosses the canonical report validation and promotion seam. Invalid selections remain visible in excluded_stores. Valid stores contribute additive counts, exact-cohort candidate support, raw store-qualified diagnostic endpoints, and grouped failure counts. Q_H mask totals are reported only when every included store completes the explicit deep count.

1.3.6 serialize_thesis_report_bundle

rollouts.presentation.reports.serialize_thesis_report_bundle(
    frames,
    *,
    candidate_benchmark_path=None,
    candidate_benchmark_binding=None,
)

Serialize report frames as strict, compact, byte-stable JSON.

The serializer rejects missing or extra tables, column drift, and infinite floats. Pandas and NumPy missing scalars become JSON null. It adds no build timestamp, so identical frames produce identical bytes.

1.3.7 summarize_temporal_population

rollouts.presentation.reports.summarize_temporal_population(
    source,
    *,
    group_fields,
    metrics=_DEFAULT_TEMPORAL_EXPLORER_METRICS,
)

Summarize a filtered temporal population for descriptive exploration.

The caller filters RolloutCorpusSummary.temporal_source before this reducer. Persisted scientific contracts are always separate. Other omitted experiment controls, including policy, temperature, horizon, branch factor, and beam width, are intentionally pooled and marked as descriptive mixed- series evidence rather than a matched or causal comparison.

1.3.7.1 Parameters

Name	Type	Description	Default
source	pd.DataFrame	Complete or caller-filtered annotated temporal source rows.	required
group_fields	Iterable[str]	Explicit supported experiment strata retained in the output. Omitted strata are descriptively pooled within a contract.	required
metrics	Iterable[str]	Supported temporal metrics. The default exposes cumulative root gain and selected one-step target RRI.	_DEFAULT_TEMPORAL_EXPLORER_METRICS

1.3.7.2 Returns

Name	Type	Description
	pd.DataFrame	One row per contract, requested group, metric, and factual step. Counts
	pd.DataFrame	distinguish the observed physical stores, store-qualified rollouts,
	pd.DataFrame	and scenes from those contributing a finite value for that metric.
	pd.DataFrame	Source-row, finite-value, and missing-value counts remain explicit.
	pd.DataFrame	Quartiles retain the inspection owner’s linear-interpolation semantics.

1.3.7.3 Raises

Name	Type	Description
	ValueError	If required annotations are absent, contract fields are requested as user groups, or a metric/group is unsupported.

1.3.8 write_thesis_report_bundle

rollouts.presentation.reports.write_thesis_report_bundle(
    path,
    frames,
    *,
    candidate_benchmark_path=None,
    candidate_benchmark_binding=None,
)

Atomically write a thesis-report bundle and return its SHA-256 digest.