srx-lib-azure 0.1.5__py3-none-any.whl → 0.4.0__py3-none-any.whl

srx_lib_azure/__init__.py

@@ -1,6 +1,23 @@
 from .blob import AzureBlobService
+from .document import AzureDocumentIntelligenceService
 from .email import EmailService
 from .table import AzureTableService
 
-__all__ = ["AzureBlobService", "EmailService", "AzureTableService"]
-
+# Optional import - only available if speech extra is installed
+try:
+    from .speech import AzureSpeechService
+    __all__ = [
+        "AzureBlobService",
+        "AzureDocumentIntelligenceService",
+        "AzureTableService",
+        "EmailService",
+        "AzureSpeechService",
+    ]
+except ImportError:
+    # Speech SDK not installed - service not available
+    __all__ = [
+        "AzureBlobService",
+        "AzureDocumentIntelligenceService",
+        "AzureTableService",
+        "EmailService",
+    ]

srx_lib_azure/blob.py

@@ -4,24 +4,43 @@ 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
 
 
 class AzureBlobService:
-    """Minimal Azure Blob helper with SAS URL generation."""
+    """Minimal Azure Blob helper with SAS URL generation.
 
-    def __init__(self) -> None:
-        self.container_name = os.getenv("AZURE_BLOB_CONTAINER", "uploads")
-        self.connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")
-        self.account_key = os.getenv("AZURE_STORAGE_ACCOUNT_KEY")
-        self.sas_token = os.getenv("AZURE_SAS_TOKEN")
-        self.base_blob_url = os.getenv("AZURE_BLOB_URL")
+    All configuration can be passed explicitly via constructor. If omitted, falls back
+    to environment variables. By default, it does not warn at startup when not
+    configured; operations will error if required values are missing.
+    """
 
-        if not self.connection_string:
+    def __init__(
+        self,
+        *,
+        connection_string: Optional[str] = None,
+        account_key: Optional[str] = None,
+        container_name: Optional[str] = None,
+        base_blob_url: Optional[str] = None,
+        sas_token: Optional[str] = None,
+        warn_if_unconfigured: bool = False,
+    ) -> None:
+        self.container_name = container_name or os.getenv("AZURE_BLOB_CONTAINER", "uploads")
+        self.connection_string = connection_string or os.getenv("AZURE_STORAGE_CONNECTION_STRING")
+        self.account_key = account_key or os.getenv("AZURE_STORAGE_ACCOUNT_KEY")
+        self.sas_token = sas_token or os.getenv("AZURE_SAS_TOKEN")
+        self.base_blob_url = base_blob_url or os.getenv("AZURE_BLOB_URL")
+
+        if warn_if_unconfigured and not self.connection_string:
             logger.warning(
-                "Azure Storage connection string not configured; blob operations will fail."
+                "Azure Storage connection string not configured; blob operations may fail."
             )
 
     def _get_blob_service(self) -> BlobServiceClient:
@@ -35,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
@@ -79,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
@@ -91,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
@@ -108,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
@@ -125,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."""
@@ -135,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}")
@@ -158,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
@@ -169,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
@@ -183,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__)
 
@@ -17,14 +25,21 @@ class EmailService:
     If not configured, send calls are skipped with a warning and a 'skipped' status.
     """
 
-    def __init__(self):
-        self.connection_string = os.getenv("ACS_CONNECTION_STRING")
-        self.sender_address = os.getenv("EMAIL_SENDER")
+    def __init__(
+        self,
+        *,
+        connection_string: str | None = None,
+        sender_address: str | None = None,
+        warn_if_unconfigured: bool = False,
+    ):
+        self.connection_string = connection_string or os.getenv("ACS_CONNECTION_STRING")
+        self.sender_address = sender_address or os.getenv("EMAIL_SENDER")
         if not self.connection_string or not self.sender_address or EmailClient is None:
             self.email_client = None
-            logger.warning(
-                "EmailService not configured (missing ACS_CONNECTION_STRING/EMAIL_SENDER or azure SDK). Calls will be skipped."
-            )
+            if warn_if_unconfigured:
+                logger.warning(
+                    "EmailService not configured (missing ACS_CONNECTION_STRING/EMAIL_SENDER or azure SDK). Calls will be skipped."
+                )
         else:
             try:
                 self.email_client = EmailClient.from_connection_string(self.connection_string)
@@ -32,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}]},
@@ -45,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}"}