Skip to content

Build simulations that keep their history

Archetype is a Python runtime for simulations and agent workflows. Components describe state. Processors transform matching entities as Daft DataFrames. Each tick is stored, so inspecting an earlier state or branching a run does not require a separate replay system.

pip install archetype-ecs

Start the quickstart · Browse examples

The model

components  +  processors  +  world
    state       behavior       history
  • A component is typed entity data, such as Position or Task.
  • A processor is a DataFrame transform that runs on entities with the components it declares.
  • A world owns entities, runs ticks, and persists the resulting rows.

The Python runtime is the usual entry point. It owns the process-level services and gives you world handles that are lazy until first use.

Pick a path

If you want to… Start here
Run your first world Quickstart
Build a simulation Building simulations
Model state Components
Write behavior Processors
Spawn, query, and fork Working with worlds
Inspect past state History and forks
Run a service over HTTP Service hosting
Find an exact method or endpoint Reference

A complete tick

await world.spawn(Position(x=0), Velocity(dx=1))
await world.run(steps=10)

history = await world.query(Position)
fork = await world.fork("faster-model")

query() returns the append-only history for the requested components. A fork inherits the source history through lineage and writes its later ticks to its own branch.

Use it from a script or a service

For scripts, use ArchetypeRuntime:

async with ArchetypeRuntime() as runtime:
    world = runtime.world("experiment", processors=[MyProcessor()])
    await world.run(steps=10)

For a long-running service, start archetype serve and use the REST API or CLI. Both enter through the command gate, which can authorize and audit a multi-user host.

Project status

Archetype is alpha software. The core world, append-only history, and fork paths are the best-tested parts. The built-in HTTP server has development-mode authentication; add real authentication before exposing it to untrusted users.

Development and design notes

The Development section contains the contribution workflow, architecture, and normative contracts. Those pages describe how the engine is built; the User Guide is the place to start when you are using it.