Update README.md

README.md

@@ -10,7 +10,6 @@ app_file: app.py
 pinned: false
 license: mit
 ---
----
 # Nova Conversation Partner
 
 A real-time, natural-sounding AI conversation partner powered by AWS NovaSonic.
@@ -22,6 +21,7 @@ A real-time, natural-sounding AI conversation partner powered by AWS NovaSonic.
 - **Speech Coaching**: Analyzes speech patterns and subtly helps improve fluency.
 - **Session Memory**: Continues conversations from where they left off.
 - **Minimal UI**: Simple interface with just a Repeat button and status information.
+- **Fallback Mode**: Works even on systems without audio devices.
 
 ## Setup
 
@@ -31,7 +31,21 @@ A real-time, natural-sounding AI conversation partner powered by AWS NovaSonic.
    ```
 
 2. **AWS Credentials**:
-   Ensure you have AWS credentials configured with access to the Amazon Bedrock service.
+   Configure your AWS credentials using environment variables:
+
+   ```bash
+   export AWS_ACCESS_KEY_ID=your_access_key
+   export AWS_SECRET_ACCESS_KEY=your_secret_key
+   export AWS_DEFAULT_REGION=us-east-1
+   ```
+
+   Alternatively, create a `.env` file in the project root:
+
+   ```
+   AWS_ACCESS_KEY_ID=your_access_key
+   AWS_SECRET_ACCESS_KEY=your_secret_key
+   AWS_DEFAULT_REGION=us-east-1
+   ```
 
 ## Usage
 
@@ -54,7 +68,15 @@ python app.py --cli
 
 In CLI mode, the conversation runs in the terminal with:
 - Automatic audio recording/playback
-- Press Ctrl+C to exit
+- Press Enter to stop the conversation
+
+### Debug Mode
+
+```
+python app.py --debug
+```
+
+Enables detailed logging of API calls and audio processing.
 
 ### Resume a Session
 
@@ -66,6 +88,17 @@ python app.py --session SESSION_ID
 
 Replace `SESSION_ID` with the ID of a previous session.
 
+## Hugging Face Spaces Integration
+
+To use this application in Hugging Face Spaces:
+
+1. Add the following secrets in your Hugging Face Space settings:
+   - `AWS_ACCESS_KEY_ID`
+   - `AWS_SECRET_ACCESS_KEY`
+   - `AWS_DEFAULT_REGION` (optional, defaults to us-east-1)
+
+2. The application will automatically use fallback mode if no audio devices are available.
+
 ## Configuration
 
 Edit `config.py` to customize:
@@ -74,14 +107,32 @@ Edit `config.py` to customize:
 - Memory limit
 - UI text
 
-## Development
+## Troubleshooting
+
+### Audio Device Issues
+
+If you encounter the error "Invalid input device (no default output device)":
+
+- The application will automatically switch to fallback mode
+- You can still interact with Nova, but no actual audio will be played or recorded
+- This is normal in cloud environments and containers without audio hardware
+
+### AWS Authentication Issues
+
+If you see authentication errors:
+
+- Ensure your AWS credentials have access to Bedrock services
+- Check that you've set the environment variables correctly
+- Verify that the region you've specified has access to the Nova Sonic model
+
+## Components
 
 The application architecture includes:
-- `nova_sonic.py`: AWS NovaSonic API client
-- `audio_utils.py`: Audio recording and playback
-- `language_coach.py`: Speech pattern analysis
-- `session_manager.py`: Conversation persistence
-- `app.py`: Main application logic
+- `nova_sonic_tool_use.py`: AWS Bedrock bidirectional streaming implementation
+- `language_coach.py`: Speech pattern analysis and coaching
+- `session_manager.py`: Conversation persistence and history management
+- `app.py`: Main application logic and UI
+- `config.py`: Configuration settings
 
 ## License