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 step and run. 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)

Contract¶

• A RunConfig identifies a run — one run_id shared by every tick in the run.
• SimulationService.step() and world.step() require an explicit RunConfig. They MUST NOT mint one per call. Callers driving a multi-tick run reuse the same RunConfig across every step so persisted rows stay addressable by run_id.
• SimulationService.run() and world.run() thread the caller's RunConfig into every internal step() call.
• EpisodeConfig wraps RunConfig with termination semantics.
• RolloutConfig wraps EpisodeConfig with fork-and-aggregate semantics.

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. Runtime/API callers create worlds through iCommandService.create_world(...); lower-level internal callers use WorldService.create_world().

from archetype.core.config import WorldConfig

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

StorageConfig¶

Configures the persistence backend. Runtime/API callers pass it through the gate; lower-level services pass it to WorldService.create_world() and StorageService.get_or_create_store().

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.

EpisodeConfig¶

EpisodeConfig describes step-until-termination execution on the world supplied by the caller. It does not fork.

Key fields:

RolloutConfig¶

RolloutConfig describes N forked episodes from a base world.

Key fields:

See Execution Hierarchy.

Source Reference¶

• RunConfig, WorldConfig, StorageConfig, CacheConfig: src/archetype/core/config.py
• EpisodeConfig, RolloutConfig: src/archetype/app/models.py