# aicc-py

Python SDK for the [AICC Protocol](https://github.com/emil28092005/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

```bash
pip install aicc
```

Or from source:

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

## Minimal example

### Bridge side

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

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

```python
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](https://github.com/emil28092005/AICC-Protocol)
`conformance/scenarios/` directory against any bridge:

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

```bash
pytest tests/test_conformance.py
```

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

## Development

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

## License

MIT — see `LICENSE`.