Archetype uses Pydantic models for all configuration. There are four config types, each scoped to a different concern: what the world is, where it stores data, how it caches, and how a run behaves.

RunConfig¶

RunConfig controls the behavior of world.run() and world.step(). Each run gets a unique run_id (UUID7) for storage isolation.

from archetype.core.config import RunConfig

config = RunConfig(num_steps=10, debug=True)
await world.run(config)

Fields¶

RunConfig is frozen (immutable after construction).

prefer_live_reads¶

Controls how _run_archetype fetches previous state at the start of each tick:

• False (default): Reads from the store via the querier. Suitable for single-step runs, validation, and benchmarks where you want to verify that persisted state round-trips correctly.
• True: Reads from the in-memory _live cache. Avoids redundant store reads between consecutive ticks. Required for multi-step runs where each step's run_id differs from the persisted rows.

In practice, _live is always used after tick 0 regardless of this flag -- the core tick loop falls back to _live when it is populated for a given signature. This flag controls the intent at the RunConfig level; the actual behavior is governed by the _live cache population logic in AsyncWorld._run_archetype.

Named Constructors¶

RunConfig provides named constructors for common scenarios:

RunConfig.dev()¶

Interactive development. Debug output on, live reads enabled, higher row display limit.

config = RunConfig.dev(steps=5)
# debug=True, prefer_live_reads=True, show_rows=5

RunConfig.benchmark()¶

Performance measurement. Debug off, no row display, optional suite/trial labels for organizing results.

config = RunConfig.benchmark(steps=100, suite="latency", trial=0)
# debug=False, show_rows=0, suite="benchmark"

RunConfig.validate()¶

Schema and invariant checking. Validation enabled, debug on, reads from store to verify persistence.

config = RunConfig.validate(steps=3)
# enable_validation=True, debug=True, prefer_live_reads=False, suite="validate"

WorldConfig¶

Identifies a world instance. Passed to WorldService.create_world().

from archetype.core.config import WorldConfig

config = WorldConfig(name="my-sim")

StorageConfig¶

Configures the persistence backend. Passed to WorldService.create_world() and StorageService.get_backend().

from archetype.core.config import StorageConfig, StorageBackend

config = StorageConfig(
    uri="./my_data",
    namespace="experiment_1",
    backend=StorageBackend.LANCEDB,
)

Path values are coerced to str via a field validator. See Stores for backend-specific behavior.

CacheConfig¶

Configures write-behind caching when wrapping a store with AsyncCachedStore. Optional -- omit for direct writes.

from archetype.core.config import CacheConfig

cache = CacheConfig(flush_rows=500_000, idle_sec=15.0)

The cache flushes when any threshold is exceeded. See Stores -- Write-Behind Cache for details.

Source Reference¶

• RunConfig, WorldConfig, StorageConfig, CacheConfig: src/archetype/core/config.py