Emil Shanaty
1314314567
- conformance.py: declarative scenario runner (subset matcher, $kind/$gt/ $enum/$required assertions, call_id/session_id echo checks), reference bridge, CLI entry (python -m aicc.conformance) - bridge.py: protocol version check before parsing (protocol_mismatch), session expiry handling (session_expired), malformed tool_call -> invalid_input, emit_event() for async events - client.py: Self return type - in_process.py: drain bridge event queue after response (event delivery), Self return type - websocket.py: Self return type, best-effort shutdown - tests: 14 passing (incl. conformance scenarios, 9/9 core scenarios) - ruff: all checks pass
134 lines
3.3 KiB
Markdown
134 lines
3.3 KiB
Markdown
# 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`.
|