wyoming_openai: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents working with code in this repository. It is symlinked as CLAUDE.md for Claude Code compatibility.

Project Overview

Wyoming OpenAI is a proxy middleware that bridges the Wyoming protocol with OpenAI-compatible endpoints for ASR (Automatic Speech Recognition) and TTS (Text-to-Speech) services. It enables Wyoming clients like Home Assistant to use various OpenAI-compatible STT/TTS services.

Development Commands

Testing

# Create and activate a repository virtual environment first

# Install development dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run tests with coverage
pytest --cov=wyoming_openai

# Run specific test file
pytest tests/test_handler.py

Code Quality

# Run these commands with the repository virtual environment activated
# Run linting with Ruff
ruff check .

# Auto-fix linting issues
ruff check . --fix

# Run type checking with Pyright
pyright

Local Development Setup

# Install in editable mode
pip install -e .

# Run the server locally
python -m wyoming_openai --uri tcp://0.0.0.0:10300 --stt-models whisper-1 --tts-models tts-1

Docker Development

# Build and run development container
docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build

# With local services (e.g., Speaches)
docker compose -f docker-compose.speaches.yml -f docker-compose.dev.yml up -d --build

Architecture

Core Components

• handler.py: Contains OpenAIEventHandler - the main Wyoming protocol event handler that processes ASR and TTS requests
• compatibility.py: Provides CustomAsyncOpenAI class with backend detection and OpenAI API compatibility layer
• __main__.py: Entry point with argument parsing and server initialization
• utilities.py: Helper functions for audio processing and data handling
• const.py: Version constants and configuration

Key Architecture Patterns