agentle 0.9.4__py3-none-any.whl → 0.9.28__py3-none-any.whl

agentle/agents/whatsapp/providers/evolution/evolution_api_provider.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 import logging
 import re
 import time
-from collections.abc import Mapping, MutableMapping
+from collections.abc import Mapping, MutableMapping, Sequence
 from datetime import datetime
 from typing import Any, override
 from urllib.parse import urljoin
@@ -307,7 +307,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
         method: str,
         url: str,
         data: Mapping[str, Any] | None = None,
-        expected_status: int = 200,
+        expected_status: int | Sequence[int] = 200,
     ) -> Mapping[str, Any]:
         """
         Make HTTP request with comprehensive resilience mechanisms.
@@ -416,7 +416,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
         method: str,
         url: str,
         data: Mapping[str, Any] | None = None,
-        expected_status: int = 200,
+        expected_status: int | Sequence[int] = 200,
     ) -> Mapping[str, Any]:
         """
         Make HTTP request with proper error handling and metrics.
@@ -531,7 +531,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
     async def _handle_response(
         self,
         response: aiohttp.ClientResponse,
-        expected_status: int,
+        expected_status: int | Sequence[int],
         request_url: str,
         request_data: Mapping[str, Any] | None,
         start_time: float,
@@ -571,7 +571,10 @@ class EvolutionAPIProvider(WhatsAppProvider):
             },
         )
 
-        if response.status == expected_status:
+        if isinstance(expected_status, int):
+            expected_status = [expected_status]
+
+        if response.status in expected_status:
             try:
                 response_data = await response.json()
                 logger.debug(f"Response data received: {response_data}")
@@ -771,7 +774,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
 
             url = self._build_url(f"sendText/{self.config.instance_name}")
             response_data = await self._make_request_with_resilience(
-                "POST", url, payload, expected_status=201
+                "POST", url, payload, expected_status=[200, 201]
             )
 
             message_id = response_data["key"]["id"]
@@ -885,7 +888,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
 
             url = self._build_url(f"{endpoint}/{self.config.instance_name}")
             response_data = await self._make_request_with_resilience(
-                "POST", url, payload, expected_status=201
+                "POST", url, payload, expected_status=[200, 201]
             )
 
             message_id = response_data["key"]["id"]
@@ -947,6 +950,168 @@ class EvolutionAPIProvider(WhatsAppProvider):
 
     # [Continue with remaining methods using enhanced patterns...]
 
+    async def send_audio_message(
+        self,
+        to: str,
+        audio_base64: str,
+        quoted_message_id: str | None = None,
+    ) -> WhatsAppMediaMessage:
+        """Send an audio message via Evolution API with enhanced error handling."""
+        logger.info(f"Sending audio message to {to}")
+        if quoted_message_id:
+            logger.debug(f"Audio message is quoting message ID: {quoted_message_id}")
+
+        try:
+            # CRITICAL FIX: Check if there's a stored remoteJid for this contact
+            session = await self.get_session(to)
+            remote_jid = session.context_data.get("remote_jid") if session else None
+
+            if remote_jid:
+                logger.info(
+                    f"🔑 Using stored remoteJid for audio to {to}: {remote_jid}"
+                )
+                normalized_to = remote_jid
+            else:
+                normalized_to = self._normalize_phone(to)
+                logger.debug(f"Normalized phone number: {to} -> {normalized_to}")
+
+            payload: MutableMapping[str, Any] = {
+                "number": normalized_to,
+                "audio": audio_base64,
+            }
+
+            if quoted_message_id:
+                payload["quoted"] = {"key": {"id": quoted_message_id}}
+
+            url = self._build_url(f"sendWhatsAppAudio/{self.config.instance_name}")
+            response_data = await self._make_request_with_resilience(
+                "POST", url, payload, expected_status=[200, 201]
+            )
+
+            message_id = response_data["key"]["id"]
+            from_jid = response_data["key"]["remoteJid"]
+
+            message = WhatsAppAudioMessage(
+                id=message_id,
+                from_number=from_jid,
+                to_number=to,
+                timestamp=datetime.now(),
+                status=WhatsAppMessageStatus.SENT,
+                media_url="",  # Base64 audio doesn't have a URL
+                media_mime_type="audio/ogg",
+                quoted_message_id=quoted_message_id,
+                is_voice_note=True,
+            )
+
+            logger.info(
+                f"Audio message sent successfully to {to}: {message_id}",
+                extra={
+                    "message_id": message_id,
+                    "to_number": to,
+                    "normalized_to": normalized_to,
+                    "from_jid": from_jid,
+                    "has_quote": quoted_message_id is not None,
+                },
+            )
+            return message
+
+        except EvolutionAPIError:
+            logger.error(f"Evolution API error while sending audio message to {to}")
+            raise
+        except Exception as e:
+            logger.error(
+                f"Failed to send audio message to {to}: {type(e).__name__}: {e}",
+                extra={
+                    "to_number": to,
+                    "error_type": type(e).__name__,
+                    "has_quote": quoted_message_id is not None,
+                },
+            )
+            raise EvolutionAPIError(f"Failed to send audio message: {e}")
+
+    async def send_audio_message_by_url(
+        self,
+        to: str,
+        audio_url: str,
+        quoted_message_id: str | None = None,
+    ) -> WhatsAppMediaMessage:
+        """Send an audio message via URL using Evolution API."""
+        logger.info(f"Sending audio message via URL to {to}: {audio_url}")
+        if quoted_message_id:
+            logger.debug(f"Audio message is quoting message ID: {quoted_message_id}")
+
+        try:
+            # CRITICAL FIX: Check if there's a stored remoteJid for this contact
+            session = await self.get_session(to)
+            remote_jid = session.context_data.get("remote_jid") if session else None
+
+            if remote_jid:
+                logger.info(
+                    f"🔑 Using stored remoteJid for audio URL to {to}: {remote_jid}"
+                )
+                normalized_to = remote_jid
+            else:
+                normalized_to = self._normalize_phone(to)
+                logger.debug(f"Normalized phone number: {to} -> {normalized_to}")
+
+            payload: MutableMapping[str, Any] = {
+                "number": normalized_to,
+                "audioUrl": audio_url,  # Use URL instead of base64
+            }
+
+            if quoted_message_id:
+                payload["quoted"] = {"key": {"id": quoted_message_id}}
+
+            url = self._build_url(f"sendWhatsAppAudio/{self.config.instance_name}")
+            response_data = await self._make_request_with_resilience(
+                "POST", url, payload, expected_status=[200, 201]
+            )
+
+            message_id = response_data["key"]["id"]
+            from_jid = response_data["key"]["remoteJid"]
+
+            message = WhatsAppAudioMessage(
+                id=message_id,
+                from_number=from_jid,
+                to_number=to,
+                timestamp=datetime.now(),
+                status=WhatsAppMessageStatus.SENT,
+                media_url=audio_url,  # Store the URL
+                media_mime_type="audio/ogg",
+                quoted_message_id=quoted_message_id,
+                is_voice_note=True,
+            )
+
+            logger.info(
+                f"Audio message sent successfully via URL to {to}: {message_id}",
+                extra={
+                    "message_id": message_id,
+                    "to_number": to,
+                    "normalized_to": normalized_to,
+                    "from_jid": from_jid,
+                    "audio_url": audio_url,
+                    "has_quote": quoted_message_id is not None,
+                },
+            )
+            return message
+
+        except EvolutionAPIError:
+            logger.error(
+                f"Evolution API error while sending audio message via URL to {to}"
+            )
+            raise
+        except Exception as e:
+            logger.error(
+                f"Failed to send audio message via URL to {to}: {type(e).__name__}: {e}",
+                extra={
+                    "to_number": to,
+                    "audio_url": audio_url,
+                    "error_type": type(e).__name__,
+                    "has_quote": quoted_message_id is not None,
+                },
+            )
+            raise EvolutionAPIError(f"Failed to send audio message via URL: {e}")
+
     async def send_typing_indicator(self, to: str, duration: int = 3) -> None:
         """Send typing indicator via Evolution API."""
         logger.debug(f"Sending typing indicator to {to} for {duration}s")
@@ -981,7 +1146,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
                 use_message_prefix=False,
             )
             await self._make_request_with_resilience(
-                "POST", url, payload, expected_status=201
+                "POST", url, payload, expected_status=[200, 201]
             )
 
             logger.debug(
@@ -1009,6 +1174,68 @@ class EvolutionAPIProvider(WhatsAppProvider):
                 },
             )
 
+    async def send_recording_indicator(self, to: str, duration: int = 3) -> None:
+        """Send recording indicator via Evolution API."""
+        logger.debug(f"Sending recording indicator to {to} for {duration}s")
+
+        try:
+            # CRITICAL FIX: Check if there's a stored remoteJid for this contact
+            # This is essential for @lid numbers (Brazilian WhatsApp contacts)
+            session = await self.get_session(to)
+            remote_jid = session.context_data.get("remote_jid") if session else None
+
+            if remote_jid:
+                logger.debug(
+                    f"🔑 Using stored remoteJid for recording indicator to {to}: {remote_jid}"
+                )
+                normalized_to = remote_jid
+            else:
+                normalized_to = self._normalize_phone(to)
+
+            payload = {
+                "number": normalized_to,
+                "presence": "recording",
+                "delay": duration * 1000,
+                "options": {
+                    "delay": duration * 1000,
+                    "presence": "recording",
+                    "number": normalized_to,
+                },  # Evolution API expects milliseconds
+            }
+
+            url = self._build_url(
+                f"chat/sendPresence/{self.config.instance_name}",
+                use_message_prefix=False,
+            )
+            await self._make_request_with_resilience(
+                "POST", url, payload, expected_status=[200, 201]
+            )
+
+            logger.debug(
+                f"Recording indicator sent successfully to {to} for {duration}s",
+                extra={
+                    "to_number": to,
+                    "normalized_to": normalized_to,
+                    "duration_seconds": duration,
+                },
+            )
+
+        except EvolutionAPIError as e:
+            # Recording indicator failures are non-critical
+            logger.warning(
+                f"Failed to send recording indicator to {to}: {e}",
+                extra={"to_number": to, "duration_seconds": duration, "error": str(e)},
+            )
+        except Exception as e:
+            logger.warning(
+                f"Failed to send recording indicator to {to}: {type(e).__name__}: {e}",
+                extra={
+                    "to_number": to,
+                    "duration_seconds": duration,
+                    "error_type": type(e).__name__,
+                },
+            )
+
     async def mark_message_as_read(self, message_id: str) -> None:
         """Mark a message as read via Evolution API."""
         logger.debug(f"Marking message as read: {message_id}")
@@ -1032,7 +1259,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
                 use_message_prefix=False,
             )
             await self._make_request_with_resilience(
-                "POST", url, payload, expected_status=201
+                "POST", url, payload, expected_status=[200, 201]
             )
 
             logger.debug(
@@ -1282,7 +1509,7 @@ class EvolutionAPIProvider(WhatsAppProvider):
             payload = {"message": {"key": {"id": media_id}}}
 
             response_data = await self._make_request_with_resilience(
-                "POST", url, payload, expected_status=201
+                "POST", url, payload, expected_status=[200, 201]
             )
 
             if "base64" not in response_data:

agentle/agents/whatsapp/providers/meta/meta_whatsapp_provider.py

@@ -837,3 +837,129 @@ class MetaWhatsAppProvider(WhatsAppProvider):
         base_stats["session_stats"] = session_stats
 
         return base_stats
+
+    async def send_audio_message(
+        self,
+        to: str,
+        audio_base64: str,
+        quoted_message_id: str | None = None,
+    ) -> WhatsAppMediaMessage:
+        """Send an audio message via Meta WhatsApp Business API."""
+        logger.info(f"Sending audio message to {to}")
+
+        try:
+            # Upload audio to Meta first
+            media_id = await self._upload_audio_base64(audio_base64)
+
+            # Send audio message
+            payload = {
+                "messaging_product": "whatsapp",
+                "to": self._normalize_phone(to),
+                "type": "audio",
+                "audio": {"id": media_id},
+            }
+
+            if quoted_message_id:
+                payload["context"] = {"message_id": quoted_message_id}
+
+            url = self._build_url(f"{self.config.phone_number_id}/messages")
+            response_data = await self._make_request("POST", url, payload)
+
+            message_id = response_data["messages"][0]["id"]
+
+            return WhatsAppAudioMessage(
+                id=message_id,
+                from_number=self.config.phone_number_id,
+                to_number=to,
+                timestamp=datetime.now(),
+                status=WhatsAppMessageStatus.SENT,
+                media_url=media_id,
+                media_mime_type="audio/ogg",
+                quoted_message_id=quoted_message_id,
+                is_voice_note=True,
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to send audio message: {e}")
+            raise MetaWhatsAppError(f"Failed to send audio message: {e}")
+
+    async def send_audio_message_by_url(
+        self,
+        to: str,
+        audio_url: str,
+        quoted_message_id: str | None = None,
+    ) -> WhatsAppMediaMessage:
+        """Send an audio message via URL using Meta WhatsApp Business API."""
+        logger.info(f"Sending audio message via URL to {to}: {audio_url}")
+
+        try:
+            # Upload audio from URL to Meta
+            media_id = await self._upload_media(audio_url, "audio")
+
+            # Send audio message
+            payload = {
+                "messaging_product": "whatsapp",
+                "to": self._normalize_phone(to),
+                "type": "audio",
+                "audio": {"id": media_id},
+            }
+
+            if quoted_message_id:
+                payload["context"] = {"message_id": quoted_message_id}
+
+            url = self._build_url(f"{self.config.phone_number_id}/messages")
+            response_data = await self._make_request("POST", url, payload)
+
+            message_id = response_data["messages"][0]["id"]
+
+            return WhatsAppAudioMessage(
+                id=message_id,
+                from_number=self.config.phone_number_id,
+                to_number=to,
+                timestamp=datetime.now(),
+                status=WhatsAppMessageStatus.SENT,
+                media_url=audio_url,
+                media_mime_type="audio/ogg",
+                quoted_message_id=quoted_message_id,
+                is_voice_note=True,
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to send audio message via URL: {e}")
+            raise MetaWhatsAppError(f"Failed to send audio message via URL: {e}")
+
+    async def _upload_audio_base64(self, audio_base64: str) -> str:
+        """Upload base64 audio to Meta and return media ID."""
+        try:
+            import base64
+
+            # Decode base64 to bytes
+            audio_data = base64.b64decode(audio_base64)
+
+            # Upload to Meta
+            upload_url = self._build_url(f"{self.config.phone_number_id}/media")
+
+            form_data = aiohttp.FormData()
+            form_data.add_field("messaging_product", "whatsapp")
+            form_data.add_field("type", "audio")
+            form_data.add_field(
+                "file",
+                audio_data,
+                filename="audio.ogg",
+                content_type="audio/ogg",
+            )
+
+            # Create a separate session for file upload
+            headers = {"Authorization": f"Bearer {self.config.access_token}"}
+            timeout = aiohttp.ClientTimeout(total=self.config.timeout)
+
+            async with aiohttp.ClientSession(
+                headers=headers, timeout=timeout
+            ) as upload_session:
+                async with upload_session.post(upload_url, data=form_data) as response:
+                    response_data = await self._handle_response(response, 200)
+                    return response_data["id"]
+
+        except Exception as e:
+            logger.error(f"Failed to upload audio base64: {e}")
+            raise MetaWhatsAppError(f"Failed to upload audio base64: {e}")

agentle/agents/whatsapp/v2/batch_processor_manager.py

@@ -0,0 +1,4 @@
+import abc
+
+
+class BatchProcessorManager(abc.ABC): ...

agentle/agents/whatsapp/v2/bot_config.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+from rsb.models.base_model import BaseModel
+from rsb.models.field import Field
+
+from agentle.agents.whatsapp.v2.message_limit import MessageLimit
+from agentle.tts.speech_config import SpeechConfig
+
+
+class BotConfig(BaseModel):
+    """Configuration for WhatsApp bot behavior with simplified constructors and better organization.
+
+    This configuration class provides comprehensive control over WhatsApp bot behavior including:
+    - Core bot behavior (typing indicators, message reading, quoting)
+    - Message batching for handling rapid message sequences
+    - Spam protection and rate limiting
+    - Human-like delays to simulate realistic human behavior patterns
+    - Text-to-speech integration
+    - Error handling and retry logic
+    - Debug and monitoring settings
+
+    Human-Like Delays Feature:
+        The human-like delays feature simulates realistic human behavior patterns by introducing
+        configurable delays at three critical points in message processing:
+
+        1. Read Delay: Time between receiving a message and marking it as read
+           - Simulates the time a human takes to read and comprehend a message
+           - Calculated based on message length using realistic reading speeds
+
+        2. Typing Delay: Time between generating a response and sending it
+           - Simulates the time a human takes to compose and type a response
+           - Calculated based on response length using realistic typing speeds
+
+        3. Send Delay: Brief final delay before message transmission
+           - Simulates the final review time before a human sends a message
+           - Random delay within configured bounds
+
+        These delays help prevent platform detection and account restrictions while
+        maintaining natural interaction timing. All delays support jitter (random variation)
+        to prevent detectable patterns.
+
+    Configuration Presets:
+        Use the class methods to create pre-configured instances optimized for specific use cases:
+        - development(): Fast iteration with delays disabled
+        - production(): Balanced configuration with delays enabled
+        - high_volume(): Optimized for throughput with balanced delays
+        - customer_service(): Professional timing with thoughtful delays
+        - minimal(): Bare minimum configuration with delays disabled
+
+    Examples:
+        >>> # Create a production configuration with default delay settings
+        >>> config = BotConfig.production()
+
+        >>> # Create a custom configuration with specific delay bounds
+        >>> config = BotConfig(
+        ...     enable_human_delays=True,
+        ...     min_read_delay_seconds=3.0,
+        ...     max_read_delay_seconds=20.0,
+        ...     min_typing_delay_seconds=5.0,
+        ...     max_typing_delay_seconds=60.0
+        ... )
+
+        >>> # Override delay settings on an existing configuration
+        >>> prod_config = BotConfig.production()
+        >>> custom_config = prod_config.with_overrides(
+        ...     min_read_delay_seconds=5.0,
+        ...     max_typing_delay_seconds=90.0
+        ... )
+    """
+
+    quote_messages: bool = Field(
+        default=False, description="Whether to quote user messages in replies"
+    )
+    session_timeout_minutes: int = Field(
+        default=30, description="Minutes of inactivity before session reset"
+    )
+    max_message_length: MessageLimit = Field(
+        default=MessageLimit.NEWLY_CREATED,
+        description="Maximum message length (WhatsApp limit)",
+    )
+    max_split_messages: int = Field(
+        default=5,
+        description="Maximum number of split messages to send (remaining will be grouped)",
+    )
+    error_message: str = Field(
+        default="Sorry, I encountered an error processing your message. Please try again.",
+        description="Default error message",
+    )
+    welcome_message: str | None = Field(
+        default=None, description="Message to send on first interaction"
+    )
+
+    # === Message Batching (Simplified) ===
+    enable_message_batching: bool = Field(
+        default=True, description="Enable message batching to prevent spam"
+    )
+    batch_delay_seconds: float = Field(
+        default=15.0,
+        description="Time to wait for additional messages before processing batch",
+    )
+    max_batch_size: int = Field(
+        default=10, description="Maximum number of messages to batch together"
+    )
+
+    # === Spam Protection ===
+    spam_protection_enabled: bool = Field(
+        default=True, description="Enable spam protection mechanisms"
+    )
+    min_message_interval_seconds: float = Field(
+        default=1,
+        description="Minimum interval between processing messages from same user",
+    )
+    max_messages_per_minute: int = Field(
+        default=20,
+        description="Maximum messages per minute per user before rate limiting",
+    )
+    rate_limit_cooldown_seconds: int = Field(
+        default=60, description="Cooldown period after rate limit is triggered"
+    )
+
+    # === Text-to-Speech (TTS) ===
+    speech_play_chance: float = Field(
+        default=0.0,
+        ge=0.0,
+        le=1.0,
+        description="Probability (0.0-1.0) of sending audio response instead of text",
+    )
+    speech_config: SpeechConfig | None = Field(
+        default=None,
+        description="Optional SpeechConfig for TTS provider customization",
+    )
+
+    # === Error Handling ===
+    retry_failed_messages: bool = Field(
+        default=True, description="Retry processing failed messages"
+    )
+    max_retry_attempts: int = Field(
+        default=3, description="Maximum number of retry attempts for failed messages"
+    )
+    retry_delay_seconds: float = Field(
+        default=1.0, description="Delay between retry attempts"
+    )
+
+    # === Human-Like Delays ===
+    enable_human_delays: bool = Field(
+        default=False,
+        description="Enable human-like delays for message processing to simulate realistic human behavior patterns",
+    )
+    min_read_delay_seconds: float = Field(
+        default=2.0,
+        ge=0.0,
+        description="Minimum delay before marking message as read (seconds). Simulates time to read incoming messages.",
+    )
+    max_read_delay_seconds: float = Field(
+        default=15.0,
+        ge=0.0,
+        description="Maximum delay before marking message as read (seconds). Prevents excessively long read delays.",
+    )
+    min_typing_delay_seconds: float = Field(
+        default=3.0,
+        ge=0.0,
+        description="Minimum delay before sending response (seconds). Simulates time to compose a response.",
+    )
+    max_typing_delay_seconds: float = Field(
+        default=45.0,
+        ge=0.0,
+        description="Maximum delay before sending response (seconds). Prevents excessively long typing delays.",
+    )
+    min_send_delay_seconds: float = Field(
+        default=0.5,
+        ge=0.0,
+        description="Minimum delay before message transmission (seconds). Simulates final message review time.",
+    )
+    max_send_delay_seconds: float = Field(
+        default=4.0,
+        ge=0.0,
+        description="Maximum delay before message transmission (seconds). Prevents excessively long send delays.",
+    )
+    enable_delay_jitter: bool = Field(
+        default=True,
+        description="Enable random variation (±20%) in delay calculations to prevent detectable patterns and simulate natural human behavior variability",
+    )
+    batch_read_compression_factor: float = Field(
+        default=0.7,
+        ge=0.1,
+        le=1.0,
+        description="Compression factor (0.1-1.0) applied to batch read delays. Lower values simulate faster batch reading (e.g., 0.7 = 30% faster than reading individually)",
+    )

agentle/agents/whatsapp/v2/message_limit.py

@@ -0,0 +1,9 @@
+from enum import IntEnum
+
+
+class MessageLimit(IntEnum):
+    NEWLY_CREATED = 250
+    SCALING_PATH = 2000
+    AUTOMATIC_SCALLING_1 = 10_000
+    AUTOMATIC_SCALLING_2 = 100_000
+    UNLIMITED = 1_000_000

agentle/agents/whatsapp/v2/whatsapp_bot.py

@@ -0,0 +1,13 @@
+from collections.abc import Callable
+from typing import Any
+
+from pydantic import ConfigDict
+from rsb.models.base_model import BaseModel
+
+from agentle.agents.whatsapp.v2.batch_processor_manager import BatchProcessorManager
+
+
+class WhatsAppBot(BaseModel):
+    webhook_handlers: list[Callable[..., Any]]
+    batch_processor_manager: BatchProcessorManager
+    model_config = ConfigDict(arbitrary_types_allowed=True)