Metadata-Version: 2.4
Name: genio-sdk
Version: 0.2.1
Summary: Connect your AI agent to a Genio avatar — face, voice, and real-time video.
License: MIT
Project-URL: Homepage, https://genio.works
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: livekit>=1.0.0
Requires-Dist: python-dotenv>=1.0.0

# genio-sdk

Connect your AI agent to a Genio avatar. Your agent handles the conversation logic; Genio handles the face, voice, and real-time video.

## Install

```bash
pip install genio-sdk
```

## Quick Start (CLI)

```bash
export GENIO_API_KEY="gk_..."
export GENIO_AVATAR_ID="your_avatar_id"

# Test connectivity (placeholder agent)
genio-bridge --backend stub

# Hermes (requires run_agent on PYTHONPATH)
genio-bridge --backend hermes --model "provider/model"

# Custom agent module
export GENIO_AGENT_MODULE="my_agent.bridge:stream_reply"
genio-bridge --backend custom
```

Create a `.env` file in your working directory — the CLI loads it automatically via `python-dotenv`.

You should see `SSE connected` in the logs; the Genio dashboard shows **Agent Connected** within a few seconds.

## One-click install (macOS / Linux)

```bash
curl -sL https://genio.works/bridge.sh | bash -s -- \
  --api-key "gk_..." \
  --avatar-id "your_avatar_id" \
  --backend stub
```

## Library usage

```python
from genio import GenioBridge

bridge = GenioBridge(api_key="gk_xxx", avatar_id="your_avatar_id")

@bridge.on_user_speech
async def handle(text, turn_id, reply):
    async for token in my_agent.stream(text):
        await reply.send_token(token)
    await reply.done()

bridge.run()  # blocks, auto-reconnects
```

## API

### `GenioBridge(api_key, avatar_id, base_url?)`

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `api_key` | `str` | Yes | Your BYOA API key (starts with `gk_`) |
| `avatar_id` | `str` | Yes | The avatar document ID |
| `base_url` | `str` | No | Genio API base URL (default: `https://genio.works`) |

### `@bridge.on_user_speech`

Decorator to register the handler. The handler receives:

- `text` — transcribed user speech
- `turn_id` — unique ID for this conversation turn
- `reply` — object with:
  - `send_token(token)` to stream final answer tokens
  - `send_status(content)` to report progress while your agent is still working
  - `done()` to end the turn

### `StatusConfig` / `run_with_status_updates`

For long-running agents, use `run_with_status_updates` to send periodic status heartbeats while your worker streams tokens (see `genio.backends.hermes`).

### `bridge.run()` / `await bridge.disconnect()`

`run()` blocks and auto-reconnects. `disconnect()` stops the bridge.

## CLI reference

| Flag / env | Description |
|------------|-------------|
| `--api-key` / `GENIO_API_KEY` | BYOA key |
| `--avatar-id` / `GENIO_AVATAR_ID` | Avatar ID |
| `--base-url` / `GENIO_BASE_URL` | API base (default `https://genio.works`) |
| `--backend` / `GENIO_BRIDGE_BACKEND` | `stub`, `hermes`, or `custom` |
| `--model` / `HERMES_GENIO_MODEL` | Hermes model |
| `--agent-module` / `GENIO_AGENT_MODULE` | `package.module:callable` for custom backend |
