Merge remote-tracking branch 'origin/main' into orpheus

Author: roryeckel

.github/copilot-instructions.md

@@ -0,0 +1,103 @@
+# GitHub Copilot Instructions
+
+## Project Context
+
+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.
+
+## Code Style and Conventions
+
+- Use async/await patterns for all I/O operations
+- Follow Python type hints for function signatures
+- Maintain consistency with existing error handling patterns
+- Use logging for debugging and error messages
+- Keep functions focused and modular
+
+## Architecture Overview
+
+### 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 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 Events
+
+The handler processes these Wyoming events:
+- `AudioStart/AudioChunk/AudioStop` → STT transcription
+- `Transcribe` → Initiate transcription request  
+- `Synthesize` → TTS audio generation
+
+### Supported Backends
+
+The `OpenAIBackend` enum defines supported backends:
+- `OPENAI`: Official OpenAI API
+- `SPEACHES`: Local Speaches service
+- `LOCALAI`: LocalAI service
+- `KOKORO_FASTAPI`: Kokoro TTS service
+
+## Testing Guidelines
+
+When writing tests:
+- Use pytest fixtures for common setup
+- Mock external API calls
+- Test both success and error scenarios
+- Include integration tests for end-to-end flows
+- Aim for high code coverage
+
+Test files 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
+
+## Common Development Tasks
+
+### Running Tests
+```bash
+pytest                              # Run all tests
+pytest --cov=wyoming_openai        # With coverage
+pytest tests/test_handler.py       # Specific test file
+```
+
+### Code Quality
+```bash
+ruff check .                       # Run linting
+ruff check . --fix                 # Auto-fix issues
+```
+
+### Local Development
+```bash
+pip install -e ".[dev]"            # Install dev dependencies
+python -m wyoming_openai --uri tcp://0.0.0.0:10300 --stt-models whisper-1 --tts-models tts-1
+```
+
+### Docker Development
+```bash
+docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
+```
+
+## Configuration
+
+The server accepts both command-line arguments and environment variables. When suggesting configuration changes, consider:
+- STT/TTS API keys and URLs
+- Model lists for STT and TTS
+- Voice configurations
+- Backend-specific settings (temperature, speed, etc.)
+
+## When Making Changes
+
+- Ensure backward compatibility with existing Wyoming clients
+- Update tests to reflect new functionality
+- Add appropriate logging for debugging
+- Document new configuration options
+- Consider impact on all supported backends
+- Validate audio format conversions maintain quality

.github/workflows/docker-image-pr.yml

@@ -2,30 +2,45 @@ name: Docker Image PR Build
 
 on:
   pull_request:
+    types: [opened, synchronize, reopened]
     branches: [ "main" ]
 
 jobs:
-  build:
+  build-and-push:
+    # Only run for PRs from the same repository (security measure)
+    if: github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      packages: read
+      packages: write
 
     steps:
     - uses: actions/checkout@v4
 
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+
+    - name: Log in to GitHub Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
     - name: Extract metadata (tags, labels) for Docker
       id: meta
       uses: docker/metadata-action@v5
       with:
         images: ghcr.io/${{ github.repository }}
         tags: |
-          type=sha
+          type=raw,value=pr-${{ github.event.number }}
 
-    - name: Build Docker image
+    - name: Build and push Docker image
       uses: docker/build-push-action@v5
       with:
         context: .
-        push: false
+        push: true
         tags: ${{ steps.meta.outputs.tags }}
         labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max

.github/workflows/pr-cleanup.yml

@@ -0,0 +1,80 @@
+name: PR Docker Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [ "main" ]
+
+jobs:
+  cleanup:
+    # Only run for PRs from the same repository (security measure)
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+    - name: Log in to GitHub Container Registry
+      uses: docker/login-action@v3
+      with:
+        registry: ghcr.io
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Delete PR Docker image
+      continue-on-error: true
+      run: |
+        # Convert repository name to lowercase for Docker registry
+        REPO_LOWER=$(echo "${{ github.repository }}" | \
+          tr '[:upper:]' '[:lower:]')
+        PACKAGE_NAME=$(basename ${REPO_LOWER})
+        TAG_NAME="pr-${{ github.event.number }}"
+
+        echo "Attempting to delete tag: ${TAG_NAME} for package: ${PACKAGE_NAME}"
+
+        # Determine the correct API base path based on repository owner type
+        OWNER_TYPE="${{ github.repository_owner_type }}"
+        OWNER="${{ github.repository_owner }}"
+        if [ "$OWNER_TYPE" = "Organization" ]; then
+          API_BASE="orgs/${OWNER}"
+        else
+          API_BASE="users/${OWNER}"
+        fi
+
+        echo "Using API base path: ${API_BASE}"
+        
+        # Get all versions of the package with error handling
+        API_URL="https://api.github.com/${API_BASE}/packages/container/${PACKAGE_NAME}/versions"
+        RESPONSE=$(curl -sSf \
+          -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+          -H "Accept: application/vnd.github+json" \
+          "${API_URL}" 2>&1)
+        CURL_EXIT_CODE=$?
+        if [ $CURL_EXIT_CODE -ne 0 ]; then
+          echo "Error: Failed to fetch package versions from GitHub API. Response:"
+          echo "$RESPONSE"
+          exit $CURL_EXIT_CODE
+        fi
+        VERSIONS=$(echo "$RESPONSE" | \
+          jq -r '.[] | select(.metadata.container.tags[]? == "'${TAG_NAME}'") | .id')
+
+        if [ -n "$VERSIONS" ]; then
+          for VERSION_ID in $VERSIONS; do
+            echo "Deleting version ID: $VERSION_ID with tag: ${TAG_NAME}"
+            DELETE_URL="${API_URL}/${VERSION_ID}"
+            DELETE_RESPONSE=$(curl -sSf -X DELETE \
+              -H "Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}" \
+              -H "Accept: application/vnd.github+json" \
+              "${DELETE_URL}" 2>&1)
+            DELETE_EXIT_CODE=$?
+            if [ $DELETE_EXIT_CODE -eq 0 ]; then
+              echo "Successfully deleted Docker image version: ${VERSION_ID}"
+            else
+              echo "Warning: Failed to delete version ID: $VERSION_ID. Response:"
+              echo "$DELETE_RESPONSE"
+            fi
+          done
+        else
+          echo "No Docker image found for tag: ${TAG_NAME}, nothing to clean up"
+        fi

.gitignore

@@ -171,4 +171,7 @@ cython_debug/
 .pypirc
 
 # VSCode settings
-.vscode/
+.vscode/
+
+# AI
+.claude/

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