airunner-services

The headless orchestration layer for Capsize-Games/airunner (AI Runner). It owns the daemon entry points, FastAPI server wiring, runtime registry, database, downloads, persistence, lifecycle control, and the modality services that coordinate LLM, STT, TTS, and art workloads. Extracted into its own repository (issue #2198, part of the repository-split tracker #2185) as the product's engine: independently useful headless and in Docker, consumed by the desktop GUI across a versioned daemon contract rather than imported directly.

flowchart LR
    GUI[airunner: desktop GUI client] --> Daemon[airunner_services daemon routes]
    Daemon --> Registry[runtime registry]
    Daemon --> Client[canonical daemon HTTP client]
    Registry --> Sidecars[llama.cpp / whisper.cpp sidecars]
    Daemon --> DB[(database)]
    Daemon --> Data[(AIRUNNER_BASE_PATH)]

Loading

What this package owns

• FastAPI server bootstrap and daemon entry points
• runtime routing, runtime load/unload control, and health checks
• the database layer (SQLAlchemy models, Alembic migrations) -- owned solely here, not duplicated on the desktop side
• service-level downloads, persistence, and settings
• orchestration for daemon-backed LLM, TTS, STT, and art requests
• the canonical daemon HTTP client (airunner_services.daemon_client), which the desktop client imports through a thin re-export layer

Importable code lives under src/airunner_services/.

Installation

From a checkout (editable, for development on this package itself):

python -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -e ".[headless,development]"

From PyPI (as a dependency of another project):

pip install "airunner-services[headless]"

headless aggregates the four runtime extras (llm-native, stt-native, art-python, tts-python); install just the one(s) you need instead if you don't want all of them. See setup.py for the full extras list (about 20 groups) -- tests/test_extras_resolve.py keeps every one of them real and resolvable.

The TTS/OpenVoice extras (openvoice, melotts, openvoice_cn/_jp/_kr/_tw, gruut_support) pull in airunner-tts-vendor rather than vendoring that fork here.

Testing

pytest tests/test_service_bootstrap.py -v
pytest tests -m llm_runtime_smoke -v
pytest tests -m stt_runtime_smoke -v
pytest tests -m art_runtime_smoke -v
pytest tests -m tts_runtime_smoke -v

Daemon-backed functional suites need real models and take longer:

pytest tests/test_tts_synthesize_functional.py -v --timeout=120
pytest tests/test_llm_functional.py -v --timeout=900
pytest tests/test_llm_tts_functional.py -v --timeout=1200
pytest tests/test_stt_transcribe_functional.py -v --timeout=1200

Provenance

Extracted from Capsize-Games/airunner (issue #2198). History for the moved files is preserved (git filter-repo). A handful of test files that spanned both the desktop GUI and this package (fork-removal parity checks, GUI-functional integration tests, monorepo-tooling tests) stayed in the source repository rather than moving here, since they can't run standalone against this package alone.

Licensing

GPL-3.0-only, matching the application this serves. See LICENSE.