Emil Shanaty
fb3b4935d9
- AGENTS.md: build instructions for AI coding agents - docs/: AICC core spec copy, JSON schema, testbed design notes - scripts/: setup.sh, BUILDLOG.md - README.md: overview and reading order
39 lines
2.6 KiB
Markdown
39 lines
2.6 KiB
Markdown
# 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.
|