# 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:

![search mission](search_mission.gif)

Regenerate it with `python -m testbed.record_search --provider polza --out search_mission.gif`.

## 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:

![smooth mission](smooth_mission.gif)

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`)