Python API

Previous Next

This reference is auto-generated from source docstrings using mkdocstrings.

Core

Component

Component

Base class for all archetype components, extending LanceModel with additional utilities.

get_type_by_name(name) classmethod

Finds a Component subclass by its name.

from_dict(data) classmethod

Create a component instance from a dictionary.

get_prefix() classmethod

Generate a standardized prefix for this component type's fields.

to_pyarrow_schema() classmethod

Convert this component type to a PyArrow schema. Uses LanceModel's built-in to_arrow_schema method.

get_prefixed_schema() classmethod

Get this component's PyArrow schema with prefixed field names. This is used when combining multiple components into an archetype schema.

to_row_dict()

AsyncProcessor

AsyncProcessor

Bases: iAsyncProcessor

process(df, **input_kwargs) async

Async version of process method. Override this in subclasses.

AsyncWorld

AsyncWorld

Bases: iAsyncWorld

add_hook(event, fn)

Register a hook for lifecycle events.

Supported events
  • "pre_tick": Before any processing (world, tick)
  • "post_tick": After all processing (world, tick, results)
  • "on_spawn": When entity created (world, entity_id, components)
  • "on_despawn": When entity removed (world, entity_id)
Example

world.add_hook("post_tick", lambda world, tick, **kw: print(f"Tick {tick} done"))

step(run_config, **input_kwargs) async

Executes one full, parallel simulation tick.

Tick Lifecycle
  1. pre_tick hook fires
  2. For each archetype (parallel): a. Query previous state (tick N-1) b. Materialize mutations (spawn/despawn caches) c. Execute processors (priority order) d. Persist to store
  3. Update _live snapshots
  4. Increment tick
  5. post_tick hook fires (tick is now N+1)

Note: Messages enqueued in tick N are dequeued in tick N+1.

Resources

Resources

Type-safe container for world-level shared state.

Usage

world.resources.insert(SimConfig(gravity=9.8)) world.resources.insert(broker)

In processor

config = resources.require(SimConfig) broker = resources.get(CommandBroker) # Returns None if not present

insert(resource)

Insert a resource, keyed by its type.

get(resource_type)

Get a resource, or None if not present.

require(resource_type)

Get a resource, raising KeyError if not present.

remove(resource_type)

Remove and return a resource, or None if not present.

Configuration

WorldConfig

WorldConfig

Bases: BaseModel

A world configuration is a container for the world configuration, including: - world_id: Optional[UUID] - The unique identifier for the world. If not provided, a new one will be generated. - name: Optional[str] - A human-readable alias for the world.

StorageConfig

StorageConfig

Bases: BaseModel

Storage Backend Context for configuring local or cloud storage access

Includes
  • uri: str - The URI location for the storage backend
  • namespace: str - The desired namespace for the catalog
  • io_config: IOConfig - The access credentials or the daft session/catalog

RunConfig

RunConfig

Bases: BaseModel

A run represents the configuration of a sequence of world.steps, and configures the runtime options for the world.

Carries configuration for the run, including: - run_id: UUID - The unique identifier for the run sequence, a uuid7 - num_steps: int - The number of steps to execute in the run sequence - debug: bool - Whether or not to enable debug mode - validate: bool - Whether or not to enable validation mode

Add ergonomic named constructors, e.g. RunConfig.dev(steps=1, debug=True, prefer_live_reads=True)

and RunConfig.benchmark(steps, explain=False) to reduce call-site verbosity.

dev(*, steps=1, prefer_live_reads=True, debug=True, explain=False, show_rows=5, metadata=None) classmethod

benchmark(*, steps, explain=False, debug=False, prefer_live_reads=False, show_rows=0, suite='benchmark', trial=None, metadata=None) classmethod

validate(*, steps=1, enable_validation=True, debug=True, prefer_live_reads=False, metadata=None) classmethod

App

ServiceContainer

ServiceContainer

Wires all services together with correct dependency ordering.

Usage

container = ServiceContainer() world = await container.world_service.create_world(config, storage_config) await container.simulation_service.step(world.world_id, run_config)

Pass registry_path to enable persistent world discovery across server restarts. The long-running archetype serve process uses the registry to rehydrate previously created worlds on startup.

shutdown() async

Gracefully shut down all services.

Command

Command

Bases: BaseModel

arrow_schema() classmethod

Return a canonical Arrow schema suitable for Parquet.

CommandType

CommandType

Bases: str, Enum

Command types for the command broker.

The broker is the universal simulation interface supporting: - Entity-level mutations (spawn, despawn, components) - Processor mutations (hot-swap behavior) - Simulation-level operations (recursive simulation, rollouts)

ActorCtx

ActorCtx

Bases: BaseModel

Identity and permissions of the caller.

CLI Auto-Merge Policy