aicc-capsule/AGENTS.md

AGENTS.md — aicc-capsule build instructions

You are building the reference testbed for the AICC Protocol: a 3D room with an AI-controlled capsule that an LLM agent drives through protocol tools. This file tells you what to build and how. Read docs/aicc-core.md (the protocol spec) and docs/testbed-design.md before writing code. The Python SDK to build on is at ~/Desktop/aicc-py (sibling checkout; use it directly, do not reinvent).

Mission

Prove the AICC Protocol end-to-end:

1. A 3D room with obstacles and one interactable object.
2. A capsule the agent can move (bridge-side physics + state).
3. A bridge implementing the protocol with tools: proprioception, vision, move, turn, look_at, interact.
4. A runnable demo: an agent (any LLM with tool calling) connects via WebSocket, perceives the room, walks to a target, interacts.

Constraints

• Use the aicc-py SDK at ~/Desktop/aicc-py (Bridge, AICCClient, WebSocketServer). Import it, do not copy its internals. If the SDK lacks something, extend the SDK repo, not the testbed.
• Engine choice is yours but must meet: Python-friendly, can render a first-person RGB frame for vision (or emit a fake-but-honest frame), simple physics for move/collision. Candidates: Panda3D, ursina, Godot (via Python bindings), or a minimal custom scene. A headless-friendly setup is strongly preferred so the demo runs without a display.
• Protocol compliance is mandatory. The bridge must pass the conformance scenarios: python -m aicc.conformance ~/Desktop/aicc-spec/conformance/scenarios (all 9 core scenarios green).
• Tools must have description (first line = tool purpose). Use snake_case ids.
• Follow the "single source of truth" principle: all world data only via sensors, manifest carries no world state.
• Keep it minimal. This is a reference, not a product. One room, one capsule, one interactable. No inventory, no combat, no save system.

Definition of done

• python -m aicc.conformance ... passes 9/9 against the testbed bridge
• A demo script that: starts bridge, connects an agent loop, agent reaches a target and interacts, prints a transcript of tool calls to stdout
• README.md in testbed/ documenting how to run bridge + agent
• At least one commit per milestone (bridge skeleton, tools, demo loop)

Environment

• Python 3.11+; venv in testbed/.venv
• aicc-py SDK available at ~/Desktop/aicc-py — add it to PYTHONPATH or pip install -e ~/Desktop/aicc-py
• If you pick an engine, add its install command to scripts/setup.sh

Communication

Report progress in short summaries. When done, print the final tool transcript example and conformance result.