Runtime

Recommended API. Start here for scripts, notebooks, and applications. A runtime owns process-level services and creates world handles.

ArchetypeRuntime

ArchetypeRuntime(*, actor_ctx=None, log=None)

Own process-level services and create world handles.

Use one runtime for a related set of worlds and close it with an async context manager. Calling world() only creates a handle; the world is activated on its first operation.

Examples:

>>> async with ArchetypeRuntime() as runtime:
...     world = runtime.world("experiment")
...     entity_id = await world.spawn()
...     result = await world.run(steps=10)

Initialize the runtime.

Parameters:

Name	Type	Description	Default
actor_ctx	ActorCtx | None	Identity, roles, and quotas for operations. The default identity is suitable for local scripts.	None
log	str | None	Package log level: debug, info, warning, or error. When omitted, ARCHETYPE_LOG is used and logging stays quiet if that variable is unset.	None

shutdown async

shutdown()

Close every world handle and release process-level resources.

Repeated calls have no effect.

world

world(
    name="world",
    *,
    storage=None,
    cache=None,
    processors=None,
    resources=None,
    hooks=None,
)

Create a lazy handle for a world.

Parameters:

Name	Type	Description	Default
name	str	Human-readable world name.	'world'
storage	str | Path | StorageConfig | None	Storage location or explicit storage configuration.	None
cache	CacheConfig | None	Optional write-cache configuration.	None
processors	list | None	Processors installed when the world is activated.	None
resources	list | None	Resources installed when the world is activated.	None
hooks	list[tuple[type[HookEvent], Any]] | None	(event type, handler) pairs installed at activation.	None

Returns:

Type	Description
RuntimeWorld	A handle that activates the world on its first operation.

resume async

resume(world_id, *, storage=None, name='resumed')

Resume a durable world as the active writer.

The resumed world restores its tick, entities, and fork lineage. Its component classes must already be imported. Processors, resources, and hooks are code rather than stored state, so reinstall them before stepping. Resuming also invalidates the previous writer; its next commit fails instead of overwriting the resumed world.

Parameters:

Name	Type	Description	Default
world_id	str | UUID	Durable identity of the world to resume.	required
storage	str | Path | StorageConfig | None	Storage containing the world.	None
name	str	Local name for the returned handle.	'resumed'

attach

attach(world_id, *, name='attached')

Attach a non-owning handle to a live world.

The identity is validated on first use. Closing the handle does not destroy the world, although an explicit RuntimeWorld.destroy() still does.

Parameters:

Name	Type	Description	Default
world_id	str | UUID	Identity of a world already active in this runtime.	required
name	str	Local name for the returned handle.	'attached'

sync classmethod

sync(*, actor_ctx=None, log=None)

Create the synchronous runtime facade.

configure_session

configure_session(config, session=None)

Configure a Daft session for Archetype's Iceberg storage backend.

Uses the global default session if none is provided. Resolves the URI, creates the Iceberg catalog, attaches it, and sets the namespace.

Parameters:

Name	Type	Description	Default
config	StorageConfig	Storage configuration with uri and namespace.	required
session	Session | None	Optional explicit session. Defaults to the global Daft session.	None

Returns:

Type	Description
Session	The configured session.