Runtime models¶

Recommended API. Configuration, result, receipt, and introspection records returned by world operations.

ProcessorInfo ¶

Read-only summary of a registered processor.

Field	Type	Default	Description
`qualname`	`str`	`required`	Qualified processor class name.
`priority`	`int`	`0`	Execution priority; lower values run first.
`components`	`tuple[str, Ellipsis]`	`generated by tuple`	Qualified component names required by the processor.

HookInfo ¶

Read-only summary of a registered hook.

Field	Type	Default	Description
`event_type`	`str`	`required`	Qualified lifecycle-event class name.
`handler_qualname`	`str`	`required`	Qualified handler name.
`mode`	`str`	`'blocking'`	Execution mode: blocking or spawn.
`handle_id`	`int`	`required`	Handle identifier used to remove the hook.

ResourceInfo ¶

Read-only summary of a resource attached to a world.

Resources are keyed by type in the underlying Resources container; the qualname IS the unique identity of a resource within a world.

Field	Type	Default	Description
`qualname`	`str`	`required`	Qualified resource class name.

WorldInfo ¶

Immutable snapshot of a world's identity and current position.

Field	Type	Default	Description
`world_id`	`str \\| UUID`	`required`	Durable world identifier.
`name`	`str \\| None`	`None`	Human-readable world name.
`tick`	`int`	`0`	Next tick to execute.
`run_id`	`str \\| UUID \\| None`	`None`	Identifier of the active or most recent run.

RunResult ¶

Summary of a completed call to RuntimeWorld.run().

Field	Type	Default	Description
`run_id`	`str \\| UUID`	`required`	Identifier of the completed run.
`world_id`	`str \\| UUID`	`required`	World advanced by the run.
`ticks_completed`	`int`	`0`	Number of ticks executed.
`commands_applied`	`int`	`0`	Number of queued commands applied during the run.
`final_tick`	`int`	`0`	World tick after the run completed.

EpisodeConfig ¶

Configure a bounded simulation episode.

An episode stops at max_steps, when termination returns true, or when its terminal component condition is satisfied. Supplying only terminal_component stops on component presence. Adding terminal_field instead tests that boolean field; terminal_all chooses whether every or any matching entity must satisfy it.

Field	Type	Default	Description
`episode_id`	`str \\| UUID`	`generated by uuid7`	Stable identifier for this episode.
`run_config`	`RunConfig`	`generated by RunConfig`	Tick execution options.
`max_steps`	`int`	`1000`	Maximum ticks before stopping.
`terminal_component`	`Any \\| None`	`None`	Component type used for structural or value termination.
`terminal_field`	`str \\| None`	`None`	Boolean field tested on the terminal component.
`terminal_all`	`bool`	`True`	Require every matching entity when testing a field.
`termination`	`Any \\| None`	`None`	Optional callable termination predicate.

EpisodeResult ¶

Result of a single episode.

Field	Type	Default	Description
`episode_id`	`str \\| UUID`	`required`	Episode identifier.
`world_id`	`str \\| UUID`	`required`	Forked world used by the episode.
`run_id`	`str \\| UUID \\| None`	`None`	Episode run identifier.
`start_tick`	`int`	`0`	World tick at episode start.
`final_tick`	`int`	`0`	World tick at episode completion.
`terminated`	`bool`	`False`	Whether a termination condition stopped the episode.
`duration_steps`	`int`	`0`	Number of ticks executed.

RolloutConfig ¶

Configure several episodes run on forks of one base world.

Field	Type	Default	Description
`rollout_id`	`str \\| UUID`	`generated by uuid7`	Stable identifier for this rollout.
`episode_config`	`EpisodeConfig`	`generated by EpisodeConfig`	Configuration shared by each episode.
`num_episodes`	`int`	`1`	Number of episode forks to run.
`parallel`	`bool`	`False`	Run episode forks concurrently.
`name_prefix`	`str`	`'ep'`	Name prefix for episode worlds.
`destroy_forks_on_complete`	`bool`	`False`	Destroy live episode worlds after collecting results.

RolloutResult ¶

Aggregate result of a rollout.

Field	Type	Default	Description
`rollout_id`	`str \\| UUID`	`required`	Rollout identifier.
`base_world_id`	`str \\| UUID`	`required`	World forked for each episode.
`episodes`	`list[EpisodeResult]`	`generated by list`	Results in episode order.
`num_episodes`	`int`	`0`	Number of completed episodes.
`total_duration_steps`	`int`	`0`	Total ticks executed across all episodes.

FactReceipt `dataclass` ¶

FactReceipt(
    world_id,
    run_id,
    producer,
    external_id,
    payload_digest,
    commit_token,
    fact_entity_id,
    tick,
    table_id,
    duplicate,
)

Describe the durable outcome of ingesting an external fact.

duplicate is true when the external identity and payload already existed. In that case, ingestion returns the original receipt without appending.

Field	Type	Default
`world_id`	`str`	`required`
`run_id`	`str`	`required`
`producer`	`str`	`required`
`external_id`	`str`	`required`
`payload_digest`	`str`	`required`
`commit_token`	`str`	`required`
`fact_entity_id`	`int`	`required`
`tick`	`int`	`required`
`table_id`	`str`	`required`
`duplicate`	`bool`	`required`