jketreno/ai-voicebot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Updated copilot instructions

Browse Source
This commit is contained in:
James Ketr 2025-09-16 14:34:35 -07:00
parent 8caef2c3de
commit ed8967f394
1 changed files with 246 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

247
.github/copilot-instructions.md vendored
View File

@ -1,5 +1,5 @@
* Use 'docker compose' not 'docker-compose' * Use 'docker compose' not 'docker-compose'
* server, client, and voicebot directories always run in a conatiners with those names * 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. * 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 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 voicebot, to run any python code, you need to run via 'docker compose exec voicebot uv run COMMAND'
@ -8,3 +8,248 @@
* Voicebot runs HTTP. It is not exposed to the host and is connected to by server at http://voicebot:8788. * 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 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. * 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=/shared:/voicebot` for voicebot, `PYTHONPATH=/shared:/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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Check container status
docker compose ps
# Restart services if needed
docker compose restart voicebot
docker compose restart server
"