srx-lib-azure 0.1.7__py3-none-any.whl → 0.2.0__py3-none-any.whl

srx_lib_azure/__init__.py

@@ -1,6 +1,11 @@
 from .blob import AzureBlobService
+from .document import AzureDocumentIntelligenceService
 from .email import EmailService
 from .table import AzureTableService
 
-__all__ = ["AzureBlobService", "EmailService", "AzureTableService"]
-
+__all__ = [
+    "AzureBlobService",
+    "AzureDocumentIntelligenceService",
+    "AzureTableService",
+    "EmailService",
+]

srx_lib_azure/blob.py

@@ -4,6 +4,11 @@ from datetime import datetime, timedelta, timezone
 from typing import Optional, BinaryIO, Tuple
 
 from azure.storage.blob import BlobServiceClient, BlobSasPermissions, generate_blob_sas
+from azure.core.exceptions import (
+    ResourceNotFoundError,
+    ClientAuthenticationError,
+    HttpResponseError,
+)
 from fastapi import UploadFile
 
 from loguru import logger
@@ -49,9 +54,7 @@ class AzureBlobService:
             return None, None
         try:
             clean = self.connection_string.strip().strip('"').strip("'")
-            parts = dict(
-                seg.split("=", 1) for seg in clean.split(";") if "=" in seg
-            )
+            parts = dict(seg.split("=", 1) for seg in clean.split(";") if "=" in seg)
             account_name = parts.get("AccountName")
             account_key = parts.get("AccountKey") or self.account_key
             return account_name, account_key
@@ -93,9 +96,20 @@ class AzureBlobService:
         if self.base_blob_url:
             base_url = self.base_blob_url.strip().strip('"').strip("'").rstrip("/")
             return f"{base_url}/{blob_name}?{sas}"
-        return f"https://{account_name}.blob.core.windows.net/{self.container_name}/{blob_name}?{sas}"
+        return (
+            f"https://{account_name}.blob.core.windows.net/{self.container_name}/{blob_name}?{sas}"
+        )
 
     async def upload_file(self, file: UploadFile, blob_path: str) -> Optional[str]:
+        """Upload a file to Azure Blob Storage and return a SAS URL.
+
+        Args:
+            file: File to upload
+            blob_path: Destination path in the container
+
+        Returns:
+            SAS URL if successful, None on error
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return None
@@ -105,13 +119,37 @@ class AzureBlobService:
             container = client.get_container_client(self.container_name)
             content = await file.read()
             blob_client = container.get_blob_client(blob_path)
-            blob_client.upload_blob(content, overwrite=True, content_type=file.content_type or "application/octet-stream")
+            blob_client.upload_blob(
+                content,
+                overwrite=True,
+                content_type=file.content_type or "application/octet-stream",
+            )
             return self._generate_sas_url(blob_path)
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed uploading {file.filename}: {e}")
+            return None
+        except HttpResponseError as e:
+            logger.error(
+                f"Azure service error uploading {file.filename}: {e.status_code} - {e.message}"
+            )
+            return None
         except Exception as e:
-            logger.error(f"Failed to upload file {file.filename}: {e}")
+            logger.error(f"Unexpected error uploading {file.filename}: {e}")
             return None
 
-    async def upload_stream(self, stream: BinaryIO, blob_path: str, content_type: str = "application/octet-stream") -> Optional[str]:
+    async def upload_stream(
+        self, stream: BinaryIO, blob_path: str, content_type: str = "application/octet-stream"
+    ) -> Optional[str]:
+        """Upload a binary stream to Azure Blob Storage and return a SAS URL.
+
+        Args:
+            stream: Binary stream to upload
+            blob_path: Destination path in the container
+            content_type: MIME type of the content
+
+        Returns:
+            SAS URL if successful, None on error
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return None
@@ -122,12 +160,27 @@ class AzureBlobService:
             blob_client = container.get_blob_client(blob_path)
             blob_client.upload_blob(stream, overwrite=True, content_type=content_type)
             return self._generate_sas_url(blob_path)
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed uploading stream to {blob_path}: {e}")
+            return None
+        except HttpResponseError as e:
+            logger.error(
+                f"Azure service error uploading stream to {blob_path}: {e.status_code} - {e.message}"
+            )
+            return None
         except Exception as e:
-            logger.error(f"Failed to upload stream to {blob_path}: {e}")
+            logger.error(f"Unexpected error uploading stream to {blob_path}: {e}")
             return None
 
     async def download_file(self, blob_path: str) -> Optional[bytes]:
-        """Download a blob's content as bytes."""
+        """Download a blob's content as bytes.
+
+        Returns:
+            bytes if successful, None if blob doesn't exist
+
+        Raises:
+            RuntimeError: For connection/auth errors (caller should handle)
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return None
@@ -139,9 +192,24 @@ class AzureBlobService:
             content = download_stream.readall()
             logger.info(f"Successfully downloaded {blob_path}")
             return content
-        except Exception as e:
-            logger.error(f"Failed to download {blob_path}: {e}")
+        except ResourceNotFoundError:
+            # Blob doesn't exist - this is expected in many scenarios
+            logger.info(f"Blob not found: {blob_path}")
             return None
+        except ClientAuthenticationError as e:
+            # Auth errors should not be retried - they need credential fixes
+            logger.error(f"Authentication failed for {blob_path}: {e}")
+            raise RuntimeError(f"Azure authentication failed: {e}") from e
+        except HttpResponseError as e:
+            # Other Azure service errors (rate limits, service issues, etc.)
+            logger.error(
+                f"Azure service error downloading {blob_path}: {e.status_code} - {e.message}"
+            )
+            raise RuntimeError(f"Azure Blob download failed for {blob_path}: {e.message}") from e
+        except Exception as e:
+            # Catch-all for unexpected errors (network, etc.)
+            logger.error(f"Unexpected error downloading {blob_path}: {e}")
+            raise RuntimeError(f"Unexpected error downloading {blob_path}: {e}") from e
 
     async def download_to_temp_file(self, blob_path: str) -> Optional[str]:
         """Download a blob to a temporary file and return its path."""
@@ -149,7 +217,9 @@ class AzureBlobService:
         if content is None:
             return None
         try:
-            with tempfile.NamedTemporaryFile(delete=False, suffix=os.path.splitext(blob_path)[1]) as tf:
+            with tempfile.NamedTemporaryFile(
+                delete=False, suffix=os.path.splitext(blob_path)[1]
+            ) as tf:
                 tf.write(content)
                 path = tf.name
             logger.info(f"Downloaded {blob_path} to temporary file: {path}")
@@ -172,7 +242,14 @@ class AzureBlobService:
         return None
 
     async def delete_file(self, blob_path: str) -> bool:
-        """Delete a blob and return True on success."""
+        """Delete a blob and return True on success.
+
+        Args:
+            blob_path: Path to the blob to delete
+
+        Returns:
+            True if deleted successfully or blob doesn't exist, False on error
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return False
@@ -183,12 +260,29 @@ class AzureBlobService:
             blob_client.delete_blob()
             logger.info(f"Successfully deleted {blob_path}")
             return True
+        except ResourceNotFoundError:
+            # Blob already doesn't exist - this is still success
+            logger.info(f"Blob {blob_path} already deleted or doesn't exist")
+            return True
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed when deleting {blob_path}: {e}")
+            return False
+        except HttpResponseError as e:
+            logger.error(f"Azure service error deleting {blob_path}: {e.status_code} - {e.message}")
+            return False
         except Exception as e:
-            logger.error(f"Failed to delete {blob_path}: {e}")
+            logger.error(f"Unexpected error deleting {blob_path}: {e}")
             return False
 
     async def file_exists(self, blob_path: str) -> bool:
-        """Check if a blob exists in the container."""
+        """Check if a blob exists in the container.
+
+        Args:
+            blob_path: Path to the blob to check
+
+        Returns:
+            True if blob exists, False otherwise (including on errors)
+        """
         if not self.connection_string:
             logger.error("Azure Storage connection string not configured")
             return False
@@ -197,6 +291,12 @@ class AzureBlobService:
             container = client.get_container_client(self.container_name)
             blob_client = container.get_blob_client(blob_path)
             return blob_client.exists()
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed checking {blob_path}: {e}")
+            return False
+        except HttpResponseError as e:
+            logger.error(f"Azure service error checking {blob_path}: {e.status_code} - {e.message}")
+            return False
         except Exception as e:
-            logger.error(f"Failed to check existence of {blob_path}: {e}")
+            logger.error(f"Unexpected error checking existence of {blob_path}: {e}")
             return False

srx_lib_azure/document.py

@@ -0,0 +1,262 @@
+import os
+import io
+import asyncio
+from typing import Dict, Any, Optional
+
+from loguru import logger
+
+try:
+    from azure.ai.documentintelligence import DocumentIntelligenceClient
+    from azure.ai.documentintelligence.models import AnalyzeDocumentRequest, AnalyzeResult
+    from azure.core.credentials import AzureKeyCredential
+    from azure.core.exceptions import (
+        ClientAuthenticationError,
+        HttpResponseError,
+        ServiceRequestError,
+    )
+except Exception:  # pragma: no cover - optional dependency at import time
+    DocumentIntelligenceClient = None  # type: ignore
+    AnalyzeDocumentRequest = None  # type: ignore
+    AnalyzeResult = None  # type: ignore
+    AzureKeyCredential = None  # type: ignore
+    ClientAuthenticationError = None  # type: ignore
+    HttpResponseError = None  # type: ignore
+    ServiceRequestError = None  # type: ignore
+
+
+class AzureDocumentIntelligenceService:
+    """Wrapper for Azure Document Intelligence (OCR/Document Analysis).
+
+    Does not raise on missing configuration to keep the library optional.
+    If not configured, analysis calls return error responses with descriptive messages.
+    """
+
+    def __init__(
+        self,
+        *,
+        endpoint: Optional[str] = None,
+        key: Optional[str] = None,
+        warn_if_unconfigured: bool = False,
+    ):
+        """Initialize Document Intelligence service.
+
+        Args:
+            endpoint: Azure Document Intelligence endpoint URL
+            key: Azure Document Intelligence API key
+            warn_if_unconfigured: Whether to log a warning if not configured
+        """
+        self.endpoint = endpoint or os.getenv("AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT")
+        self.key = key or os.getenv("AZURE_DOCUMENT_INTELLIGENCE_KEY")
+
+        if not self.endpoint or not self.key or DocumentIntelligenceClient is None:
+            self.client = None
+            if warn_if_unconfigured:
+                logger.warning(
+                    "AzureDocumentIntelligenceService not configured "
+                    "(missing endpoint/key or azure-ai-documentintelligence SDK). "
+                    "Calls will return error responses."
+                )
+        else:
+            try:
+                self.client = DocumentIntelligenceClient(
+                    endpoint=self.endpoint, credential=AzureKeyCredential(self.key)
+                )
+            except Exception as e:
+                self.client = None
+                logger.warning("DocumentIntelligenceClient initialization failed: %s", e)
+
+    async def analyze_document_from_url(
+        self, url: str, model_id: str = "prebuilt-read"
+    ) -> Dict[str, Any]:
+        """Analyze a document from a URL using Azure Document Intelligence.
+
+        Args:
+            url: URL of the document to analyze (must be accessible to Azure)
+            model_id: Model to use (default: "prebuilt-read" for OCR)
+                     Other options: "prebuilt-layout", "prebuilt-invoice", etc.
+
+        Returns:
+            Dict with analysis results:
+            - success (bool): Whether analysis succeeded
+            - content (str | None): Extracted text content
+            - pages (list[dict] | None): Page information
+            - page_count (int | None): Total number of pages
+            - confidence (float | None): Average OCR confidence (0-1)
+            - model_id (str | None): Model used
+            - metadata (dict | None): Additional metadata
+            - error (str | None): Error message if failed
+        """
+        if not self.client:
+            logger.warning("Document analysis from URL skipped: service not configured")
+            return {
+                "success": False,
+                "error": "Document Intelligence service not configured",
+            }
+
+        try:
+            logger.info(f"Starting document analysis from URL: {url} (model: {model_id})")
+
+            # Run the blocking operation in a thread pool
+            poller = await asyncio.to_thread(
+                self.client.begin_analyze_document,
+                model_id,
+                AnalyzeDocumentRequest(url_source=url),
+            )
+
+            # Wait for the result
+            result: AnalyzeResult = await asyncio.to_thread(poller.result)
+
+            logger.info(
+                f"Document analysis completed (model: {model_id}, pages: {len(result.pages or [])})"
+            )
+
+            return self._format_result(result, model_id)
+
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed for document analysis: {e}")
+            return {"success": False, "error": f"Authentication failed: {e}"}
+        except HttpResponseError as e:
+            logger.error(f"Azure service error analyzing document: {e.status_code} - {e.message}")
+            return {
+                "success": False,
+                "error": f"Azure service error ({e.status_code}): {e.message}",
+            }
+        except ServiceRequestError as e:
+            logger.error(f"Network error analyzing document: {e}")
+            return {"success": False, "error": f"Network error: {e}"}
+        except Exception as e:
+            logger.error(f"Unexpected error analyzing document from URL: {e}")
+            return {"success": False, "error": f"Unexpected error: {e}"}
+
+    async def analyze_document_from_bytes(
+        self, file_content: bytes, model_id: str = "prebuilt-read"
+    ) -> Dict[str, Any]:
+        """Analyze a document from bytes using Azure Document Intelligence.
+
+        Args:
+            file_content: Document content as bytes (PDF, image, etc.)
+            model_id: Model to use (default: "prebuilt-read" for OCR)
+
+        Returns:
+            Dict with analysis results (same format as analyze_document_from_url)
+        """
+        if not self.client:
+            logger.warning("Document analysis from bytes skipped: service not configured")
+            return {
+                "success": False,
+                "error": "Document Intelligence service not configured",
+            }
+
+        try:
+            logger.info(
+                f"Starting document analysis from bytes (size: {len(file_content)} bytes, model: {model_id})"
+            )
+
+            # Create a file-like object from bytes
+            file_stream = io.BytesIO(file_content)
+
+            # Run the blocking operation in a thread pool
+            poller = await asyncio.to_thread(
+                self.client.begin_analyze_document,
+                model_id,
+                body=file_stream,
+            )
+
+            # Wait for the result
+            result: AnalyzeResult = await asyncio.to_thread(poller.result)
+
+            logger.info(
+                f"Document analysis completed (model: {model_id}, pages: {len(result.pages or [])})"
+            )
+
+            return self._format_result(result, model_id)
+
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed for document analysis: {e}")
+            return {"success": False, "error": f"Authentication failed: {e}"}
+        except HttpResponseError as e:
+            logger.error(f"Azure service error analyzing document: {e.status_code} - {e.message}")
+            return {
+                "success": False,
+                "error": f"Azure service error ({e.status_code}): {e.message}",
+            }
+        except ServiceRequestError as e:
+            logger.error(f"Network error analyzing document: {e}")
+            return {"success": False, "error": f"Network error: {e}"}
+        except Exception as e:
+            logger.error(f"Unexpected error analyzing document from bytes: {e}")
+            return {"success": False, "error": f"Unexpected error: {e}"}
+
+    def _format_result(self, result: AnalyzeResult, model_id: str) -> Dict[str, Any]:
+        """Format the AnalyzeResult into a dict response.
+
+        Args:
+            result: Azure Document Intelligence AnalyzeResult
+            model_id: Model ID used for analysis
+
+        Returns:
+            Formatted dict with extracted content and metadata
+        """
+        # Extract all text content
+        content_parts: list[str] = []
+        pages_info: list[Dict[str, Any]] = []
+        total_confidence = 0.0
+        confidence_count = 0
+
+        if result.pages:
+            for page in result.pages:
+                # Collect page info
+                page_info = {
+                    "page_number": page.page_number,
+                    "width": page.width,
+                    "height": page.height,
+                    "unit": page.unit,
+                    "lines_count": len(page.lines or []),
+                    "words_count": len(page.words or []),
+                }
+                pages_info.append(page_info)
+
+                # Extract text from lines
+                if page.lines:
+                    for line in page.lines:
+                        content_parts.append(line.content)
+                        # Track confidence if available
+                        if hasattr(line, "confidence") and line.confidence is not None:
+                            total_confidence += line.confidence
+                            confidence_count += 1
+
+        # Combine all content with newlines
+        full_content = "\n".join(content_parts)
+
+        # Calculate average confidence
+        avg_confidence = total_confidence / confidence_count if confidence_count > 0 else None
+
+        # Build metadata
+        metadata: Dict[str, Any] = {
+            "content_format": (
+                result.content_format if hasattr(result, "content_format") else None
+            ),
+            "api_version": result.api_version if hasattr(result, "api_version") else None,
+        }
+
+        # Add languages if detected
+        if hasattr(result, "languages") and result.languages:
+            metadata["languages"] = [
+                {"locale": lang.locale, "confidence": lang.confidence} for lang in result.languages
+            ]
+
+        # Add styles if detected (e.g., handwriting)
+        if hasattr(result, "styles") and result.styles:
+            metadata["has_handwriting"] = any(
+                style.is_handwritten for style in result.styles if hasattr(style, "is_handwritten")
+            )
+
+        return {
+            "success": True,
+            "content": full_content if full_content else None,
+            "pages": pages_info if pages_info else None,
+            "page_count": len(pages_info) if pages_info else None,
+            "confidence": avg_confidence,
+            "model_id": model_id,
+            "metadata": metadata,
+        }

srx_lib_azure/email.py

@@ -4,8 +4,16 @@ from typing import Dict, Any
 
 try:
     from azure.communication.email.aio import EmailClient
+    from azure.core.exceptions import (
+        ClientAuthenticationError,
+        HttpResponseError,
+        ServiceRequestError,
+    )
 except Exception:  # pragma: no cover - optional dependency at import time
     EmailClient = None  # type: ignore
+    ClientAuthenticationError = None  # type: ignore
+    HttpResponseError = None  # type: ignore
+    ServiceRequestError = None  # type: ignore
 
 logger = logging.getLogger(__name__)
 
@@ -39,10 +47,27 @@ class EmailService:
                 self.email_client = None
                 logger.warning("EmailService initialization failed: %s", e)
 
-    async def send_notification(self, recipient: str, subject: str, body: str, html: bool = False) -> Dict[str, Any]:
+    async def send_notification(
+        self, recipient: str, subject: str, body: str, html: bool = False
+    ) -> Dict[str, Any]:
+        """Send an email notification via Azure Communication Services.
+
+        Args:
+            recipient: Email address of the recipient
+            subject: Email subject line
+            body: Email body content
+            html: If True, send as HTML; otherwise plain text
+
+        Returns:
+            Dict with status, message, and optional message_id
+            - status: "success" | "error" | "skipped"
+            - message: Human-readable message
+            - message_id: Azure message ID (only on success)
+        """
         if not self.email_client or not self.sender_address:
             logger.warning("Email skipped: service not configured")
             return {"status": "skipped", "message": "Email service not configured"}
+
         message = {
             "content": {"subject": subject},
             "recipients": {"to": [{"address": recipient}]},
@@ -52,15 +77,41 @@ class EmailService:
             message["content"]["html"] = body
         else:
             message["content"]["plainText"] = body
+
         try:
             poller = await self.email_client.begin_send(message)
             result = await poller.result()
             message_id = result.get("id")
             if message_id:
                 logger.info("Email sent to %s with Message ID: %s", recipient, message_id)
-                return {"status": "success", "message": "Email sent successfully", "message_id": message_id}
+                return {
+                    "status": "success",
+                    "message": "Email sent successfully",
+                    "message_id": message_id,
+                }
             logger.error("Failed to send email. Result: %s", result)
             return {"status": "error", "message": f"Failed to send email: {result}"}
+        except ClientAuthenticationError as e:
+            # Auth errors should not be retried - they need credential fixes
+            logger.error("Authentication failed sending email to %s: %s", recipient, e)
+            return {"status": "error", "message": f"Authentication failed: {e}"}
+        except HttpResponseError as e:
+            # Azure service errors (rate limits, invalid recipient, etc.)
+            logger.error(
+                "Azure service error sending email to %s: %s - %s",
+                recipient,
+                e.status_code,
+                e.message,
+            )
+            return {
+                "status": "error",
+                "message": f"Azure service error ({e.status_code}): {e.message}",
+            }
+        except ServiceRequestError as e:
+            # Network/connection errors - may be retryable
+            logger.error("Network error sending email to %s: %s", recipient, e)
+            return {"status": "error", "message": f"Network error: {e}"}
         except Exception as e:
-            logger.error("Email send exception: %s", e)
-            return {"status": "error", "message": str(e)}
+            # Catch-all for unexpected errors
+            logger.error("Unexpected error sending email to %s: %s", recipient, e)
+            return {"status": "error", "message": f"Unexpected error: {e}"}

srx_lib_azure/table.py

@@ -9,8 +9,18 @@ from loguru import logger
 
 try:
     from azure.data.tables import TableServiceClient
+    from azure.core.exceptions import (
+        ResourceNotFoundError,
+        ResourceExistsError,
+        ClientAuthenticationError,
+        HttpResponseError,
+    )
 except Exception:  # pragma: no cover
     TableServiceClient = None  # type: ignore
+    ResourceNotFoundError = None  # type: ignore
+    ResourceExistsError = None  # type: ignore
+    ClientAuthenticationError = None  # type: ignore
+    HttpResponseError = None  # type: ignore
 
 
 def _now_iso() -> str:
@@ -62,15 +72,25 @@ class AzureTableService:
             table_name: Name of the table to delete
 
         Returns:
-            True if deleted successfully, False otherwise
+            True if deleted successfully or table doesn't exist, False on other errors
         """
         client = self._get_client()
         try:
             client.delete_table(table_name=table_name)
             logger.info("Deleted table: %s", table_name)
             return True
+        except ResourceNotFoundError:
+            # Table already deleted or doesn't exist - this is still success
+            logger.info(f"Table {table_name} already deleted or doesn't exist")
+            return True
+        except ClientAuthenticationError as exc:
+            logger.error("Authentication failed deleting table %s: %s", table_name, exc)
+            return False
+        except HttpResponseError as exc:
+            logger.error("Azure service error deleting table %s: %s", table_name, exc.message)
+            return False
         except Exception as exc:
-            logger.error("Failed to delete table %s: %s", table_name, exc)
+            logger.error("Unexpected error deleting table %s: %s", table_name, exc)
             return False
 
     def table_exists(self, table_name: str) -> bool:
@@ -85,38 +105,105 @@ class AzureTableService:
         return table_name in self.list_tables()
 
     def put_entity(self, table_name: str, entity: Dict[str, Any]) -> Dict[str, Any]:
+        """Insert a new entity into a table.
+
+        Args:
+            table_name: Name of the table
+            entity: Entity dictionary with PartitionKey and RowKey
+
+        Returns:
+            Dict with etag and timestamp
+
+        Raises:
+            RuntimeError: If entity already exists or other errors occur
+        """
         client = self._get_client()
         table = client.get_table_client(table_name)
-        res = table.create_entity(entity=entity)
-        logger.info(
-            "Inserted entity into %s: PK=%s RK=%s",
-            table_name,
-            entity.get("PartitionKey"),
-            entity.get("RowKey"),
-        )
-        return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        try:
+            res = table.create_entity(entity=entity)
+            logger.info(
+                "Inserted entity into %s: PK=%s RK=%s",
+                table_name,
+                entity.get("PartitionKey"),
+                entity.get("RowKey"),
+            )
+            return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        except ResourceExistsError as e:
+            pk, rk = entity.get("PartitionKey"), entity.get("RowKey")
+            logger.error(f"Entity already exists in {table_name}: PK={pk} RK={rk}")
+            raise RuntimeError(f"Entity already exists: {e}") from e
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed inserting entity into {table_name}: {e}")
+            raise RuntimeError(f"Authentication failed: {e}") from e
+        except HttpResponseError as e:
+            logger.error(f"Azure service error inserting entity into {table_name}: {e.message}")
+            raise RuntimeError(f"Failed to insert entity: {e.message}") from e
 
     def upsert_entity(self, table_name: str, entity: Dict[str, Any]) -> Dict[str, Any]:
+        """Insert or update an entity in a table.
+
+        Args:
+            table_name: Name of the table
+            entity: Entity dictionary with PartitionKey and RowKey
+
+        Returns:
+            Dict with etag and timestamp
+
+        Raises:
+            RuntimeError: If authentication or service errors occur
+        """
         client = self._get_client()
         table = client.get_table_client(table_name)
-        res = table.upsert_entity(entity=entity, mode="merge")
-        logger.info(
-            "Upserted entity into %s: PK=%s RK=%s",
-            table_name,
-            entity.get("PartitionKey"),
-            entity.get("RowKey"),
-        )
-        return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        try:
+            res = table.upsert_entity(entity=entity, mode="merge")
+            logger.info(
+                "Upserted entity into %s: PK=%s RK=%s",
+                table_name,
+                entity.get("PartitionKey"),
+                entity.get("RowKey"),
+            )
+            return {"etag": getattr(res, "etag", None), "ts": _now_iso()}
+        except ClientAuthenticationError as e:
+            logger.error(f"Authentication failed upserting entity into {table_name}: {e}")
+            raise RuntimeError(f"Authentication failed: {e}") from e
+        except HttpResponseError as e:
+            logger.error(f"Azure service error upserting entity into {table_name}: {e.message}")
+            raise RuntimeError(f"Failed to upsert entity: {e.message}") from e
 
     def delete_entity(self, table_name: str, partition_key: str, row_key: str) -> bool:
+        """Delete an entity from a table.
+
+        Args:
+            table_name: Name of the table
+            partition_key: Partition key of the entity
+            row_key: Row key of the entity
+
+        Returns:
+            True if deleted successfully or entity doesn't exist, False on other errors
+
+        Note:
+            Azure Tables delete_entity doesn't fail if entity doesn't exist
+        """
         client = self._get_client()
         table = client.get_table_client(table_name)
         try:
             table.delete_entity(partition_key=partition_key, row_key=row_key)
             logger.info("Deleted entity in %s (%s/%s)", table_name, partition_key, row_key)
             return True
+        except ResourceNotFoundError:
+            # Entity already deleted or doesn't exist - this is still success
+            logger.info(
+                f"Entity in {table_name} ({partition_key}/{row_key}) already deleted or doesn't exist"
+            )
+            return True
+        except ClientAuthenticationError as exc:
+            logger.error("Authentication failed deleting entity in %s: %s", table_name, exc)
+            return False
+        except HttpResponseError as exc:
+            logger.error("Azure service error deleting entity in %s: %s", table_name, exc.message)
+            return False
         except Exception as exc:
-            logger.error("Failed to delete entity in %s: %s", table_name, exc)
+            logger.error("Unexpected error deleting entity in %s: %s", table_name, exc)
             return False
 
     def get_entity(
@@ -130,7 +217,7 @@ class AzureTableService:
             row_key: Row key of the entity
 
         Returns:
-            Entity dict if found, None otherwise
+            Entity dict if found, None otherwise (including on auth/service errors)
         """
         client = self._get_client()
         table = client.get_table_client(table_name)
@@ -138,11 +225,20 @@ class AzureTableService:
             entity = table.get_entity(partition_key=partition_key, row_key=row_key)
             logger.info("Retrieved entity from %s: PK=%s RK=%s", table_name, partition_key, row_key)
             return dict(entity)
-        except Exception as exc:
-            logger.warning(
-                "Entity not found in %s (%s/%s): %s", table_name, partition_key, row_key, exc
+        except ResourceNotFoundError:
+            logger.info("Entity not found in %s (%s/%s)", table_name, partition_key, row_key)
+            return None
+        except ClientAuthenticationError as exc:
+            logger.error("Authentication failed retrieving entity from %s: %s", table_name, exc)
+            return None
+        except HttpResponseError as exc:
+            logger.error(
+                "Azure service error retrieving entity from %s: %s", table_name, exc.message
             )
             return None
+        except Exception as exc:
+            logger.error("Unexpected error retrieving entity from %s: %s", table_name, exc)
+            return None
 
     def entity_exists(self, table_name: str, partition_key: str, row_key: str) -> bool:
         """Check if an entity exists without retrieving it.

srx_lib_azure-0.2.0.dist-info/METADATA

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: srx-lib-azure
+Version: 0.2.0
+Summary: Azure helpers for SRX services: Blob, Email, Table, Document Intelligence
+Author-email: SRX <dev@srx.id>
+Requires-Python: >=3.12
+Requires-Dist: azure-ai-documentintelligence>=1.0.0
+Requires-Dist: azure-communication-email>=1.0.0
+Requires-Dist: azure-data-tables>=12.7.0
+Requires-Dist: azure-storage-blob>=12.22.0
+Requires-Dist: loguru>=0.7.2
+Provides-Extra: all
+Requires-Dist: azure-ai-documentintelligence>=1.0.0; extra == 'all'
+Provides-Extra: document
+Requires-Dist: azure-ai-documentintelligence>=1.0.0; extra == 'document'
+Description-Content-Type: text/markdown
+
+# srx-lib-azure
+
+Lightweight wrappers over Azure SDKs used across SRX services.
+
+What it includes:
+- **Blob**: upload/download helpers, SAS URL generation
+- **Email** (Azure Communication Services): simple async sender
+- **Table**: simple CRUD helpers
+- **Document Intelligence** (OCR): document analysis from URLs or bytes
+
+## Install
+
+PyPI (public):
+
+- `pip install srx-lib-azure`
+
+uv (pyproject):
+```
+[project]
+dependencies = ["srx-lib-azure>=0.1.0"]
+```
+
+## Usage
+
+Blob:
+```
+from srx_lib_azure.blob import AzureBlobService
+blob = AzureBlobService()
+url = await blob.upload_file(upload_file, "documents/report.pdf")
+```
+
+Email:
+```
+from srx_lib_azure.email import EmailService
+svc = EmailService()
+await svc.send_notification("user@example.com", "Subject", "Hello", html=False)
+```
+
+Table:
+```
+from srx_lib_azure.table import AzureTableService
+store = AzureTableService()
+store.ensure_table("events")
+store.upsert_entity("events", {"PartitionKey":"p","RowKey":"r","EventType":"x"})
+```
+
+Document Intelligence (OCR):
+```python
+from srx_lib_azure import AzureDocumentIntelligenceService
+
+# Initialize with endpoint and key
+doc_service = AzureDocumentIntelligenceService(
+    endpoint="https://your-resource.cognitiveservices.azure.com/",
+    key="your-api-key"
+)
+
+# Analyze document from URL
+result = await doc_service.analyze_document_from_url(
+    url="https://example.com/document.pdf",
+    model_id="prebuilt-read"  # or "prebuilt-layout", "prebuilt-invoice", etc.
+)
+
+# Analyze document from bytes
+with open("document.pdf", "rb") as f:
+    content = f.read()
+result = await doc_service.analyze_document_from_bytes(
+    file_content=content,
+    model_id="prebuilt-read"
+)
+
+# Result structure:
+# {
+#     "success": True/False,
+#     "content": "extracted text...",
+#     "pages": [{"page_number": 1, "width": 8.5, ...}, ...],
+#     "page_count": 10,
+#     "confidence": 0.98,
+#     "model_id": "prebuilt-read",
+#     "metadata": {...},
+#     "error": None  # or error message if failed
+# }
+```
+
+## Environment Variables
+
+- **Blob & Table**: `AZURE_STORAGE_CONNECTION_STRING` (required)
+- **Email (ACS)**: `ACS_CONNECTION_STRING`, `EMAIL_SENDER`
+- **Document Intelligence**: `AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT`, `AZURE_DOCUMENT_INTELLIGENCE_KEY`
+- **Optional**: `AZURE_STORAGE_ACCOUNT_KEY`, `AZURE_BLOB_URL`, `AZURE_SAS_TOKEN`
+
+## Optional Dependencies
+
+All services are optional and won't break if their dependencies aren't installed:
+
+```bash
+# Base installation (includes all services by default)
+pip install srx-lib-azure
+
+# Or install only what you need - document intelligence is optional
+pip install srx-lib-azure[document]  # Adds Document Intelligence support
+
+# Install with all optional dependencies
+pip install srx-lib-azure[all]
+```
+
+If you import a service without its required Azure SDK, it will log a warning but won't crash.
+
+## Release
+
+Tag `vX.Y.Z` to publish to GitHub Packages via Actions.
+
+## License
+
+Proprietary © SRX

srx_lib_azure-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+srx_lib_azure/__init__.py,sha256=I2nQgMpTptWYHMqHfSYYv3cuC5wkeeYpawQ31zVN5mQ,283
+srx_lib_azure/blob.py,sha256=pAOIPAImhIChMCoxQhe79N11vLF24yAlw0R8gcnitvA,12730
+srx_lib_azure/document.py,sha256=gAVIJRRwtDscAYAUKH7XiAqdCSmoZ-TpzivWS12XQXM,10551
+srx_lib_azure/email.py,sha256=qZWZUjoUMocivU-S7Qa4mJV8aj4jtQPfy868wnPgPlA,4837
+srx_lib_azure/table.py,sha256=-RPMlZ2gzXi-6bJSkGFuV5XyIp8-3pdwulI-IEZUs1Y,18607
+srx_lib_azure-0.2.0.dist-info/METADATA,sha256=l0KQ0OTRlwZsDD8Z6lzGiJYTzbfYp5mB5Pg6x7LrUZI,3584
+srx_lib_azure-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+srx_lib_azure-0.2.0.dist-info/RECORD,,

srx_lib_azure-0.1.7.dist-info/METADATA

@@ -1,70 +0,0 @@
-Metadata-Version: 2.4
-Name: srx-lib-azure
-Version: 0.1.7
-Summary: Azure helpers for SRX services: Blob, Email, Table
-Author-email: SRX <dev@srx.id>
-Requires-Python: >=3.12
-Requires-Dist: azure-communication-email>=1.0.0
-Requires-Dist: azure-data-tables>=12.7.0
-Requires-Dist: azure-storage-blob>=12.22.0
-Requires-Dist: loguru>=0.7.2
-Description-Content-Type: text/markdown
-
-# srx-lib-azure
-
-Lightweight wrappers over Azure SDKs used across SRX services.
-
-What it includes:
-- Blob: upload/download helpers, SAS URL generation
-- Email (Azure Communication Services): simple async sender
-- Table: simple CRUD helpers
-
-## Install
-
-PyPI (public):
-
-- `pip install srx-lib-azure`
-
-uv (pyproject):
-```
-[project]
-dependencies = ["srx-lib-azure>=0.1.0"]
-```
-
-## Usage
-
-Blob:
-```
-from srx_lib_azure.blob import AzureBlobService
-blob = AzureBlobService()
-url = await blob.upload_file(upload_file, "documents/report.pdf")
-```
-
-Email:
-```
-from srx_lib_azure.email import EmailService
-svc = EmailService()
-await svc.send_notification("user@example.com", "Subject", "Hello", html=False)
-```
-
-Table:
-```
-from srx_lib_azure.table import AzureTableService
-store = AzureTableService()
-store.ensure_table("events")
-store.upsert_entity("events", {"PartitionKey":"p","RowKey":"r","EventType":"x"})
-```
-
-## Environment Variables
-
-- Blob & Table: `AZURE_STORAGE_CONNECTION_STRING` (required)
-- Email (ACS): `ACS_CONNECTION_STRING`, `EMAIL_SENDER`
-- Optional: `AZURE_STORAGE_ACCOUNT_KEY`, `AZURE_BLOB_URL`, `AZURE_SAS_TOKEN`
-
-## Release
-
-Tag `vX.Y.Z` to publish to GitHub Packages via Actions.
-
-## License
-
-Proprietary © SRX

srx_lib_azure-0.1.7.dist-info/RECORD

@@ -1,7 +0,0 @@
-srx_lib_azure/__init__.py,sha256=K0UCmkKw7HWJMshp6Xv3SxD4y26r7bdcPtb_2aRc2rs,174
-srx_lib_azure/blob.py,sha256=3g5r3cOOdTAN283PBEU__p5gLYQ97LE_KEeNc2mVnLg,8889
-srx_lib_azure/email.py,sha256=2J5zlgJMhx7pMINwN4kW23PmdwL1JyU9xFsSl5gAAM4,2831
-srx_lib_azure/table.py,sha256=0qb1t84wEkpif3t1KybasZYffgTGQQ5ULfjfk2mjy54,14262
-srx_lib_azure-0.1.7.dist-info/METADATA,sha256=bjyMw1i1lMXVw7Q6cbv_yYz9snHpH6pckSPTFR_JZyQ,1600
-srx_lib_azure-0.1.7.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-srx_lib_azure-0.1.7.dist-info/RECORD,,