Imported from lateralus426/ai-town-port (AGENTS.md). Install upstream with npx skills add lateralus426/ai-town-port. Copyright stays with the author.

AGENTS.md — AI Town Port: Workspace Root

Projects in This Workspace

Never modify files inside ./ai-town/. Always read it, never write it. Always check ./openspec/changes/ for an active proposal before implementing anything. If no proposal exists for a module, create one first and wait for approval.

Port Overview

Porting a16z-infra/ai-town from TypeScript/Convex/PixiJS to Python.

• Frontend: React + PixiJS → raylib-py (Raylib 5.x Python bindings)
• Backend: Convex serverless functions → FastAPI + asyncio + SQLAlchemy
• Vector DB: Convex built-in vector search → ChromaDB (dev) / pgvector (prod)
• AI agents: Convex internalActions → asyncio background tasks + httpx LLM calls

Current Focus: Phase 1 — Raylib Frontend

Work only on the frontend renderer until Phase 1 is complete. Do not start backend porting (engine, agents, API) until explicitly instructed.

Frontend Source Reference

The original frontend lives in ./ai-town/src/. Key files to read before writing anything:

Frontend Target

All Raylib code goes in ./ai-town-py/renderer/:

renderer/ ├── main_window.py # Raylib window init, main render loop, FPS cap ├── game_board.py # Camera, tile layer rendering (ground → objects → players) ├── player_sprite.py # Sprite sheet loading, animation state, facing direction ├── conversation_hud.py # Speech bubbles, typing dots, message text ├── input_handler.py # Keyboard/mouse → movement inputs, camera pan └── assets.py # Asset loader: textures, tile sheets, sprite atlases

Raylib Frontend Rules

• Raylib window must run on the main thread — never move it to a background thread
• Target 60 FPS render loop with SetTargetFPS(60)
• World state is stubbed as static Python dicts during Phase 1 — no backend needed yet
• Sprite sheets from ./ai-town/data/spritesheets/ are reused directly via LoadTexture()
• Map tiles from ./ai-town/data/gentle.js must be converted once: run python util/convert_map.py → outputs ./ai-town-py/data/gentle.json
• Camera follows the human player; support WASD pan override
• Render order: ground tiles → decoration tiles → conversation indicators → players → HUD

Phase 1 Milestone Definition

Phase 1 is complete when:

• Tiled map renders correctly (all layers, correct Z-order)
• At least one character walks between two points with correct sprite animation
• Speech bubble appears above a character with static placeholder text
• Camera follows the active player
• Input handler moves the human player on screen

Phase 2 — Backend (starts after Phase 1 milestone)

Do not implement any of this during Phase 1. Listed here for context only.

1. port-data-models → SQLAlchemy models mirroring convex/schema.ts
2. port-util → util/llm.py, util/navigation.py, util/geometry.py
3. port-engine → asyncio tick loop mirroring convex/aiTown/game.ts
4. port-agent-memory → agent/memory.py (embed, store, retrieve)
5. port-agent-conversation → agent/conversation.py (prompt engineering)
6. port-agent-operations → agent/operations.py (decision cycle)
7. port-http-api → FastAPI routes connecting backend to Raylib renderer

General Conventions (apply to all phases)

• Python 3.11+, all async code uses async def and await
• httpx.AsyncClient for all HTTP/LLM calls — never requests
• Env vars mirror originals: OPENAI_API_KEY, OLLAMA_HOST, OLLAMA_MODEL, OLLAMA_EMBEDDING_MODEL
• Config loaded via python-dotenv in config.py
• Use ruff for linting, black for formatting
• Type-hint everything — use dataclasses for in-memory game state, Pydantic for API schemas

Analysis Artifacts

Before implementing any module, Pi must write findings to ./analysis/:

OpenSpec Workflow

1. Read ./openspec/AGENTS.md at session start
2. For each module: check ./openspec/changes/ for an active proposal
3. If no proposal exists: create proposal.md + tasks.md in a new change folder, stop, and wait
4. If proposal is approved: implement per tasks.md, then run openspec archive <change-name>
5. Never write implementation code without an approved OpenSpec proposal

Raylib Frontend Rules

• Raylib window must run on the main thread — never move it to a background thread
• Target 60 FPS render loop with SetTargetFPS(60)
• World state is stubbed as static Python dicts during Phase 1 — no backend needed yet
• Sprite sheets from ./ai-town/data/spritesheets/ are reused directly via LoadTexture()
• Map tiles from ./ai-town/data/gentle.js must be converted once: run python util/convert_map.py → outputs ./ai-town-py/data/gentle.json
• Camera follows the human player; support WASD pan override
• Render order: ground tiles → decoration tiles → conversation indicators → players → HUD

Phase 1 Milestone Definition

Phase 1 is complete when:

• Tiled map renders correctly (all layers, correct Z-order)
• At least one character walks between two points with correct sprite animation
• Speech bubble appears above a character with static placeholder text
• Camera follows the active player
• Input handler moves the human player on screen

Phase 2 — Backend (starts after Phase 1 milestone)

Do not implement any of this during Phase 1. Listed here for context only.

1. port-data-models → SQLAlchemy models mirroring convex/schema.ts
2. port-util → util/llm.py, util/navigation.py, util/geometry.py
3. port-engine → asyncio tick loop mirroring convex/aiTown/game.ts
4. port-agent-memory → agent/memory.py (embed, store, retrieve)
5. port-agent-conversation → agent/conversation.py (prompt engineering)
6. port-agent-operations → agent/operations.py (decision cycle)
7. port-http-api → FastAPI routes connecting backend to Raylib renderer

General Conventions (apply to all phases)

• Python 3.11+, all async code uses async def and await
• httpx.AsyncClient for all HTTP/LLM calls — never requests
• Env vars mirror originals: OPENAI_API_KEY, OLLAMA_HOST, OLLAMA_MODEL, OLLAMA_EMBEDDING_MODEL
• Config loaded via python-dotenv in config.py
• Use ruff for linting, black for formatting
• Type-hint everything — use dataclasses for in-memory game state, Pydantic for API schemas

Analysis Artifacts

Before implementing any module, Pi must write findings to ./analysis/:

OpenSpec Workflow

1. Read ./openspec/AGENTS.md at session start
2. For each module: check ./openspec/changes/ for an active proposal
3. If no proposal exists: create proposal.md + tasks.md in a new change folder, stop, and wait
4. If proposal is approved: implement per tasks.md, then run openspec archive <change-name>
5. Never write implementation code without an approved OpenSpec proposal