aicc-py

Python SDK for the AICC Protocol (AI-Controlled Character).

aicc-py provides client and bridge primitives for connecting language-model agents to virtual environments via the AICC wire protocol. Engine-agnostic, transport-pluggable, async-first.

Status

0.1.0 — matches AICC protocol aicc/0.1. Alpha.

Install

pip install aicc

Or from source:

git clone https://github.com/emil28092005/aicc-py
cd aicc-py
pip install -e ".[dev]"

Minimal example

Bridge side

from aicc import Bridge

bridge = Bridge(name="capsule-room", kind="3d")

@bridge.tool(description="Get the agent's current position and rotation.")
async def proprioception() -> dict:
    return {
        "position": {"x": 1.0, "y": 0.5, "z": 2.0},
        "rotation": {"yaw": 0.0, "pitch": 0.0},
        "velocity": {"x": 0.0, "y": 0.0, "z": 0.0},
        "health": 100,
    }

@bridge.tool(description="Move the agent forward by the given distance in meters.")
async def move(forward: float = 0.0) -> dict:
    # your physics / path-planning code here
    return {"moved": forward}

from aicc.transport import WebSocketServer
async with WebSocketServer(bridge, port=8765):
    await bridge.serve_forever()

Client side

import asyncio
from aicc import AICCClient
from aicc.transport import WebSocketClientTransport

async def main():
    async with AICCClient(WebSocketClientTransport("ws://localhost:8765")) as client:
        manifest = await client.handshake()
        result = await client.call_tool("proprioception", {})
        print(result.output)

asyncio.run(main())

In-process (for tests and embedding)

from aicc import Bridge, AICCClient
from aicc.transport import InProcessTransport

bridge = Bridge(name="test")
@bridge.tool(description="noop")
async def ping() -> dict:
    return {"pong": True}

async with InProcessTransport(bridge) as transport:
    client = AICCClient(transport)
    manifest = await client.handshake()
    result = await client.call_tool("ping", {})
    assert result.output == {"pong": True}

Architecture

aicc/
  protocol.py     # message types, envelope, errors (pydantic models)
  client.py       # AICCClient — agent side
  bridge.py       # Bridge — environment side, tool registration
  tool.py         # @tool decorator and tool metadata
  schema.py       # JSON Schema generation utilities
  conformance.py  # declarative scenario runner (AICC conformance tests)
  transport/
    base.py           # Transport interface
    in_process.py     # In-process transport (tests, embedded)
    websocket.py      # WebSocket transport (client + server)

Conformance

aicc-py ships the reference conformance runner for the AICC protocol. It executes the declarative scenarios from the AICC-Protocol conformance/scenarios/ directory against any bridge:

python -m aicc.conformance ~/AICC-Protocol/conformance/scenarios

Or via pytest (scenarios are loaded automatically if the spec repo is checked out next to aicc-py):

pytest tests/test_conformance.py

A bridge is AICC-conformant for aicc/0.1 when all core scenarios pass.

Development

pip install -e ".[dev]"
pytest
ruff check .

License

MIT — see LICENSE.