ai-voicebot/.github/copilot-instructions.md

• Use 'docker compose' not 'docker-compose'
• server, client, and voicebot directories always run in containers with those names
• All tests created must be put in tests/, which is bind mounted into the containers in /tests.
• In client, to run any npm, npx, node, etc. you need to run via 'docker compose exec client COMMAND'
• In voicebot, to run any python code, you need to run via 'docker compose exec voicebot uv run COMMAND'
• In server, to run any python code, you need to run via 'docker compose exec server uv run COMMAND'
• Server runs HTTPS, self-signed (-k for curl). It is port 8001 on the host and port 8000 inside the docker container. public_url is set to /ai-voicebot, so URLs should be https://localhost:8001/ai-voicebot/... (from host) or https://server:8000/ai-voicebot/... (from inside docker).
• Voicebot runs HTTP. It is not exposed to the host and is connected to by server at http://voicebot:8788.
• All services use hot-load. Any time you change a file, the service will reload. This is not an error. Examination of logs should occur beginning with the messages after the most recent startup complete.
• All docker tail calls should be time relative, not message count relative. Eg., --since 10m not -n 100.

Testing Instructions

General Testing Guidelines

• Always run tests inside the appropriate Docker containers using docker compose exec
• Use uv run for Python commands in voicebot and server containers
• Tests should be placed in the tests/ directory (bind mounted to /tests in containers)
• Use proper PYTHONPATH when running Python code: PYTHONPATH=/:/voicebot for voicebot, PYTHONPATH=/:/server for server
• Check container logs with docker compose logs --since 10m SERVICE_NAME for debugging

Voicebot Testing (Python with uv)

Running Python Code in Voicebot Container

# Basic Python execution
docker compose exec voicebot uv run python3 -c "print('Hello from voicebot')"

# Running Python scripts with proper imports
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 script.py
"

# Running tests
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -m pytest /tests/ -v
"

# Interactive Python session
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3
"

Voicebot-Specific Testing Patterns

# Test bot configuration updates
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
from bots.minimal import create_minimal_bot_tracks, handle_config_update
tracks = create_minimal_bot_tracks('test_session', {'visualization': 'ball'})
success = handle_config_update('test_session', {'visualization': 'waveform'})
print(f'Config update success: {success}')
\"
"

# Test WebRTC signaling
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
from webrtc_signaling import WebRTCSignalingClient
# Test signaling client instantiation
\"
"

Server Testing (Python with uv)

Running Python Code in Server Container

# Basic Python execution
docker compose exec server uv run python3 -c "print('Hello from server')"

# Running server scripts with proper imports
docker compose exec server bash -c "
cd /server && PYTHONPATH=/shared:/server uv run python3 script.py
"

# Running FastAPI server tests
docker compose exec server bash -c "
cd /server && PYTHONPATH=/shared:/server uv run python3 -m pytest /tests/ -v
"

# Interactive Python session
docker compose exec server bash -c "
cd /server && PYTHONPATH=/shared:/server uv run python3
"

Server-Specific Testing Patterns

# Test API endpoints
docker compose exec server bash -c "
cd /server && PYTHONPATH=/shared:/server uv run python3 -c \"
import requests
# Test internal API calls
response = requests.get('http://localhost:8000/health')
print(f'Health check: {response.status_code}')
\"
"

# Test WebSocket connections
docker compose exec server bash -c "
cd /server && PYTHONPATH=/shared:/server uv run python3 -c \"
from websocket.connection import WebSocketConnection
# Test WebSocket connection logic
\"
"

Shared Module Testing

Testing Shared Modules from Voicebot

# Test shared modules from voicebot container
docker compose exec voicebot bash -c "
cd /shared && PYTHONPATH=/shared uv run python3 -c \"
from shared.logger import logger
from shared.models import ChatMessageModel
logger.info('Testing shared modules')
print('Shared modules imported successfully')
\"
"

# Run shared module tests
docker compose exec voicebot bash -c "
cd /shared && PYTHONPATH=/shared uv run python3 -m pytest /tests/test_shared/ -v
"

Testing Shared Modules from Server

# Test shared modules from server container
docker compose exec server bash -c "
cd /shared && PYTHONPATH=/shared uv run python3 -c \"
from shared.logger import logger
from shared.models import BotConfigSchema
logger.info('Testing shared modules from server')
print('Shared modules imported successfully')
\"
"

Integration Testing

Cross-Service Testing

# Test voicebot-server communication
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
import requests
# Test connection to server
try:
    response = requests.get('http://server:8000/health')
    print(f'Server connection: {response.status_code}')
except Exception as e:
    print(f'Connection failed: {e}')
\"
"

# Test server-voicebot communication
docker compose exec server bash -c "
cd /server && PYTHONPATH=/shared:/server uv run python3 -c \"
import requests
# Test connection to voicebot
try:
    response = requests.get('http://voicebot:8788/health')
    print(f'Voicebot connection: {response.status_code}')
except Exception as e:
    print(f'Connection failed: {e}')
\"
"

Debugging and Logging

Container Logs

# View recent logs for all services
docker compose logs --since 10m

# View logs for specific service
docker compose logs --since 10m voicebot
docker compose logs --since 10m server
docker compose logs --since 10m client

# Follow logs in real-time
docker compose logs -f voicebot

Debugging Python Code

# Run with debug output
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
import logging
logging.basicConfig(level=logging.DEBUG)
# Your debug code here
\"
"

# Check Python path and imports
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
import sys
print('Python path:', sys.path)
import shared.logger
print('Shared logger imported successfully')
\"
"

Best Practices

1. Always use proper PYTHONPATH: Include /shared and the service directory
2. Test in containers: Never run Python code directly on host - always use docker compose exec
3. Use uv run: Always prefix Python commands with uv run in voicebot and server
4. Check logs: Use docker compose logs --since 10m for debugging
5. Hot reload: Services reload automatically on file changes - wait for reload messages
6. Test isolation: Use unique identifiers for test sessions to avoid conflicts
7. Network calls: Use service names (server, voicebot) for internal communication
8. Dependencies: All Python dependencies are managed via uv - don't use pip directly

Common Issues and Solutions

Import Errors

# If shared modules can't be imported
docker compose exec voicebot bash -c "
cd /voicebot && PYTHONPATH=/shared:/voicebot uv run python3 -c \"
import sys
sys.path.insert(0, '/shared')
from shared.logger import logger
print('Import successful')
\"
"

Module Not Found

# Check if modules exist and PYTHONPATH is correct
docker compose exec voicebot bash -c "
ls -la /shared/
echo 'PYTHONPATH=/shared:/voicebot'
PYTHONPATH=/shared:/voicebot uv run python3 -c 'import shared.logger'
"

Container Connection Issues

# Check container status
docker compose ps

# Restart services if needed
docker compose restart voicebot
docker compose restart server
"