archetype-ecs 0.1.0

AI-native simulation engine: ECS as data (Daft) with time-travel storage (LanceDB).

Archetype

AI-native simulation engine for emergent composite AI systems.

Built for agents, by agents. Powered by Daft DataFrames + LanceDB.

---

AI Agents: Start with AGENTS.md — it's written for you.

Special Note for Humans

Welcome to the future of AI engineering.

This project represents years of iteration on ECS patterns and DataFrame-centric simulation. The core engine was designed and built by hand; the service layer, API, and CLI were built with AI assistance.

The codebase is built to be rewritten. With the exception of the core modules, you could re-write the entire service layer to your liking. The decoupling patterns support arbitrary experimentation in both simulation logic and infrastructure.

Build what you want.
Build what brings you joy.
Build what inspires you.

I know I have.
And it's made all the difference...

— **Everett Kleven**
*Founder of Vangelis Technologies*
*Creator of Archetype*

---

What is Archetype?

Archetype is a data-centric Entity-Component-System (ECS) runtime where:

• World state is columnar tables (Daft DataFrames / Arrow)
• Each tick is an append-only write to storage (LanceDB)
• Agent behaviors are pure DataFrame transforms

This gives you:

• Simulation as data — Query any tick, replay any run
• Time-travel state — Fork worlds, branch futures, compare outcomes
• MCTS & counterfactuals — Fork worlds for inner simulations
• Self-improving systems — Use Archetype to evaluate Archetype

Core Engine Diagram

Quick Start

# Clone and install
git clone https://github.com/vangelis-tech/archetype.git
cd archetype
uv sync

# Start the API server
archetype serve

# Or use the CLI directly
archetype world create my-sim
archetype run <world-id> --steps 100
archetype query <world-id>

Minimal Example

import asyncio
from archetype.app.container import ServiceContainer
from archetype.app.models import Command, CommandType
from archetype.app.auth.models import ActorCtx
from archetype.core.config import WorldConfig, StorageConfig, RunConfig
from uuid_utils import uuid7

async def main():
    container = ServiceContainer()

    # Create a world
    world = await container.world_service.create_world(
        WorldConfig(name="my-sim"),
        StorageConfig(),
    )

    # Submit a spawn command
    ctx = ActorCtx(id=uuid7(), roles={"admin"})
    cmd = Command(type=CommandType.SPAWN, payload={"components": []})
    await container.command_service.submit(world.world_id, cmd, ctx)

    # Step the simulation
    result = await container.simulation_service.run(
        world.world_id,
        RunConfig(num_steps=10),
    )
    print(f"Completed {result.ticks_completed} ticks")

    await container.shutdown()

asyncio.run(main())

Architecture

archetype/
├── src/archetype/
│   ├── core/          # ECS engine (Daft + Arrow + LanceDB)
│   ├── app/           # Service layer
│   │   ├── auth/      #   RBAC guard (ActorCtx, role permissions, quotas)
│   │   ├── broker.py  #   CommandBroker (priority queue, RBAC, history)
│   │   ├── command_service.py    # Command dispatch
│   │   ├── world_service.py      # World lifecycle
│   │   ├── simulation_service.py # Tick stepping / runs
│   │   ├── query_service.py      # Read path (time-travel queries)
│   │   ├── storage_service.py    # Storage backend pooling
│   │   └── container.py          # Wires all services together
│   ├── api/           # FastAPI REST layer
│   │   ├── routes/    #   worlds, commands, simulation, query
│   │   ├── deps.py    #   Dependency injection
│   │   └── app.py     #   App factory with lifespan
│   └── cli/           # Typer CLI
├── tests/             # Comprehensive test suite
├── AGENTS.md          # Start here if you're an AI
└── LEARNINGS.md       # Hard-won architectural knowledge

API

Start with archetype serve (default: http://localhost:8000).

Method	Endpoint	Description
POST	/worlds	Create a world
GET	/worlds	List worlds
GET	/worlds/{id}	Get world info
DELETE	/worlds/{id}	Remove a world
POST	/worlds/{id}/fork	Fork a world
POST	/worlds/{id}/commands	Submit a command
POST	/worlds/{id}/commands/batch	Submit batch
GET	/worlds/{id}/commands	Command history
POST	/worlds/{id}/step	Single tick
POST	/worlds/{id}/run	Run N ticks
GET	/worlds/{id}/state	World snapshot
GET	/worlds/{id}/entities/{eid}	Entity state
GET	/worlds/{id}/components	Query components
GET	/worlds/{id}/history	Command history
GET	/worlds/{id}/processors	List processors

CLI

archetype serve [--host] [--port]     # Start API server
archetype status                      # Show all worlds
archetype world create --name NAME    # Create world
archetype world list                  # List worlds
archetype world inspect WORLD_ID      # Inspect world
archetype world remove WORLD_ID       # Remove world
archetype run WORLD_ID --steps N      # Run simulation
archetype step WORLD_ID               # Single tick
archetype query WORLD_ID [--tick T]   # Query state
archetype history WORLD_ID            # Command history

Service Layer

All mutations flow through the CommandBroker with RBAC enforcement:

External API → CommandService → CommandBroker (RBAC + queue) → World
                                     ↓
                              SimulationService (drain + step)
                                     ↓
                              QueryService (read path)

Roles: viewer (read-only), player (spawn/despawn/message), coder (components/update), maintainer (+ processors), admin (all)

Quotas: 500 commands/tick, 200k token budget/day

For AI Agents

This repository is AI-native. It was built for AI agents to:

1. Rapidly prototype emergent multi-agent systems
2. Fork worlds for reasoning and self-improvement
3. Contribute to the codebase as collaborators

Read AGENTS.md for orientation.

Install

# Recommended
uv sync

# Or pip
pip install -e .

Python 3.12+ required.

Tests

uv run pytest tests/ -v              # All tests
uv run pytest tests/integration/ -v  # Full-stack integration
uv run pytest tests/api/ -v          # API routes
uv run pytest tests/app/ -v          # Auth + services

License

Apache 2.0

---

Vangelis Technologies Inc.