auris_tools 0.0.1__py3-none-any.whl

auris_tools/configuration.py

@@ -0,0 +1,81 @@
+import logging
+import os
+
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+class AWSConfiguration:
+    """
+    AWS Configuration class that handles credentials and region settings.
+    Prioritizes environment variables over constructor parameters.
+    """
+
+    def __init__(
+        self,
+        access_key: str = None,
+        secret_key: str = None,
+        region: str = None,
+        profile: str = None,
+        endpoint_url: str = None,
+    ):
+        # Try to get credentials from environment variables first
+        self.access_key = (
+            access_key if access_key else os.environ.get('AWS_ACCESS_KEY_ID')
+        )
+        self.secret_key = (
+            secret_key
+            if secret_key
+            else os.environ.get('AWS_SECRET_ACCESS_KEY')
+        )
+        self.region = (
+            region
+            if region
+            else os.environ.get('AWS_DEFAULT_REGION') or 'us-east-1'
+        )
+        self.profile = profile if profile else os.environ.get('AWS_PROFILE')
+        self.endpoint_url = (
+            endpoint_url
+            if endpoint_url
+            else os.environ.get('AWS_ENDPOINT_URL')
+        )
+
+        # Validate configuration
+        self._validate_config()
+
+    def _validate_config(self):
+        """Validate that we have enough configuration to proceed."""
+        if not ((self.access_key and self.secret_key) or self.profile):
+            logging.warning(
+                'No AWS credentials provided via environment variables or constructor. '
+                'AWS operations may fail unless credentials are configured via '
+                '~/.aws/credentials, IAM roles, or other AWS credential providers.'
+            )
+
+    def get_boto3_session_args(self):
+        """
+        Return a dictionary of arguments that can be passed to boto3.session.Session()
+        """
+        session_args = {'region_name': self.region}
+
+        if self.access_key and self.secret_key:
+            session_args['aws_access_key_id'] = self.access_key
+            session_args['aws_secret_access_key'] = self.secret_key
+
+        if self.profile:
+            session_args['profile_name'] = self.profile
+
+        return session_args
+
+    def get_client_args(self):
+        """
+        Return a dictionary of arguments that can be passed to boto3 client creation
+        """
+        client_args = {}
+
+        if self.endpoint_url:
+            client_args['endpoint_url'] = self.endpoint_url
+
+        return client_args

auris_tools/databaseHandlers.py

@@ -0,0 +1,132 @@
+import logging
+
+import boto3
+from boto3.dynamodb.types import TypeDeserializer, TypeSerializer
+
+from auris_tools.configuration import AWSConfiguration
+from auris_tools.utils import generate_uuid
+
+
+class DatabaseHandler:
+    def __init__(self, table_name, config=None):
+        """
+        Initialize the database handler.
+
+        Args:
+            table_name: Name of the DynamoDB table.
+            config: An AWSConfiguration object, or None to use environment variables.
+        """
+        self.table_name = table_name
+        if config is None:
+            config = AWSConfiguration()
+
+        # Create a boto3 session with the configuration
+        session = boto3.session.Session(**config.get_boto3_session_args())
+
+        # Create a DynamoDB client with additional configuration if needed
+        self.client = session.client('dynamodb', **config.get_client_args())
+
+        if not self._check_table_exists(table_name):
+            raise Exception(f'Table does not exist: {table_name}')
+
+        logging.info(f'Initialized DynamoDB client in region {config.region}')
+
+    def insert_item(self, item, primary_key: str = 'id'):
+        """Insert an item with automatic type conversion"""
+        if not isinstance(item, dict):
+            raise TypeError('Item must be a dictionary')
+
+        if primary_key not in item:
+            item[primary_key] = generate_uuid()
+
+        dynamo_item = self._serialize_item(item)
+        response = self.client.put_item(
+            TableName=self.table_name, Item=dynamo_item
+        )
+        return response
+
+    def get_item(self, key):
+        """
+        Retrieve an item from a DynamoDB table.
+
+        Args:
+            key: A dictionary representing the key of the item to retrieve.
+
+        Returns:
+            The retrieved item, or None if not found.
+        """
+        if not isinstance(key, dict):
+            raise TypeError('Key must be a dictionary')
+
+        # Check if the key is in DynamoDB format (i.e., values are dicts with type keys)
+        if not all(isinstance(v, dict) and len(v) == 1 for v in key.values()):
+            # Convert to DynamoDB format
+            key = self._serialize_item(key)
+
+        try:
+            response = self.client.get_item(TableName=self.table_name, Key=key)
+            return response.get('Item')
+        except Exception as e:
+            logging.error(
+                f'Error retrieving item from {self.table_name}: {str(e)}'
+            )
+            return None
+
+    def delete_item(self, key, primary_key='id'):
+        """
+        Delete an item from a DynamoDB table.
+
+        Args:
+            key (str or dict): Either a string identifier for the primary key,
+                              or a dictionary containing the complete key structure.
+            primary_key (str, optional): Name of the primary key field. Defaults to 'id'.
+
+        Returns:
+            bool: True if deletion was successful, False otherwise.
+        """
+        # Convert string key to a dictionary with the primary key
+        if isinstance(key, str):
+            key = {primary_key: key}
+        elif not isinstance(key, dict):
+            raise TypeError('Key must be a string identifier or a dictionary')
+
+        # Check if the key is in DynamoDB format
+        if not self.item_is_serialized(key):
+            key = self._serialize_item(key)
+
+        try:
+            self.client.delete_item(
+                TableName=self.table_name,
+                Key=key,
+                ReturnValues='ALL_OLD',  # Return the deleted item
+            )
+            logging.info(f'Deleted item from {self.table_name} with key {key}')
+            return True
+        except Exception as e:
+            logging.error(
+                f'Error deleting item from {self.table_name}: {str(e)}'
+            )
+            return False
+
+    def item_is_serialized(self, item):
+        """Check if an item is in DynamoDB serialized format"""
+        return all(isinstance(v, dict) and len(v) == 1 for v in item.values())
+
+    def _serialize_item(self, item):
+        """Convert Python types to DynamoDB format"""
+        serializer = TypeSerializer()
+        return {k: serializer.serialize(v) for k, v in item.items()}
+
+    def _deserialize_item(self, item):
+        """Convert DynamoDB format back to Python types"""
+        deserializer = TypeDeserializer()
+        return {k: deserializer.deserialize(v) for k, v in item.items()}
+
+    def _check_table_exists(self, table_name):
+        """Check if a DynamoDB table exists"""
+        try:
+            existing_tables = self.client.list_tables().get('TableNames', [])
+            return table_name in existing_tables
+        except Exception as e:
+            logging.error(f'Error checking table existence: {str(e)}')
+            return False

auris_tools/geminiHandler.py

@@ -0,0 +1,245 @@
+import logging
+import os
+
+import google.generativeai as genai
+from dotenv import load_dotenv
+
+# Load environment variables from .env file
+load_dotenv()
+
+logger = logging.getLogger(__name__)
+
+
+class GoogleGeminiHandler:
+    """A handler class for interacting with Google's Gemini AI models.
+
+    This class provides a convenient interface for generating content using Google's
+    Gemini generative AI models. It handles authentication, model configuration,
+    and content generation with automatic error handling and logging.
+
+    Attributes:
+        api_key (str): The Google AI API key used for authentication.
+        model_name (str): The name of the Gemini model to use.
+        temperature (float): Controls randomness in generation (0.0 to 1.0).
+        response_schema (dict): Optional schema for structured responses.
+        response_mime_type (str): MIME type for response format.
+        generation_config (genai.types.GenerationConfig): Configuration for content generation.
+        model (genai.GenerativeModel): The configured Gemini model instance.
+
+    Example:
+        Basic usage with environment variable API key:
+
+        >>> handler = GoogleGeminiHandler()
+        >>> response = handler.generate_output("What is artificial intelligence?")
+        >>> text = handler.get_text(response)
+
+        Usage with custom parameters:
+
+        >>> handler = GoogleGeminiHandler(
+        ...     api_key="your-api-key",
+        ...     model="gemini-2.0-flash-exp",
+        ...     temperature=0.7,
+        ...     response_mime_type="text/plain"
+        ... )
+    """
+
+    def __init__(
+        self, api_key: str = None, model: str = 'gemini-2.5-flash', **kwargs
+    ):
+        """Initialize the Google Gemini handler.
+
+        Args:
+            api_key (str, optional): Google AI API key. If not provided, will attempt
+                to load from GEMINI_API_KEY environment variable. Defaults to None.
+            model (str, optional): Name of the Gemini model to use.
+                Defaults to 'gemini-2.5-flash'.
+            **kwargs: Additional configuration parameters:
+                - temperature (float): Controls randomness (0.0-1.0). Defaults to 0.5.
+                - response_schema (dict): Schema for structured responses. Defaults to None.
+                - response_mime_type (str): Response MIME type. Defaults to 'application/json'.
+
+        Raises:
+            TypeError: If the specified model is not available.
+
+        Example:
+            >>> handler = GoogleGeminiHandler(
+            ...     api_key="your-api-key",
+            ...     model="gemini-2.0-flash-exp",
+            ...     temperature=0.7
+            ... )
+        """
+
+        self.api_key = api_key if api_key else os.getenv('GEMINI_API_KEY')
+        if self.api_key is None:
+            logger.error(
+                'Gemini API key not configured. Please, define the GEMINI_API_KEY environment variable or enter your key directly in the code.'
+            )
+
+        self.model_name = model
+        self._check_model_availability()
+
+        # More configuration from input parameters
+        self.temperature = kwargs.get('temperature', 0.5)
+        self.response_schema = kwargs.get('response_schema', None)
+        self.response_mime_type = kwargs.get(
+            'response_mime_type', 'application/json'
+        )
+
+        self.generation_config = genai.types.GenerationConfig(
+            temperature=self.temperature,
+            response_schema=self.response_schema,
+            response_mime_type=self.response_mime_type,
+        )
+
+        self.model = genai.GenerativeModel(
+            generation_config=self.generation_config,
+            model_name=self.model_name,
+        )
+
+    def generate_output(
+        self, prompt: str, input_data: str = None, input_mime_type: str = None
+    ):
+        """Generate content using the configured Gemini model.
+
+        This method sends a prompt to the Gemini model and returns the generated response.
+        It supports both text-only prompts and multimodal inputs with additional data.
+
+        Args:
+            prompt (str): The text prompt to send to the model. This is the main
+                instruction or question for the AI to respond to.
+            input_data (str, optional): Additional input data to include with the prompt.
+                This could be text content, encoded media, or other data. Requires
+                input_mime_type to be specified. Defaults to None.
+            input_mime_type (str, optional): MIME type of the input_data. Required if
+                input_data is provided. Examples: 'text/plain', 'image/jpeg',
+                'application/pdf'. Defaults to None.
+
+        Returns:
+            genai.types.GenerateContentResponse or str: The response from the Gemini model
+            if successful, or an empty string if an error occurred.
+
+        Raises:
+            ValueError: If input_data is provided without input_mime_type or vice versa.
+
+        Example:
+            Text-only generation:
+
+            >>> response = handler.generate_output("Explain quantum computing")
+
+            Multimodal generation with additional data:
+
+            >>> response = handler.generate_output(
+            ...     prompt="Describe this image",
+            ...     input_data=base64_encoded_image,
+            ...     input_mime_type="image/jpeg"
+            ... )
+        """
+        if (input_data is not None and input_mime_type is None) or (
+            input_data is None and input_mime_type is not None
+        ):
+            raise ValueError(
+                'input_mime_type must be provided if input_data is given, or otherwise both must be None.'
+            )
+
+        if input_data and input_mime_type:  # Add input data if provided
+            prompt = [
+                prompt,
+                {'mime_type': input_mime_type, 'content': input_data},
+            ]
+
+        try:
+            response = self.model.generate_content(prompt)
+            return response
+        except Exception as e:
+            logger.error(f'Error generating LLM output: {str(e)}')
+            return ''
+
+    def get_text(self, response) -> str:
+        """Extract text content from a Gemini model response.
+
+        This method parses the response object returned by the Gemini model and
+        extracts the generated text content. It handles the response structure
+        safely and provides fallbacks for various response formats.
+
+        Args:
+            response (genai.types.GenerateContentResponse or dict): The response object
+                returned from the generate_output method. This can be either a
+                GenerateContentResponse object or a dictionary representation.
+
+        Returns:
+            str: The extracted text content from the response. Returns an empty
+            string if no content is found or if an error occurs during extraction.
+
+        Example:
+            >>> response = handler.generate_output("What is AI?")
+            >>> text_content = handler.get_text(response)
+            >>> print(text_content)
+            "Artificial Intelligence (AI) refers to..."
+
+            >>> # Handle case with no candidates
+            >>> empty_response = {'candidates': []}
+            >>> text = handler.get_text(empty_response)
+            >>> print(text)  # Returns empty string
+            ""
+        """
+        try:
+            if 'candidates' in response and len(response['candidates']) > 0:
+                return response['candidates'][0]['content']
+            else:
+                logger.warning('No candidates found in the response.')
+                return ''
+        except Exception as e:
+            logger.error(f'Error extracting text from response: {str(e)}')
+            return ''
+
+    def _check_model_availability(self):
+        """Check if the specified Gemini model is available.
+
+        This private method validates that the requested model name exists in the
+        list of available Google Gemini models. It queries the Google AI API to
+        get the current list of available models and compares against the requested
+        model name.
+
+        Raises:
+            TypeError: If the specified model is not found in the list of available
+                models from the Google AI API.
+
+        Note:
+            This method is called automatically during initialization and will
+            prevent the handler from being created if an invalid model is specified.
+            It also logs the availability check results for debugging purposes.
+
+        Example:
+            This method is called internally during initialization:
+
+            >>> # This will call _check_model_availability internally
+            >>> handler = GoogleGeminiHandler(model="gemini-2.5-flash")  # Success
+            >>> handler = GoogleGeminiHandler(model="invalid-model")     # Raises TypeError
+        """
+        try:
+            available_models = genai.list_models()
+            # Extract model names and handle the 'models/' prefix
+            available_model_names = []
+            for model in available_models:
+                model_name = model.name
+                # Remove 'models/' prefix if present
+                if model_name.startswith('models/'):
+                    model_name = model_name[7:]  # Remove 'models/' prefix
+                available_model_names.append(model_name)
+
+            if self.model_name not in available_model_names:
+                logger.error(
+                    f'Model {self.model_name} is not available. Please check the model name.'
+                )
+                logger.info(
+                    f'Available models: {", ".join(available_model_names)}'
+                )
+                raise TypeError(f'Invalid model name: {self.model_name}')
+            else:
+                logger.info(f'Model {self.model_name} is available.')
+        except Exception as e:
+            if 'Invalid model name' in str(e):
+                raise  # Re-raise our custom error
+            else:
+                logger.error(f'Error checking model availability: {str(e)}')
+                # Don't raise error for API connectivity issues, just log

auris_tools/officeWordHandler.py

@@ -0,0 +1,271 @@
+import io
+import logging
+import re
+from typing import List, Optional
+
+import boto3
+from docx import Document
+from docx.opc.constants import RELATIONSHIP_TYPE as RT
+from docx.text.paragraph import Paragraph
+
+from auris_tools.configuration import AWSConfiguration
+
+
+class OfficeWordHandler:
+    """
+    Handler for DOCX operations including text extraction and manipulation.
+
+    This class provides methods to interact with Microsoft Word documents (DOCX)
+    stored in S3, including reading, extracting text, and text replacement operations.
+    """
+
+    def __init__(self, config=None):
+        """
+        Initialize the Office Word handler with AWS configuration.
+
+        Args:
+            config: An AWSConfiguration object, or None to use environment variables
+        """
+        if config is None:
+            config = AWSConfiguration()
+
+        # Create a boto3 session with the configuration
+        session = boto3.session.Session(**config.get_boto3_session_args())
+
+        # Create an S3 client with additional configuration if needed
+        self.s3_client = session.client('s3', **config.get_client_args())
+        logging.info(f'Initialized S3 client in region {config.region}')
+
+    def read_from_s3(self, bucket_name, object_name, as_bytes_io=False):
+        """
+        Read a DOCX file from S3 and return its bytes.
+
+        Args:
+            bucket_name: Name of the S3 bucket containing the document
+            object_name: Object key of the document in the S3 bucket
+            as_bytes_io: If True, return a BytesIO object instead of raw bytes
+
+        Returns:
+            bytes or BytesIO: The document content
+
+        Raises:
+            Exception: If there is an error retrieving the document
+        """
+        try:
+            response = self.s3_client.get_object(
+                Bucket=bucket_name, Key=object_name
+            )
+            content = response['Body'].read()
+
+            if as_bytes_io:
+                return io.BytesIO(content)
+            return content
+        except Exception as e:
+            logging.error(
+                f'Error reading document from {bucket_name}/{object_name}: {str(e)}'
+            )
+            raise Exception(f'Error reading file from S3: {str(e)}')
+
+    def upload_docx(self, docx_document, bucket_name, object_name):
+        """
+        Upload a DOCX document to S3.
+
+        Args:
+            docx_document: The Document object to upload
+            bucket_name: Name of the S3 bucket
+            object_name: Object key for the document in S3
+
+        Returns:
+            bool: True if upload was successful, False otherwise
+
+        Raises:
+            Exception: If there is an error uploading the document
+        """
+        try:
+            logging.info(f'Starting upload to S3: {bucket_name}/{object_name}')
+
+            # Convert document to bytes
+            temp_stream = io.BytesIO()
+            docx_document.save(temp_stream)
+            temp_stream.seek(0)
+            document_size = len(temp_stream.getvalue())
+
+            # Upload to S3
+            self.s3_client.upload_fileobj(
+                temp_stream,
+                Bucket=bucket_name,
+                Key=object_name,
+                ExtraArgs={
+                    'ContentType': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
+                },
+            )
+
+            logging.info(
+                f'Upload finished successfully. Size: {document_size} bytes'
+            )
+            return True
+        except Exception as e:
+            logging.error(f'Failed to upload to S3: {str(e)}')
+            raise Exception(f'Error uploading file to S3: {str(e)}')
+
+    def get_text_from_bytes(self, bytes_data):
+        """
+        Extract text from a DOCX file bytes.
+
+        Args:
+            bytes_data: The document bytes
+
+        Returns:
+            str: Extracted text from the document
+
+        Raises:
+            ValueError: If there is an error extracting the text
+        """
+        try:
+            doc = Document(io.BytesIO(bytes_data))
+            full_text = []
+
+            # Extract text from paragraphs
+            for para in doc.paragraphs:
+                full_text.append(para.text)
+
+            # Extract text from tables
+            for table in doc.tables:
+                for row in table.rows:
+                    for cell in row.cells:
+                        full_text.append(cell.text)
+
+            return '\n'.join(full_text)
+        except Exception as e:
+            logging.error(f'Error extracting text from DOCX: {str(e)}')
+            raise ValueError(f'Error extracting text from DOCX: {str(e)}')
+
+    def clean_text(self, text):
+        """
+        Clean extracted text from a DOCX file.
+
+        Args:
+            text: Text to clean
+
+        Returns:
+            str: Cleaned text
+        """
+        if not text:
+            return ''
+
+        # Basic cleaning (can be extended)
+        cleaned_text = text.strip()
+        return cleaned_text
+
+    def collect_all_paragraphs(self, document: Document) -> List[Paragraph]:
+        """
+        Collect all paragraphs from a Document object.
+
+        This method collects paragraphs from the main document body,
+        tables, headers, and footers.
+
+        Args:
+            document: The Document object
+
+        Returns:
+            List[Paragraph]: List of all paragraphs in the document
+        """
+        paragraphs = list(document.paragraphs)
+
+        for table in document.tables:
+            for row in table.rows:
+                for cell in row.cells:
+                    paragraphs.extend(cell.paragraphs)
+
+        for section in document.sections:
+            paragraphs.extend(section.header.paragraphs)
+            paragraphs.extend(section.footer.paragraphs)
+
+        return paragraphs
+
+    def replace_placeholder_by_text(
+        self,
+        paragraphs: List[Paragraph],
+        document: Document,
+        placeholder: str,
+        replacement: str,
+        max_count: Optional[int] = None,
+    ) -> int:
+        """
+        Replace placeholder text with replacement in document's XML w:t nodes.
+
+        Args:
+            paragraphs: List of paragraphs to process
+            document: Document object
+            placeholder: Text to find and replace
+            replacement: Text to insert instead of placeholder
+            max_count: Maximum number of replacements, or None for unlimited
+
+        Returns:
+            int: Number of replacements made
+
+        Note:
+            This method works at the XML level to ensure proper formatting is preserved.
+        """
+        count = 0
+        WORD_NAMESPACE = (
+            'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+        )
+        T_TAG = f'{{{WORD_NAMESPACE}}}t'
+
+        if placeholder in replacement:
+            logging.warning(
+                f'Replacement skipped to avoid recursion: {placeholder} -> {replacement}'
+            )
+            return 0
+
+        def replace_in_element(element):
+            nonlocal count
+            for node in element.iter(tag=T_TAG):
+                if node.text and placeholder in node.text:
+                    remaining = (
+                        None if max_count is None else max_count - count
+                    )
+                    new_text, n = re.subn(
+                        re.escape(placeholder),
+                        replacement,
+                        node.text,
+                        count=remaining if remaining else 0,
+                    )
+                    if n > 0:
+                        node.text = new_text
+                        count += n
+                        if max_count is not None and count >= max_count:
+                            return True
+            return False
+
+        # Main paragraphs
+        for para in paragraphs:
+            if replace_in_element(para._element):
+                return count
+
+        # Headers/footers
+        for section in document.sections:
+            for container in [section.header, section.footer]:
+                for para in container.paragraphs:
+                    if replace_in_element(para._element):
+                        return count
+
+        # Tables
+        for table in document.tables:
+            for row in table.rows:
+                for cell in row.cells:
+                    for para in cell.paragraphs:
+                        if replace_in_element(para._element):
+                            return count
+
+        # Hyperlinks
+        for rel in document.part.rels.values():
+            if rel.reltype == RT.HYPERLINK and placeholder in rel.target_ref:
+                logging.info(
+                    f'Replacing hyperlink: {rel.target_ref} -> {rel.target_ref.replace(placeholder, replacement)}'
+                )
+                rel._target = rel.target_ref.replace(placeholder, replacement)
+                count += 1
+
+        return count

auris_tools/storageHandler.py

@@ -0,0 +1,195 @@
+import logging
+from http import HTTPStatus
+
+import boto3
+
+from auris_tools.configuration import AWSConfiguration
+
+
+class StorageHandler:
+    def __init__(self, config=None):
+        """
+        Initialize the storage handler with AWS configuration.
+
+        Args:
+            config: An AWSConfiguration object, or None to use environment variables
+        """
+        if config is None:
+            config = AWSConfiguration()
+
+        # Create a boto3 session with the configuration
+        session = boto3.session.Session(**config.get_boto3_session_args())
+
+        # Create an S3 client with additional configuration if needed
+        self.client = session.client('s3', **config.get_client_args())
+        logging.info(f'Initialized S3 client in region {config.region}')
+
+    def upload_file(self, file_path, bucket_name, object_name):
+        """
+        Upload a file to an S3 bucket.
+
+        Args:
+            file_path: Path to the file to upload
+            bucket_name: Name of the bucket to upload to
+            object_name: S3 object name (key)
+
+        Returns:
+            True if file was uploaded successfully, else False
+        """
+        try:
+            self.client.upload_file(file_path, bucket_name, object_name)
+            logging.info(
+                f'Uploaded {file_path} to {bucket_name}/{object_name}'
+            )
+            return True
+        except Exception as e:
+            logging.error(f'Error uploading file {file_path}: {str(e)}')
+            return False
+
+    def download_file(self, bucket_name, object_name, file_path):
+        """
+        Download a file from an S3 bucket.
+
+        Args:
+            bucket_name: Bucket name
+            object_name: S3 object name (key)
+            file_path: Path where the file should be saved
+
+        Returns:
+            True if file was downloaded successfully, else False
+        """
+        try:
+            self.client.download_file(bucket_name, object_name, file_path)
+            logging.info(
+                f'Downloaded {bucket_name}/{object_name} to {file_path}'
+            )
+            return True
+        except Exception as e:
+            logging.error(f'Error downloading file {object_name}: {str(e)}')
+            return False
+
+    def get_file_object(self, bucket_name, object_name, as_bytes=False):
+        """
+        Get a file object from an S3 bucket.
+
+        Args:
+            bucket_name: Bucket name
+            object_name: S3 object name (key)
+            as_bytes: If True, return the content as bytes instead of a streaming object
+
+        Returns:
+            S3 object (streaming) or bytes if as_bytes=True or None if not found
+        """
+        try:
+            response = self.client.get_object(
+                Bucket=bucket_name, Key=object_name
+            )
+            if as_bytes:
+                return response['Body'].read()
+            return response['Body']
+        except Exception as e:
+            logging.error(f'Error getting file object {object_name}: {str(e)}')
+            return None
+
+    def check_file_exists(self, bucket_name, object_name):
+        """
+        Check if a file exists in an S3 bucket.
+
+        Args:
+            bucket_name: Bucket name
+            object_name: S3 object name (key)
+
+        Returns:
+            True if file exists, else False
+        """
+        try:
+            self.client.head_object(Bucket=bucket_name, Key=object_name)
+            return True
+        except Exception:
+            return False
+
+    def check_file_size(self, bucket_name, object_name):
+        """
+        Get the size of a file in an S3 bucket.
+
+        Args:
+            bucket_name: Bucket name
+            object_name: S3 object name (key)
+
+        Returns:
+            File size in bytes or None if file doesn't exist
+        """
+        try:
+            response = self.client.head_object(
+                Bucket=bucket_name, Key=object_name
+            )
+            return response.get('ContentLength')
+        except Exception as e:
+            logging.error(
+                f'Error checking file size for {object_name}: {str(e)}'
+            )
+            return None
+
+    def delete_file(self, bucket_name, object_name):
+        """
+        Delete a file from an S3 bucket.
+
+        Args:
+            bucket_name: Bucket name
+            object_name: S3 object name (key)
+
+        Returns:
+            True if file was deleted successfully, else False
+        """
+        try:
+            # Check if file exists before attempting deletion
+            if not self.check_file_exists(bucket_name, object_name):
+                logging.warning(
+                    f'File {bucket_name}/{object_name} does not exist.'
+                )
+                return False
+
+            response = self.client.delete_object(
+                Bucket=bucket_name, Key=object_name
+            )
+            status_code = response.get('ResponseMetadata', {}).get(
+                'HTTPStatusCode'
+            )
+            # Both 200 (OK) and 204 (No Content) are successful responses
+            if status_code not in (HTTPStatus.OK, HTTPStatus.NO_CONTENT):
+                logging.error(
+                    f'Failed to delete {bucket_name}/{object_name}, status code: {status_code}'
+                )
+                return False
+
+            logging.info(f'Deleted {bucket_name}/{object_name}')
+            return True
+        except Exception as e:
+            logging.error(f'Error deleting file {object_name}: {str(e)}')
+            return False
+
+    def list_files(self, bucket_name, prefix=''):
+        """
+        List files in an S3 bucket with optional prefix filtering.
+
+        Args:
+            bucket_name: Bucket name
+            prefix: Prefix to filter objects (folder path)
+
+        Returns:
+            List of object keys or empty list if error occurs
+        """
+        try:
+            response = self.client.list_objects_v2(
+                Bucket=bucket_name, Prefix=prefix
+            )
+            files = []
+            if 'Contents' in response:
+                for obj in response['Contents']:
+                    files.append(obj['Key'])
+            return files
+        except Exception as e:
+            logging.error(
+                f'Error listing files in {bucket_name}/{prefix}: {str(e)}'
+            )
+            return []

auris_tools/textractHandler.py

@@ -0,0 +1,169 @@
+import logging
+import time
+
+import boto3
+
+from auris_tools.configuration import AWSConfiguration
+
+
+class TextractHandler:
+    """
+    Handler for Amazon Textract operations to extract text from documents.
+
+    This class provides methods to interact with AWS Textract service for
+    text extraction from documents stored in S3.
+    """
+
+    def __init__(self, config=None):
+        """
+        Initialize the Textract handler with AWS configuration.
+
+        Args:
+            config: An AWSConfiguration object, or None to use environment variables
+        """
+        if config is None:
+            config = AWSConfiguration()
+
+        # Create a boto3 session with the configuration
+        session = boto3.session.Session(**config.get_boto3_session_args())
+
+        # Create a Textract client with additional configuration if needed
+        self.client = session.client('textract', **config.get_client_args())
+        logging.info(f'Initialized Textract client in region {config.region}')
+
+    def start_job(self, s3_bucket_name, object_name):
+        """
+        Start an asynchronous text detection job for a document in S3.
+
+        Args:
+            s3_bucket_name: Name of the S3 bucket containing the document
+            object_name: Object key of the document in the S3 bucket
+
+        Returns:
+            str: The JobId of the started Textract job
+
+        Raises:
+            Exception: If there is an error starting the job
+        """
+        try:
+            response = self.client.start_document_text_detection(
+                DocumentLocation={
+                    'S3Object': {'Bucket': s3_bucket_name, 'Name': object_name}
+                }
+            )
+            job_id = response['JobId']
+            logging.info(
+                f'Started Textract job {job_id} for {s3_bucket_name}/{object_name}'
+            )
+            return job_id
+        except Exception as e:
+            logging.error(
+                f'Error starting Textract job for {s3_bucket_name}/{object_name}: {str(e)}'
+            )
+            raise
+
+    def get_job_status(self, job_id):
+        """
+        Get the status of a Textract job.
+
+        Args:
+            job_id: ID of the Textract job
+
+        Returns:
+            str: The job status (e.g., 'IN_PROGRESS', 'SUCCEEDED', 'FAILED')
+        """
+        try:
+            response = self.client.get_document_text_detection(JobId=job_id)
+            status = response['JobStatus']
+            logging.info(f'Textract job {job_id} status: {status}')
+            return status
+        except Exception as e:
+            logging.error(
+                f'Error getting status for Textract job {job_id}: {str(e)}'
+            )
+            raise
+
+    def is_job_complete(self, job_id):
+        """
+        Check if a Textract job has completed.
+
+        Args:
+            job_id: ID of the Textract job
+
+        Returns:
+            str: The job status
+        """
+        time.sleep(1)  # Avoid rate limiting
+        return self.get_job_status(job_id)
+
+    def get_job_results(self, job_id):
+        """
+        Get the results of a completed Textract job.
+
+        This method handles pagination of results automatically.
+
+        Args:
+            job_id: ID of the Textract job
+
+        Returns:
+            list: List of response pages from Textract
+        """
+        pages = []
+        next_token = None
+
+        try:
+            # Get first page
+            response = self.client.get_document_text_detection(JobId=job_id)
+            pages.append(response)
+            logging.info(f'Received page 1 of results for job {job_id}')
+
+            # Get next token if available
+            if 'NextToken' in response:
+                next_token = response['NextToken']
+
+            # Get additional pages if available
+            page_num = 2
+            while next_token:
+                time.sleep(1)  # Avoid rate limiting
+                response = self.client.get_document_text_detection(
+                    JobId=job_id, NextToken=next_token
+                )
+                pages.append(response)
+                logging.info(
+                    f'Received page {page_num} of results for job {job_id}'
+                )
+                page_num += 1
+
+                next_token = response.get('NextToken')
+
+            return pages
+        except Exception as e:
+            logging.error(
+                f'Error getting results for Textract job {job_id}: {str(e)}'
+            )
+            raise
+
+    def get_full_text(self, response):
+        """
+        Extract the full text from Textract response pages.
+
+        Args:
+            response: List of response pages from Textract
+
+        Returns:
+            str: The full extracted text as a string
+        """
+        try:
+            text_lines = []
+            for result_page in response:
+                for item in result_page.get('Blocks', []):
+                    if item.get('BlockType') == 'LINE':
+                        text_lines.append(item.get('Text', ''))
+
+            full_text = ' '.join(text_lines)
+            return full_text
+        except Exception as e:
+            logging.error(
+                f'Error extracting full text from Textract response: {str(e)}'
+            )
+            return ''

auris_tools/utils.py

@@ -0,0 +1,120 @@
+import time
+from contextlib import contextmanager
+from datetime import datetime
+from uuid import uuid4
+
+
+def collect_timestamp(as_str: bool = True):
+    """
+    Collect the current timestamp in ISO 8601 format.
+
+    Parameters
+    ----------
+    as_str : bool, default=True
+        If True, returns the timestamp as an ISO 8601 formatted string.
+        If False, returns a datetime object.
+
+    Returns
+    -------
+    str or datetime
+        Current timestamp as an ISO 8601 formatted string (if as_str=True)
+        or as a datetime object (if as_str=False).
+
+    Examples
+    --------
+    >>> collect_timestamp()
+    '2023-05-18T15:30:45.123456'
+
+    >>> collect_timestamp(as_str=False)
+    datetime.datetime(2023, 5, 18, 15, 30, 45, 123456)
+    """
+    if as_str:
+        return datetime.now().isoformat()
+    return datetime.now()
+
+
+def parse_timestamp(timestamp_input):
+    """Parse a timestamp to a datetime object.
+
+    Args:
+        timestamp_input: Either an ISO 8601 timestamp string or a datetime object.
+
+    Returns:
+        datetime: The parsed datetime object.
+    """
+    if isinstance(timestamp_input, datetime):
+        return timestamp_input
+    return datetime.fromisoformat(timestamp_input)
+
+
+def generate_uuid():
+    """
+    Generate a unique Universally Unique Identifier (UUID) string.
+
+    This function creates a random UUID using version 4 (random) of the UUID
+    specification and returns it as a string. UUIDs are 128-bit identifiers
+    that are guaranteed to be unique across space and time.
+
+    Returns:
+        str: A string representation of a UUID4 (e.g., '9f8d8f79-2d6d-4b96-a3f5-e1f025e6379b')
+
+    Example:
+        >>> unique_id = generate_uuid()
+        >>> print(unique_id)
+        '9f8d8f79-2d6d-4b96-a3f5-e1f025e6379b'
+    """
+    return str(uuid4())
+
+
+def collect_processing_time():
+    """
+    Context manager for measuring code execution time.
+
+    This function provides a context manager that measures the execution time of
+    code within its scope. The execution time is returned in seconds.
+
+    Returns
+    -------
+    callable
+        Function that returns the current elapsed time in seconds when called.
+
+    Examples
+    --------
+    >>> with collect_processing_time() as total_time:
+    ...     # Your code here
+    ...     import time
+    ...     time.sleep(1)
+    >>> print(f"Execution took {total_time()} seconds")
+    Execution took 1.001234 seconds
+
+    >>> # Example with multiple measurements during execution
+    >>> with collect_processing_time() as get_time:
+    ...     # First operation
+    ...     time.sleep(0.5)
+    ...     first_step = get_time()
+    ...     print(f"First step: {first_step:.2f}s")
+    ...
+    ...     # Second operation
+    ...     time.sleep(0.5)
+    ...     second_step = get_time()
+    ...     print(f"Second step: {second_step:.2f}s")
+    First step: 0.50s
+    Second step: 1.00s
+    """
+
+    @contextmanager
+    def _timing_context():
+        start_time = time.time()
+
+        # Create a function to get the current elapsed time
+        def get_elapsed_time():
+            return time.time() - start_time
+
+        try:
+            # Yield the function that returns elapsed time
+            yield get_elapsed_time
+        finally:
+            # No cleanup needed
+            pass
+
+    return _timing_context()

auris_tools-0.0.1.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.3
+Name: auris_tools
+Version: 0.0.1
+Summary: The swiss knife tools to coordinates cloud frameworks with an easy for Auris platforms
+Author: Antonio Senra
+Author-email: acsenrafilho@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: boto3 (>=1.40.29,<2.0.0)
+Requires-Dist: dotenv (>=0.9.9,<0.10.0)
+Requires-Dist: google-generativeai (>=0.8.5,<0.9.0)
+Requires-Dist: python-docx (>=1.2.0,<2.0.0)
+Requires-Dist: rich (>=14.1.0,<15.0.0)
+Description-Content-Type: text/markdown
+
+# auris-tools
+
+The swiss knife tools to coordinates cloud frameworks with an easy for Auris platforms
+
+## Installation
+
+This project requires **Python 3.10** and uses [Poetry](https://python-poetry.org/) for dependency management.
+
+1. **Clone the repository:**
+   ```bash
+   git clone https://github.com/AurisAASI/auris-tools.git
+   cd auris-tools
+   ```
+2. **Install Poetry (if not already installed):**
+   ```bash
+   pip install poetry
+   ```
+3. **Install dependencies:**
+   ```bash
+   poetry install
+   ```
+
+---
+
+## Project Structure
+
+The main classes and modules are organized as follows:
+
+```
+/auris_tools
+├── __init__.py
+├── configuration.py         # AWS configuration utilities
+├── databaseHandlers.py      # DynamoDB handler class
+├── officeWordHandler.py     # Office Word document handler
+├── storageHandler.py        # AWS S3 storage handler
+├── textractHandler.py       # AWS Textract handler
+├── utils.py                 # Utility functions
+├── geminiHandler.py         # Google Gemini AI handler
+```
+
+---
+
+## Testing & Linting
+
+- **Run all tests:**
+  ```bash
+  task test
+  ```
+- **Run linter (ruff):**
+  ```bash
+  task lint
+  ```
+
+Test coverage and linting are enforced in CI. Make sure all tests pass and code is linted before submitting a PR.
+
+---
+

auris_tools-0.0.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+auris_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+auris_tools/configuration.py,sha256=GzBI95GadtW5os_LfFNY0NsV7PzLaj8-IotLKKZ-p8I,2502
+auris_tools/databaseHandlers.py,sha256=YkKABs1YfoEEMr9bDrU7Vg0-aKwOT1c_wh4iI8ET5cI,4777
+auris_tools/geminiHandler.py,sha256=Cdgle1NICGUIx6XmyfEpJ13obiHJgRkvkRpvqPY8l_c,10137
+auris_tools/officeWordHandler.py,sha256=Y_6K2fpmrEP-B7PZYmCYE6P0p1deSguIiopkHNL_V5E,8885
+auris_tools/storageHandler.py,sha256=-rbD0Oi4lstLv3ZVrF2ikUM8A5uPPrXfKGrn-dbXToI,6315
+auris_tools/textractHandler.py,sha256=OGrCwP_Jvehqivqw9ssLDeasJZX93Lg1O6A2NN553Wo,5247
+auris_tools/utils.py,sha256=pBI_2B0e0hMYFg337bbcjHUQQDM_-AdNgof5rJbcaC8,3308
+auris_tools-0.0.1.dist-info/METADATA,sha256=zcgXRMjeplXPk0GNsvQx-MI66iO78e6hDxACttZ97Jw,2061
+auris_tools-0.0.1.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+auris_tools-0.0.1.dist-info/RECORD,,

auris_tools-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: poetry-core 2.1.3
+Root-Is-Purelib: true
+Tag: py3-none-any