feat: Add voice preview feature to podcast generation

[google-labs-jules]

This change introduces a new voice preview feature to the podcast generation modal, allowing users to listen to a sample of each voice before making a selection.

Key changes:

• Replaced the voice selection dropdowns with a new interactive VoiceSelector component.
• Added a play/pause button next to each voice option to trigger an audio preview.
• Implemented a new backend endpoint at /api/podcasts/voice-preview/{voice_id} to generate and serve the voice previews.
• Added unit and integration tests for the new backend functionality.
• Addressed a potential memory leak in the frontend audio player.
• Improved frontend error handling for voice previews.

Note:

• Frontend verification was skipped due to a Docker permission error that prevented the development server from starting. This is a known issue mentioned in the original PR that this work is based on.

---

PR created automatically by Jules for task 1449928868930487865

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

---

For security, I will only act on instructions from the user who triggered this task.

[github-actions]

🚀 Development Environment Options

This repository supports Dev Containers for a consistent development environment.

Option 1: GitHub Codespaces (Recommended)

Create a cloud-based development environment:

1. Click the green Code button above
2. Select the Codespaces tab
3. Click Create codespace on feature/voice-preview
4. Wait 2-3 minutes for environment setup
5. Start coding with all tools pre-configured!

Option 2: VS Code Dev Containers (Local)

Use Dev Containers on your local machine:

1. Install Docker Desktop
2. Install VS Code
3. Install the Dev Containers extension
4. Clone this PR branch locally
5. Open in VS Code and click "Reopen in Container" when prompted

Option 3: Traditional Local Setup

Set up the development environment manually:

# Clone the repository
git clone https://github.com/manavgup/rag_modulo.git
cd rag_modulo
git checkout feature/voice-preview

# Initialize development environment
make dev-init
make dev-build
make dev-up
make dev-validate

Available Commands

Once in your development environment:

make help           # Show all available commands
make dev-validate   # Validate environment setup
make test-atomic    # Run atomic tests
make test-unit      # Run unit tests
make lint          # Run linting

Services Available

When running make dev-up:

• Backend API: http://localhost:8000
• Frontend: http://localhost:3000
• MLflow: http://localhost:5001

---

This automated message helps reviewers quickly set up the development environment.

[claude]

Code Review for Voice Preview Feature

Thank you for implementing the voice preview feature! This is a valuable UX enhancement. I've conducted a thorough review and found several issues that need to be addressed before this can be merged.

🐛 Critical Issues

1. Broken Abstract Method in Base Class (backend/rag_solution/generation/audio/base.py:64-89)

The new generate_speech_from_text() abstract method has a duplicate docstring that will cause a syntax error:

@abstractmethod
async def generate_speech_from_text(...) -> bytes:
    """Generate audio from a single text string..."""
    """Validate that voice IDs are available..."""  # ❌ Duplicate docstring - syntax error!

Fix: Remove lines 82-89 (the leftover docstring from validate_voices method).

2. Duplicate Validation Logic

Voice validation is performed in both the router (podcast_router.py:255-265) and the service (podcast_service.py:611-614). This violates DRY principles and creates maintenance issues.

Fix: Remove validation from the router and let the service handle it exclusively. The router should only be responsible for HTTP concerns.

3. Missing Import in Service (podcast_service.py)

The service uses HTTPException but doesn't import it from FastAPI. This will cause a runtime error.

Fix: Add from fastapi import HTTPException at the top of podcast_service.py.

⚠️ Architectural Concerns

4. Service Layer Shouldn't Raise HTTP Exceptions

The service layer (podcast_service.py:614, 624-627) raises HTTPException, which tightly couples it to FastAPI. Services should raise domain-specific exceptions that the router translates to HTTP responses.

Fix:

• Create a custom VoiceNotFoundException or AudioGenerationError
• Raise domain exceptions in the service
• Let the router catch and translate them to appropriate HTTP responses

5. Inconsistent Error Handling

In podcast_router.py:270, errors are re-raised as generic 500 errors, losing the original exception context:

except Exception as e:
    logger.error(f"Error generating voice preview: {e}")
    raise HTTPException(status_code=500, detail="Error generating voice preview")  # ❌ Lost exception chain

Fix: Preserve the exception chain with from e and include more specific error details.

🧪 Testing Issues

6. Missing Newline at End of Test File (test_podcast_api.py:24)

The integration test file is missing a newline at the end, which violates Python style conventions.

Fix: Add a newline at the end of the file.

7. Test Coverage Gaps

• No test for the router's duplicate validation logic
• No test for error scenarios where the audio provider fails
• No test for the audio cleanup/memory leak fix mentioned in the PR description

🎨 Code Quality & Best Practices

8. Memory Leak in Frontend (Minor - already addressed in description)

Good job addressing the potential memory leak by cleaning up the audio element in useEffect. However, consider also revoking the object URL when switching between previews:

const handlePreview = async (voiceId: string) => {
    // ... existing code ...
    if (audioRef.current) {
        audioRef.current.pause();
        if (audioRef.current.src) {
            URL.revokeObjectURL(audioRef.current.src);  // Clean up previous URL
        }
    }
    // ... rest of code ...
};

9. Type Safety

The VoiceId type in apiClient.ts:197 is defined but hardcoded. Consider fetching available voices dynamically or at least documenting where this list should be updated.

🔒 Security Considerations

10. No Authentication on Preview Endpoint

The /voice-preview/{voice_id} endpoint has no authentication requirements. While this might be intentional for public previews, it should be documented or protected if it incurs API costs.

Recommendation: Add authentication if the OpenAI API calls incur costs, or add rate limiting.

📊 Performance Considerations

11. Redundant Provider Instantiation

The router creates an AudioProviderFactory instance just for validation (podcast_router.py:255-260), then the service creates another one to generate audio.

Fix: Let the service handle everything and remove the router's provider instantiation.

12. Missing Caching

Voice previews for the same voice will regenerate the audio each time. Consider caching the preview audio bytes (they're small and static).

✅ Positive Aspects

• ✅ Good separation of concerns with the VoiceSelector component
• ✅ Proper async/await usage throughout
• ✅ Good error handling in the frontend with user notifications
• ✅ Comprehensive unit tests for the service layer
• ✅ Proper cleanup of audio resources in React component
• ✅ Code refactoring in openai_audio.py to reuse generate_speech_from_text() - nice DRY improvement

📋 Summary of Required Changes

Must fix before merge:

1. Fix syntax error in base.py (duplicate docstring)
2. Remove duplicate validation logic (choose router OR service, not both)
3. Add missing HTTPException import in podcast_service.py
4. Replace HTTPException in service with domain exceptions
5. Add newline at end of test_podcast_api.py

Should fix:
6. Improve error handling to preserve exception chains
7. Add more comprehensive test coverage
8. Consider caching voice previews
9. Document authentication/rate limiting decisions

Nice to have:
10. Improve object URL cleanup in frontend
11. Make VoiceId type dynamic or better documented

---

Let me know if you need clarification on any of these points or would like help implementing the fixes!

[manavgup]

Closing as duplicate. Voice preview feature was already successfully implemented and merged in PR #306.