67 lines
3.0 KiB
Markdown
67 lines
3.0 KiB
Markdown
# aicc-capsule — Reference Testbed
|
||
|
||
Reference implementation of the [AICC Protocol](https://github.com/emil28092005/AICC-Protocol) in a 3D environment: an AI-controlled capsule in a room. This is the "hello world" of the protocol — a working end-to-end vertical that proves the spec is implementable and gives other projects a template to copy.
|
||
|
||
## Goal
|
||
|
||
A 3D room with a capsule that an LLM agent controls through AICC sensor/actuator tools. The agent perceives the world via tools (`vision`, `proprioception`, `hear`), reasons, and acts (`move`, `turn`, `look_at`, `interact`). No pixel-clicking, no engine-specific hooks — pure protocol.
|
||
|
||
## Status
|
||
|
||
**Working.** The testbed is built: headless 3D room with a capsule, a
|
||
protocol-conformant bridge (`9/9` conformance scenarios), and a demo in which
|
||
an agent (LLM or scripted) navigates to the beacon and activates it. See
|
||
`testbed/README.md` for run instructions; `scripts/BUILDLOG.md` for the build
|
||
log.
|
||
|
||
## Search challenge
|
||
|
||
The agent can also be sent on an autonomous search: an orange triangle is
|
||
hidden on the back side of one of the crates, and the model must explore the
|
||
room with real vision, spot it, and report it. This recording shows the run
|
||
from three angles — the top-down map, the actual first-person frames the
|
||
model saw, and its chat/reasoning (recorded with smooth motion, ~2 Hz):
|
||
|
||
|
||
|
||
Regenerate it with `python -m testbed.record_search --provider polza --goal search
|
||
--out search_mission.gif --capture-hz 2.0 --cruise 0.8 --steps 60`.
|
||
|
||
## Smooth & proactive movement
|
||
|
||
The same recording setup with a beacon mission and the cruise mode — the
|
||
capsule glides with animated `move`/`turn` calls and keeps moving while the
|
||
model thinks (`--cruise`). Frames are sampled at ~2.5 Hz by an observer
|
||
client, so the GIF shows the actual motion, not step endpoints:
|
||
|
||
|
||
|
||
Regenerate with `python -m testbed.record_search --provider polza --goal beacon
|
||
--out smooth_mission.gif --capture-hz 2.5 --cruise 1.0`.
|
||
|
||
## Layout
|
||
|
||
```
|
||
aicc-capsule/
|
||
AGENTS.md # instructions for AI coding agents (opencode, claude, etc.)
|
||
README.md # this file
|
||
docs/
|
||
aicc-core.md # AICC Protocol spec, v0.1 (copy from AICC-Protocol repo)
|
||
aicc.schema.json # JSON Schema for all AICC messages
|
||
testbed-design.md # design notes for the testbed itself (see below)
|
||
scripts/ # build/run/dev scripts
|
||
testbed/ # the testbed source (empty until built)
|
||
```
|
||
|
||
## Reading order for an agent
|
||
|
||
1. `AGENTS.md` — what to build, constraints, definition of done
|
||
2. `docs/aicc-core.md` — the protocol contract (sections 1–5 are essential)
|
||
3. `docs/testbed-design.md` — how the testbed maps onto the protocol
|
||
4. `~/Desktop/aicc-py` — the SDK to build on (Bridge, AICCClient, transports)
|
||
|
||
## Related repositories
|
||
|
||
- Spec: https://github.com/emil28092005/AICC-Protocol
|
||
- Python SDK: https://github.com/emil28092005/aicc-py (local checkout: `~/Desktop/aicc-py`)
|