Merge pull request #25 from roryeckel/copilot/fix-1d0977a5-6a91-4c8a-a123-0f8f86119ad8

Restore missing Voxtral documentation and fix section numbering after main branch merge

Author: roryeckel

CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 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
+```bash
+# 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
+```bash
+# Run linting with Ruff
+ruff check .
+
+# Auto-fix linting issues
+ruff check . --fix
+```
+
+### Local Development Setup
+```bash
+# 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
+```bash
+# 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
+
+1. **Async Event Handling**: Uses Wyoming's `AsyncEventHandler` to process incoming protocol events
+2. **Backend Abstraction**: `CustomAsyncOpenAI` wraps different backends (OpenAI, Speaches, LocalAI, etc.) with a unified interface
+3. **Stream Processing**: Handles both streaming and non-streaming transcription modes
+4. **Audio Buffer Management**: Collects audio chunks into complete files for processing
+
+### Wyoming Protocol Flow
+
+The handler processes these Wyoming events:
+- `AudioStart/AudioChunk/AudioStop` → STT transcription
+- `Transcribe` → Initiate transcription request  
+- `Synthesize` → TTS audio generation
+
+### Backend Support
+
+The `OpenAIBackend` enum defines supported backends:
+- `OPENAI`: Official OpenAI API
+- `SPEACHES`: Local Speaches service
+- `LOCALAI`: LocalAI service
+- `KOKORO_FASTAPI`: Kokoro TTS service
+
+## Configuration
+
+The server accepts both command-line arguments and environment variables. Key configuration includes:
+- STT/TTS API keys and URLs
+- Model lists for STT and TTS
+- Voice configurations
+- Backend-specific settings (temperature, speed, etc.)
+
+## Testing Strategy
+
+Tests are organized by module:
+- `test_handler.py`: Event handler logic
+- `test_compatibility.py`: Backend compatibility
+- `test_utilities.py`: Helper functions
+- `test_integration.py`: End-to-end scenarios

Dockerfile

@@ -5,13 +5,13 @@ FROM python:3.12-slim
 ENV PYTHONDONTWRITEBYTECODE=1
 ENV PYTHONUNBUFFERED=1
 
-# Install system dependencies (if any)
-# build-essential and libssl-dev might be needed for some dependencies
-RUN apt-get update && \
-    apt-get install -y --no-install-recommends \
-        build-essential \
-        libssl-dev \
-    && rm -rf /var/lib/apt/lists/*
+# No system dependencies needed - all Python packages have pre-compiled wheels
+# Uncomment the following lines if you need to install system dependencies
+# RUN apt-get update && \
+#     apt-get install -y --no-install-recommends \
+#         build-essential \
+#         libssl-dev \
+#     && rm -rf /var/lib/apt/lists/*
 
 # Set the working directory in the container
 WORKDIR /app

README.md

@@ -0,0 +1,38 @@
+services:
+  wyoming_openai:
+    image: ghcr.io/roryeckel/wyoming_openai:latest
+    container_name: wyoming_openai
+    ports:
+      - "10300:10300"
+    restart: unless-stopped
+    environment:
+      WYOMING_URI: tcp://0.0.0.0:10300
+      WYOMING_LOG_LEVEL: INFO
+      WYOMING_LANGUAGES: en
+      TTS_OPENAI_URL: http://openai-edge-tts:5050/v1
+      TTS_MODELS: "tts-1"
+      TTS_BACKEND: "OPENAI"
+      TTS_VOICES: "en-US-AnaNeural en-US-AndrewMultilingualNeural en-US-AndrewNeural en-US-AriaNeural en-US-AvaMultilingualNeural en-US-AvaNeural en-US-BrianMultilingualNeural en-US-BrianNeural en-US-ChristopherNeural en-US-EmmaMultilingualNeural en-US-EmmaNeural en-US-EricNeural en-US-GuyNeural en-US-JennyNeural en-US-MichelleNeural en-US-RogerNeural en-US-SteffanNeural"
+      TTS_SPEED: "1.0"
+    depends_on:
+      openai-edge-tts:
+        condition: service_healthy
+
+  openai-edge-tts:
+    image: travisvn/openai-edge-tts:latest
+    container_name: openai-edge-tts
+    restart: unless-stopped
+    ports:
+      - "5050:5050"
+    environment:
+      - PORT=5050
+      - DEFAULT_SPEED=1.0
+      - DEFAULT_LANGUAGE=en-US
+      - REQUIRE_API_KEY=False
+      - REMOVE_FILTER=False
+      - EXPAND_API=False
+    healthcheck:
+      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5050/v1/models', timeout=5)"]
+      interval: 30s
+      retries: 3
+      start_period: 40s

docker-compose.openai-edge-tts.yml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "wyoming_openai"
-version = "0.3.5"
+version = "0.3.6"
 description = "OpenAI-Compatible Proxy Middleware for the Wyoming Protocol"
 authors = [
     { name = "Rory Eckel" }
@@ -21,8 +21,8 @@ classifiers = [
     "Operating System :: OS Independent",
 ]
 dependencies = [
-    "openai==1.91.0",
-    "wyoming==1.7.1"
+    "openai==1.98.0",
+    "wyoming==1.7.2"
 ]
 
 [project.urls]
@@ -35,6 +35,7 @@ dev = [
     "pytest==8.4.1",
     "pytest-asyncio==1.0.0",
     "pytest-mock==3.14.1",
+    "pytest-cov==6.2.1",
 ]
 
 [tool.setuptools.packages.find]

pyproject.toml

@@ -242,4 +242,5 @@ async def main():
             )
         )
 
-asyncio.run(main())
+if __name__ == "__main__":
+    asyncio.run(main())

src/wyoming_openai/__main__.py

@@ -1,6 +1,5 @@
 import logging
 from enum import Enum
-from typing import override
 
 from openai import AsyncOpenAI
 from wyoming.info import AsrModel, AsrProgram, Attribution, Info, TtsProgram, TtsVoice
@@ -277,16 +276,6 @@ def __init__(self, *args, **kwargs):
         self.backend: OpenAIBackend = kwargs.pop("backend", OpenAIBackend.OPENAI)
         super().__init__(*args, **kwargs)
 
-    @property
-    @override
-    def auth_headers(self) -> dict[str, str]:
-        """
-        Override the auth_headers property to remove the Authorization header if no API key is provided.
-        """
-        super_headers = super().auth_headers
-        if not self.api_key:
-            del super_headers["Authorization"]
-        return super_headers
 
     # OpenAI