Metadata-Version: 2.4
Name: aivg
Version: 0.2.1
Summary: AIVG — AI Voice Gateway: agent-platform-agnostic voice-satellite management plane + CLI
Author-email: Cloudomate <hello@cloudomate.com>
Maintainer: Cloudomate / AIVG contributors
License: MIT
Project-URL: Repository, https://github.com/cloudomate/aivg
Project-URL: Issues, https://github.com/cloudomate/aivg/issues
Project-URL: Changelog, https://github.com/cloudomate/aivg/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/cloudomate/aivg/blob/main/README.md
Keywords: voice,satellite,webrtc,hermes,aivg,ai,agent,speech
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Telephony
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiortc>=1.6
Requires-Dist: aiohttp>=3.9
Requires-Dist: aiohttp-sse>=2.2
Requires-Dist: av>=11
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13
Requires-Dist: PyYAML>=6
Requires-Dist: aioesphomeapi<46,>=45
Requires-Dist: noiseprotocol<0.4,>=0.3
Requires-Dist: chacha20poly1305-reuseable<0.14,>=0.13
Provides-Extra: ble
Requires-Dist: bleak>=0.22; extra == "ble"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: black>=24; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"
Dynamic: license-file

# AIVG — AI Voice Gateway

**AIVG** is a platform-neutral voice satellite system: a thin, realtime
voice transport (WebRTC / Opus) bridged into whichever **agent platform
plugin** is configured (v1 canonical: **Hermes**; planned: OpenClaw).
Satellites capture audio and play it back; STT, the agent loop, TTS,
and end-of-utterance detection live in the upstream agent platform.

## Install (PyPI)

```bash
pip install aivg
```

**Supported**: Python 3.11+ on Linux x86_64/aarch64, macOS arm64/x86_64.

**⚠ Install into your existing Hermes virtualenv, not a fresh venv.** The
`aivg-satellite` entry point is only discoverable by Hermes's plugin loader
if AIVG lives in the same venv Hermes runs from:

```bash
uv pip install --python ~/.hermes/hermes-agent/venv/bin/python aivg
```

Then add `aivg-satellite` under `plugins.enabled:` in `~/.hermes/config.yaml`
and restart the gateway. Full setup flow: see [docs/](docs/) or run
`aivg setup --help`.

Repo: <https://github.com/cloudomate/aivg> · Changelog:
[CHANGELOG.md](CHANGELOG.md) · License: MIT.

## Status

| Layer | State |
|---|---|
| Voice plane (WebRTC, Opus, server-side endpointing) | Implemented (features 001/005/006/008/010) |
| Management plane (registry, adoption, control WS, SSE logs) | Implemented (feature 011 Phases 1–4) |
| `aivg` CLI + Hermes agent skill | Implemented (feature 011 Phase 3+4) |

## Quickstart

```bash
pip install -e .          # picks up the renamed entry point
aivg --version            # JSON envelope, contract_version 1.0.0
aivg list                 # see the fleet
aivg device get kitchen   # full state of one device
aivg logs kitchen --follow
aivg onboard --ssid "MyWiFi" --password "..." --name "bedroom"
```

## Repo layout

```text
src/aivg_core/           # platform-neutral management plane
  platforms/hermes/        # v1 Hermes plugin (Hermes-platform agent skill, bridge)
  platforms/openclaw/      # planned plugin (stub)
  webrtc/                  # voice plane
  management/              # App. A REST + SSE + control WS
src/aivg_cli/            # `aivg` Typer CLI
skills/hermes-agent/     # Hermes-platform agent skill (invokes `aivg` CLI)
specs/                   # Spec Kit features 001–012
docs/                    # design notes, data-dir reference, rebrand allow-list
```

## Hermes vs AIVG

| Use this | When you mean |
|---|---|
| **AIVG** | the product, the repo, the system as a whole |
| **Hermes** | the v1 agent-platform plugin (one of several AIVG supports) |
| **`aivg`** | the CLI binary |
| **`aivg_core`** | the platform-neutral Python package |
| **`~/.aivg/`** | AIVG's operator data (state, firmware manifests) |
| **`~/.hermes/`** | the Hermes plugin's data (provider config, secrets) |


## Development

```bash
# Editable install with all dev deps (pytest, ruff, black, etc.)
pip install -e ".[dev]"
# or with uv:
uv pip install -e ".[dev]"

# Run the suite
pytest -q                 # 300+ tests
```

Runtime + dev deps are declared in `pyproject.toml` under
`[project]` and `[project.optional-dependencies]` respectively.
(The legacy `requirements-dev.txt` was removed in feature 018 —
single source of truth is the `pyproject.toml` extras now.)

See [`specs/`](specs/) for the design history and the active feature
(currently [018-aivg-pypi-distribution](specs/018-aivg-pypi-distribution/)).
