Examples¶

Every example on this page runs end-to-end with a single command. The recommended pattern is ArchetypeRuntime for scripts. A small number of examples intentionally exercise internal services as focused implementation fixtures; application examples stay on the runtime.

Choose by package¶

The owning distribution identifies the behavior being demonstrated; every script itself remains repository example code rather than shipped package content.

Package context	Examples
Framework — `archetype-ecs` / `archetype`	Quickstart, world mutations, counterfactual forks, time travel, messaging, LLM agents, hooks, cloud storage, graphs, prefabs, Biome RTS, and live Biome
Missions — `archetype-missions` / `archetype.missions`	Trajectory analysis, HTN resolution, and coding-agent mission
Research — `archetype-research` / `archetype.research`	AutoResearch
Physical AI — `archetype-physical-ai` / `archetype.physical_ai`	The hosted-episode runnable contract lives in Physical AI; there is no numbered script.
Framework + Missions composition	Mission Factory assets

Example details¶

0. Quickstart¶

Package context: Framework (archetype-ecs, import archetype).

The smallest complete simulation defines one component and one processor, then runs through the public runtime surface. It stays below 30 non-comment source lines and is part of the credential-free example smoke suite.

uv run python examples/00_quickstart.py

Source: examples/00_quickstart.py

The script prints 3: the initial state is persisted first, then the processor increments the counter on three subsequent ticks.

1. World Mutations¶

Package context: Framework (archetype-ecs, import archetype).

Demonstrates the trusted mutation surface: spawn entities with components, inject processors at runtime, fork a world, and query state/history.

uv run python examples/01_world_mutations.py

Source: examples/01_world_mutations.py

This example uses actor-free ArchetypeRuntime. RBAC is intentionally absent from trusted scripting; the dispatcher-policy and API tests cover role policy.

What it demonstrates:

SPAWN / DESPAWN / UPDATE through the runtime world surface
ADD_COMPONENT / REMOVE_COMPONENT with archetype migration at tick boundaries
ADD_PROCESSOR to inject a MovementProcessor at runtime
FORK while preserving runtime ownership and independent world identity
History reads through world.history() without fabricating access events

Its structured receipt checks component migration, despawn, processor installation/removal, fork isolation, and the fact that trusted runtime calls do not fabricate actor-aware access rows.

Runtime operations in this example (curated, not exhaustive):

Runtime call	Owning behavior
`world.step()` / `world.run()`	`world.simulation`, registered through commands
entity/component mutations	`world.mutation`, registered through commands
processor mutations	`world.mutation`, registered through commands
`world.fork()` / `world.info()`	world lifecycle, registered through commands
`world.query()`	`world.query`, registered through commands
`world.history()`	commands-owned `AuditLog` projection

The runtime constructs exact family operations and uses trusted dispatcher entry; it does not construct an ActorCtx. See the normative Command Gate for the separate untrusted-adapter permission matrix.

2. Fork for Counterfactuals¶

Package context: Framework (archetype-ecs, import archetype).

Run three logistic-map regimes on one prime timeline, fork once, perturb each forked value by 1e-9, then advance both worlds and compare their append-only histories with one Daft join.

uv run python examples/02_fork_counterfactual.py

Source: examples/02_fork_counterfactual.py

The receipt proves distinct world identity, an identical pre-fork prefix, the exact perturbation at the branch point, aligned post-fork histories, and regime-specific divergence. Forks share resource instances by default; trusted scripts attach replacement resources through the runtime when per-branch resource isolation is required.

3. Time-Travel Queries¶

Package context: Framework (archetype-ecs, import archetype).

Run ticks, rewind to any past tick by filtering the tick column, then fork a counterfactual branch and diff it against the source at the same tick. Every tick is preserved.

uv run python examples/03_time_travel.py

Source: examples/03_time_travel.py

world.query(...) returns the full append-only history, so a point-in-time view is a Daft filter:

df = await world.query(Position, Velocity)
at_tick_2 = df.where(col("tick") == 2)

The fork half of the example stages a divergent component value on the fork (fork.update(entity, Velocity(vx=10.0))), steps both worlds the same number of ticks, and prints the source-vs-fork diff at the same tick — plus the fork's view of its pre-fork history, read through lineage.

Initial conditions are part of the ledger: an entity's first persisted row is its raw spawn values at the tick it materializes, and processors first apply on the following tick — the table contains x_0, f(x_0), f^2(x_0), ....

4. Agent Messaging¶

Package context: Framework (archetype-ecs, import archetype).

Three agents exchange greetings through an example-local shared Mailbox. Priority-ordered processors realize pending messages on the following tick, then update mood and energy from each inbox.

uv run python examples/04_messaging.py

Source: examples/04_messaging.py

What it demonstrates:

Components: AgentState (name, mood, energy), Inbox, Outbox
Resources: SimConfig for shared parameters, Mailbox for pending messages
Processors: GreetingProcessor (deposits messages), MessageRealizationProcessor (drains the mailbox into inboxes), MoodProcessor (updates mood based on inbox)
Hooks: PreTick and PostTick lifecycle callbacks

The structured receipt verifies the one-tick mailbox delay, six realized messages, two received messages per agent, sender/receiver pairs, hook tick sequences, and the final energy values without retaining temporary storage paths.

5. LLM-Powered Agents¶

Package context: Framework (archetype-ecs, import archetype).

Three agents with different personalities, each calling an LLM every tick via daft.functions.prompt. The ECS handles batching automatically — all entities get LLM calls in parallel because world state is a DataFrame.

export OPENAI_API_KEY=sk-...
uv run python examples/05_llm_agents.py

Source: examples/05_llm_agents.py

What it demonstrates:

Component: Agent with name, role, a journal_json, and durable thought count
Processor: ThinkProcessor uses daft.functions.prompt to call an LLM for every agent entity in a single DataFrame operation
Pattern: spawn, persist the raw initial state with world.step(), run five model-processing ticks, then filter the append-only query to the latest tick
Receipt: proves three latest agent rows, five processor calls per agent, and five valid JSON journal entries without retaining model text

Requires an OpenAI API key (or any provider via daft.set_provider()).

6. Mission Trajectory Analysis¶

Package context: Missions (archetype-missions, import archetype.missions).

Persist normalized turn and reward rows keyed by episode_id, then select and grade one episode's evidence through MissionWorld. The example is deterministic and requires no model credentials.

uv run python examples/06_trajectory_analysis.py

Source: examples/06_trajectory_analysis.py

What it demonstrates:

Normalized evidence: turn and reward rows remain independently queryable per episode.
Typed selection: TrajectorySelection filters one evidence table by episode_id.
Derived view: trajectory(...) reconstructs one episode's seq-ordered evidence lazily.
Typed composition: MissionWorld.query_trajectory() uses persisted query access; MissionWorld.grade_trajectory() delegates graders to evaluation.
No duplicate trajectory model: the example consumes archetype.missions.trajectories directly.

7. Lifecycle Hooks¶

Package context: Framework (archetype-ecs, import archetype).

Record lifecycle audit events, measure tick duration, and publish per-tick metrics without putting side effects inside processors.

uv run python examples/07_hooks.py

Source: examples/07_hooks.py

What it demonstrates:

Mutation audit: OnSpawn, OnDespawn, OnComponentAdded, and OnComponentRemoved
Tick telemetry: PreTick starts a timer and PostTick computes metrics from event.results
Hook handles: unregister a temporary debug hook with world.remove_hook(handle)
Boundary discipline: hooks emit side effects; processors keep the simulation state deterministic

8. HTN Resolution¶

Package context: Missions (archetype-missions, import archetype.missions).

Resolve a hierarchical task network into a fan-out AND/OR forest.

uv run python examples/08_htn_resolution.py

Source: examples/08_htn_resolution.py

This is a planning primitive, not the Agent Missions V1 planner. The future mission-planning adapter may translate a resolved plan into task entities and DependsOn edges; it may not advance those tasks.

9. Cloud Storage¶

Package context: Framework (archetype-ecs, import archetype).

Configure cloud-backed storage through StorageConfig without changing the runtime workflow.

uv run python examples/09_cloud_storage.py

Source: examples/09_cloud_storage.py

The local path runs without cloud credentials. Provider-specific branches need the matching host credentials.

10. AutoResearch¶

Package context: Research (archetype-research, import archetype.research).

Run a multi-candidate research workflow through the runtime-owned world and evaluation boundaries.

uv run python examples/10_autoresearch.py

Source: examples/10_autoresearch.py

AutoResearch is a sibling workflow, not a coding-agent mission subfamily. It may consume an agent callback without inheriting mission transition authority. Its transient ResearchCandidateContext is not the persisted missions Candidate review subject.

11a. Coding-Agent Mission¶

Package context: Missions (archetype-missions, import archetype.missions).

Submit a two-task repository mission: first prove a regression is red, then implement the fix only after that predecessor is accepted.

# Inspect the typed graph without creating Modal resources.
uv run python examples/11_coding_agent_mission.py --dry-run

# Run the credentialed dogfood.
uv run python examples/11_coding_agent_mission.py

Source: examples/11_coding_agent_mission.py

What it demonstrates:

typed AgentTask and CommandValidator authoring;
a temporal DependsOn relationship instead of a JSON plan cursor;
an expected-nonzero validator for the red regression;
committed dispatch admitted as a durable author Activity after its tick;
revision-bound validation and exact-head publication producing an immutable candidate rather than acceptance;
independent review of that exact candidate in a distinct critic sandbox;
processor-owned acceptance only after a complete candidate-bound critic receipt; and
same-worktree repair carrying durable validator failures or blocking critic findings into a new dispatch and candidate.

See Agent Missions V1 for the complete state machine, sequence diagram, ownership map, dogfood result, and explicit limits.

11b. Graph Relationships¶

Package context: Framework (archetype-ecs, import archetype).

Represent hierarchy edges as temporal ECS entities, traverse a bounded command tree, read it at an earlier tick, and cascade cleanup after a despawn.

uv run python examples/11_graph_relationships.py

Source: examples/11_graph_relationships.py

The receipt proves traversal order, temporal edge visibility, and the remaining unit/edge counts after cascade.

12. Prefabs¶

Package context: Framework (archetype-ecs, import archetype).

Author a prefab subtree, instantiate isolated copies with overrides and IsA lineage, then edit the template and re-instantiate without mutating prior instances.

uv run python examples/12_prefabs.py

Source: examples/12_prefabs.py

13. Biome-Inspired RTS¶

Package context: Framework (archetype-ecs, import archetype); the biome_rts modules are example-local.

Compose a prefab asset catalog into a live RTS command hierarchy with registered processors, minimap and fog-of-war projections, and a possessed-unit view.

uv run python examples/13_biome_rts.py

Source: examples/13_biome_rts.py

The hosted physical-AI episode path has no numbered example script; its runnable snippet and contract live in Physical AI.

14. Live Biome Agent¶

Package context: Framework (archetype-ecs, import archetype) composed with an external Biome/Flecs process.

Run a closed-loop mission against Sander Mertens' actual Biome executable. The agent observes reflected deposits, selects a requested resource and a free power cell, composes Biome's real buildings.Drill and buildings.Solar prefabs through Flecs REST, and waits for native power/mining systems to prove the result. Archetype persists the goal, decision, and terminal evidence.

# Clone pinned upstream sources into .context, build, launch, act, and verify.
uv run python examples/14_biome_agent.py --launch --keep-open

# Or control a Biome process already listening on port 27750.
uv run python examples/14_biome_agent.py --require-live

Source: examples/14_biome_agent.py

This example is opt-in external dogfood, not a local simulation stand-in. In ordinary example smoke runs it exits with an explicit skip when no Biome server is present. See Prefab Libraries for the ownership boundary, upstream pins, and reproducibility notes.

15. Mission Factory Assets¶

Package context: Framework prefab primitives plus Missions authoring contracts (archetype-ecs + archetype-missions).

Author a software factory as an ECS prefab library, instantiate its reusable BugFixLine, and compile the copied recipe entities into the same MissionSubmission, AgentTask, validators, publication policy, and critic policy accepted by Agent Missions. No agent, provider, or 3D renderer is started.

# Prove the semantic composition and print a compact receipt.
uv run python examples/15_mission_factory_assets.py

# Export all nine committed AI-ready object briefs.
uv run python examples/15_mission_factory_assets.py --briefs-json

Source: examples/15_mission_factory_assets.py

The example is deliberately not a new production family or a simulated game. Agent Missions remains the transition authority. The prefab world contains queryable task, validator, connection, geometry, socket, presentation, and interaction recipes; a trusted example-local compiler turns only the allowlisted DependsOn and Guards rules into supported authoring values. See the Mission Factory Asset Bible for the factory grammar and 3D generation contract.