wingman-ai 1.0.0__py3-none-any.whl

wingman/core/policy/evaluator.py

@@ -0,0 +1,265 @@
+"""Policy evaluation engine for determining response behavior."""
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from wingman.config.registry import (
+    ContactProfile,
+    ContactRole,
+    GroupCategory,
+    GroupConfig,
+    ReplyPolicy,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class MessageContext:
+    """Context information for a message being evaluated."""
+
+    # Message details
+    chat_id: str
+    sender_id: str
+    text: str
+
+    # Chat type
+    is_dm: bool
+    is_group: bool
+
+    # Resolved profiles
+    contact: ContactProfile
+
+    # Optional fields with defaults
+    group: GroupConfig | None = None
+    platform: str = "whatsapp"
+    is_reply_to_bot: bool = False
+    is_mentioned: bool = False
+
+    @property
+    def role(self) -> ContactRole:
+        """Get the sender's role."""
+        return self.contact.role
+
+    @property
+    def group_category(self) -> GroupCategory | None:
+        """Get the group category if in a group."""
+        return self.group.category if self.group else None
+
+
+@dataclass
+class PolicyDecision:
+    """Result of policy evaluation."""
+
+    should_respond: bool
+    reason: str
+    rule_name: str | None = None
+    action: ReplyPolicy = ReplyPolicy.SELECTIVE
+
+
+@dataclass
+class PolicyRule:
+    """A single policy rule."""
+
+    name: str
+    conditions: dict
+    action: ReplyPolicy
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "PolicyRule":
+        """Create a PolicyRule from config dict."""
+        return cls(
+            name=data.get("name", "unnamed"),
+            conditions=data.get("conditions", {}),
+            action=ReplyPolicy(data.get("action", "selective")),
+        )
+
+
+class PolicyEvaluator:
+    """
+    Evaluates policy rules against message context to determine
+    whether the bot should respond.
+    """
+
+    def __init__(self, config_path: Path | None = None, bot_name: str = "Maximus"):
+        self._rules: list[PolicyRule] = []
+        self._fallback_action = ReplyPolicy.SELECTIVE
+        self._bot_name = bot_name.lower()
+
+        if config_path and config_path.exists():
+            self._load_config(config_path)
+
+    def _load_config(self, config_path: Path) -> None:
+        """Load policy configuration from YAML file."""
+        try:
+            with open(config_path) as f:
+                config = yaml.safe_load(f) or {}
+
+            # Load rules
+            rules_data = config.get("rules", [])
+            for rule_data in rules_data:
+                try:
+                    rule = PolicyRule.from_dict(rule_data)
+                    self._rules.append(rule)
+                    logger.debug(f"Loaded policy rule: {rule.name}")
+                except (ValueError, KeyError) as e:
+                    logger.warning(f"Invalid policy rule: {e}")
+
+            # Load fallback
+            fallback_data = config.get("fallback", {})
+            if fallback_data:
+                self._fallback_action = ReplyPolicy(fallback_data.get("action", "selective"))
+
+            logger.info(f"Loaded {len(self._rules)} policy rules from {config_path}")
+
+        except Exception as e:
+            logger.error(f"Failed to load policies config: {e}")
+
+    def _check_mentioned(self, text: str) -> bool:
+        """Check if the bot is mentioned in the text."""
+        if not text:
+            return False
+
+        text_lower = text.lower()
+
+        # Check for @mention or name mention
+        if f"@{self._bot_name}" in text_lower:
+            return True
+        if self._bot_name in text_lower:
+            return True
+
+        return False
+
+    def _matches_conditions(self, rule: PolicyRule, context: MessageContext) -> bool:
+        """Check if a rule's conditions match the message context."""
+        conditions = rule.conditions
+
+        # Check platform
+        if "platform" in conditions:
+            if conditions["platform"] != context.platform:
+                return False
+
+        # Check is_dm
+        if "is_dm" in conditions:
+            if conditions["is_dm"] != context.is_dm:
+                return False
+
+        # Check is_group
+        if "is_group" in conditions:
+            if conditions["is_group"] != context.is_group:
+                return False
+
+        # Check role
+        if "role" in conditions:
+            if conditions["role"] != context.role.value:
+                return False
+
+        # Check group_category
+        if "group_category" in conditions:
+            if context.group_category is None:
+                return False
+            if conditions["group_category"] != context.group_category.value:
+                return False
+
+        # Check is_reply_to_bot
+        if "is_reply_to_bot" in conditions:
+            if conditions["is_reply_to_bot"] != context.is_reply_to_bot:
+                return False
+
+        # Check is_mentioned
+        if "is_mentioned" in conditions:
+            if conditions["is_mentioned"] != context.is_mentioned:
+                return False
+
+        return True
+
+    def evaluate(self, context: MessageContext) -> PolicyDecision:
+        """
+        Evaluate policy rules against the message context.
+
+        Args:
+            context: The message context to evaluate
+
+        Returns:
+            PolicyDecision with should_respond and reason
+        """
+        # Check if bot is mentioned (for selective policies)
+        is_mentioned = self._check_mentioned(context.text)
+        # Update context with mention status
+        context.is_mentioned = is_mentioned
+
+        logger.debug(
+            f"Evaluating policy: platform={context.platform}, is_dm={context.is_dm}, "
+            f"role={context.role.value}, "
+            f"group_category={context.group_category.value if context.group_category else 'N/A'}, "
+            f"is_mentioned={is_mentioned}"
+        )
+
+        # Evaluate rules in order
+        for rule in self._rules:
+            if self._matches_conditions(rule, context):
+                logger.debug(f"Rule matched: {rule.name} -> {rule.action.value}")
+
+                should_respond = self._should_respond_for_action(
+                    rule.action, is_mentioned, context.is_reply_to_bot
+                )
+
+                return PolicyDecision(
+                    should_respond=should_respond,
+                    reason=f"rule:{rule.name}",
+                    rule_name=rule.name,
+                    action=rule.action,
+                )
+
+        # No rule matched, use fallback
+        logger.debug(f"No rule matched, using fallback: {self._fallback_action.value}")
+        should_respond = self._should_respond_for_action(
+            self._fallback_action, is_mentioned, context.is_reply_to_bot
+        )
+
+        return PolicyDecision(
+            should_respond=should_respond,
+            reason="fallback",
+            rule_name=None,
+            action=self._fallback_action,
+        )
+
+    def _should_respond_for_action(
+        self, action: ReplyPolicy, is_mentioned: bool, is_reply_to_bot: bool
+    ) -> bool:
+        """Determine if should respond based on action type."""
+        if action == ReplyPolicy.ALWAYS:
+            return True
+        elif action == ReplyPolicy.NEVER:
+            return False
+        elif action == ReplyPolicy.SELECTIVE:
+            # Respond if mentioned or replying to bot
+            return is_mentioned or is_reply_to_bot
+        return False
+
+    def create_context(
+        self,
+        chat_id: str,
+        sender_id: str,
+        text: str,
+        is_group: bool,
+        contact: ContactProfile,
+        group: GroupConfig | None = None,
+        is_reply_to_bot: bool = False,
+        platform: str = "whatsapp",
+    ) -> MessageContext:
+        """Helper to create a MessageContext."""
+        return MessageContext(
+            chat_id=chat_id,
+            sender_id=sender_id,
+            text=text,
+            is_dm=not is_group,
+            is_group=is_group,
+            platform=platform,
+            contact=contact,
+            group=group,
+            is_reply_to_bot=is_reply_to_bot,
+        )

wingman/core/process_manager.py

@@ -0,0 +1,135 @@
+"""Node.js subprocess management."""
+
+import asyncio
+import logging
+from pathlib import Path
+
+from .ipc_handler import IPCCommand, IPCHandler
+
+logger = logging.getLogger(__name__)
+
+
+class NodeProcessManager:
+    """Manages the Node.js listener subprocess."""
+
+    def __init__(self, node_dir: Path, auth_state_dir: Path | None = None):
+        self.node_dir = node_dir
+        self.auth_state_dir = auth_state_dir
+        self.process: asyncio.subprocess.Process | None = None
+        self.ipc: IPCHandler | None = None
+        self._stderr_task: asyncio.Task | None = None
+
+    async def start(self) -> IPCHandler:
+        """Start the Node.js subprocess and return IPC handler."""
+        node_script = self.node_dir / "dist" / "index.js"
+
+        if not node_script.exists():
+            raise FileNotFoundError(
+                f"Node.js script not found: {node_script}\n"
+                "Run 'npm run build' in node_listener directory first."
+            )
+
+        logger.info(f"Starting Node.js subprocess: {node_script}")
+
+        # Build environment with optional auth state directory
+        env = None
+        if self.auth_state_dir:
+            import os
+
+            env = os.environ.copy()
+            env["AUTH_STATE_DIR"] = str(self.auth_state_dir)
+
+        self.process = await asyncio.create_subprocess_exec(
+            "node",
+            str(node_script),
+            stdin=asyncio.subprocess.PIPE,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            cwd=str(self.node_dir),
+            env=env,
+        )
+
+        if not self.process.stdin or not self.process.stdout:
+            raise RuntimeError("Failed to create subprocess pipes")
+
+        # Create IPC handler
+        self.ipc = IPCHandler(stdin=self.process.stdin, stdout=self.process.stdout)
+
+        # Start stderr reader for logging
+        self._stderr_task = asyncio.create_task(self._read_stderr())
+
+        logger.info(f"Node.js subprocess started (PID: {self.process.pid})")
+        return self.ipc
+
+    async def _read_stderr(self) -> None:
+        """Read and log Node.js stderr output."""
+        if not self.process or not self.process.stderr:
+            return
+
+        while True:
+            try:
+                line = await self.process.stderr.readline()
+                if not line:
+                    break
+
+                # Node logs JSON to stderr
+                log_line = line.decode("utf-8").strip()
+                if log_line:
+                    # Check if it's a QR code line (contains block characters)
+                    if any(c in log_line for c in ["▄", "█", "▀", "="]):
+                        # Print QR directly to stderr for user to see
+                        print(log_line, flush=True)
+                    else:
+                        logger.debug(f"[Node] {log_line}")
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Error reading stderr: {e}")
+                break
+
+    async def stop(self) -> None:
+        """Stop the Node.js subprocess gracefully."""
+        if not self.process:
+            return
+
+        logger.info("Stopping Node.js subprocess...")
+
+        # Cancel stderr reader
+        if self._stderr_task:
+            self._stderr_task.cancel()
+            try:
+                await self._stderr_task
+            except asyncio.CancelledError:
+                pass
+
+        # Try graceful shutdown first
+        if self.ipc:
+            try:
+                await asyncio.wait_for(
+                    self.ipc.send_command(IPCCommand(action="shutdown")), timeout=2.0
+                )
+            except Exception as e:
+                logger.warning(f"Failed to send shutdown command: {e}")
+
+        # Wait for process to exit
+        try:
+            await asyncio.wait_for(self.process.wait(), timeout=5.0)
+            logger.info("Node.js subprocess exited gracefully")
+        except asyncio.TimeoutError:
+            logger.warning("Node.js subprocess did not exit, terminating...")
+            self.process.terminate()
+            try:
+                await asyncio.wait_for(self.process.wait(), timeout=2.0)
+            except asyncio.TimeoutError:
+                logger.error("Node.js subprocess did not terminate, killing...")
+                self.process.kill()
+                await self.process.wait()
+
+        self.process = None
+        self.ipc = None
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the subprocess is running."""
+        return self.process is not None and self.process.returncode is None

wingman/core/safety/__init__.py

@@ -0,0 +1,8 @@
+"""Safety features for Wingman."""
+
+from .cooldown import CooldownManager
+from .quiet_hours import QuietHoursChecker
+from .rate_limiter import RateLimiter
+from .triggers import TriggerDetector
+
+__all__ = ["RateLimiter", "CooldownManager", "QuietHoursChecker", "TriggerDetector"]

wingman/core/safety/cooldown.py

@@ -0,0 +1,63 @@
+"""Per-chat cooldown management."""
+
+import logging
+import time
+
+logger = logging.getLogger(__name__)
+
+
+class CooldownManager:
+    """
+    Manages per-chat cooldowns to prevent rapid-fire responses.
+    """
+
+    def __init__(self, default_cooldown_seconds: int = 60):
+        self.default_cooldown = default_cooldown_seconds
+        self._last_reply: dict[str, float] = {}
+        self._custom_cooldowns: dict[str, int] = {}
+
+    def set_cooldown(self, chat_id: str, seconds: int) -> None:
+        """Set a custom cooldown for a specific chat."""
+        self._custom_cooldowns[chat_id] = seconds
+        logger.debug(f"Set custom cooldown for {chat_id}: {seconds}s")
+
+    def get_cooldown(self, chat_id: str) -> int:
+        """Get the cooldown duration for a chat."""
+        return self._custom_cooldowns.get(chat_id, self.default_cooldown)
+
+    def is_on_cooldown(self, chat_id: str) -> bool:
+        """Check if a chat is currently on cooldown."""
+        last_reply = self._last_reply.get(chat_id)
+        if last_reply is None:
+            return False
+
+        cooldown = self.get_cooldown(chat_id)
+        elapsed = time.time() - last_reply
+        on_cooldown = elapsed < cooldown
+
+        if on_cooldown:
+            remaining = cooldown - elapsed
+            logger.debug(f"Chat {chat_id} on cooldown: {remaining:.1f}s remaining")
+
+        return on_cooldown
+
+    def record_reply(self, chat_id: str) -> None:
+        """Record that a reply was sent to a chat."""
+        self._last_reply[chat_id] = time.time()
+        logger.debug(f"Recorded reply to {chat_id}")
+
+    def get_remaining_cooldown(self, chat_id: str) -> float:
+        """Get seconds remaining in cooldown, or 0 if not on cooldown."""
+        last_reply = self._last_reply.get(chat_id)
+        if last_reply is None:
+            return 0
+
+        cooldown = self.get_cooldown(chat_id)
+        elapsed = time.time() - last_reply
+        return max(0, cooldown - elapsed)
+
+    def clear_cooldown(self, chat_id: str) -> None:
+        """Manually clear cooldown for a chat."""
+        if chat_id in self._last_reply:
+            del self._last_reply[chat_id]
+            logger.debug(f"Cleared cooldown for {chat_id}")

wingman/core/safety/quiet_hours.py

@@ -0,0 +1,75 @@
+"""Quiet hours enforcement."""
+
+import logging
+from datetime import datetime
+from datetime import time as dt_time
+
+logger = logging.getLogger(__name__)
+
+
+class QuietHoursChecker:
+    """
+    Enforces quiet hours during which the bot will not respond.
+    Default: midnight (0:00) to 6:00 AM.
+    """
+
+    def __init__(self, start_hour: int = 0, end_hour: int = 6, enabled: bool = True):
+        self.start_hour = start_hour
+        self.end_hour = end_hour
+        self.enabled = enabled
+
+    def is_quiet_time(self, check_time: datetime | None = None) -> bool:
+        """
+        Check if the given time falls within quiet hours.
+
+        Args:
+            check_time: Time to check (defaults to current time)
+
+        Returns:
+            True if currently in quiet hours
+        """
+        if not self.enabled:
+            return False
+
+        if check_time is None:
+            check_time = datetime.now()
+
+        current_hour = check_time.hour
+
+        # Handle both same-day and overnight ranges
+        if self.start_hour <= self.end_hour:
+            # Same day range (e.g., 9 AM to 5 PM)
+            is_quiet = self.start_hour <= current_hour < self.end_hour
+        else:
+            # Overnight range (e.g., 10 PM to 6 AM)
+            is_quiet = current_hour >= self.start_hour or current_hour < self.end_hour
+
+        if is_quiet:
+            logger.debug(
+                f"Quiet hours active: {self.start_hour}:00 - {self.end_hour}:00, "
+                f"current hour: {current_hour}"
+            )
+
+        return is_quiet
+
+    def get_end_time(self) -> dt_time:
+        """Get the time when quiet hours end."""
+        return dt_time(hour=self.end_hour)
+
+    def set_hours(self, start: int, end: int) -> None:
+        """Update quiet hours range."""
+        if not (0 <= start <= 23 and 0 <= end <= 23):
+            raise ValueError("Hours must be between 0 and 23")
+        self.start_hour = start
+        self.end_hour = end
+        logger.info(f"Quiet hours updated: {start}:00 - {end}:00")
+
+    def disable(self) -> None:
+        """Disable quiet hours."""
+        self.enabled = False
+        logger.info("Quiet hours disabled")
+
+    def enable(self) -> None:
+        """Enable quiet hours."""
+        self.enabled = True
+        logger.info("Quiet hours enabled")

wingman/core/safety/rate_limiter.py

@@ -0,0 +1,58 @@
+"""Global rate limiting for bot replies."""
+
+import logging
+import time
+from collections import deque
+
+logger = logging.getLogger(__name__)
+
+
+class RateLimiter:
+    """
+    Implements a sliding window rate limiter.
+    Tracks replies in a 1-hour window and enforces max replies limit.
+    """
+
+    def __init__(self, max_replies_per_hour: int = 30):
+        self.max_replies = max_replies_per_hour
+        self.window_seconds = 3600  # 1 hour
+        self._timestamps: deque[float] = deque()
+
+    def _cleanup_old_entries(self) -> None:
+        """Remove timestamps older than the window."""
+        cutoff = time.time() - self.window_seconds
+        while self._timestamps and self._timestamps[0] < cutoff:
+            self._timestamps.popleft()
+
+    def can_reply(self) -> bool:
+        """Check if a reply is allowed within rate limits."""
+        self._cleanup_old_entries()
+        allowed = len(self._timestamps) < self.max_replies
+
+        if not allowed:
+            logger.warning(
+                f"Rate limit reached: {len(self._timestamps)}/{self.max_replies} "
+                f"replies in the last hour"
+            )
+
+        return allowed
+
+    def record_reply(self) -> None:
+        """Record that a reply was sent."""
+        self._cleanup_old_entries()
+        self._timestamps.append(time.time())
+        logger.debug(
+            f"Reply recorded: {len(self._timestamps)}/{self.max_replies} " f"in current window"
+        )
+
+    def get_remaining(self) -> int:
+        """Get number of remaining allowed replies."""
+        self._cleanup_old_entries()
+        return max(0, self.max_replies - len(self._timestamps))
+
+    def get_reset_time(self) -> float:
+        """Get seconds until oldest reply expires from window."""
+        if not self._timestamps:
+            return 0
+        oldest = self._timestamps[0]
+        return max(0, (oldest + self.window_seconds) - time.time())