Learning outcomes
- Separate state from rules
- Distinguish intent from result
- Validate grid coordinates
- Assign clear responsibilities
- Model discrete simulation time
- Test an invalid action
1. Begin with reality, not intelligence
Project In-A-Gadda-Da-Vida begins with a 60 × 60 garden containing paths, obstacles, food and water. Adam starts at a known position with simulated needs, but he does not yet know the entire map. Eve will arrive later. The inhabitants may request actions; they never rewrite the laws of the world.
For the first experiment, reduce the garden to 10 × 10 and control Adam manually. Fewer moving parts make architectural mistakes visible. Once the domain behaves correctly, the same rules can serve a keyboard controller, a local language model or a deterministic algorithm.
2. State, rules, intentions and events
State: what is true now?
State is a snapshot: the grid dimensions, Adam's position, the current tick, available resources and current needs. It is neither a command nor an explanation.
Rules: which changes are legal?
Rules apply regardless of what an agent wants. They stop an inhabitant leaving the map, crossing an obstacle, drinking where no water exists or spending energy that is not available. Python owns these rules.
Intent: what does an actor want?
An intent is a request such as “move east”. It is not proof that Adam moved. The engine must validate the candidate destination against current reality.
Event: what actually happened?
An event records a confirmed outcome: a successful movement or a rejected attempt. Events support the UI, debugging, persistence and later behavioural analysis.
3. Responsibility map
- World owns terrain, dimensions, resources and inhabitant state.
- SimulationEngine advances ticks and applies valid actions.
- Agent owns needs and later chooses goals and intentions.
- Presentation displays confirmed state; it does not decide whether a wall is passable.
- AI adapter obtains a proposal from LiteLLM/Ollama; it cannot mutate the world.
- Memory stores and retrieves historical information; it is not physical truth.
If Turtle is replaced tomorrow, movement rules should not change. If Ollama is offline, the engine should still advance a tick.
4. Coordinates and simulation time
A logical cell uses (x, y). In this guide, (0, 0) is the top-left cell; x increases to the right and y increases downwards. A 10 × 10 world therefore accepts indices from 0 through 9. Screen pixels belong to the presentation layer and may use a different origin.
A tick is one discrete world step. It is not necessarily one real second and it does not imply one LLM request. World updates, visual refreshes and agent deliberations will eventually operate at different rates.
5. First Python experiment
from dataclasses import dataclass
@dataclass(frozen=True)
class Position:
"""A logical cell in the garden."""
x: int
y: int
def is_inside(position: Position, width: int, height: int) -> bool:
"""Validate domain bounds without consulting the GUI."""
return 0 <= position.x < width and 0 <= position.y < height
assert is_inside(Position(4, 4), width=10, height=10)
assert not is_inside(Position(10, 5), width=10, height=10)A frozen dataclass makes a position an explicit value. Movement creates a candidate position instead of silently mutating the old one. A standalone validation function is easy to test without Tkinter, Ollama or a database.
6. Guided laboratory
Represent the world
Create World(width, height, adam_position) using dataclasses.
Build a candidate
Write move_request(position, dx, dy) without mutating World.
Apply the rule
Update Adam only when the candidate is inside the grid.
Prove rejection
Show that moving west from (0, 0) leaves the state unchanged.
Protocol completion
You are ready to continue when you can explain who owns every value, why an intention is not a result and how one test proves that an invalid movement cannot alter the world.