intellema-vdk 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

intellema_vdk/stt/client.py

@@ -0,0 +1,482 @@
+import os  # Used for operating system dependent functionality, like checking file existence.
+import json  # Used for JSON serialization.
+import logging  # Used for logging events.
+import subprocess  # Used for installing packages
+import sys  # Used for sys operations
+from pathlib import Path  # Used for path operations.
+from typing import Optional, Tuple, Any, List, Dict, Union, TYPE_CHECKING  # Used for type hinting.
+
+# httpx is a core dependency and should be available
+import httpx  # Modern asynchronous HTTP client.
+
+# Lazy import OpenAI - only load when STTManager is instantiated
+if TYPE_CHECKING:
+    from openai import APIError, AsyncOpenAI
+else:
+    APIError = None
+    AsyncOpenAI = None
+
+from ..config import get_env  # Used to get environment variables.
+from .exceptions import (
+    STTConfigurationError,
+    STTFileError,
+    STTTranscriptionError,
+    STTAgentError,
+    STTError
+)
+
+# Setup logger for this module.
+logger = logging.getLogger(__name__)
+
+
+class STTManager:
+    """Manages Speech-to-Text (STT) operations using OpenAI's Whisper model.
+
+    This class provides functionality to transcribe audio files and optionally
+    post the transcribed text to an external agent API.
+
+    Attributes:
+        _api_key (str): The OpenAI API key.
+        _agent_api_url (Optional[str]): The URL of the agent API to post
+            transcriptions to.
+        _agent_post_key (str): The key to use when posting to the agent API.
+        _openai_client (AsyncOpenAI): The asynchronous OpenAI API client.
+        _http_client (httpx.AsyncClient): The asynchronous HTTP client for
+            making requests to the agent API.
+
+    Example:
+        >>> async def main():
+        ...     stt_manager = STTManager(agent_post_key="transcript")
+        ...     try:
+        ...         result, response = await stt_manager.transcribe_and_post("your/audio/file.wav")
+        ...         print(f"Transcript: {result['text']}")
+        ...         print(f"Response from agent: {response}")
+        ...     except STTError as e:
+        ...         print(f"An STT error occurred: {e}")
+        ...     finally:
+        ...         await stt_manager.close()
+        ...
+        >>> if __name__ == "__main__":
+        ...     import asyncio
+        ...     asyncio.run(main())
+    """
+
+    # Default supported audio extensions
+    DEFAULT_BATCH_EXTENSIONS = [".mp3", ".mp4", ".mpeg", ".mpga", ".m4a", ".wav", ".webm"]
+
+    def __init__(self, agent_post_key: str = "message") -> None:
+        """Initializes the STTManager.
+
+        It retrieves the necessary API keys and URLs from environment variables
+        and sets up the API clients.
+
+        Args:
+            agent_post_key (str): The key to use if posting transcriptions to
+                an agent API. Defaults to "message".
+                Transcript will be sent under this key in the JSON payload.
+
+
+        Raises:
+            STTConfigurationError: If the `OPENAI_API_KEY` is not set in the
+                environment variables.
+        """
+        # Lazy import OpenAI - only install when actually used
+        global AsyncOpenAI, APIError
+        if AsyncOpenAI is None:
+            try:
+                from openai import APIError as _APIError, AsyncOpenAI as _AsyncOpenAI
+                APIError = _APIError
+                AsyncOpenAI = _AsyncOpenAI
+            except ImportError:
+                print("OpenAI SDK is not installed. Installing now...")
+                print("Run: pip install intellema-vdk[stt]")
+                try:
+                    subprocess.check_call([sys.executable, "-m", "pip", "install", "openai>=1.0.0"])
+                    from openai import APIError as _APIError, AsyncOpenAI as _AsyncOpenAI
+                    APIError = _APIError
+                    AsyncOpenAI = _AsyncOpenAI
+                    print("✓ OpenAI SDK installed successfully!")
+                except Exception as e:
+                    raise STTConfigurationError(
+                        "Failed to install openai. Please install manually:\n"
+                        "  pip install intellema-vdk[stt]\n"
+                        "or:\n"
+                        "  pip install openai>=1.0.0"
+                    ) from e
+        
+        self._api_key = get_env("OPENAI_API_KEY")
+        if not self._api_key:
+            raise STTConfigurationError(
+                "OPENAI_API_KEY must be set in your .env file.")
+
+        self._agent_api_url = get_env("AGENT_API_URL")
+        if not self._agent_api_url:
+            logger.warning(
+                "AGENT_API_URL is not set in .env. Posting to agent will be disabled.")
+
+        self._agent_post_key = agent_post_key
+        self._openai_client = AsyncOpenAI(api_key=self._api_key)
+        self._http_client = httpx.AsyncClient()
+
+    async def close(self) -> None:
+        """Cleans up resources used by the STTManager.
+
+        This method should be called when the STTManager is no longer needed
+        to close the underlying HTTP and API clients.
+        """
+        await self._http_client.aclose()
+        await self._openai_client.close()
+
+    def _get_audio_files(self, folder_path: str, extensions: List[str], recursive: bool = False) -> List[str]:
+        """Gets all audio files from a folder.
+
+        Args:
+            folder_path (str): The path to the folder.
+            extensions (List[str]): List of file extensions to include (e.g., [".wav", ".mp3"]).
+            recursive (bool): Whether to scan subfolders recursively.
+
+        Returns:
+            List[str]: List of file paths.
+        """
+        folder = Path(folder_path)
+        audio_files = []
+        
+        if recursive:
+            for ext in extensions:
+                audio_files.extend([str(f) for f in folder.rglob(f"*{ext}")])
+        else:
+            for ext in extensions:
+                audio_files.extend([str(f) for f in folder.glob(f"*{ext}")])
+        
+        return sorted(audio_files)
+
+    async def _validate_audio(self, file_path: str, allowed_extensions: Optional[List[str]] = None) -> Tuple[bool, Optional[str]]:
+        """Validates an audio file.
+
+        Args:
+            file_path (str): The path to the audio file.
+            allowed_extensions (Optional[List[str]]): List of allowed extensions. If None,
+                uses DEFAULT_BATCH_EXTENSIONS.
+
+        Returns:
+            Tuple[bool, Optional[str]]: A tuple of (is_valid, error_message).
+                If valid, returns (True, None). If invalid, returns (False, error_message).
+        """
+        # Check if file exists
+        if not os.path.exists(file_path):
+            return False, f"File not found: {file_path}"
+        
+        # Check if it's a file (not a directory)
+        if not os.path.isfile(file_path):
+            return False, f"Path is not a file: {file_path}"
+        
+        # Check if file is readable
+        if not os.access(file_path, os.R_OK):
+            return False, f"File is not readable: {file_path}"
+        
+        # Check file extension
+        file_ext = Path(file_path).suffix.lower()
+        valid_extensions = allowed_extensions if allowed_extensions else self.DEFAULT_BATCH_EXTENSIONS
+        if file_ext not in valid_extensions:
+            return False, f"Unsupported file format: {file_ext}. Allowed: {', '.join(valid_extensions)}"
+        
+        # Check file size (must be > 0)
+        file_size = os.path.getsize(file_path)
+        if file_size == 0:
+            return False, f"File is empty: {file_path}"
+        
+        return True, None
+
+    def _write_output_to_file(self, output_path: str, data: Union[Dict, List[Dict]]) -> None:
+        """Writes transcription results to a file.
+
+        Args:
+            output_path (str): The path to the output file.
+            data (Union[Dict, List[Dict]]): The data to write.
+        """
+        try:
+            output_file = Path(output_path)
+            output_file.parent.mkdir(parents=True, exist_ok=True)
+            
+            with open(output_path, 'w', encoding='utf-8') as f:
+                json.dump(data, f, indent=2, ensure_ascii=False)
+            
+            logger.info(f"Successfully wrote output to: {output_path}")
+        except Exception as e:
+            logger.error(f"Failed to write output to {output_path}: {e}")
+            raise STTFileError(f"Failed to write output to {output_path}: {e}") from e
+
+    async def transcribe_audio(
+        self,
+        path: str,
+        model: str = "whisper-1",
+        language: Optional[str] = None,
+        temperature: Optional[float] = None,
+        batch_process: bool = False,
+        batch_extensions: Optional[List[str]] = None,
+        recursive: bool = False,
+        validate_audio: bool = True,
+        output_file: Optional[str] = None
+    ) -> Union[Dict[str, Any], List[Dict[str, Any]]]:
+        """Transcribes an audio file or batch of audio files using OpenAI's Whisper model.
+
+        Args:
+            path (str): Either a single file path or a folder path when batch_process=True.
+            model (str): The name of the Whisper model to use. Currently, only
+                "whisper-1" is supported by the OpenAI API.
+            language (Optional[str]): The language of the audio in ISO-639-1 format
+                (e.g., "en" for English, "es" for Spanish). If None, the API will
+                auto-detect the language. Defaults to None.
+            temperature (Optional[float]): The sampling temperature, between 0 and 1.
+                Higher values like 0.8 will make the output more random, while lower
+                values like 0.2 will make it more focused and deterministic. If None,
+                the API will use its default value. Defaults to None.
+            batch_process (bool): If False, path must be a single audio file.
+                If True, path is a folder and all supported files inside will be transcribed.
+            batch_extensions (Optional[List[str]]): When batch_process=True, which extensions
+                to include (e.g., [".wav", ".mp3"]). Defaults to all supported formats.
+            recursive (bool): When batch_process=True, whether to scan subfolders.
+            validate_audio (bool): Whether to validate audio files before transcription.
+            output_file (Optional[str]): Path to save the transcription results as JSON.
+
+        Returns:
+            Union[Dict[str, Any], List[Dict[str, Any]]]: 
+                - Single file: {"text": "...", "language": "...", "path": "..."}
+                - Batch: [{"path": "...", "text": "...", "language": "...", "error": None}, ...]
+
+        Raises:
+            STTFileError: If the audio file/folder is not found or invalid.
+            STTTranscriptionError: If there is an error with the OpenAI API.
+        """
+        if batch_process:
+            # Batch processing
+            if not os.path.isdir(path):
+                raise STTFileError(f"Batch processing requires a valid folder path, got: {path}")
+            
+            extensions = batch_extensions or self.DEFAULT_BATCH_EXTENSIONS
+            audio_files = self._get_audio_files(path, extensions, recursive)
+            
+            if not audio_files:
+                logger.warning(f"No audio files found in {path} with extensions {extensions}")
+                result = []
+            else:
+                logger.info(f"Found {len(audio_files)} audio files to process")
+                results = []
+                
+                for file_path in audio_files:
+                    file_result = {
+                        "path": file_path,
+                        "text": None,
+                        "language": None,
+                        "error": None
+                    }
+                    
+                    try:
+                        # Validate if needed
+                        if validate_audio:
+                            is_valid, error_msg = await self._validate_audio(file_path, extensions)
+                            if not is_valid:
+                                file_result["error"] = error_msg
+                                logger.warning(f"Validation failed for {file_path}: {error_msg}")
+                                results.append(file_result)
+                                continue
+                        
+                        # Transcribe
+                        single_result = await self._transcribe_single_file(file_path, model, language, temperature, validate_audio=False)
+                        file_result["text"] = single_result["text"]
+                        file_result["language"] = single_result.get("language")
+                        
+                    except Exception as e:
+                        file_result["error"] = str(e)
+                        logger.error(f"Failed to transcribe {file_path}: {e}")
+                    
+                    results.append(file_result)
+                
+                result = results
+            
+            # Write to file if specified
+            if output_file:
+                self._write_output_to_file(output_file, result)
+            
+            return result
+        else:
+            # Single file processing
+            # Warn if batch_extensions is specified without batch_process
+            if batch_extensions:
+                logger.warning(
+                    f"batch_extensions={batch_extensions} specified but batch_process=False. "
+                    f"The extension filter will be used for validation."
+                )
+            
+            # Warn if recursive is specified without batch_process
+            if recursive:
+                logger.warning(
+                    "recursive=True specified but batch_process=False. "
+                    "This parameter is ignored for single file processing."
+                )
+            
+            result = await self._transcribe_single_file(
+                path, model, language, temperature, validate_audio, 
+                allowed_extensions=batch_extensions
+            )
+            
+            # Write to file if specified
+            if output_file:
+                self._write_output_to_file(output_file, result)
+            
+            return result
+
+    async def _transcribe_single_file(
+        self,
+        file_path: str,
+        model: str,
+        language: Optional[str],
+        temperature: Optional[float],
+        validate_audio: bool = True,
+        allowed_extensions: Optional[List[str]] = None
+    ) -> Dict[str, Any]:
+        """Transcribes a single audio file.
+
+        Args:
+            file_path (str): The path to the audio file.
+            model (str): The Whisper model to use.
+            language (Optional[str]): The language code.
+            temperature (Optional[float]): The sampling temperature.
+            validate_audio (bool): Whether to validate the audio file.
+            allowed_extensions (Optional[List[str]]): Allowed file extensions for validation.
+
+        Returns:
+            Dict[str, Any]: {"text": "...", "language": "...", "path": "..."}
+
+        Raises:
+            STTFileError: If validation fails.
+            STTTranscriptionError: If transcription fails.
+        """
+        logger.info(f"Starting transcription for file: {file_path}")
+        
+        # Validate if needed
+        if validate_audio:
+            is_valid, error_msg = await self._validate_audio(file_path, allowed_extensions)
+            if not is_valid:
+                raise STTFileError(error_msg)
+
+        try:
+            with open(file_path, "rb") as audio_file:
+                transcription_params = {
+                    "model": model,
+                    "file": audio_file
+                }
+                if language:
+                    transcription_params["language"] = language
+                if temperature is not None:
+                    transcription_params["temperature"] = temperature
+                
+                transcript = await self._openai_client.audio.transcriptions.create(**transcription_params)
+        except APIError as e:
+            raise STTTranscriptionError(f"OpenAI API error: {e}") from e
+        
+        logger.info(f"Successfully transcribed file: {file_path}")
+        
+        return {
+            "text": transcript.text,
+            "language": language,
+            "path": file_path
+        }
+
+    async def transcribe_and_post(
+        self,
+        path: str,
+        model: str = "whisper-1",
+        language: Optional[str] = None,
+        temperature: Optional[float] = None,
+        batch_process: bool = False,
+        batch_extensions: Optional[List[str]] = None,
+        recursive: bool = False,
+        validate_audio: bool = True,
+        output_file: Optional[str] = None
+    ) -> Tuple[Union[Dict[str, Any], List[Dict[str, Any]]], Optional[Any]]:
+        """Transcribes an audio file or batch and posts the result to the agent API.
+
+        Args:
+            path (str): Either a single file path or a folder path when batch_process=True.
+            model (str): The name of the Whisper model to use.
+            language (Optional[str]): The language of the audio in ISO-639-1 format.
+            temperature (Optional[float]): The sampling temperature, between 0 and 1.
+            batch_process (bool): If False, path is a single file. If True, path is a folder.
+            batch_extensions (Optional[List[str]]): File extensions to include in batch mode.
+            recursive (bool): Whether to scan subfolders in batch mode.
+            validate_audio (bool): Whether to validate audio files before transcription.
+            output_file (Optional[str]): Path to save the transcription results as JSON.
+
+        Returns:
+            A tuple containing:
+            - Union[Dict[str, Any], List[Dict[str, Any]]]: Transcription result(s).
+            - Optional[Any]: The JSON response from the agent API, or None if disabled.
+
+        Raises:
+            STTError: If any step in the process fails.
+        """
+        try:
+            # Transcribe the audio file(s)
+            transcript_result = await self.transcribe_audio(
+                path=path,
+                model=model,
+                language=language,
+                temperature=temperature,
+                batch_process=batch_process,
+                batch_extensions=batch_extensions,
+                recursive=recursive,
+                validate_audio=validate_audio,
+                output_file=output_file
+            )
+
+            response = None
+            # Post the transcribed text to the agent API if the URL is configured
+            if self._agent_api_url:
+                if batch_process:
+                    # For batch, post all successful transcriptions
+                    texts = [r["text"] for r in transcript_result if r["text"] is not None]
+                    if texts:
+                        response = await self._post_to_agent(texts)
+                else:
+                    # For single file, post the text
+                    response = await self._post_to_agent(transcript_result["text"])
+            else:
+                logger.info("AGENT_API_URL not set, skipping post to agent.")
+
+            return transcript_result, response
+
+        except STTError as e:
+            logger.error(
+                f"STT Error during processing of {path}: {e}", exc_info=True)
+            raise
+        except Exception as e:
+            logger.error(
+                f"An unexpected error occurred during processing of {path}: {e}", exc_info=True)
+            raise
+
+    async def _post_to_agent(self, data: Union[str, List[str]]) -> Any:
+        """Posts the transcribed text to the agent API.
+
+        The text is sent in a JSON payload under the configured key.
+
+        Args:
+            data (Union[str, List[str]]): The transcribed text or list of texts to post.
+
+        Returns:
+            Any: The JSON response from the agent API.
+
+        Raises:
+            STTAgentError: If the HTTP request to the agent API fails.
+        """
+        payload = {self._agent_post_key: data}
+        try:
+            logger.info(f"Posting to agent with payload: {payload}")
+            response = await self._http_client.post(self._agent_api_url, json=payload)
+            response.raise_for_status()  # Raises HTTPError for bad responses (4xx or 5xx)
+            logger.info(
+                f"Successfully posted to agent. Status: {response.status_code}")
+            return response.json()
+        except httpx.HTTPError as e:
+            logger.error(f"Failed to post to agent API: {e}", exc_info=True)
+            raise STTAgentError(f"Failed to post to agent API: {e}") from e

intellema_vdk/stt/exceptions.py

@@ -0,0 +1,19 @@
+class STTError(Exception):
+    """Base exception for all STT-related errors."""
+    pass
+
+class STTConfigurationError(STTError):
+    """Raised when configuration (API keys, URLs) is missing or invalid."""
+    pass
+
+class STTFileError(STTError):
+    """Raised when the audio file is not found or inaccessible."""
+    pass
+
+class STTTranscriptionError(STTError):
+    """Raised when the transcription service (OpenAI) fails."""
+    pass
+
+class STTAgentError(STTError):
+    """Raised when posting to the agent API fails."""
+    pass

intellema_vdk/tts/__init__.py

@@ -0,0 +1,15 @@
+from .client import TTSStreamer
+from .exceptions import (
+    TTSError,
+    TTSConfigurationError,
+    TTSStreamError,
+    TTSAPIError,
+)
+
+__all__ = [
+    "TTSStreamer",
+    "TTSError",
+    "TTSConfigurationError",
+    "TTSStreamError",
+    "TTSAPIError",
+]