Python SDK / ZeliClient
ZeliClient
The client holds your configuration and event handlers, and opens sessions. All constructor arguments are keyword-only.
from zeli import ZeliClientConstructor
ZeliClient(
*,
api_key: str | None = None,
avatar_id: str | None = None,
avatar_config: AvatarConfig | None = None,
options: ClientOptions | None = None,
)Optional credential, forwarded to the server when it requires auth. See Authentication.
Shorthand for AvatarConfig(avatar_id=...). Mutually exclusive
with avatar_config.
Full persona configuration. Mutually exclusive with avatar_id.
Server URL, ICE servers, timeouts. Defaults to localhost:8080.
Passing both avatar_id and
avatar_config raises ConfigurationError, as does an
empty options.server_url.
Methods
connect(session_options=None)
Opens a session. The return value is both awaitable and an async context manager:
async with client.connect() as session: # recommended
...
session = await client.connect() # manual lifetimeOptionally takes a SessionOptions.
on(event)
Decorator that registers a handler for a ZeliEvent. Handlers may
be sync or async.
@client.on(ZeliEvent.MESSAGE_RECEIVED)
async def handler(message): ...add_listener(event, callback) / remove_listener(event, callback)
Programmatic registration and removal. Callbacks may be sync or async.
get_message_history() -> list[Message]
Returns a copy of the conversation transcript accumulated so far — mutating it won't affect the client.
Example
from zeli import ZeliClient, AvatarConfig, ClientOptions, ZeliEvent
client = ZeliClient(
avatar_config=AvatarConfig(avatar_id="presenter-male-1080"),
options=ClientOptions(server_url="http://your-server:8080"),
)
@client.on(ZeliEvent.MESSAGE_RECEIVED)
async def log(message):
print(message.role.value, message.content)
async with client.connect() as session:
await session.send_message("Hello!")
await session.wait_until_closed()