wingman-ai 1.0.0__py3-none-any.whl

wingman/core/llm/client.py

@@ -0,0 +1,77 @@
+"""OpenAI API client wrapper."""
+
+import logging
+
+from openai import AsyncOpenAI
+
+logger = logging.getLogger(__name__)
+
+
+class LLMClient:
+    """Async OpenAI API client for generating responses."""
+
+    def __init__(
+        self, api_key: str, model: str = "gpt-4o", max_tokens: int = 150, temperature: float = 0.8
+    ):
+        self.client = AsyncOpenAI(api_key=api_key)
+        self.model = model
+        self.max_tokens = max_tokens
+        self.temperature = temperature
+
+    async def generate_response(
+        self,
+        system_prompt: str,
+        messages: list[dict[str, str]],
+        language_instruction: str | None = None,
+    ) -> str | None:
+        """
+        Generate a response using the OpenAI API.
+
+        Args:
+            system_prompt: The personality/system prompt
+            messages: Conversation history
+            language_instruction: Optional language-specific instruction
+
+        Returns:
+            Generated response text or None on error
+        """
+        try:
+            # Build full system prompt
+            full_system = system_prompt
+            if language_instruction:
+                full_system += f"\n\n{language_instruction}"
+
+            # Prepare messages for API
+            api_messages = [{"role": "system", "content": full_system}, *messages]
+
+            logger.debug(f"Sending request to {self.model} with {len(messages)} context messages")
+
+            response = await self.client.chat.completions.create(
+                model=self.model,
+                messages=api_messages,
+                max_tokens=self.max_tokens,
+                temperature=self.temperature,
+            )
+
+            if response.choices and response.choices[0].message.content:
+                text = response.choices[0].message.content.strip()
+                logger.debug(f"Generated response: {text[:50]}...")
+                return text
+
+            logger.warning("Empty response from API")
+            return None
+
+        except Exception as e:
+            logger.error(f"API error: {e}")
+            return None
+
+    async def health_check(self) -> bool:
+        """Check if the API is accessible."""
+        try:
+            response = await self.client.chat.completions.create(
+                model=self.model, messages=[{"role": "user", "content": "Hi"}], max_tokens=5
+            )
+            return bool(response.choices)
+        except Exception as e:
+            logger.error(f"Health check failed: {e}")
+            return False

wingman/core/memory/__init__.py

@@ -0,0 +1,6 @@
+"""Memory system for conversation storage."""
+
+from .context import ContextBuilder
+from .models import Message, MessageStore
+
+__all__ = ["MessageStore", "Message", "ContextBuilder"]

wingman/core/memory/context.py

@@ -0,0 +1,109 @@
+"""Context building for LLM conversations."""
+
+import logging
+from typing import Any
+
+from .models import MessageStore
+
+logger = logging.getLogger(__name__)
+
+
+class ContextBuilder:
+    """Builds conversation context for LLM from stored messages."""
+
+    def __init__(
+        self, message_store: MessageStore, window_size: int = 30, bot_name: str = "Maximus"
+    ):
+        self.store = message_store
+        self.window_size = window_size
+        self.bot_name = bot_name
+
+    def build_context(self, chat_id: str, current_message: dict[str, Any]) -> list[dict[str, str]]:
+        """
+        Build conversation context for the LLM.
+
+        Args:
+            chat_id: Chat to build context for
+            current_message: The current incoming message
+
+        Returns:
+            List of message dicts for OpenAI API format
+        """
+        # Get recent messages from storage
+        messages = self.store.get_recent_messages(chat_id, limit=self.window_size)
+
+        # Convert to OpenAI message format
+        context = []
+        for msg in messages:
+            if msg.is_self:
+                context.append({"role": "assistant", "content": msg.text})
+            else:
+                # Format user messages with sender name for context
+                sender = msg.sender_name or "User"
+                content = f"[{sender}]: {msg.text}"
+                context.append({"role": "user", "content": content})
+
+        # Add current message
+        sender_name = current_message.get("senderName") or "User"
+        context.append(
+            {"role": "user", "content": f"[{sender_name}]: {current_message.get('text', '')}"}
+        )
+
+        logger.debug(f"Built context with {len(context)} messages for {chat_id}")
+        return context
+
+    def detect_language(self, text: str) -> str:
+        """
+        Detect the primary language of the text.
+        Simple heuristic for Hindi/Hinglish/English detection.
+
+        Returns:
+            'hindi', 'hinglish', or 'english'
+        """
+        # Devanagari Unicode range
+        hindi_chars = sum(1 for c in text if "\u0900" <= c <= "\u097f")
+
+        if hindi_chars > len(text) * 0.3:
+            return "hindi"
+
+        # Check for common Hinglish words/patterns
+        hinglish_markers = [
+            "hai",
+            "hain",
+            "kya",
+            "nahi",
+            "aur",
+            "bhi",
+            "kaise",
+            "kaisa",
+            "accha",
+            "theek",
+            "yaar",
+            "bhai",
+            "arre",
+            "haan",
+            "matlab",
+            "wala",
+            "kar",
+            "karo",
+            "karna",
+            "raha",
+            "rahi",
+        ]
+
+        text_lower = text.lower()
+        hinglish_count = sum(1 for word in hinglish_markers if word in text_lower)
+
+        if hinglish_count >= 2:
+            return "hinglish"
+
+        return "english"
+
+    def get_language_instruction(self, language: str) -> str:
+        """Get language-specific instruction for the LLM."""
+        instructions = {
+            "hindi": "Respond in Hindi (Devanagari script). Match the casual tone.",
+            "hinglish": "Respond in Hinglish (Hindi words in Roman script mixed with English). Keep it natural and casual.",
+            "english": "Respond in English. Keep it casual and friendly.",
+        }
+        return instructions.get(language, instructions["english"])

wingman/core/memory/models.py

@@ -0,0 +1,213 @@
+"""SQLite database models and operations."""
+
+import logging
+import sqlite3
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Message:
+    """Represents a stored message."""
+
+    id: int | None
+    chat_id: str
+    sender_id: str
+    sender_name: str | None
+    text: str
+    timestamp: float
+    is_self: bool = False
+    platform: str = "whatsapp"
+
+
+class MessageStore:
+    """SQLite-based message storage."""
+
+    def __init__(self, db_path: Path):
+        self.db_path = db_path
+        self._ensure_db_exists()
+
+    def _ensure_db_exists(self) -> None:
+        """Create database and tables if they don't exist."""
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+
+        with self._get_connection() as conn:
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS messages (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    chat_id TEXT NOT NULL,
+                    sender_id TEXT NOT NULL,
+                    sender_name TEXT,
+                    text TEXT NOT NULL,
+                    timestamp REAL NOT NULL,
+                    is_self BOOLEAN DEFAULT 0,
+                    platform TEXT DEFAULT 'whatsapp'
+                )
+            """)
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_messages_chat
+                ON messages(chat_id, timestamp DESC)
+            """)
+            # Add platform column if it doesn't exist (migration for existing DBs)
+            try:
+                conn.execute("SELECT platform FROM messages LIMIT 1")
+            except Exception:
+                conn.execute("ALTER TABLE messages ADD COLUMN platform TEXT DEFAULT 'whatsapp'")
+                logger.info("Added platform column to messages table")
+            conn.commit()
+            logger.info(f"Database initialized: {self.db_path}")
+
+    @contextmanager
+    def _get_connection(self):
+        """Get a database connection context manager."""
+        conn = sqlite3.connect(str(self.db_path))
+        conn.row_factory = sqlite3.Row
+        try:
+            yield conn
+        finally:
+            conn.close()
+
+    def store_message(self, message: Message) -> int:
+        """
+        Store a message in the database.
+
+        Returns:
+            The ID of the inserted message
+        """
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                INSERT INTO messages (chat_id, sender_id, sender_name, text, timestamp, is_self, platform)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    message.chat_id,
+                    message.sender_id,
+                    message.sender_name,
+                    message.text,
+                    message.timestamp,
+                    1 if message.is_self else 0,
+                    message.platform,
+                ),
+            )
+            conn.commit()
+            msg_id = cursor.lastrowid
+            logger.debug(
+                f"Stored message {msg_id} in chat {message.chat_id} (platform={message.platform})"
+            )
+            return msg_id
+
+    def get_recent_messages(self, chat_id: str, limit: int = 30) -> list[Message]:
+        """
+        Get recent messages from a chat.
+
+        Args:
+            chat_id: The chat to get messages from
+            limit: Maximum number of messages to return
+
+        Returns:
+            List of messages, oldest first
+        """
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                SELECT id, chat_id, sender_id, sender_name, text, timestamp, is_self, platform
+                FROM messages
+                WHERE chat_id = ?
+                ORDER BY timestamp DESC
+                LIMIT ?
+                """,
+                (chat_id, limit),
+            )
+            rows = cursor.fetchall()
+
+        # Convert to Message objects and reverse for chronological order
+        messages = [
+            Message(
+                id=row["id"],
+                chat_id=row["chat_id"],
+                sender_id=row["sender_id"],
+                sender_name=row["sender_name"],
+                text=row["text"],
+                timestamp=row["timestamp"],
+                is_self=bool(row["is_self"]),
+                platform=row["platform"] or "whatsapp",
+            )
+            for row in reversed(rows)
+        ]
+
+        logger.debug(f"Retrieved {len(messages)} messages from {chat_id}")
+        return messages
+
+    def get_last_sender(self, chat_id: str) -> str | None:
+        """
+        Get the sender ID of the last message in a chat.
+
+        Returns:
+            Sender ID or None if chat is empty
+        """
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                SELECT sender_id, is_self
+                FROM messages
+                WHERE chat_id = ?
+                ORDER BY timestamp DESC
+                LIMIT 1
+                """,
+                (chat_id,),
+            )
+            row = cursor.fetchone()
+
+        if row:
+            return "self" if row["is_self"] else row["sender_id"]
+        return None
+
+    def was_last_message_from_self(self, chat_id: str) -> bool:
+        """Check if the last message in a chat was from the bot."""
+        with self._get_connection() as conn:
+            cursor = conn.execute(
+                """
+                SELECT is_self
+                FROM messages
+                WHERE chat_id = ?
+                ORDER BY timestamp DESC
+                LIMIT 1
+                """,
+                (chat_id,),
+            )
+            row = cursor.fetchone()
+
+        return bool(row and row["is_self"])
+
+    def get_message_count(self, chat_id: str | None = None) -> int:
+        """Get total message count, optionally filtered by chat."""
+        with self._get_connection() as conn:
+            if chat_id:
+                cursor = conn.execute("SELECT COUNT(*) FROM messages WHERE chat_id = ?", (chat_id,))
+            else:
+                cursor = conn.execute("SELECT COUNT(*) FROM messages")
+            return cursor.fetchone()[0]
+
+    def cleanup_old_messages(self, days: int = 30) -> int:
+        """
+        Delete messages older than specified days.
+
+        Returns:
+            Number of deleted messages
+        """
+        import time
+
+        cutoff = time.time() - (days * 24 * 60 * 60)
+
+        with self._get_connection() as conn:
+            cursor = conn.execute("DELETE FROM messages WHERE timestamp < ?", (cutoff,))
+            conn.commit()
+            deleted = cursor.rowcount
+
+        if deleted > 0:
+            logger.info(f"Cleaned up {deleted} old messages")
+        return deleted

wingman/core/message_processor.py

@@ -0,0 +1,277 @@
+"""Core message processing logic."""
+
+import logging
+import time
+from collections.abc import Callable, Coroutine
+from typing import Any
+
+from wingman.config.personality import RoleBasedPromptBuilder, get_personality_prompt
+from wingman.config.registry import ContactProfile, ContactRegistry, GroupRegistry
+
+from .llm.client import LLMClient
+from .memory.context import ContextBuilder
+from .memory.models import Message, MessageStore
+from .policy import PolicyEvaluator
+from .safety import CooldownManager, QuietHoursChecker, RateLimiter, TriggerDetector
+
+logger = logging.getLogger(__name__)
+
+# Type alias for message sender callback
+MessageSender = Callable[[str, str, str], Coroutine[Any, Any, bool]]
+
+
+class MessageProcessor:
+    """
+    Core orchestrator for processing incoming messages.
+    Implements the full message handling flow with safety checks.
+
+    Transport-agnostic: uses a sender callback instead of direct IPC.
+    """
+
+    def __init__(
+        self,
+        store: MessageStore,
+        llm: LLMClient,
+        contact_registry: ContactRegistry,
+        group_registry: GroupRegistry,
+        policy_evaluator: PolicyEvaluator,
+        bot_name: str = "Maximus",
+        max_replies_per_hour: int = 30,
+        default_cooldown: int = 60,
+        quiet_start: int = 0,
+        quiet_end: int = 6,
+        context_window: int = 30,
+    ):
+        self.store = store
+        self.llm = llm
+        self.bot_name = bot_name
+
+        # Config-driven registries
+        self.contact_registry = contact_registry
+        self.group_registry = group_registry
+        self.policy_evaluator = policy_evaluator
+
+        # Initialize safety components
+        self.rate_limiter = RateLimiter(max_replies_per_hour)
+        self.cooldown = CooldownManager(default_cooldown)
+        self.quiet_hours = QuietHoursChecker(quiet_start, quiet_end)
+        self.triggers = TriggerDetector(bot_name)  # Keep for fallback
+
+        # Context builder
+        self.context_builder = ContextBuilder(store, context_window, bot_name)
+
+        # Role-based prompt builder
+        self.prompt_builder = RoleBasedPromptBuilder(bot_name)
+
+        # Track our own user ID per platform
+        self.self_ids: dict[str, str] = {}
+
+        # Message sender callback: (platform, chat_id, text) -> success
+        self._send_message: MessageSender | None = None
+
+    def set_self_id(self, user_id: str, platform: str = "whatsapp") -> None:
+        """Set our own user ID for self-message detection."""
+        self.self_ids[platform] = user_id
+        logger.info(f"Self ID set for {platform}: {user_id}")
+
+    def set_sender(self, sender: MessageSender) -> None:
+        """Set the message sender callback."""
+        self._send_message = sender
+
+    async def process_message(self, data: dict[str, Any]) -> None:
+        """
+        Process an incoming message through the full pipeline.
+
+        Flow:
+        1. Store message in SQLite
+        2. Check safety rules
+        3. Check for triggers
+        4. Generate and send response
+        """
+        chat_id = data.get("chatId", "")
+        sender_id = data.get("senderId", "")
+        sender_name = data.get("senderName")
+        text = data.get("text", "")
+        timestamp = data.get("timestamp", time.time())
+        is_group = data.get("isGroup", False)
+        is_self = data.get("isSelf", False)
+        platform = data.get("platform", "whatsapp")
+
+        logger.info(
+            f"Processing message: platform={platform}, chat={chat_id[:20]}..., "
+            f"sender={sender_name or sender_id[:15]}..., "
+            f"text={text[:50]}..."
+        )
+
+        # 1. Always store the message
+        message = Message(
+            id=None,
+            chat_id=chat_id,
+            sender_id=sender_id,
+            sender_name=sender_name,
+            text=text,
+            timestamp=timestamp,
+            is_self=is_self,
+            platform=platform,
+        )
+        self.store.store_message(message)
+
+        # Don't process our own messages
+        if is_self:
+            logger.debug("Skipping self message")
+            return
+
+        # 2. Resolve contact and group profiles
+        contact = self.contact_registry.resolve(sender_id)
+        group = self.group_registry.resolve(chat_id) if is_group else None
+
+        logger.info(
+            f"Resolved: contact={contact.name} (role={contact.role.value}, tone={contact.tone.value})"
+            + (f", group={group.name} (category={group.category.value})" if group else "")
+        )
+
+        # 3. Apply per-contact cooldown override if configured
+        if contact.cooldown_override is not None:
+            self.cooldown.set_cooldown(chat_id, contact.cooldown_override)
+
+        # 4. Check safety rules
+        skip_reason = self._check_safety_rules(chat_id)
+        if skip_reason:
+            logger.info(f"Skipping message: {skip_reason}")
+            return
+
+        # 5. Evaluate policy rules
+        is_reply_to_bot = self._is_reply_to_bot(data, platform)
+
+        context = self.policy_evaluator.create_context(
+            chat_id=chat_id,
+            sender_id=sender_id,
+            text=text,
+            is_group=is_group,
+            contact=contact,
+            group=group,
+            is_reply_to_bot=is_reply_to_bot,
+            platform=platform,
+        )
+
+        decision = self.policy_evaluator.evaluate(context)
+
+        if not decision.should_respond:
+            logger.debug(f"Policy decision: no response (reason: {decision.reason})")
+            return
+
+        logger.info(
+            f"Responding to message (policy: {decision.reason}, action: {decision.action.value})"
+        )
+
+        # 6. Generate response with role-based prompt
+        response = await self._generate_response(chat_id, data, contact)
+
+        if not response:
+            logger.warning("Failed to generate response")
+            return
+
+        # 7. Send response via transport
+        if self._send_message:
+            success = await self._send_message(platform, chat_id, response)
+            if not success:
+                logger.error(f"Failed to send message via {platform}")
+                return
+        else:
+            logger.error("No message sender configured")
+            return
+
+        # 8. Update safety trackers
+        self.rate_limiter.record_reply()
+        self.cooldown.record_reply(chat_id)
+
+        # 9. Store our response
+        self_id = self.self_ids.get(platform, "self")
+        bot_message = Message(
+            id=None,
+            chat_id=chat_id,
+            sender_id=self_id,
+            sender_name=self.bot_name,
+            text=response,
+            timestamp=time.time(),
+            is_self=True,
+            platform=platform,
+        )
+        self.store.store_message(bot_message)
+
+        logger.info(f"Response sent via {platform}: {response[:50]}...")
+
+    def _check_safety_rules(self, chat_id: str) -> str | None:
+        """
+        Check all safety rules.
+
+        Returns:
+            Reason string if should skip, None if OK to proceed
+        """
+        # Check quiet hours
+        if self.quiet_hours.is_quiet_time():
+            return "quiet_hours"
+
+        # Check rate limit
+        if not self.rate_limiter.can_reply():
+            return "rate_limit"
+
+        # Check per-chat cooldown
+        if self.cooldown.is_on_cooldown(chat_id):
+            return "cooldown"
+
+        # Check double-reply (don't reply if last message was ours)
+        if self.store.was_last_message_from_self(chat_id):
+            return "double_reply"
+
+        return None
+
+    def _is_reply_to_bot(self, data: dict[str, Any], platform: str = "whatsapp") -> bool:
+        """Check if the message is a reply to one of our messages."""
+        quoted = data.get("quotedMessage")
+        if not quoted:
+            return False
+
+        quoted_sender = quoted.get("senderId", "")
+
+        # Check if quoted message is from us (platform-specific self ID)
+        self_id = self.self_ids.get(platform)
+        if self_id and quoted_sender == self_id:
+            return True
+
+        # Also check for our name in the quoted sender
+        if self.bot_name.lower() in quoted_sender.lower():
+            return True
+
+        return False
+
+    async def _generate_response(
+        self, chat_id: str, message_data: dict[str, Any], contact: ContactProfile | None = None
+    ) -> str | None:
+        """Generate an LLM response for the message."""
+        # Build context
+        context = self.context_builder.build_context(chat_id, message_data)
+
+        # Detect language
+        text = message_data.get("text", "")
+        language = self.context_builder.detect_language(text)
+        language_instruction = self.context_builder.get_language_instruction(language)
+
+        logger.debug(f"Detected language: {language}")
+
+        # Build role-based system prompt
+        if contact:
+            system_prompt = self.prompt_builder.build_prompt(
+                tone=contact.tone,
+                contact_name=contact.name if contact.name != "Unknown" else None,
+            )
+            logger.debug(f"Using tone: {contact.tone.value} for {contact.name}")
+        else:
+            system_prompt = get_personality_prompt(self.bot_name)
+
+        # Generate response
+        response = await self.llm.generate_response(
+            system_prompt=system_prompt, messages=context, language_instruction=language_instruction
+        )
+
+        return response

wingman/core/policy/__init__.py

@@ -0,0 +1,5 @@
+"""Policy evaluation module."""
+
+from .evaluator import MessageContext, PolicyDecision, PolicyEvaluator
+
+__all__ = ["PolicyEvaluator", "PolicyDecision", "MessageContext"]