OakEmu-RL v0.1.0

Appearance

TrajectoryStore ​

python
TrajectoryStore(store_configuration: TrajectoryStoreConfiguration, replay_selection_configuration: TrajectorySelectionConfiguration, start_selection_configuration: TrajectorySelectionConfiguration, rng: random.Random, *, utilities: TrajectoryUtilitiesConfiguration | None = None, backward_curriculum: BackwardCurriculumConfiguration | None = None, require_start_frame_stacks: bool = False) -> None

Shared replay and start-state stores for trajectory-driven training.

Source

Properties ​

archived_best_route ​

python
archived_best_route: TrajectoryRepositoryPath | None

Get the stored path of the highest-priority archived route, or None when the archive is empty.

The route-level priority packs the win tiebreak field and the route's action count into one float (see CaptureProcessor._route_priority), which makes small improvements unreadable once the value is logged as float32 -- its spacing near the win-dominance offset of 1e9 is 64, so an improvement of fewer than ~64 actions is quantised away entirely. Exposing the path itself lets the reporter emit the action count and tiebreak value as their own metrics.

Source

archived_max_priority ​

python
archived_max_priority: float | None

Get the highest archived route priority, or None when the archive is empty.

Source

archived_path_count ​

python
archived_path_count: int

Get the number of routes currently held in the best-route archive.

Source

backward_curriculum ​

python
backward_curriculum: BackwardCurriculum

The receding-front curriculum over the archived route (inert unless enabled in configuration).

Source

bucket_count ​

python
bucket_count: int

Source

cell_statistics ​

python
cell_statistics: TrajectoryCellStatistics

The store's cell-level statistics: visit/reach/successor counts, competence tables, successor route values and route costs. Callers record and read through this object directly; the store only owns its lifecycle and persistence.

Source

wins_recorded ​

python
wins_recorded: int

Get the number of winning episodes ingested into the store.

Source

Methods ​

add_path ​

python
add_path(recordings: list[TrajectoryRecording], *, prefix_recordings: list[TrajectoryRecording] | None = None, priority: float = 0.0, archive_eligible: bool = True) -> list[TrajectoryInsertOutcome]

Store one episode path and index its segments for replay and midpoint starts.

When prefix_recordings is given (a midpoint episode continuing a stored route), the prefix and the new segments are stored flat as one canonical path so no parent-lineage chains are created; the prefix's snapshot bytes objects are shared with the parent path by reference, and only the new segments are indexed.

The whole route is offered to the best-route archive at priority: when it beats the worst archived route (or the archive is not yet full) it is retained there independently of the per-cell buckets, so the best full routes survive ordinary retention churn for sub-segment BC.

Parameters:

  • recordings (list[TrajectoryRecording]) – The newly recorded segments in episode order.
  • prefix_recordings (list[TrajectoryRecording] | None) – Optional already-stored route segments leading to the first recording.
  • priority (float) – The route-level priority score used for best-route archiving.

Returns:

  • list[TrajectoryInsertOutcome] – The replay-store outcomes for recordings.

Source

archived_route_ids ​

python
archived_route_ids() -> list[int]

Return the trajectory ids of every archived best route.

Source

archived_route_priorities ​

python
archived_route_priorities() -> dict[int, float]

Return each archived best route's priority keyed by trajectory id.

Source

curriculum_action_restart_coverage ​

python
curriculum_action_restart_coverage() -> tuple[int, int]

Return (minted per-action restarts, route actions) for the archived route in granular mode.

Observable rather than inferred, for the same reason as frame-stack coverage: an unminted route looks exactly like a hard one (a front that never moves).

Source

curriculum_frame_stack_coverage ​

python
curriculum_frame_stack_coverage() -> tuple[int, int]

Return (segments with a frame stack, total segments) for the archived route.

Whether restarts are seeded must be observable rather than inferred: a run where the stacks were never built looks exactly like one where acquisition is genuinely hard -- both show a front that will not move -- and that ambiguity cost a full overnight run on 2026-08-10. Reports (0, 0) in action_granular mode; see curriculum_action_restart_coverage there instead.

Source

curriculum_route_needing_action_restarts ​

python
curriculum_route_needing_action_restarts() -> tuple[int, TrajectoryRepositoryPath] | None

Return the archived route whose per-action restarts have not been minted, or None.

Only meaningful in action_granular mode. Like frame stacks, restarts are derived by replay and rebuilt rather than checkpointed; the caller owns the emulator.

Source

curriculum_route_needing_frame_stacks ​

python
curriculum_route_needing_frame_stacks() -> tuple[int, TrajectoryRepositoryPath] | None

Return the archived route whose segments have no frame stacks yet, or None when none is due.

Stacks are derived by replaying the route, so they are rebuilt rather than checkpointed. The caller owns an emulator and does the replay; this only says which route needs it. Never due in action_granular mode, where the per-action restarts carry their own stacks.

Source

frame_stack_coverage ​

python
frame_stack_coverage() -> tuple[int, int]

Return (seeded, total) start-eligible restorable segment counts across all stored paths.

Returns:

  • tuple[int, int] – The seeded and total counts.

Source

load_runtime_state_dict ​

python
load_runtime_state_dict(state: dict[str, Any]) -> None

Source

materialize_prefix_segments ​

python
materialize_prefix_segments(reference: TrajectorySliceReference) -> list[TrajectoryRecording] | None

Materialize the archived prefix a midpoint episode continued from, for stitching into a full route.

In action_granular mode the reference's index is a RUNG (an action offset), not a segment. The prefix machinery is segment-aligned, so a prefix is only materialized when the offset lands exactly on a segment boundary; a mid-segment offset returns None and the episode is not stitched into the archive (its outcome still counts for the curriculum). Segment mode returns the prefix as before.

Parameters:

  • reference (TrajectorySliceReference) – The restart reference the episode began from.

Returns:

  • list[TrajectoryRecording] | None – The prefix recordings, or None when the restart cannot be stitched.

Source

materialize_slice ​

python
materialize_slice(trajectory_id: int, *, start_segment: int, min_actions: int = 16, max_actions: int = 48) -> TrajectoryRecording

Materialize a contiguous min_actions..max_actions slice of a stored route.

Source

paths_needing_frame_stacks ​

python
paths_needing_frame_stacks(limit: int) -> list[tuple[int, TrajectoryRepositoryPath]]

Return up to limit stored paths with restorable segments missing frame stacks, newest first.

Parameters:

  • limit (int) – The maximum number of paths to return.

Returns:

  • list[tuple[int, TrajectoryRepositoryPath]] – (trajectory_id, path) pairs needing a frame-stack replay.

Source

record_win ​

python
record_win() -> None

Record that one winning episode has been ingested.

Source

refresh_backward_curriculum ​

python
refresh_backward_curriculum() -> int | None

Point the curriculum at the current best archived route and return that route's trajectory id.

Called on the capture path so the front tracks whichever route is archived now: if the archive is displaced by a better route, the curriculum re-anchors to it rather than filtering against a trajectory id that no longer exists.

Returns:

  • int | None – The archived route's trajectory id, or None when nothing is archived.

Source

release_reference ​

python
release_reference(reference: TrajectorySliceReference) -> None

Source

replay_metric_summary ​

python
replay_metric_summary(metric_key: str, *, floor: float | None = None) -> TrajectoryMetricSummary | None

Source

repository_diagnostics ​

python
repository_diagnostics() -> TrajectoryRepositoryDiagnostics

Return repository occupancy diagnostics for debugging hidden retained lineage.

Source

repository_path ​

python
repository_path(trajectory_id: int) -> TrajectoryRepositoryPath | None

Return the stored route for trajectory_id, or None when absent.

Source

retain_reference ​

python
retain_reference(reference: TrajectorySliceReference) -> None

Source

runtime_state_dict ​

python
runtime_state_dict() -> dict[str, Any]

Source

sample_curriculum_start ​

python
sample_curriculum_start(rng: random.Random) -> tuple[TrajectoryRecording, TrajectorySliceReference, bytes | None] | None

Materialize a restart state from the archived route at the backward curriculum's front.

This deliberately bypasses the segment store's buckets. The archive pins the route's path in the repository, so its segments are always available at full precision for as long as the route is archived -- unlike bucket entries, which priority retention evicts. Restoring to the END of the sampled segment leaves the route's remaining segments for the policy to play.

Parameters:

  • rng (Random) – The selector's random source, used to pick a segment within the front band.

Returns:

  • tuple[TrajectoryRecording, TrajectorySliceReference, bytes | None] | None – The restart recording, its slice reference and the frame stack to seed the observation with (None when it has not been rebuilt yet), or None when nothing is archived.

Source

sample_replay_with_reference ​

python
sample_replay_with_reference(*, filter_fn: TrajectoryRecordFilter | None = None, context: TrajectorySamplingContext | None = None) -> tuple[TrajectoryRecording, TrajectorySliceReference] | None

Source

sample_start_with_reference ​

python
sample_start_with_reference(*, filter_fn: TrajectoryRecordFilter | None = None, context: TrajectorySamplingContext | None = None) -> tuple[TrajectoryRecording, TrajectorySliceReference, bytes | None] | None

Sample a midpoint restart segment from the cell buckets.

With require_start_frame_stacks on, only segments whose restart frame stack has been minted are offered, and the stack is returned alongside; a restart is then never blind. Off, the stack element is whatever the segment holds (usually None).

Parameters:

  • filter_fn (TrajectoryRecordFilter | None) – Optional additional predicate over candidate recordings.
  • context (TrajectorySamplingContext | None) – Optional sampling context.

Returns:

  • tuple[TrajectoryRecording, TrajectorySliceReference, bytes | None] | None – The recording, its reference and the restart frame stack, or None when nothing matches.

Source

segment_buckets_view ​

python
segment_buckets_view() -> ItemsView[TrajectoryKey, TrajectoryBucket]

Return the live (key, bucket) pairs of the segment index; callers must not mutate them.

Source

segment_debug_bucket_weights ​

python
segment_debug_bucket_weights(name: str, *, context: TrajectorySamplingContext) -> dict[TrajectoryKey, float]

Return one named segment selector's current per-bucket sampling weights, for checkpoint debug exports.

Source

set_action_restarts ​

python
set_action_restarts(trajectory_id: int, restarts: dict[int, tuple[bytes, bytes]]) -> None

Attach minted per-action restarts to a stored route.

Parameters:

  • trajectory_id (int) – The route they were minted from.
  • restarts (dict[int, tuple[bytes, bytes]]) – Offset -> (machine state, frame stack).

Source

set_frame_stacks ​

python
set_frame_stacks(trajectory_id: int, frame_stacks: dict[int, bytes]) -> bool

Attach rebuilt frame stacks to a stored route.

Parameters:

  • trajectory_id (int) – The route to attach to.
  • frame_stacks (dict[int, bytes]) – Segment index -> the stack at that segment's end state.

Returns:

  • bool – Whether the route was present and updated.

Source

start_metric_summary ​

python
start_metric_summary(metric_key: str, *, floor: float | None = None) -> TrajectoryMetricSummary | None

Source