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

wappa/cli/examples/redis_cache_example/app/models/redis_demo_models.py

@@ -0,0 +1,256 @@
+"""
+Pydantic models for Redis cache demonstration.
+
+These models demonstrate how to structure data for different cache types
+in the Wappa Redis caching system.
+"""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class MessageHistory(BaseModel):
+    """
+    Individual message entry for message history storage.
+
+    Stores a single message with its timestamp.
+    """
+
+    message: str = Field(
+        ..., description="The message content or type description", max_length=500
+    )
+
+    timestamp: datetime = Field(
+        default_factory=datetime.utcnow, description="When the message was sent"
+    )
+
+    message_type: str = Field(
+        default="text",
+        description="Type of message (text, image, audio, etc.)",
+        max_length=20,
+    )
+
+
+class User(BaseModel):
+    """
+    User profile model for user_cache demonstration.
+
+    Stores user information extracted from WhatsApp webhook data.
+    """
+
+    phone_number: str = Field(
+        ...,
+        description="User's phone number (WhatsApp ID)",
+        min_length=10,
+        max_length=20,
+    )
+
+    user_name: str | None = Field(
+        None, description="User's display name from WhatsApp profile", max_length=100
+    )
+
+    first_seen: datetime = Field(
+        default_factory=datetime.utcnow, description="When the user was first seen"
+    )
+
+    last_seen: datetime = Field(
+        default_factory=datetime.utcnow, description="When the user was last seen"
+    )
+
+    message_count: int = Field(
+        default=0, description="Total number of messages received from this user", ge=0
+    )
+
+    is_active: bool = Field(
+        default=True, description="Whether the user is currently active"
+    )
+
+    @field_validator("phone_number", mode="before")
+    @classmethod
+    def validate_phone_number(cls, v) -> str:
+        """Convert phone number to string if it's an integer."""
+        if isinstance(v, int):
+            return str(v)
+        return v
+
+    def increment_message_count(self) -> None:
+        """Increment the message count and update last_seen timestamp."""
+        self.message_count += 1
+        self.last_seen = datetime.utcnow()
+
+
+class MessageLog(BaseModel):
+    """
+    Message log model for table_cache demonstration.
+
+    Stores message history for a user with waid as primary key.
+    Contains a list of all messages sent by the user.
+    """
+
+    user_id: str = Field(
+        ...,
+        description="User's phone number/ID (primary key)",
+        min_length=10,
+        max_length=20,
+    )
+
+    text_message: list[MessageHistory] = Field(
+        default_factory=list, description="List of all messages sent by this user"
+    )
+
+    tenant_id: str | None = Field(
+        None,
+        description="Tenant/business ID that received the messages",
+        max_length=100,
+    )
+
+    def get_log_key(self) -> str:
+        """Generate the primary key for this user's message log."""
+        return f"msg_history:{self.user_id}"
+
+    def add_message(self, message: str, message_type: str = "text") -> None:
+        """Add a new message to the user's history."""
+        new_message = MessageHistory(
+            message=message, message_type=message_type, timestamp=datetime.utcnow()
+        )
+        self.text_message.append(new_message)
+
+    def get_recent_messages(self, count: int = 10) -> list[MessageHistory]:
+        """Get the most recent messages from the user's history."""
+        return self.text_message[-count:] if self.text_message else []
+
+    @field_validator("user_id", "tenant_id", mode="before")
+    @classmethod
+    def validate_string_ids(cls, v) -> str:
+        """Convert ID fields to string if they're integers."""
+        if isinstance(v, int):
+            return str(v)
+        return v
+
+    def get_message_count(self) -> int:
+        """Get the total number of messages in the history."""
+        return len(self.text_message)
+
+
+class StateHandler(BaseModel):
+    """
+    State handler model for state_cache demonstration.
+
+    Manages user state for the /WAPPA command flow.
+    """
+
+    is_wappa: bool = Field(
+        default=False, description="Whether the user is in 'WAPPA' state"
+    )
+
+    activated_at: datetime | None = Field(
+        None, description="When the WAPPA state was activated"
+    )
+
+    command_count: int = Field(
+        default=0, description="Number of commands processed while in WAPPA state", ge=0
+    )
+
+    last_command: str | None = Field(
+        None, description="Last command processed in WAPPA state", max_length=100
+    )
+
+    def activate_wappa(self) -> None:
+        """Activate WAPPA state."""
+        self.is_wappa = True
+        self.activated_at = datetime.utcnow()
+        self.command_count = 0
+        self.last_command = "/WAPPA"
+
+    def deactivate_wappa(self) -> None:
+        """Deactivate WAPPA state."""
+        self.is_wappa = False
+        self.last_command = "/EXIT"
+
+    def process_command(self, command: str) -> None:
+        """Process a command while in WAPPA state."""
+        self.command_count += 1
+        self.last_command = command
+
+    def get_state_duration(self) -> int | None:
+        """Get how long the WAPPA state has been active in seconds."""
+        if not self.is_wappa or not self.activated_at:
+            return None
+        return int((datetime.utcnow() - self.activated_at).total_seconds())
+
+
+class CacheStats(BaseModel):
+    """
+    Cache statistics model for monitoring cache usage.
+
+    Used to track cache performance and usage statistics.
+    """
+
+    # Cache performance metrics
+    user_cache_hits: int = Field(default=0, ge=0)
+    user_cache_misses: int = Field(default=0, ge=0)
+    table_cache_entries: int = Field(default=0, ge=0)
+    state_cache_active: int = Field(default=0, ge=0)
+
+    # Operation tracking
+    total_operations: int = Field(default=0, ge=0)
+    errors: int = Field(default=0, ge=0)
+
+    # System information
+    cache_type: str = Field(default="Unknown")
+    connection_status: str = Field(default="Unknown")
+    is_healthy: bool = Field(default=True)
+
+    # Timing
+    last_updated: datetime = Field(default_factory=datetime.utcnow)
+
+    def record_user_hit(self) -> None:
+        """Record a user cache hit."""
+        self.user_cache_hits += 1
+        self.total_operations += 1
+        self.last_updated = datetime.utcnow()
+
+    def record_user_miss(self) -> None:
+        """Record a user cache miss."""
+        self.user_cache_misses += 1
+        self.total_operations += 1
+        self.last_updated = datetime.utcnow()
+
+    def record_table_entry(self) -> None:
+        """Record a new table cache entry."""
+        self.table_cache_entries += 1
+        self.total_operations += 1
+        self.last_updated = datetime.utcnow()
+
+    def record_state_activation(self) -> None:
+        """Record a state cache activation."""
+        self.state_cache_active += 1
+        self.total_operations += 1
+        self.last_updated = datetime.utcnow()
+
+    def record_state_deactivation(self) -> None:
+        """Record a state cache deactivation."""
+        if self.state_cache_active > 0:
+            self.state_cache_active -= 1
+        self.total_operations += 1
+        self.last_updated = datetime.utcnow()
+
+    def record_error(self) -> None:
+        """Record an error."""
+        self.errors += 1
+        self.total_operations += 1
+        self.last_updated = datetime.utcnow()
+
+    def get_user_hit_rate(self) -> float:
+        """Calculate user cache hit rate."""
+        total_user_ops = self.user_cache_hits + self.user_cache_misses
+        if total_user_ops == 0:
+            return 0.0
+        return round(self.user_cache_hits / total_user_ops, 3)
+
+    def get_error_rate(self) -> float:
+        """Calculate overall error rate."""
+        if self.total_operations == 0:
+            return 0.0
+        return round(self.errors / self.total_operations, 3)

wappa/cli/examples/redis_cache_example/app/scores/__init__.py

@@ -0,0 +1,35 @@
+"""
+Score modules for Redis Cache Example following SOLID principles.
+
+Each score module handles a specific business concern:
+- score_user_management: User profile and caching logic
+- score_message_history: Message logging and history retrieval
+- score_state_commands: /WAPPA, /EXIT command processing
+- score_cache_statistics: Cache monitoring and statistics
+
+This architecture follows the Single Responsibility and Open/Closed principles.
+"""
+
+from .score_base import ScoreBase, ScoreDependencies
+from .score_cache_statistics import CacheStatisticsScore
+from .score_message_history import MessageHistoryScore
+from .score_state_commands import StateCommandsScore
+from .score_user_management import UserManagementScore
+
+# Available score modules for automatic discovery
+AVAILABLE_SCORES = [
+    UserManagementScore,
+    MessageHistoryScore,
+    StateCommandsScore,
+    CacheStatisticsScore,
+]
+
+__all__ = [
+    "ScoreBase",
+    "ScoreDependencies",
+    "UserManagementScore",
+    "MessageHistoryScore",
+    "StateCommandsScore",
+    "CacheStatisticsScore",
+    "AVAILABLE_SCORES",
+]

wappa/cli/examples/redis_cache_example/app/scores/score_base.py

@@ -0,0 +1,192 @@
+"""
+Base interface for score modules following Interface Segregation Principle.
+
+This module defines the common interface that all score modules must implement,
+ensuring consistent behavior across different business logic handlers.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from logging import Logger
+
+from wappa.domain.interfaces.cache_interface import ICache
+from wappa.messaging.whatsapp.messenger.whatsapp_messenger import WhatsAppMessenger
+from wappa.webhooks import IncomingMessageWebhook
+
+
+@dataclass
+class ScoreDependencies:
+    """
+    Dependencies required by score modules.
+
+    This follows Dependency Inversion Principle by providing
+    abstractions that score modules depend on.
+    """
+
+    messenger: WhatsAppMessenger
+    user_cache: ICache
+    table_cache: ICache
+    state_cache: ICache
+    logger: Logger
+
+
+class ScoreBase(ABC):
+    """
+    Base class for all score modules.
+
+    Implements Interface Segregation Principle by providing
+    only the methods that score modules actually need.
+    """
+
+    def __init__(self, dependencies: ScoreDependencies):
+        """
+        Initialize score with injected dependencies.
+
+        Args:
+            dependencies: Required dependencies for the score
+        """
+        self.messenger = dependencies.messenger
+        self.user_cache = dependencies.user_cache
+        self.table_cache = dependencies.table_cache
+        self.state_cache = dependencies.state_cache
+        self.logger = dependencies.logger
+
+        # Track processing statistics
+        self._processing_count = 0
+        self._error_count = 0
+
+    @property
+    def score_name(self) -> str:
+        """Return the name of this score module."""
+        return self.__class__.__name__
+
+    @property
+    def processing_stats(self) -> dict:
+        """Return processing statistics for this score."""
+        return {
+            "processed": self._processing_count,
+            "errors": self._error_count,
+            "success_rate": (
+                (self._processing_count - self._error_count) / self._processing_count
+                if self._processing_count > 0
+                else 0.0
+            ),
+        }
+
+    @abstractmethod
+    async def can_handle(self, webhook: IncomingMessageWebhook) -> bool:
+        """
+        Determine if this score can handle the given webhook.
+
+        Args:
+            webhook: Incoming message webhook to evaluate
+
+        Returns:
+            True if this score should process the webhook
+        """
+        pass
+
+    @abstractmethod
+    async def process(self, webhook: IncomingMessageWebhook) -> bool:
+        """
+        Process the webhook with this score's business logic.
+
+        Args:
+            webhook: Incoming message webhook to process
+
+        Returns:
+            True if processing was successful and complete
+        """
+        pass
+
+    async def validate_dependencies(self) -> bool:
+        """
+        Validate that all required dependencies are available.
+
+        Returns:
+            True if all dependencies are valid
+        """
+        if not all(
+            [
+                self.messenger,
+                self.user_cache,
+                self.table_cache,
+                self.state_cache,
+                self.logger,
+            ]
+        ):
+            self.logger.error(f"{self.score_name}: Missing required dependencies")
+            return False
+        return True
+
+    def _record_processing(self, success: bool = True) -> None:
+        """Record processing statistics."""
+        self._processing_count += 1
+        if not success:
+            self._error_count += 1
+
+    async def _handle_error(self, error: Exception, context: str) -> None:
+        """
+        Handle errors consistently across score modules.
+
+        Args:
+            error: Exception that occurred
+            context: Context where error occurred
+        """
+        self._record_processing(success=False)
+        self.logger.error(
+            f"{self.score_name} error in {context}: {str(error)}", exc_info=True
+        )
+
+    def __str__(self) -> str:
+        """String representation of the score."""
+        return f"{self.score_name}(processed={self._processing_count}, errors={self._error_count})"
+
+
+class ScoreRegistry:
+    """
+    Registry for managing score modules.
+
+    Implements Open/Closed Principle by allowing new scores
+    to be registered without modifying existing code.
+    """
+
+    def __init__(self):
+        self._scores: list[ScoreBase] = []
+
+    def register_score(self, score: ScoreBase) -> None:
+        """Register a score module."""
+        if not isinstance(score, ScoreBase):
+            raise ValueError("Score must inherit from ScoreBase")
+
+        self._scores.append(score)
+
+    def get_scores(self) -> list[ScoreBase]:
+        """Get all registered scores."""
+        return self._scores.copy()
+
+    async def find_handler(self, webhook: IncomingMessageWebhook) -> ScoreBase | None:
+        """
+        Find the first score that can handle the webhook.
+
+        Args:
+            webhook: Webhook to find handler for
+
+        Returns:
+            Score that can handle the webhook, or None
+        """
+        for score in self._scores:
+            try:
+                if await score.can_handle(webhook):
+                    return score
+            except Exception as e:
+                # Log error but continue to next score
+                score.logger.error(
+                    f"Error checking if {score.score_name} can handle webhook: {e}"
+                )
+
+        return None
+
+    def get_score_stats(self) -> dict:
+        """Get statistics for all registered scores."""
+        return {score.score_name: score.processing_stats for score in self._scores}