Runtime

Package	Value
Distribution	archetype-ecs
Import package	archetype

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

ArchetypeRuntime

ArchetypeRuntime(
    *,
    log=None,
    artifact_store=None,
    world_libraries=None,
    world_library_configs=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
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
artifact_store	ArtifactStoreConfig | None	Optional content-addressed object-store bounds.	None
world_libraries	tuple[WorldLibraryManifest, ...] | None	Explicit trusted manifests, primarily for tests or embedded hosts. Installed entry points are discovered when omitted.	None
world_library_configs	Mapping[str, object] | None	Family-name to typed extension-configuration values consumed while trusted libraries are installed.	None

shutdown async

shutdown()

Delegate retryable process teardown to the sole resource owner.

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.

library

library(name, *args, **kwargs)

Construct one installed runtime-scoped library adapter.

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'

discover async

discover(storage=None)

List every world recorded for a storage identity.

Discovery works without a live world and includes destroyed worlds, whose durable rows remain queryable.

Parameters:

Name	Type	Description	Default
storage	str | Path | StorageConfig | None	Storage whose durable world catalog should be listed.	None

Returns:

Type	Description
list[WorldInfo]	Durable descriptors for every world recorded in that storage.

attach

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

Attach a non-owning handle to a live or durable world.

With explicit storage, info() and query() can resolve a world that is not live in this process. 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	Durable identity of the world to attach.	required
name	str	Local name for the returned handle.	'attached'
storage	str | Path | StorageConfig | None	Storage containing the world. It may be omitted for live-world capabilities; storage-addressed capabilities require explicit coordinates.	None

sync classmethod

sync(
    *,
    log=None,
    artifact_store=None,
    world_libraries=None,
    world_library_configs=None,
)

Create the synchronous runtime facade.

SyncArchetypeRuntime

SyncArchetypeRuntime(
    *,
    log=None,
    artifact_store=None,
    world_libraries=None,
    world_library_configs=None,
)

Synchronous facade over ArchetypeRuntime.

Use it as a context manager. New asynchronous applications should use ArchetypeRuntime directly.

shutdown

shutdown()

Retry process teardown and release the runner only after success.

discover

discover(storage=None)

List durable worlds through the synchronous facade.

attach

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

Attach a synchronous handle to a live or durable world.

resume

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

Resume a durable world as the active writer.

SyncRuntimeWorld

SyncRuntimeWorld

Synchronous compatibility facade over RuntimeWorld.

evaluate

evaluate

Persist one evaluation result for an evaluation identity.

run_sync

run_sync(coro)

Run one coroutine when no event loop is active in this thread.

configure_session

configure_session(config, session=None)

Build Archetype's concrete local SQLite-catalog Iceberg session.

Remote and managed catalogs are caller-owned. They enter through an already-configured Session passed to StorageService rather than being reconstructed from storage fields or environment variables.

Parameters:

Name	Type	Description	Default
config	StorageConfig	Storage configuration with uri and namespace.	required
session	Session | None	Optional session to configure for backward-compatible local construction. Managed sessions should instead be injected through StorageService and are not reconfigured by Archetype.	None

Returns:

Type	Description
Session	The configured session.

entrypoint

entrypoint(*, log=None)

Wrap a script's main function with a managed ArchetypeRuntime.

The wrapped function is called with the runtime prepended to its arguments and may be sync or async. The wrapper itself is always sync (script boundary), returning whatever the function returns.

public_api

public_api(obj)

Mark a callable or class as archetype public API (see module docstring).