1 rollouts.storage.manifest
rollouts.storage.manifest
Top-level manifest helpers for standalone rollout Zarr stores.
The rollout store keeps large replay facts in Zarr arrays, while this module owns the small JSON sidecar that should be inspectable with normal shell tools. The manifest is intentionally outside the Zarr payload so users can understand how a store was generated without loading candidate, step, or target arrays.
1.1 Attributes
| Name | Description |
|---|---|
| ROLLOUT_MANIFEST_FILENAME | Filename of the human-readable rollout-store sidecar manifest. |
| ROLLOUT_MANIFEST_VERSION | Version tag for the top-level rollout-store manifest payload. |
1.2 Classes
| Name | Description |
|---|---|
| RolloutStoreInvocation | How a rollout store generation run was invoked. |
| RolloutStoreManifestContext | Optional rich context attached by higher-level rollout writers. |
| RriMetricPolicy | Numerical policy used to generate persisted RRI-family metrics. |
1.2.1 RolloutStoreInvocation
rollouts.storage.manifest.RolloutStoreInvocation(
mode='programmatic',
argv=(),
config_path=None,
raw_toml_text=None,
raw_toml_sha256=None,
)How a rollout store generation run was invoked.
1.2.1.1 Attributes
| Name | Description |
|---|---|
| mode | Invocation mode used to produce the store. |
| argv | Command arguments for CLI runs. |
| config_path | Resolved TOML path for CLI runs. |
| raw_toml_text | Raw TOML text supplied to the writer CLI. |
| raw_toml_sha256 | SHA-256 of raw_toml_text. |
1.2.1.2 Methods
| Name | Description |
|---|---|
| programmatic | Return the default invocation for non-CLI calls. |
| from_cli | Build CLI invocation metadata from parsed arguments and TOML source. |
| to_jsonable | Return JSON-friendly invocation metadata. |
1.2.1.2.1 programmatic
rollouts.storage.manifest.RolloutStoreInvocation.programmatic()Return the default invocation for non-CLI calls.
1.2.1.2.2 from_cli
rollouts.storage.manifest.RolloutStoreInvocation.from_cli(argv, config_path)Build CLI invocation metadata from parsed arguments and TOML source.
1.2.1.2.3 to_jsonable
rollouts.storage.manifest.RolloutStoreInvocation.to_jsonable()Return JSON-friendly invocation metadata.
1.2.2 RolloutStoreManifestContext
rollouts.storage.manifest.RolloutStoreManifestContext(
writer_config=None,
invocation=RolloutStoreInvocation.programmatic(),
runtime=dict(),
shard=None,
candidate_family_preflight=None,
metric_policy=None,
target_task_sampling=None,
)Optional rich context attached by higher-level rollout writers.
1.2.2.1 Attributes
| Name | Description |
|---|---|
| writer_config | Resolved writer configuration, if available. |
| invocation | How generation was invoked. |
| runtime | Runtime provenance such as git and package versions. |
| shard | Optional rollout shard manifest entry for cluster generation runs. |
| candidate_family_preflight | Complete persisted candidate-family policy for reader-backed gates. |
| metric_policy | Numerical metric policy, present only when this run computes RRI-family values. |
| target_task_sampling | Source-bound eligible target pools and selected probabilities, when admission is enabled. |
1.2.2.2 Methods
| Name | Description |
|---|---|
| programmatic | Build provenance context for a non-CLI rollout-store invocation. |
| from_cli | Build context for nbv-build-rollouts CLI runs. |
| to_jsonable | Return the resolved writer, invocation, runtime, and shard metadata. |
1.2.2.2.1 programmatic
rollouts.storage.manifest.RolloutStoreManifestContext.programmatic(
writer_config=None,
)Build provenance context for a non-CLI rollout-store invocation.
The optional resolved writer configuration is serialized into the sidecar together with current runtime provenance. No source payloads or mutable runtime objects are retained.
1.2.2.2.2 from_cli
rollouts.storage.manifest.RolloutStoreManifestContext.from_cli(
writer_config,
argv,
config_path,
)Build context for nbv-build-rollouts CLI runs.
1.2.2.2.3 to_jsonable
rollouts.storage.manifest.RolloutStoreManifestContext.to_jsonable()Return the resolved writer, invocation, runtime, and shard metadata.
The returned mapping is suitable for stable JSON serialization and intentionally contains provenance only; heavy rollout facts remain in normalized Zarr arrays.
1.2.3 RriMetricPolicy
rollouts.storage.manifest.RriMetricPolicy(epsilon)Numerical policy used to generate persisted RRI-family metrics.
1.2.3.1 Attributes
| Name | Description |
|---|---|
| epsilon | Positive additive guard shared by normalized and logarithmic gains. |
| revision | Stable identifier for the additive-epsilon formula family. |
| normalized_gain_denominator | Denominator policy for RRI and rollout-root normalized gains. |
| log_error_guard | Guard policy applied to each logarithmic error term. |
1.2.3.2 Methods
| Name | Description |
|---|---|
| to_jsonable | Return the stable manifest representation of this policy. |
1.2.3.2.1 to_jsonable
rollouts.storage.manifest.RriMetricPolicy.to_jsonable()Return the stable manifest representation of this policy.
1.3 Functions
| Name | Description |
|---|---|
| collect_runtime_provenance | Collect runtime and installed geometry-provider identity for a store. |
| manifest_sha256 | Return the SHA-256 for the canonical manifest JSON bytes. |
| read_rollout_store_manifest | Read the human-inspectable manifest beside a rollout Zarr payload. |
| utc_timestamp | Return an ISO-8601 UTC timestamp for metadata payloads. |
| write_rollout_store_manifest | Write manifest.json next to zarr.json and return its SHA-256. |
1.3.1 collect_runtime_provenance
rollouts.storage.manifest.collect_runtime_provenance(cwd=None)Collect runtime and installed geometry-provider identity for a store.
Distribution metadata records the exact source independently of configured devices. It does not prove a working compiled kernel; the backend preflight and actual generation observations provide that separate execution proof.
1.3.2 manifest_sha256
rollouts.storage.manifest.manifest_sha256(payload)Return the SHA-256 for the canonical manifest JSON bytes.
1.3.3 read_rollout_store_manifest
rollouts.storage.manifest.read_rollout_store_manifest(store_dir)Read the human-inspectable manifest beside a rollout Zarr payload.
1.3.3.1 Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| store_dir | Path | str | Standalone rollout-store directory containing manifest.json. |
required |
1.3.3.2 Returns
| Name | Type | Description |
|---|---|---|
| dict[str, Any] | Parsed provenance and schema metadata. The function performs no Zarr | |
| dict[str, Any] | reads and does not mutate the completed store. |
1.3.4 utc_timestamp
rollouts.storage.manifest.utc_timestamp()Return an ISO-8601 UTC timestamp for metadata payloads.
1.3.5 write_rollout_store_manifest
rollouts.storage.manifest.write_rollout_store_manifest(store_dir, payload)Write manifest.json next to zarr.json and return its SHA-256.