wappa 0.1.8__py3-none-any.whl → 0.1.10__py3-none-any.whl

wappa/cli/examples/json_cache_example/app/utils/cache_utils.py

@@ -0,0 +1,174 @@
+"""
+Cache utility functions following Single Responsibility Principle.
+
+This module provides cache-related helper functions used across
+different score modules for consistent cache management.
+"""
+
+import re
+
+
+def generate_cache_key(prefix: str, identifier: str, suffix: str | None = None) -> str:
+    """
+    Generate a standardized cache key.
+
+    Args:
+        prefix: Cache type prefix (e.g., 'user', 'state', 'msg_history')
+        identifier: Unique identifier (e.g., user_id, session_id)
+        suffix: Optional suffix for additional specificity
+
+    Returns:
+        Properly formatted cache key
+
+    Examples:
+        >>> generate_cache_key('user', '1234567890')
+        'user:1234567890'
+        >>> generate_cache_key('msg_history', '1234567890', 'recent')
+        'msg_history:1234567890:recent'
+    """
+    if not prefix or not identifier:
+        raise ValueError("Both prefix and identifier are required")
+
+    # Sanitize inputs
+    prefix = sanitize_cache_component(prefix)
+    identifier = sanitize_cache_component(identifier)
+
+    key = f"{prefix}:{identifier}"
+
+    if suffix:
+        suffix = sanitize_cache_component(suffix)
+        key += f":{suffix}"
+
+    return key
+
+
+def sanitize_cache_component(component: str) -> str:
+    """
+    Sanitize a cache key component by removing invalid characters.
+
+    Args:
+        component: Component string to sanitize
+
+    Returns:
+        Sanitized component safe for cache keys
+    """
+    # Remove spaces and special characters, keep alphanumeric, underscore, hyphen
+    sanitized = re.sub(r"[^\w\-]", "_", str(component).strip())
+
+    # Remove multiple consecutive underscores
+    sanitized = re.sub(r"_+", "_", sanitized)
+
+    # Remove leading/trailing underscores
+    return sanitized.strip("_")
+
+
+def get_cache_ttl(cache_type: str) -> int:
+    """
+    Get standard TTL (time-to-live) values for different cache types.
+
+    Args:
+        cache_type: Type of cache ('user', 'state', 'message', 'statistics')
+
+    Returns:
+        TTL in seconds
+
+    Raises:
+        ValueError: If cache_type is not recognized
+    """
+    ttl_mapping = {
+        "user": 86400,  # 24 hours - User profiles
+        "state": 3600,  # 1 hour - Command states
+        "message": 604800,  # 7 days - Message history
+        "statistics": 3600,  # 1 hour - Cache statistics
+        "temporary": 600,  # 10 minutes - Temporary data
+    }
+
+    if cache_type not in ttl_mapping:
+        raise ValueError(
+            f"Unknown cache_type: {cache_type}. Valid types: {list(ttl_mapping.keys())}"
+        )
+
+    return ttl_mapping[cache_type]
+
+
+def validate_cache_key(key: str) -> bool:
+    """
+    Validate if a cache key follows the expected format.
+
+    Args:
+        key: Cache key to validate
+
+    Returns:
+        True if valid, False otherwise
+    """
+    if not key or not isinstance(key, str):
+        return False
+
+    # Basic format check: should contain at least one colon
+    if ":" not in key:
+        return False
+
+    # Check for invalid characters (spaces, special chars except : _ -)
+    if re.search(r"[^\w:\-]", key):
+        return False
+
+    # Should not start or end with colon
+    if key.startswith(":") or key.endswith(":"):
+        return False
+
+    # Should not have consecutive colons
+    return "::" not in key
+
+
+def create_user_profile_key(user_id: str) -> str:
+    """Create standardized user profile cache key."""
+    return generate_cache_key("user", user_id, "profile")
+
+
+def create_message_history_key(user_id: str) -> str:
+    """Create standardized message history cache key."""
+    return generate_cache_key("msg_history", user_id)
+
+
+def create_state_key(user_id: str, state_type: str = "wappa") -> str:
+    """Create standardized state cache key."""
+    return generate_cache_key("state", user_id, state_type)
+
+
+def create_statistics_key(scope: str = "global") -> str:
+    """Create standardized cache statistics key."""
+    return generate_cache_key("stats", scope)
+
+
+def format_cache_error(operation: str, key: str, error: Exception) -> str:
+    """
+    Format cache operation error messages consistently.
+
+    Args:
+        operation: Cache operation ('get', 'set', 'delete')
+        key: Cache key that failed
+        error: Exception that occurred
+
+    Returns:
+        Formatted error message
+    """
+    return f"Cache {operation} failed for key '{key}': {str(error)}"
+
+
+def log_cache_operation(
+    logger, operation: str, key: str, success: bool, duration_ms: float | None = None
+) -> None:
+    """
+    Log cache operations consistently across score modules.
+
+    Args:
+        logger: Logger instance
+        operation: Cache operation performed
+        key: Cache key used
+        success: Whether operation succeeded
+        duration_ms: Optional operation duration in milliseconds
+    """
+    status = "✅" if success else "❌"
+    duration_str = f" ({duration_ms:.1f}ms)" if duration_ms else ""
+
+    logger.debug(f"{status} Cache {operation}: {key}{duration_str}")

wappa/cli/examples/json_cache_example/app/utils/message_utils.py

@@ -0,0 +1,251 @@
+"""
+Message processing utility functions following Single Responsibility Principle.
+
+This module provides message-related helper functions used across
+different score modules for consistent message handling.
+"""
+
+from datetime import datetime
+
+from wappa.webhooks import IncomingMessageWebhook
+
+
+def extract_user_data(webhook: IncomingMessageWebhook) -> dict[str, str]:
+    """
+    Extract user data from webhook in a standardized format.
+
+    Args:
+        webhook: Incoming message webhook
+
+    Returns:
+        Dictionary with standardized user data
+    """
+    return {
+        "user_id": webhook.user.user_id,
+        "user_name": webhook.user.profile_name or "Unknown User",
+        "tenant_id": webhook.tenant.get_tenant_key(),
+        "message_id": webhook.message.message_id,
+    }
+
+
+def sanitize_message_text(text: str, max_length: int = 500) -> str:
+    """
+    Sanitize message text for safe storage and processing.
+
+    Args:
+        text: Raw message text
+        max_length: Maximum allowed length
+
+    Returns:
+        Sanitized message text
+    """
+    if not text:
+        return ""
+
+    # Convert to string and strip whitespace
+    sanitized = str(text).strip()
+
+    # Truncate if too long
+    if len(sanitized) > max_length:
+        sanitized = sanitized[: max_length - 3] + "..."
+
+    # Replace problematic characters
+    sanitized = sanitized.replace("\x00", "").replace("\r\n", "\n")
+
+    return sanitized
+
+
+def format_timestamp(dt: datetime, format_type: str = "display") -> str:
+    """
+    Format timestamps consistently across the application.
+
+    Args:
+        dt: Datetime to format
+        format_type: Format type ('display', 'compact', 'iso')
+
+    Returns:
+        Formatted timestamp string
+    """
+    if format_type == "display":
+        return dt.strftime("%Y-%m-%d %H:%M:%S")
+    elif format_type == "compact":
+        return dt.strftime("%m/%d %H:%M")
+    elif format_type == "iso":
+        return dt.isoformat()
+    else:
+        raise ValueError(f"Unknown format_type: {format_type}")
+
+
+def extract_command_from_message(text: str) -> tuple[str | None, str]:
+    """
+    Extract command and remaining text from message.
+
+    Args:
+        text: Message text
+
+    Returns:
+        Tuple of (command, remaining_text)
+        Command is None if no command found
+
+    Examples:
+        >>> extract_command_from_message("/WAPPA hello")
+        ("/WAPPA", "hello")
+        >>> extract_command_from_message("regular message")
+        (None, "regular message")
+    """
+    if not text:
+        return None, ""
+
+    text = text.strip()
+
+    # Check if it starts with a command
+    if text.startswith("/"):
+        parts = text.split(" ", 1)
+        command = parts[0].upper()
+        remaining = parts[1] if len(parts) > 1 else ""
+        return command, remaining
+
+    return None, text
+
+
+def is_special_command(text: str) -> bool:
+    """
+    Check if message text contains a special command.
+
+    Args:
+        text: Message text to check
+
+    Returns:
+        True if text contains a recognized command
+    """
+    command, _ = extract_command_from_message(text)
+
+    if not command:
+        return False
+
+    # List of recognized commands
+    special_commands = ["/WAPPA", "/EXIT", "/HISTORY", "/HELP", "/STATUS"]
+
+    return command in special_commands
+
+
+def get_message_type_display_name(message_type: str) -> str:
+    """
+    Get human-readable display name for message types.
+
+    Args:
+        message_type: Technical message type
+
+    Returns:
+        Human-readable display name
+    """
+    type_mapping = {
+        "text": "Text",
+        "image": "Image",
+        "audio": "Audio",
+        "video": "Video",
+        "document": "Document",
+        "location": "Location",
+        "contacts": "Contact",
+        "interactive": "Interactive",
+        "button": "Button Response",
+        "list": "List Response",
+        "sticker": "Sticker",
+    }
+
+    return type_mapping.get(message_type.lower(), message_type.title())
+
+
+def create_user_greeting(user_name: str | None, message_count: int) -> str:
+    """
+    Create personalized user greeting message.
+
+    Args:
+        user_name: User's display name (can be None)
+        message_count: Number of messages from user
+
+    Returns:
+        Personalized greeting text
+    """
+    name = user_name or "there"
+
+    if message_count == 1:
+        return f"👋 Hello {name}! Welcome to the Redis Cache Demo!"
+    elif message_count < 5:
+        return f"👋 Hello {name}! Nice to see you again!"
+    else:
+        return f"👋 Hello {name}! You're becoming a regular here! ({message_count} messages)"
+
+
+def format_message_history_display(
+    messages, total_count: int, display_count: int = 20
+) -> str:
+    """
+    Format message history for display to user.
+
+    Args:
+        messages: List of MessageHistory objects
+        total_count: Total number of messages in history
+        display_count: Number of messages being displayed
+
+    Returns:
+        Formatted history text
+    """
+    if not messages:
+        return "📚 Your message history is empty. Start chatting to build your history!"
+
+    history_text = f"📚 Your Message History ({total_count} total messages):\n\n"
+
+    for i, msg_history in enumerate(messages, 1):
+        timestamp_str = format_timestamp(msg_history.timestamp, "compact")
+        msg_type = (
+            f"[{get_message_type_display_name(msg_history.message_type)}]"
+            if msg_history.message_type != "text"
+            else ""
+        )
+
+        # Truncate long messages for display
+        display_message = sanitize_message_text(msg_history.message, 50)
+
+        history_text += f"{i:2d}. {timestamp_str} {msg_type} {display_message}\n"
+
+    if total_count > display_count:
+        history_text += f"\n... showing last {display_count} of {total_count} messages"
+
+    return history_text
+
+
+def create_cache_info_message(user_profile, cache_stats) -> str:
+    """
+    Create informational message about cache status.
+
+    Args:
+        user_profile: User profile data
+        cache_stats: Cache statistics data
+
+    Returns:
+        Formatted cache information message
+    """
+    info_lines = [
+        "👤 Your Profile:",
+        f"• Messages sent: {user_profile.message_count}",
+        f"• First seen: {format_timestamp(user_profile.first_seen, 'compact')}",
+        f"• Last seen: {format_timestamp(user_profile.last_seen, 'compact')}",
+        "",
+        "🎯 Special Commands:",
+        "• Send '/WAPPA' to enter special state",
+        "• Send '/EXIT' to leave special state",
+        "• Send '/HISTORY' to see your message history",
+        "",
+        "📊 Cache Statistics:",
+        f"• Total operations: {cache_stats.total_operations}",
+        f"• User cache hit rate: {cache_stats.get_user_hit_rate():.1%}",
+        f"• Active states: {cache_stats.state_cache_active}",
+        "",
+        "💾 This demo showcases Redis caching:",
+        "• User data cached in user_cache",
+        "• Message history stored in table_cache per user",
+        "• Commands tracked in state_cache",
+    ]
+
+    return "\n".join(info_lines)

wappa/cli/examples/openai_transcript/.gitignore

@@ -1,10 +1,69 @@
-# Python-generated files
+# Wappa
+logs/
+
+# Environment variables
+.env
+.env.local
+.env.development
+.env.production
+
+# Python
 __pycache__/
-*.py[oc]
+*.py[cod]
+*$py.class
+*.so
+.Python
 build/
+develop-eggs/
 dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
 wheels/
-*.egg-info
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
 
 # Virtual environments
-.venv
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+app/logs/
+logs/
+*.log
+
+# Redis dumps
+dump.rdb
+
+# Temporary files
+.tmp/
+temp/
+tmp/
+
+# Coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+.pytest_cache/

wappa/cli/examples/openai_transcript/app/main.py

@@ -0,0 +1,9 @@
+from wappa import Wappa
+
+from .master_event import TranscriptEventHandler
+
+app = Wappa()
+app.set_event_handler(TranscriptEventHandler())
+
+if __name__ == "__main__":
+    app.run()

wappa/cli/examples/openai_transcript/app/master_event.py

@@ -0,0 +1,62 @@
+from openai import AsyncOpenAI
+
+from wappa import WappaEventHandler
+from wappa.core.config import settings
+from wappa.core.logging import get_logger
+from wappa.webhooks import IncomingMessageWebhook
+
+from .openai_utils import AudioProcessingService
+
+logger = get_logger("TranscriptEventHandler")
+
+
+class TranscriptEventHandler(WappaEventHandler):
+    async def process_message(self, webhook: IncomingMessageWebhook):
+        message_type = webhook.get_message_type_name()
+
+        await self.messenger.mark_as_read(
+            webhook.message.message_id, webhook.user.user_id
+        )
+
+        if message_type == "audio":
+            audio_id = webhook.message.audio.id
+
+            openai_client = AsyncOpenAI(api_key=settings.openai_api_key)
+            audio_service = AudioProcessingService(openai_client)
+
+            # Option 1: Using tempfile context manager (automatic cleanup)
+            async with self.messenger.media_handler.download_media_tempfile(
+                audio_id
+            ) as audio_download:
+                if audio_download.success:
+                    transcription = await audio_service.transcribe_audio(
+                        audio_download.file_path
+                    )
+                    await self.messenger.send_text(
+                        f"*Transcript:*\n\n{transcription}", webhook.user.user_id
+                    )
+                    logger.info(
+                        f"Transcribed audio from temp file: {audio_download.file_path}"
+                    )
+                else:
+                    logger.error(f"Failed to download audio: {audio_download.error}")
+                    await self.messenger.send_text(
+                        "Sorry, I couldn't download the audio file.",
+                        webhook.user.user_id,
+                    )
+
+            # Option 2: Memory-only processing (no files created)
+            # Uncomment to use bytes-based processing instead:
+            # audio_bytes_result = await self.messenger.media_handler.get_media_as_bytes(audio_id)
+            # if audio_bytes_result.success:
+            #     transcription = await audio_service.transcribe_audio(audio_bytes_result.file_data, "audio.ogg")
+            #     await self.messenger.send_text(f"*Transcript:*\n\n{transcription}", webhook.user.user_id)
+            #     logger.info(f"Transcribed audio from memory ({audio_bytes_result.file_size} bytes)")
+            # else:
+            #     logger.error(f"Failed to download audio: {audio_bytes_result.error}")
+            #     await self.messenger.send_text("Sorry, I couldn't download the audio file.", webhook.user.user_id)
+        else:
+            await self.messenger.send_text(
+                "*Hey Wapp@!*\n\nThis app only receives Audio, send a Voice Note for Transcript",
+                webhook.user.user_id,
+            )

wappa/cli/examples/openai_transcript/app/openai_utils/__init__.py

@@ -0,0 +1,3 @@
+from .audio_processing import AudioProcessingService
+
+all = ["AudioProcessingService"]

wappa/cli/examples/openai_transcript/app/openai_utils/audio_processing.py

@@ -0,0 +1,89 @@
+# Removed direct config import
+# from config.env import OPENAI_API_KEY
+import io
+from pathlib import Path
+from typing import BinaryIO
+
+from openai import AsyncOpenAI
+
+from wappa.core.logging import get_logger  # Corrected relative import
+
+# Initialize logger with class name
+logger = get_logger("AudioProcessingService")
+
+
+class AudioProcessingService:
+    def __init__(self, async_openai_client: AsyncOpenAI):
+        # Accept api_key in init
+        self.async_openai_client = async_openai_client
+
+    async def transcribe_audio(
+        self, audio_source: str | Path | bytes | BinaryIO, filename: str = "audio"
+    ) -> str:
+        """
+        Transcribes the audio using OpenAI's speech-to-text API with the gpt-4o-mini-transcribe model.
+
+        Args:
+            audio_source: Can be:
+                - str/Path: Path to the audio file to transcribe
+                - bytes: Raw audio data
+                - BinaryIO: File-like object containing audio data
+            filename: Name for the audio (used for OpenAI API, especially for bytes/BinaryIO)
+
+        Returns:
+            The transcribed text.
+        """
+        try:
+            # Handle different input types
+            if isinstance(audio_source, str | Path):
+                # File path input (original behavior)
+                audio_path = Path(audio_source)
+                with audio_path.open("rb") as audio_file:
+                    transcription = (
+                        await self.async_openai_client.audio.transcriptions.create(
+                            model="gpt-4o-mini-transcribe",
+                            file=audio_file,
+                            response_format="json",
+                        )
+                    )
+                logger.debug(f"Transcription successful for file: {audio_path}")
+
+            elif isinstance(audio_source, bytes):
+                # Bytes input - create BytesIO stream
+                audio_stream = io.BytesIO(audio_source)
+                audio_stream.name = filename  # OpenAI API needs a filename attribute
+                transcription = (
+                    await self.async_openai_client.audio.transcriptions.create(
+                        model="gpt-4o-mini-transcribe",
+                        file=audio_stream,
+                        response_format="json",
+                    )
+                )
+                logger.debug(
+                    f"Transcription successful for bytes data ({len(audio_source)} bytes)"
+                )
+
+            else:
+                # File-like object input
+                # Ensure it has a name attribute for OpenAI API
+                if not hasattr(audio_source, "name"):
+                    audio_source.name = filename
+                transcription = (
+                    await self.async_openai_client.audio.transcriptions.create(
+                        model="gpt-4o-mini-transcribe",
+                        file=audio_source,
+                        response_format="json",
+                    )
+                )
+                logger.debug(
+                    f"Transcription successful for file-like object: {getattr(audio_source, 'name', 'unknown')}"
+                )
+
+            return transcription.text
+
+        except FileNotFoundError:
+            logger.error(f"Audio file not found for transcription: {audio_source}")
+            raise
+        except Exception as e:
+            logger.error(f"Error during OpenAI transcription call: {e}", exc_info=True)
+            raise

wappa/cli/examples/redis_cache_example/.env.example

@@ -0,0 +1,33 @@
+# ================================================================
+# WAPPA WHATSAPP FRAMEWORK CONFIGURATION
+# ================================================================
+
+# General Configuration
+PORT=8000
+TIME_ZONE=America/Bogota
+
+# DEBUG or INFO or WARNING or ERROR or CRITICAL
+LOG_LEVEL=DEBUG
+LOG_DIR=./logs
+## Environment DEV or PROD
+ENVIRONMENT=DEV  
+
+# WhatsApp Graph API
+BASE_URL=https://graph.facebook.com/
+API_VERSION=v23.0
+
+# WhatsApp Business API Credentials
+WP_ACCESS_TOKEN=
+WP_PHONE_ID=
+WP_BID=
+
+# Webhook Configuration
+WHATSAPP_WEBHOOK_VERIFY_TOKEN=
+
+# Redis Configuration (Optional - uncomment to enable Redis persistence)
+REDIS_URL=redis://localhost:6379/
+REDIS_MAX_CONNECTIONS=64
+
+# Optional: AI Tools
+# OPENAI_API_KEY=
+