---
title: App Trial Current
emoji: 📈
colorFrom: purple
colorTo: purple
sdk: gradio
sdk_version: 5.29.1
python_version: 3.12
app_file: app.py
pinned: false
license: mit
---
# Nova Conversation Partner

A real-time, natural-sounding AI conversation partner powered by AWS NovaSonic.

## Core Features

- **Live, Natural-Sounding AI Conversation**: Nova acts as a friendly, responsive conversation partner.
- **Low-Latency Real-Time Streaming**: Audio streams directly to NovaSonic's bidirectional API.
- **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

1. **Install Dependencies**:
   ```
   pip install -r requirements.txt
   ```

2. **AWS Credentials**:
   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

### UI Mode (Default)

```
python app.py
```

This launches a Gradio web interface with:
- Start/Stop conversation buttons
- Replay last message button
- Status indicator

### Command Line Mode

```
python app.py --cli
```

In CLI mode, the conversation runs in the terminal with:
- Automatic audio recording/playback
- Press Enter to stop the conversation

### Debug Mode

```
python app.py --debug
```

Enables detailed logging of API calls and audio processing.

### Resume a Session

To continue a previous conversation:

```
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:
- Audio settings
- Greeting message
- Memory limit
- UI text

## 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_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

MIT