Emil Shanaty
0cfb4277b5
- protocol.py: pydantic models for all AICC message types (envelope, session_init, tool_call, tool_result, event, error, heartbeat) - bridge.py: Bridge with @bridge.tool registration, capability checks, session management, serve_forever - client.py: AICCClient with single background reader (safe on concurrent transports like WebSocket), call_tool, events, manifest - tool.py: @tool decorator with schema generation from type hints - schema.py: JSON Schema generation (str/int/float/bool, list, dict, Optional, pydantic models) - transport: Transport protocol, InProcessTransport, WebSocket client+server - tests: 12 passing (integration, schema, websocket roundtrip) - examples: bridge_minimal.py + agent_minimal.py (verified end-to-end)
113 lines
2.7 KiB
Markdown
113 lines
2.7 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
|
|
transport/
|
|
base.py # Transport interface
|
|
in_process.py # In-process transport (tests, embedded)
|
|
websocket.py # WebSocket transport (client + server)
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
pip install -e ".[dev]"
|
|
pytest
|
|
ruff check .
|
|
```
|
|
|
|
## License
|
|
|
|
MIT — see `LICENSE`.
|