Implement infrastructure base classes

src/infrastructure/__init__.py

@@ -1,3 +1 @@
-"""Infrastructure layer package."""
-
-# Infrastructure implementations will be added in subsequent tasks
+"""Infrastructure layer for external service implementations."""

src/infrastructure/base/__init__.py

@@ -0,0 +1 @@
+"""Base classes for infrastructure providers."""

src/infrastructure/base/file_utils.py

@@ -0,0 +1,409 @@
+"""File generation and management utilities for infrastructure providers."""
+
+import logging
+import os
+import tempfile
+import time
+from pathlib import Path
+from typing import Optional, Union
+import hashlib
+
+logger = logging.getLogger(__name__)
+
+
+class FileManager:
+    """Utility class for managing temporary files and directories."""
+
+    def __init__(self, base_dir: Optional[Union[str, Path]] = None):
+        """
+        Initialize the file manager.
+
+        Args:
+            base_dir: Base directory for file operations (defaults to system temp)
+        """
+        if base_dir:
+            self.base_dir = Path(base_dir)
+        else:
+            self.base_dir = Path(tempfile.gettempdir()) / "tts_app"
+
+        self.base_dir.mkdir(exist_ok=True)
+        logger.debug(f"FileManager initialized with base directory: {self.base_dir}")
+
+    def create_temp_file(self, suffix: str = ".tmp", prefix: str = "temp", content: bytes = None) -> Path:
+        """
+        Create a temporary file.
+
+        Args:
+            suffix: File suffix/extension
+            prefix: File prefix
+            content: Optional content to write to the file
+
+        Returns:
+            Path: Path to the created temporary file
+        """
+        timestamp = int(time.time() * 1000)
+        filename = f"{prefix}_{timestamp}{suffix}"
+        file_path = self.base_dir / filename
+
+        if content:
+            with open(file_path, 'wb') as f:
+                f.write(content)
+        else:
+            file_path.touch()
+
+        logger.debug(f"Created temporary file: {file_path}")
+        return file_path
+
+    def create_unique_filename(self, base_name: str, extension: str = "", content_hash: bool = False, content: bytes = None) -> str:
+        """
+        Create a unique filename.
+
+        Args:
+            base_name: Base name for the file
+            extension: File extension (with or without dot)
+            content_hash: Whether to include content hash in filename
+            content: Content to hash (required if content_hash=True)
+
+        Returns:
+            str: Unique filename
+        """
+        timestamp = int(time.time() * 1000)
+
+        if not extension.startswith('.') and extension:
+            extension = '.' + extension
+
+        filename = f"{base_name}_{timestamp}"
+
+        if content_hash and content:
+            hash_obj = hashlib.md5(content)
+            content_hash_str = hash_obj.hexdigest()[:8]
+            filename += f"_{content_hash_str}"
+
+        filename += extension
+        return filename
+
+    def save_audio_file(self, audio_data: bytes, format: str = "wav", prefix: str = "audio") -> Path:
+        """
+        Save audio data to a file.
+
+        Args:
+            audio_data: Raw audio data
+            format: Audio format (wav, mp3, etc.)
+            prefix: Filename prefix
+
+        Returns:
+            Path: Path to the saved audio file
+        """
+        if not format.startswith('.'):
+            format = '.' + format
+
+        filename = self.create_unique_filename(prefix, format, content_hash=True, content=audio_data)
+        file_path = self.base_dir / filename
+
+        with open(file_path, 'wb') as f:
+            f.write(audio_data)
+
+        logger.debug(f"Saved audio file: {file_path} ({len(audio_data)} bytes)")
+        return file_path
+
+    def save_text_file(self, text_content: str, encoding: str = "utf-8", prefix: str = "text") -> Path:
+        """
+        Save text content to a file.
+
+        Args:
+            text_content: Text content to save
+            encoding: Text encoding
+            prefix: Filename prefix
+
+        Returns:
+            Path: Path to the saved text file
+        """
+        filename = self.create_unique_filename(prefix, ".txt")
+        file_path = self.base_dir / filename
+
+        with open(file_path, 'w', encoding=encoding) as f:
+            f.write(text_content)
+
+        logger.debug(f"Saved text file: {file_path} ({len(text_content)} characters)")
+        return file_path
+
+    def cleanup_file(self, file_path: Union[str, Path]) -> bool:
+        """
+        Clean up a single file.
+
+        Args:
+            file_path: Path to the file to clean up
+
+        Returns:
+            bool: True if file was successfully deleted, False otherwise
+        """
+        try:
+            path = Path(file_path)
+            if path.exists() and path.is_file():
+                path.unlink()
+                logger.debug(f"Cleaned up file: {path}")
+                return True
+            return False
+        except Exception as e:
+            logger.warning(f"Failed to cleanup file {file_path}: {str(e)}")
+            return False
+
+    def cleanup_old_files(self, max_age_hours: int = 24, pattern: str = "*") -> int:
+        """
+        Clean up old files in the base directory.
+
+        Args:
+            max_age_hours: Maximum age of files to keep in hours
+            pattern: File pattern to match (glob pattern)
+
+        Returns:
+            int: Number of files cleaned up
+        """
+        try:
+            current_time = time.time()
+            max_age_seconds = max_age_hours * 3600
+            cleaned_count = 0
+
+            for file_path in self.base_dir.glob(pattern):
+                if file_path.is_file():
+                    file_age = current_time - file_path.stat().st_mtime
+                    if file_age > max_age_seconds:
+                        if self.cleanup_file(file_path):
+                            cleaned_count += 1
+
+            if cleaned_count > 0:
+                logger.info(f"Cleaned up {cleaned_count} old files")
+
+            return cleaned_count
+
+        except Exception as e:
+            logger.error(f"Failed to cleanup old files: {str(e)}")
+            return 0
+
+    def get_file_info(self, file_path: Union[str, Path]) -> dict:
+        """
+        Get information about a file.
+
+        Args:
+            file_path: Path to the file
+
+        Returns:
+            dict: File information
+        """
+        try:
+            path = Path(file_path)
+            if not path.exists():
+                return {'exists': False}
+
+            stat = path.stat()
+            return {
+                'exists': True,
+                'size_bytes': stat.st_size,
+                'created_time': stat.st_ctime,
+                'modified_time': stat.st_mtime,
+                'is_file': path.is_file(),
+                'is_directory': path.is_dir(),
+                'extension': path.suffix,
+                'name': path.name,
+                'parent': str(path.parent)
+            }
+        except Exception as e:
+            logger.error(f"Failed to get file info for {file_path}: {str(e)}")
+            return {'exists': False, 'error': str(e)}
+
+    def ensure_directory(self, dir_path: Union[str, Path]) -> Path:
+        """
+        Ensure a directory exists, creating it if necessary.
+
+        Args:
+            dir_path: Path to the directory
+
+        Returns:
+            Path: Path to the directory
+        """
+        path = Path(dir_path)
+        path.mkdir(parents=True, exist_ok=True)
+        logger.debug(f"Ensured directory exists: {path}")
+        return path
+
+    def get_disk_usage(self) -> dict:
+        """
+        Get disk usage information for the base directory.
+
+        Returns:
+            dict: Disk usage information
+        """
+        try:
+            total_size = 0
+            file_count = 0
+
+            for file_path in self.base_dir.rglob('*'):
+                if file_path.is_file():
+                    total_size += file_path.stat().st_size
+                    file_count += 1
+
+            return {
+                'base_directory': str(self.base_dir),
+                'total_size_bytes': total_size,
+                'total_size_mb': total_size / (1024 * 1024),
+                'file_count': file_count
+            }
+        except Exception as e:
+            logger.error(f"Failed to get disk usage: {str(e)}")
+            return {'error': str(e)}
+
+
+class AudioFileGenerator:
+    """Utility class for generating audio files from raw audio data."""
+
+    @staticmethod
+    def save_wav_file(audio_data: bytes, sample_rate: int, file_path: Union[str, Path], channels: int = 1, sample_width: int = 2) -> Path:
+        """
+        Save raw audio data as a WAV file.
+
+        Args:
+            audio_data: Raw audio data
+            sample_rate: Sample rate in Hz
+            file_path: Output file path
+            channels: Number of audio channels
+            sample_width: Sample width in bytes
+
+        Returns:
+            Path: Path to the saved WAV file
+        """
+        try:
+            import wave
+
+            path = Path(file_path)
+
+            with wave.open(str(path), 'wb') as wav_file:
+                wav_file.setnchannels(channels)
+                wav_file.setsampwidth(sample_width)
+                wav_file.setframerate(sample_rate)
+                wav_file.writeframes(audio_data)
+
+            logger.debug(f"Saved WAV file: {path} (sample_rate={sample_rate}, channels={channels})")
+            return path
+
+        except Exception as e:
+            logger.error(f"Failed to save WAV file: {str(e)}")
+            raise
+
+    @staticmethod
+    def convert_numpy_to_wav(audio_array, sample_rate: int, file_path: Union[str, Path]) -> Path:
+        """
+        Convert numpy array to WAV file.
+
+        Args:
+            audio_array: Numpy array containing audio data
+            sample_rate: Sample rate in Hz
+            file_path: Output file path
+
+        Returns:
+            Path: Path to the saved WAV file
+        """
+        try:
+            import numpy as np
+            import soundfile as sf
+
+            path = Path(file_path)
+
+            # Ensure audio is in the correct format
+            if audio_array.dtype != np.float32:
+                audio_array = audio_array.astype(np.float32)
+
+            # Normalize if needed
+            if np.max(np.abs(audio_array)) > 1.0:
+                audio_array = audio_array / np.max(np.abs(audio_array))
+
+            sf.write(str(path), audio_array, sample_rate)
+
+            logger.debug(f"Converted numpy array to WAV: {path}")
+            return path
+
+        except ImportError:
+            logger.error("soundfile library not available for numpy conversion")
+            raise
+        except Exception as e:
+            logger.error(f"Failed to convert numpy array to WAV: {str(e)}")
+            raise
+
+
+class ErrorHandler:
+    """Utility class for handling and logging errors in infrastructure providers."""
+
+    def __init__(self, provider_name: str):
+        """
+        Initialize the error handler.
+
+        Args:
+            provider_name: Name of the provider for error context
+        """
+        self.provider_name = provider_name
+        self.logger = logging.getLogger(f"{__name__}.{provider_name}")
+
+    def handle_error(self, error: Exception, context: str = "", reraise_as: type = None) -> None:
+        """
+        Handle an error with proper logging and optional re-raising.
+
+        Args:
+            error: The original error
+            context: Additional context about when the error occurred
+            reraise_as: Exception type to re-raise as (if None, re-raises original)
+        """
+        error_msg = f"{self.provider_name} error"
+        if context:
+            error_msg += f" during {context}"
+        error_msg += f": {str(error)}"
+
+        self.logger.error(error_msg, exc_info=True)
+
+        if reraise_as:
+            raise reraise_as(error_msg) from error
+        else:
+            raise
+
+    def log_warning(self, message: str, context: str = "") -> None:
+        """
+        Log a warning message.
+
+        Args:
+            message: Warning message
+            context: Additional context
+        """
+        warning_msg = f"{self.provider_name}"
+        if context:
+            warning_msg += f" ({context})"
+        warning_msg += f": {message}"
+
+        self.logger.warning(warning_msg)
+
+    def log_info(self, message: str, context: str = "") -> None:
+        """
+        Log an info message.
+
+        Args:
+            message: Info message
+            context: Additional context
+        """
+        info_msg = f"{self.provider_name}"
+        if context:
+            info_msg += f" ({context})"
+        info_msg += f": {message}"
+
+        self.logger.info(info_msg)
+
+    def log_debug(self, message: str, context: str = "") -> None:
+        """
+        Log a debug message.
+
+        Args:
+            message: Debug message
+            context: Additional context
+        """
+        debug_msg = f"{self.provider_name}"
+        if context:
+            debug_msg += f" ({context})"
+        debug_msg += f": {message}"
+
+        self.logger.debug(debug_msg)

src/infrastructure/base/stt_provider_base.py

@@ -0,0 +1,306 @@
+"""Base class for STT provider implementations."""
+
+import logging
+import os
+import tempfile
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...domain.models.audio_content import AudioContent
+    from ...domain.models.text_content import TextContent
+
+from ...domain.interfaces.speech_recognition import ISpeechRecognitionService
+from ...domain.exceptions import SpeechRecognitionException
+
+logger = logging.getLogger(__name__)
+
+
+class STTProviderBase(ISpeechRecognitionService, ABC):
+    """Abstract base class for STT provider implementations."""
+
+    def __init__(self, provider_name: str, supported_languages: list[str] = None):
+        """
+        Initialize the STT provider.
+
+        Args:
+            provider_name: Name of the STT provider
+            supported_languages: List of supported language codes
+        """
+        self.provider_name = provider_name
+        self.supported_languages = supported_languages or []
+        self._temp_dir = self._ensure_temp_directory()
+
+    def transcribe(self, audio: 'AudioContent', model: str) -> 'TextContent':
+        """
+        Transcribe audio content to text.
+
+        Args:
+            audio: The audio content to transcribe
+            model: The STT model to use for transcription
+
+        Returns:
+            TextContent: The transcribed text
+
+        Raises:
+            SpeechRecognitionException: If transcription fails
+        """
+        try:
+            logger.info(f"Starting transcription with {self.provider_name} provider using model {model}")
+            self._validate_audio(audio)
+
+            # Preprocess audio if needed
+            processed_audio_path = self._preprocess_audio(audio)
+
+            try:
+                # Perform transcription using provider-specific implementation
+                transcribed_text = self._perform_transcription(processed_audio_path, model)
+
+                # Create TextContent from transcription result
+                from ...domain.models.text_content import TextContent
+
+                # Detect language if not specified (default to English)
+                detected_language = self._detect_language(transcribed_text) or 'en'
+
+                text_content = TextContent(
+                    text=transcribed_text,
+                    language=detected_language,
+                    encoding='utf-8'
+                )
+
+                logger.info(f"Transcription completed successfully with {self.provider_name}")
+                return text_content
+
+            finally:
+                # Clean up temporary audio file
+                self._cleanup_temp_file(processed_audio_path)
+
+        except Exception as e:
+            logger.error(f"Transcription failed with {self.provider_name}: {str(e)}")
+            raise SpeechRecognitionException(f"STT transcription failed: {str(e)}") from e
+
+    @abstractmethod
+    def _perform_transcription(self, audio_path: Path, model: str) -> str:
+        """
+        Perform the actual transcription using provider-specific implementation.
+
+        Args:
+            audio_path: Path to the preprocessed audio file
+            model: The STT model to use
+
+        Returns:
+            str: The transcribed text
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        Check if the STT provider is available and ready to use.
+
+        Returns:
+            bool: True if provider is available, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_available_models(self) -> list[str]:
+        """
+        Get list of available models for this provider.
+
+        Returns:
+            list[str]: List of model identifiers
+        """
+        pass
+
+    def _preprocess_audio(self, audio: 'AudioContent') -> Path:
+        """
+        Preprocess audio content for transcription.
+
+        Args:
+            audio: The audio content to preprocess
+
+        Returns:
+            Path: Path to the preprocessed audio file
+        """
+        try:
+            # Create temporary file for audio processing
+            temp_file = self._temp_dir / f"audio_{id(audio)}.wav"
+
+            # Write audio data to temporary file
+            with open(temp_file, 'wb') as f:
+                f.write(audio.data)
+
+            # Convert to required format if needed
+            processed_file = self._convert_audio_format(temp_file, audio)
+
+            logger.debug(f"Audio preprocessed and saved to: {processed_file}")
+            return processed_file
+
+        except Exception as e:
+            logger.error(f"Audio preprocessing failed: {str(e)}")
+            raise SpeechRecognitionException(f"Audio preprocessing failed: {str(e)}") from e
+
+    def _convert_audio_format(self, audio_path: Path, audio: 'AudioContent') -> Path:
+        """
+        Convert audio to the required format for transcription.
+
+        Args:
+            audio_path: Path to the original audio file
+            audio: The audio content metadata
+
+        Returns:
+            Path: Path to the converted audio file
+        """
+        try:
+            # Import audio processing library
+            from pydub import AudioSegment
+
+            # Load audio file
+            if audio.format.lower() == 'mp3':
+                audio_segment = AudioSegment.from_mp3(audio_path)
+            elif audio.format.lower() == 'wav':
+                audio_segment = AudioSegment.from_wav(audio_path)
+            elif audio.format.lower() == 'flac':
+                audio_segment = AudioSegment.from_file(audio_path, format='flac')
+            elif audio.format.lower() == 'ogg':
+                audio_segment = AudioSegment.from_ogg(audio_path)
+            else:
+                # Try to load as generic audio file
+                audio_segment = AudioSegment.from_file(audio_path)
+
+            # Convert to standard format for STT (16kHz, mono, WAV)
+            standardized_audio = audio_segment.set_frame_rate(16000).set_channels(1)
+
+            # Create output path
+            output_path = audio_path.with_suffix('.wav')
+            if output_path == audio_path:
+                output_path = audio_path.with_name(f"converted_{audio_path.name}")
+
+            # Export converted audio
+            standardized_audio.export(output_path, format="wav")
+
+            logger.debug(f"Audio converted from {audio.format} to WAV: {output_path}")
+            return output_path
+
+        except ImportError:
+            logger.warning("pydub not available, using original audio file")
+            return audio_path
+        except Exception as e:
+            logger.warning(f"Audio conversion failed, using original file: {str(e)}")
+            return audio_path
+
+    def _validate_audio(self, audio: 'AudioContent') -> None:
+        """
+        Validate the audio content for transcription.
+
+        Args:
+            audio: The audio content to validate
+
+        Raises:
+            SpeechRecognitionException: If audio is invalid
+        """
+        if not audio.data:
+            raise SpeechRecognitionException("Audio data cannot be empty")
+
+        if audio.duration > 3600:  # 1 hour limit
+            raise SpeechRecognitionException("Audio duration exceeds maximum limit of 1 hour")
+
+        if audio.duration < 0.1:  # Minimum 100ms
+            raise SpeechRecognitionException("Audio duration too short (minimum 100ms)")
+
+        if not audio.is_valid_format:
+            raise SpeechRecognitionException(f"Unsupported audio format: {audio.format}")
+
+    def _detect_language(self, text: str) -> Optional[str]:
+        """
+        Detect the language of transcribed text.
+
+        Args:
+            text: The transcribed text
+
+        Returns:
+            Optional[str]: Detected language code or None if detection fails
+        """
+        try:
+            # Simple heuristic-based language detection
+            # This is a basic implementation - in production, you might use langdetect or similar
+
+            # Check for common English words
+            english_indicators = ['the', 'and', 'is', 'in', 'to', 'of', 'a', 'that', 'it', 'with']
+            text_lower = text.lower()
+            english_count = sum(1 for word in english_indicators if word in text_lower)
+
+            if english_count >= 2:
+                return 'en'
+
+            # Default to English if uncertain
+            return 'en'
+
+        except Exception as e:
+            logger.warning(f"Language detection failed: {str(e)}")
+            return None
+
+    def _ensure_temp_directory(self) -> Path:
+        """
+        Ensure temporary directory exists and return its path.
+
+        Returns:
+            Path: Path to the temporary directory
+        """
+        temp_dir = Path(tempfile.gettempdir()) / "stt_temp"
+        temp_dir.mkdir(exist_ok=True)
+        return temp_dir
+
+    def _cleanup_temp_file(self, file_path: Path) -> None:
+        """
+        Clean up a temporary file.
+
+        Args:
+            file_path: Path to the file to clean up
+        """
+        try:
+            if file_path.exists():
+                file_path.unlink()
+                logger.debug(f"Cleaned up temp file: {file_path}")
+        except Exception as e:
+            logger.warning(f"Failed to cleanup temp file {file_path}: {str(e)}")
+
+    def _cleanup_old_temp_files(self, max_age_hours: int = 24) -> None:
+        """
+        Clean up old temporary files.
+
+        Args:
+            max_age_hours: Maximum age of files to keep in hours
+        """
+        try:
+            import time
+            current_time = time.time()
+            max_age_seconds = max_age_hours * 3600
+
+            for file_path in self._temp_dir.glob("*"):
+                if file_path.is_file():
+                    file_age = current_time - file_path.stat().st_mtime
+                    if file_age > max_age_seconds:
+                        file_path.unlink()
+                        logger.debug(f"Cleaned up old temp file: {file_path}")
+
+        except Exception as e:
+            logger.warning(f"Failed to cleanup old temp files: {str(e)}")
+
+    def _handle_provider_error(self, error: Exception, context: str = "") -> None:
+        """
+        Handle provider-specific errors and convert to domain exceptions.
+
+        Args:
+            error: The original error
+            context: Additional context about when the error occurred
+        """
+        error_msg = f"{self.provider_name} error"
+        if context:
+            error_msg += f" during {context}"
+        error_msg += f": {str(error)}"
+
+        logger.error(error_msg, exc_info=True)
+        raise SpeechRecognitionException(error_msg) from error

src/infrastructure/base/translation_provider_base.py

@@ -0,0 +1,356 @@
+"""Base class for translation provider implementations."""
+
+import logging
+import re
+from abc import ABC, abstractmethod
+from typing import List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ...domain.models.translation_request import TranslationRequest
+    from ...domain.models.text_content import TextContent
+
+from ...domain.interfaces.translation import ITranslationService
+from ...domain.exceptions import TranslationFailedException
+
+logger = logging.getLogger(__name__)
+
+
+class TranslationProviderBase(ITranslationService, ABC):
+    """Abstract base class for translation provider implementations."""
+
+    def __init__(self, provider_name: str, supported_languages: dict[str, list[str]] = None):
+        """
+        Initialize the translation provider.
+
+        Args:
+            provider_name: Name of the translation provider
+            supported_languages: Dict mapping source languages to supported target languages
+        """
+        self.provider_name = provider_name
+        self.supported_languages = supported_languages or {}
+        self.max_chunk_length = 1000  # Default chunk size for text processing
+
+    def translate(self, request: 'TranslationRequest') -> 'TextContent':
+        """
+        Translate text from source language to target language.
+
+        Args:
+            request: The translation request
+
+        Returns:
+            TextContent: The translated text
+
+        Raises:
+            TranslationFailedException: If translation fails
+        """
+        try:
+            logger.info(f"Starting translation with {self.provider_name} provider")
+            logger.info(f"Translating from {request.source_text.language} to {request.target_language}")
+
+            self._validate_request(request)
+
+            # Split text into chunks for processing
+            text_chunks = self._chunk_text(request.source_text.text)
+            logger.info(f"Split text into {len(text_chunks)} chunks for processing")
+
+            # Translate each chunk
+            translated_chunks = []
+            for i, chunk in enumerate(text_chunks):
+                logger.debug(f"Translating chunk {i+1}/{len(text_chunks)}")
+                translated_chunk = self._translate_chunk(
+                    chunk,
+                    request.source_text.language,
+                    request.target_language
+                )
+                translated_chunks.append(translated_chunk)
+
+            # Reassemble translated text
+            translated_text = self._reassemble_chunks(translated_chunks)
+
+            # Create TextContent from translation result
+            from ...domain.models.text_content import TextContent
+
+            result = TextContent(
+                text=translated_text,
+                language=request.target_language,
+                encoding='utf-8'
+            )
+
+            logger.info(f"Translation completed successfully with {self.provider_name}")
+            logger.info(f"Original length: {len(request.source_text.text)}, Translated length: {len(translated_text)}")
+
+            return result
+
+        except Exception as e:
+            logger.error(f"Translation failed with {self.provider_name}: {str(e)}")
+            raise TranslationFailedException(f"Translation failed: {str(e)}") from e
+
+    @abstractmethod
+    def _translate_chunk(self, text: str, source_language: str, target_language: str) -> str:
+        """
+        Translate a single chunk of text using provider-specific implementation.
+
+        Args:
+            text: The text chunk to translate
+            source_language: Source language code
+            target_language: Target language code
+
+        Returns:
+            str: The translated text chunk
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        Check if the translation provider is available and ready to use.
+
+        Returns:
+            bool: True if provider is available, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_supported_languages(self) -> dict[str, list[str]]:
+        """
+        Get supported language pairs for this provider.
+
+        Returns:
+            dict: Mapping of source languages to supported target languages
+        """
+        pass
+
+    def _chunk_text(self, text: str) -> List[str]:
+        """
+        Split text into chunks for translation processing.
+
+        Args:
+            text: The text to chunk
+
+        Returns:
+            List[str]: List of text chunks
+        """
+        if len(text) <= self.max_chunk_length:
+            return [text]
+
+        chunks = []
+        current_chunk = ""
+
+        # Split by sentences first to maintain context
+        sentences = self._split_into_sentences(text)
+
+        for sentence in sentences:
+            # If adding this sentence would exceed chunk limit
+            if len(current_chunk) + len(sentence) > self.max_chunk_length:
+                if current_chunk:
+                    chunks.append(current_chunk.strip())
+                    current_chunk = ""
+
+                # If single sentence is too long, split by words
+                if len(sentence) > self.max_chunk_length:
+                    word_chunks = self._split_long_sentence(sentence)
+                    chunks.extend(word_chunks[:-1])  # Add all but last chunk
+                    current_chunk = word_chunks[-1]  # Start new chunk with last piece
+                else:
+                    current_chunk = sentence
+            else:
+                current_chunk += " " + sentence if current_chunk else sentence
+
+        # Add remaining chunk
+        if current_chunk.strip():
+            chunks.append(current_chunk.strip())
+
+        logger.debug(f"Text chunked into {len(chunks)} pieces")
+        return chunks
+
+    def _split_into_sentences(self, text: str) -> List[str]:
+        """
+        Split text into sentences using basic punctuation rules.
+
+        Args:
+            text: The text to split
+
+        Returns:
+            List[str]: List of sentences
+        """
+        # Simple sentence splitting using regex
+        # This handles basic cases - more sophisticated NLP libraries could be used
+        sentence_endings = r'[.!?]+\s+'
+        sentences = re.split(sentence_endings, text)
+
+        # Filter out empty sentences and strip whitespace
+        sentences = [s.strip() for s in sentences if s.strip()]
+
+        return sentences
+
+    def _split_long_sentence(self, sentence: str) -> List[str]:
+        """
+        Split a long sentence into smaller chunks by words.
+
+        Args:
+            sentence: The sentence to split
+
+        Returns:
+            List[str]: List of word chunks
+        """
+        words = sentence.split()
+        chunks = []
+        current_chunk = ""
+
+        for word in words:
+            if len(current_chunk) + len(word) + 1 > self.max_chunk_length:
+                if current_chunk:
+                    chunks.append(current_chunk.strip())
+                    current_chunk = word
+                else:
+                    # Single word is too long, just add it
+                    chunks.append(word)
+            else:
+                current_chunk += " " + word if current_chunk else word
+
+        if current_chunk.strip():
+            chunks.append(current_chunk.strip())
+
+        return chunks
+
+    def _reassemble_chunks(self, chunks: List[str]) -> str:
+        """
+        Reassemble translated chunks into a single text.
+
+        Args:
+            chunks: List of translated text chunks
+
+        Returns:
+            str: Reassembled text
+        """
+        # Simple reassembly with space separation
+        # More sophisticated approaches could preserve original formatting
+        return " ".join(chunk.strip() for chunk in chunks if chunk.strip())
+
+    def _validate_request(self, request: 'TranslationRequest') -> None:
+        """
+        Validate the translation request.
+
+        Args:
+            request: The translation request to validate
+
+        Raises:
+            TranslationFailedException: If request is invalid
+        """
+        if not request.source_text.text.strip():
+            raise TranslationFailedException("Source text cannot be empty")
+
+        if request.source_text.language == request.target_language:
+            raise TranslationFailedException("Source and target languages cannot be the same")
+
+        # Check if language pair is supported
+        if self.supported_languages:
+            source_lang = request.source_text.language
+            target_lang = request.target_language
+
+            if source_lang not in self.supported_languages:
+                raise TranslationFailedException(
+                    f"Source language {source_lang} not supported by {self.provider_name}. "
+                    f"Supported source languages: {list(self.supported_languages.keys())}"
+                )
+
+            if target_lang not in self.supported_languages[source_lang]:
+                raise TranslationFailedException(
+                    f"Translation from {source_lang} to {target_lang} not supported by {self.provider_name}. "
+                    f"Supported target languages for {source_lang}: {self.supported_languages[source_lang]}"
+                )
+
+    def _preprocess_text(self, text: str) -> str:
+        """
+        Preprocess text before translation.
+
+        Args:
+            text: The text to preprocess
+
+        Returns:
+            str: Preprocessed text
+        """
+        # Basic text preprocessing
+        # Remove excessive whitespace
+        text = re.sub(r'\s+', ' ', text)
+
+        # Strip leading/trailing whitespace
+        text = text.strip()
+
+        return text
+
+    def _postprocess_text(self, text: str) -> str:
+        """
+        Postprocess text after translation.
+
+        Args:
+            text: The text to postprocess
+
+        Returns:
+            str: Postprocessed text
+        """
+        # Basic text postprocessing
+        # Remove excessive whitespace
+        text = re.sub(r'\s+', ' ', text)
+
+        # Strip leading/trailing whitespace
+        text = text.strip()
+
+        # Fix common spacing issues around punctuation
+        text = re.sub(r'\s+([.!?,:;])', r'\1', text)
+        text = re.sub(r'([.!?])\s*([A-Z])', r'\1 \2', text)
+
+        return text
+
+    def _handle_provider_error(self, error: Exception, context: str = "") -> None:
+        """
+        Handle provider-specific errors and convert to domain exceptions.
+
+        Args:
+            error: The original error
+            context: Additional context about when the error occurred
+        """
+        error_msg = f"{self.provider_name} error"
+        if context:
+            error_msg += f" during {context}"
+        error_msg += f": {str(error)}"
+
+        logger.error(error_msg, exc_info=True)
+        raise TranslationFailedException(error_msg) from error
+
+    def set_chunk_size(self, chunk_size: int) -> None:
+        """
+        Set the maximum chunk size for text processing.
+
+        Args:
+            chunk_size: Maximum characters per chunk
+        """
+        if chunk_size <= 0:
+            raise ValueError("Chunk size must be positive")
+
+        self.max_chunk_length = chunk_size
+        logger.info(f"Chunk size set to {chunk_size} characters")
+
+    def get_translation_stats(self, request: 'TranslationRequest') -> dict:
+        """
+        Get statistics about a translation request.
+
+        Args:
+            request: The translation request
+
+        Returns:
+            dict: Translation statistics
+        """
+        text = request.source_text.text
+        chunks = self._chunk_text(text)
+
+        return {
+            'provider': self.provider_name,
+            'source_language': request.source_text.language,
+            'target_language': request.target_language,
+            'text_length': len(text),
+            'word_count': len(text.split()),
+            'chunk_count': len(chunks),
+            'max_chunk_length': max(len(chunk) for chunk in chunks) if chunks else 0,
+            'avg_chunk_length': sum(len(chunk) for chunk in chunks) / len(chunks) if chunks else 0
+        }

src/infrastructure/base/tts_provider_base.py

@@ -0,0 +1,269 @@
+"""Base class for TTS provider implementations."""
+
+import logging
+import os
+import time
+import tempfile
+from abc import ABC, abstractmethod
+from typing import Iterator, Optional, TYPE_CHECKING
+from pathlib import Path
+
+if TYPE_CHECKING:
+    from ...domain.models.speech_synthesis_request import SpeechSynthesisRequest
+    from ...domain.models.audio_content import AudioContent
+    from ...domain.models.audio_chunk import AudioChunk
+
+from ...domain.interfaces.speech_synthesis import ISpeechSynthesisService
+from ...domain.exceptions import SpeechSynthesisException
+
+logger = logging.getLogger(__name__)
+
+
+class TTSProviderBase(ISpeechSynthesisService, ABC):
+    """Abstract base class for TTS provider implementations."""
+
+    def __init__(self, provider_name: str, supported_languages: list[str] = None):
+        """
+        Initialize the TTS provider.
+
+        Args:
+            provider_name: Name of the TTS provider
+            supported_languages: List of supported language codes
+        """
+        self.provider_name = provider_name
+        self.supported_languages = supported_languages or []
+        self._output_dir = self._ensure_output_directory()
+
+    def synthesize(self, request: 'SpeechSynthesisRequest') -> 'AudioContent':
+        """
+        Synthesize speech from text.
+
+        Args:
+            request: The speech synthesis request
+
+        Returns:
+            AudioContent: The synthesized audio
+
+        Raises:
+            SpeechSynthesisException: If synthesis fails
+        """
+        try:
+            logger.info(f"Starting synthesis with {self.provider_name} provider")
+            self._validate_request(request)
+
+            # Generate audio using provider-specific implementation
+            audio_data, sample_rate = self._generate_audio(request)
+
+            # Create AudioContent from the generated data
+            from ...domain.models.audio_content import AudioContent
+
+            audio_content = AudioContent(
+                data=audio_data,
+                format='wav',  # Most providers output WAV
+                sample_rate=sample_rate,
+                duration=self._calculate_duration(audio_data, sample_rate),
+                filename=f"{self.provider_name}_{int(time.time())}.wav"
+            )
+
+            logger.info(f"Synthesis completed successfully with {self.provider_name}")
+            return audio_content
+
+        except Exception as e:
+            logger.error(f"Synthesis failed with {self.provider_name}: {str(e)}")
+            raise SpeechSynthesisException(f"TTS synthesis failed: {str(e)}") from e
+
+    def synthesize_stream(self, request: 'SpeechSynthesisRequest') -> Iterator['AudioChunk']:
+        """
+        Synthesize speech from text as a stream.
+
+        Args:
+            request: The speech synthesis request
+
+        Returns:
+            Iterator[AudioChunk]: Stream of audio chunks
+
+        Raises:
+            SpeechSynthesisException: If synthesis fails
+        """
+        try:
+            logger.info(f"Starting streaming synthesis with {self.provider_name} provider")
+            self._validate_request(request)
+
+            # Generate audio stream using provider-specific implementation
+            chunk_index = 0
+            for audio_data, sample_rate, is_final in self._generate_audio_stream(request):
+                from ...domain.models.audio_chunk import AudioChunk
+
+                chunk = AudioChunk(
+                    data=audio_data,
+                    format='wav',
+                    sample_rate=sample_rate,
+                    chunk_index=chunk_index,
+                    is_final=is_final,
+                    timestamp=time.time()
+                )
+
+                yield chunk
+                chunk_index += 1
+
+            logger.info(f"Streaming synthesis completed with {self.provider_name}")
+
+        except Exception as e:
+            logger.error(f"Streaming synthesis failed with {self.provider_name}: {str(e)}")
+            raise SpeechSynthesisException(f"TTS streaming synthesis failed: {str(e)}") from e
+
+    @abstractmethod
+    def _generate_audio(self, request: 'SpeechSynthesisRequest') -> tuple[bytes, int]:
+        """
+        Generate audio data from synthesis request.
+
+        Args:
+            request: The speech synthesis request
+
+        Returns:
+            tuple: (audio_data_bytes, sample_rate)
+        """
+        pass
+
+    @abstractmethod
+    def _generate_audio_stream(self, request: 'SpeechSynthesisRequest') -> Iterator[tuple[bytes, int, bool]]:
+        """
+        Generate audio data stream from synthesis request.
+
+        Args:
+            request: The speech synthesis request
+
+        Returns:
+            Iterator: (audio_data_bytes, sample_rate, is_final) tuples
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """
+        Check if the TTS provider is available and ready to use.
+
+        Returns:
+            bool: True if provider is available, False otherwise
+        """
+        pass
+
+    @abstractmethod
+    def get_available_voices(self) -> list[str]:
+        """
+        Get list of available voices for this provider.
+
+        Returns:
+            list[str]: List of voice identifiers
+        """
+        pass
+
+    def _validate_request(self, request: 'SpeechSynthesisRequest') -> None:
+        """
+        Validate the synthesis request.
+
+        Args:
+            request: The synthesis request to validate
+
+        Raises:
+            SpeechSynthesisException: If request is invalid
+        """
+        if not request.text_content.text.strip():
+            raise SpeechSynthesisException("Text content cannot be empty")
+
+        if self.supported_languages and request.text_content.language not in self.supported_languages:
+            raise SpeechSynthesisException(
+                f"Language {request.text_content.language} not supported by {self.provider_name}. "
+                f"Supported languages: {self.supported_languages}"
+            )
+
+        available_voices = self.get_available_voices()
+        if available_voices and request.voice_settings.voice_id not in available_voices:
+            raise SpeechSynthesisException(
+                f"Voice {request.voice_settings.voice_id} not available for {self.provider_name}. "
+                f"Available voices: {available_voices}"
+            )
+
+    def _ensure_output_directory(self) -> Path:
+        """
+        Ensure output directory exists and return its path.
+
+        Returns:
+            Path: Path to the output directory
+        """
+        output_dir = Path(tempfile.gettempdir()) / "tts_output"
+        output_dir.mkdir(exist_ok=True)
+        return output_dir
+
+    def _generate_output_path(self, prefix: str = None, extension: str = "wav") -> Path:
+        """
+        Generate a unique output path for audio files.
+
+        Args:
+            prefix: Optional prefix for the filename
+            extension: File extension (default: wav)
+
+        Returns:
+            Path: Unique file path
+        """
+        prefix = prefix or self.provider_name
+        timestamp = int(time.time() * 1000)
+        filename = f"{prefix}_{timestamp}.{extension}"
+        return self._output_dir / filename
+
+    def _calculate_duration(self, audio_data: bytes, sample_rate: int, channels: int = 1, sample_width: int = 2) -> float:
+        """
+        Calculate audio duration from raw audio data.
+
+        Args:
+            audio_data: Raw audio data in bytes
+            sample_rate: Sample rate in Hz
+            channels: Number of audio channels (default: 1)
+            sample_width: Sample width in bytes (default: 2 for 16-bit)
+
+        Returns:
+            float: Duration in seconds
+        """
+        if not audio_data or sample_rate <= 0:
+            return 0.0
+
+        bytes_per_sample = channels * sample_width
+        total_samples = len(audio_data) // bytes_per_sample
+        return total_samples / sample_rate
+
+    def _cleanup_temp_files(self, max_age_hours: int = 24) -> None:
+        """
+        Clean up old temporary files.
+
+        Args:
+            max_age_hours: Maximum age of files to keep in hours
+        """
+        try:
+            current_time = time.time()
+            max_age_seconds = max_age_hours * 3600
+
+            for file_path in self._output_dir.glob("*"):
+                if file_path.is_file():
+                    file_age = current_time - file_path.stat().st_mtime
+                    if file_age > max_age_seconds:
+                        file_path.unlink()
+                        logger.debug(f"Cleaned up old temp file: {file_path}")
+
+        except Exception as e:
+            logger.warning(f"Failed to cleanup temp files: {str(e)}")
+
+    def _handle_provider_error(self, error: Exception, context: str = "") -> None:
+        """
+        Handle provider-specific errors and convert to domain exceptions.
+
+        Args:
+            error: The original error
+            context: Additional context about when the error occurred
+        """
+        error_msg = f"{self.provider_name} error"
+        if context:
+            error_msg += f" during {context}"
+        error_msg += f": {str(error)}"
+
+        logger.error(error_msg, exc_info=True)
+        raise SpeechSynthesisException(error_msg) from error