wingman-ai 1.0.0__py3-none-any.whl

wingman/config/settings.py

@@ -0,0 +1,294 @@
+"""Configuration settings loaded from environment or YAML."""
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+from dotenv import load_dotenv
+
+from .paths import WingmanPaths
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Settings:
+    """Application settings loaded from YAML config or environment variables."""
+
+    # OpenAI
+    openai_api_key: str = ""
+    openai_model: str = "gpt-4o"
+
+    # Bot identity
+    bot_name: str = "Maximus"
+
+    # Safety limits
+    max_replies_per_hour: int = 30
+    default_cooldown_seconds: int = 60
+    quiet_hours_start: int = 0  # Midnight
+    quiet_hours_end: int = 6  # 6 AM
+    quiet_hours_enabled: bool = True
+
+    # LLM settings
+    context_window_size: int = 30
+    max_response_tokens: int = 150
+    temperature: float = 0.8
+
+    # iMessage settings
+    imessage_enabled: bool = False
+    imessage_poll_interval: float = 2.0
+    imessage_max_replies_per_hour: int = 15
+    imessage_cooldown: int = 120
+
+    # Paths (set after loading)
+    node_dir: Path = field(default_factory=Path)
+    data_dir: Path = field(default_factory=Path)
+    log_dir: Path = field(default_factory=Path)
+    db_path: Path = field(default_factory=Path)
+    auth_state_dir: Path = field(default_factory=Path)
+
+    # Config file paths
+    contacts_config: Path = field(default_factory=Path)
+    groups_config: Path = field(default_factory=Path)
+    policies_config: Path = field(default_factory=Path)
+
+    # Source mode
+    _is_cli_mode: bool = False
+
+    @classmethod
+    def load(cls, env_path: Path | None = None, paths: WingmanPaths | None = None) -> "Settings":
+        """
+        Load settings with fallback chain:
+        1. YAML config file (if paths provided and config exists)
+        2. Environment variables
+        3. Defaults
+        """
+        # Determine paths
+        if paths is None:
+            # Try CLI mode first (XDG paths)
+            paths = WingmanPaths()
+            if paths.config_exists():
+                return cls._load_from_yaml(paths)
+
+            # Fall back to legacy mode (project root)
+            project_root = Path(__file__).parent.parent.parent.parent
+            if (project_root / ".env").exists() or (project_root / "node_listener").exists():
+                return cls._load_from_env(project_root, env_path)
+
+            # No config found, use XDG paths with env vars
+            return cls._load_from_env_with_paths(paths, env_path)
+        else:
+            if paths.config_exists():
+                return cls._load_from_yaml(paths)
+            else:
+                return cls._load_from_env_with_paths(paths, env_path)
+
+    @classmethod
+    def _load_from_yaml(cls, paths: WingmanPaths) -> "Settings":
+        """Load settings from YAML config file."""
+        config_file = paths.config_file
+        logger.info(f"Loading settings from {config_file}")
+
+        with open(config_file) as f:
+            config = yaml.safe_load(f) or {}
+
+        # Parse config sections
+        bot_config = config.get("bot", {})
+        openai_config = config.get("openai", {})
+        safety_config = config.get("safety", {})
+        quiet_hours_config = safety_config.get("quiet_hours", {})
+        imessage_config = config.get("imessage", {})
+
+        # Get API key from config or environment
+        api_key = openai_config.get("api_key") or os.getenv("OPENAI_API_KEY", "")
+
+        settings = cls(
+            # OpenAI
+            openai_api_key=api_key,
+            openai_model=openai_config.get("model", "gpt-4o"),
+            # Bot identity
+            bot_name=bot_config.get("name", "Maximus"),
+            # Safety limits
+            max_replies_per_hour=safety_config.get("max_replies_per_hour", 30),
+            default_cooldown_seconds=safety_config.get("cooldown_seconds", 60),
+            quiet_hours_start=quiet_hours_config.get("start", 0),
+            quiet_hours_end=quiet_hours_config.get("end", 6),
+            quiet_hours_enabled=quiet_hours_config.get("enabled", True),
+            # LLM settings
+            context_window_size=openai_config.get("context_window_size", 30),
+            max_response_tokens=openai_config.get("max_response_tokens", 150),
+            temperature=openai_config.get("temperature", 0.8),
+            # iMessage settings
+            imessage_enabled=imessage_config.get("enabled", False),
+            imessage_poll_interval=imessage_config.get("poll_interval", 2.0),
+            imessage_max_replies_per_hour=imessage_config.get("max_replies_per_hour", 15),
+            imessage_cooldown=imessage_config.get("cooldown", 120),
+            # Paths from WingmanPaths
+            node_dir=paths.node_dir,
+            data_dir=paths.data_dir,
+            log_dir=paths.log_dir,
+            db_path=paths.db_path,
+            auth_state_dir=paths.auth_state_dir,
+            contacts_config=paths.contacts_config,
+            groups_config=paths.groups_config,
+            policies_config=paths.policies_config,
+            _is_cli_mode=True,
+        )
+
+        # Ensure directories exist
+        paths.ensure_directories()
+
+        logger.info(f"Settings loaded: bot_name={settings.bot_name}, model={settings.openai_model}")
+        return settings
+
+    @classmethod
+    def _load_from_env(cls, project_root: Path, env_path: Path | None = None) -> "Settings":
+        """Load settings from environment variables (legacy mode)."""
+        # Load .env file
+        if env_path:
+            load_dotenv(env_path)
+        else:
+            load_dotenv(project_root / ".env")
+
+        settings = cls(
+            # OpenAI
+            openai_api_key=os.getenv("OPENAI_API_KEY", ""),
+            openai_model=os.getenv("OPENAI_MODEL", "gpt-4o"),
+            # Bot identity
+            bot_name=os.getenv("BOT_NAME", "Maximus"),
+            # Safety limits
+            max_replies_per_hour=int(os.getenv("MAX_REPLIES_PER_HOUR", "30")),
+            default_cooldown_seconds=int(os.getenv("DEFAULT_COOLDOWN_SECONDS", "60")),
+            quiet_hours_start=int(os.getenv("QUIET_HOURS_START", "0")),
+            quiet_hours_end=int(os.getenv("QUIET_HOURS_END", "6")),
+            # LLM settings
+            context_window_size=int(os.getenv("CONTEXT_WINDOW_SIZE", "30")),
+            max_response_tokens=int(os.getenv("MAX_RESPONSE_TOKENS", "150")),
+            temperature=float(os.getenv("TEMPERATURE", "0.8")),
+            # iMessage settings
+            imessage_enabled=os.getenv("IMESSAGE_ENABLED", "false").lower() == "true",
+            imessage_poll_interval=float(os.getenv("IMESSAGE_POLL_INTERVAL", "2.0")),
+            imessage_max_replies_per_hour=int(os.getenv("IMESSAGE_MAX_REPLIES_PER_HOUR", "15")),
+            imessage_cooldown=int(os.getenv("IMESSAGE_COOLDOWN", "120")),
+            # Paths (legacy project structure)
+            node_dir=project_root / "node_listener",
+            data_dir=project_root / "data",
+            log_dir=project_root / "logs",
+            db_path=project_root / "data" / "conversations.db",
+            auth_state_dir=project_root / "auth_state",
+            contacts_config=project_root / "config" / "contacts.yaml",
+            groups_config=project_root / "config" / "groups.yaml",
+            policies_config=project_root / "config" / "policies.yaml",
+            _is_cli_mode=False,
+        )
+
+        # Validate required settings
+        if not settings.openai_api_key:
+            logger.warning("OPENAI_API_KEY not set - LLM features will fail")
+
+        # Ensure directories exist
+        settings.data_dir.mkdir(parents=True, exist_ok=True)
+        settings.log_dir.mkdir(parents=True, exist_ok=True)
+
+        logger.info(f"Settings loaded: bot_name={settings.bot_name}, model={settings.openai_model}")
+        return settings
+
+    @classmethod
+    def _load_from_env_with_paths(
+        cls, paths: WingmanPaths, env_path: Path | None = None
+    ) -> "Settings":
+        """Load settings from environment variables with XDG paths."""
+        if env_path:
+            load_dotenv(env_path)
+
+        settings = cls(
+            # OpenAI
+            openai_api_key=os.getenv("OPENAI_API_KEY", ""),
+            openai_model=os.getenv("OPENAI_MODEL", "gpt-4o"),
+            # Bot identity
+            bot_name=os.getenv("BOT_NAME", "Maximus"),
+            # Safety limits
+            max_replies_per_hour=int(os.getenv("MAX_REPLIES_PER_HOUR", "30")),
+            default_cooldown_seconds=int(os.getenv("DEFAULT_COOLDOWN_SECONDS", "60")),
+            quiet_hours_start=int(os.getenv("QUIET_HOURS_START", "0")),
+            quiet_hours_end=int(os.getenv("QUIET_HOURS_END", "6")),
+            # LLM settings
+            context_window_size=int(os.getenv("CONTEXT_WINDOW_SIZE", "30")),
+            max_response_tokens=int(os.getenv("MAX_RESPONSE_TOKENS", "150")),
+            temperature=float(os.getenv("TEMPERATURE", "0.8")),
+            # iMessage settings
+            imessage_enabled=os.getenv("IMESSAGE_ENABLED", "false").lower() == "true",
+            imessage_poll_interval=float(os.getenv("IMESSAGE_POLL_INTERVAL", "2.0")),
+            imessage_max_replies_per_hour=int(os.getenv("IMESSAGE_MAX_REPLIES_PER_HOUR", "15")),
+            imessage_cooldown=int(os.getenv("IMESSAGE_COOLDOWN", "120")),
+            # Paths from WingmanPaths
+            node_dir=paths.node_dir,
+            data_dir=paths.data_dir,
+            log_dir=paths.log_dir,
+            db_path=paths.db_path,
+            auth_state_dir=paths.auth_state_dir,
+            contacts_config=paths.contacts_config,
+            groups_config=paths.groups_config,
+            policies_config=paths.policies_config,
+            _is_cli_mode=True,
+        )
+
+        paths.ensure_directories()
+        return settings
+
+    def validate(self) -> list[str]:
+        """Validate settings and return list of errors."""
+        errors = []
+
+        if not self.openai_api_key:
+            errors.append("OPENAI_API_KEY is required")
+
+        if not self.node_dir.exists():
+            errors.append(f"Node listener directory not found: {self.node_dir}")
+
+        if not (self.node_dir / "dist" / "index.js").exists():
+            errors.append(
+                f"Node listener not built. Run 'wingman init' or manually build: "
+                f"cd {self.node_dir} && npm install && npm run build"
+            )
+
+        if not 0 <= self.quiet_hours_start <= 23:
+            errors.append("quiet_hours_start must be 0-23")
+
+        if not 0 <= self.quiet_hours_end <= 23:
+            errors.append("quiet_hours_end must be 0-23")
+
+        return errors
+
+    def to_yaml_dict(self) -> dict[str, Any]:
+        """Convert settings to a dictionary suitable for YAML serialization."""
+        return {
+            "bot": {
+                "name": self.bot_name,
+            },
+            "openai": {
+                "api_key": self.openai_api_key,
+                "model": self.openai_model,
+                "context_window_size": self.context_window_size,
+                "max_response_tokens": self.max_response_tokens,
+                "temperature": self.temperature,
+            },
+            "safety": {
+                "max_replies_per_hour": self.max_replies_per_hour,
+                "cooldown_seconds": self.default_cooldown_seconds,
+                "quiet_hours": {
+                    "enabled": self.quiet_hours_enabled,
+                    "start": self.quiet_hours_start,
+                    "end": self.quiet_hours_end,
+                },
+            },
+            "imessage": {
+                "enabled": self.imessage_enabled,
+                "poll_interval": self.imessage_poll_interval,
+                "max_replies_per_hour": self.imessage_max_replies_per_hour,
+                "cooldown": self.imessage_cooldown,
+            },
+        }

wingman/core/__init__.py

@@ -0,0 +1,16 @@
+"""Core orchestration module for Wingman."""
+
+from .agent import MultiTransportAgent, WhatsAppAgent
+from .ipc_handler import IPCCommand, IPCHandler, IPCMessage
+from .message_processor import MessageProcessor
+from .process_manager import NodeProcessManager
+
+__all__ = [
+    "MultiTransportAgent",
+    "WhatsAppAgent",
+    "NodeProcessManager",
+    "IPCHandler",
+    "IPCMessage",
+    "IPCCommand",
+    "MessageProcessor",
+]

wingman/core/agent.py

@@ -0,0 +1,257 @@
+"""Main agent entry point for the Python orchestrator."""
+
+import asyncio
+import logging
+import signal
+import sys
+from pathlib import Path
+
+from wingman.config.registry import ContactRegistry, GroupRegistry
+from wingman.config.settings import Settings
+
+from .llm.client import LLMClient
+from .memory.models import MessageStore
+from .message_processor import MessageProcessor
+from .policy import PolicyEvaluator
+from .transports import (
+    BaseTransport,
+    IMessageTransport,
+    MessageEvent,
+    Platform,
+    WhatsAppTransport,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def setup_logging(log_dir: Path) -> None:
+    """Set up logging to file and console."""
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_file = log_dir / "agent.log"
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[logging.FileHandler(log_file), logging.StreamHandler(sys.stderr)],
+    )
+
+    # Reduce noise from some libraries
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("openai").setLevel(logging.WARNING)
+
+
+class MultiTransportAgent:
+    """
+    Multi-transport agent that manages WhatsApp and iMessage.
+
+    Shares MessageProcessor, registries, and LLM across all transports.
+    """
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.store = MessageStore(settings.db_path)
+        self.llm = LLMClient(
+            api_key=settings.openai_api_key,
+            model=settings.openai_model,
+            max_tokens=settings.max_response_tokens,
+            temperature=settings.temperature,
+        )
+
+        # Initialize config-driven registries
+        self.contact_registry = ContactRegistry(settings.contacts_config)
+        self.group_registry = GroupRegistry(settings.groups_config)
+        self.policy_evaluator = PolicyEvaluator(
+            settings.policies_config, bot_name=settings.bot_name
+        )
+
+        # Initialize message processor (transport-agnostic)
+        self.processor = MessageProcessor(
+            store=self.store,
+            llm=self.llm,
+            contact_registry=self.contact_registry,
+            group_registry=self.group_registry,
+            policy_evaluator=self.policy_evaluator,
+            bot_name=settings.bot_name,
+            max_replies_per_hour=settings.max_replies_per_hour,
+            default_cooldown=settings.default_cooldown_seconds,
+            quiet_start=settings.quiet_hours_start,
+            quiet_end=settings.quiet_hours_end,
+            context_window=settings.context_window_size,
+        )
+
+        # Set up message sender callback
+        self.processor.set_sender(self._send_message)
+
+        # Transports
+        self.transports: dict[Platform, BaseTransport] = {}
+        self._transport_tasks: list[asyncio.Task] = []
+        self._shutdown_event = asyncio.Event()
+
+    async def _send_message(self, platform: str, chat_id: str, text: str) -> bool:
+        """Route message to appropriate transport."""
+        try:
+            plat = Platform(platform)
+            transport = self.transports.get(plat)
+            if transport:
+                return await transport.send_message(chat_id, text)
+            else:
+                logger.error(f"No transport for platform: {platform}")
+                return False
+        except ValueError:
+            logger.error(f"Unknown platform: {platform}")
+            return False
+
+    async def _on_message(self, event: MessageEvent) -> None:
+        """Handle incoming message from any transport."""
+        # Convert MessageEvent to dict format expected by processor
+        data = {
+            "chatId": event.chat_id,
+            "senderId": event.sender_id,
+            "senderName": event.sender_name,
+            "text": event.text,
+            "timestamp": event.timestamp,
+            "isGroup": event.is_group,
+            "isSelf": event.is_self,
+            "platform": event.platform.value,
+            "quotedMessage": event.quoted_message,
+        }
+        await self.processor.process_message(data)
+
+    async def start(self) -> None:
+        """Start all configured transports."""
+        logger.info("Starting Multi-Transport Agent...")
+        logger.info(f"Bot name: {self.settings.bot_name}")
+        logger.info(f"Model: {self.settings.openai_model}")
+
+        # Initialize WhatsApp transport
+        whatsapp = WhatsAppTransport(
+            self.settings.node_dir, auth_state_dir=self.settings.auth_state_dir
+        )
+        whatsapp.set_message_handler(self._on_message)
+        whatsapp.set_connected_handler(self._on_whatsapp_connected)
+        self.transports[Platform.WHATSAPP] = whatsapp
+
+        # Initialize iMessage transport if enabled
+        if self.settings.imessage_enabled:
+            imessage = IMessageTransport(poll_interval=self.settings.imessage_poll_interval)
+
+            # Check if iMessage is available on this system
+            if await imessage.check_availability():
+                imessage.set_message_handler(self._on_message)
+                self.transports[Platform.IMESSAGE] = imessage
+                logger.info("iMessage transport initialized")
+            else:
+                logger.warning(
+                    "iMessage not available. Ensure Full Disk Access is granted "
+                    "and Messages.app is configured."
+                )
+
+        # Start all transports
+        for platform, transport in self.transports.items():
+            logger.info(f"Starting {platform.value} transport...")
+            task = asyncio.create_task(
+                self._run_transport(platform, transport), name=f"transport_{platform.value}"
+            )
+            self._transport_tasks.append(task)
+
+        logger.info(f"Agent started with {len(self.transports)} transport(s)")
+
+        # Wait for shutdown or all tasks to complete
+        try:
+            await asyncio.gather(*self._transport_tasks)
+        except asyncio.CancelledError:
+            logger.info("Transport tasks cancelled")
+
+    async def _run_transport(self, platform: Platform, transport: BaseTransport) -> None:
+        """Run a single transport, handling errors."""
+        try:
+            await transport.start()
+        except Exception as e:
+            logger.error(f"{platform.value} transport error: {e}")
+            raise
+
+    async def _on_whatsapp_connected(self, user_id: str) -> None:
+        """Handle WhatsApp connection."""
+        self.processor.set_self_id(user_id, "whatsapp")
+
+    async def stop(self) -> None:
+        """Stop all transports gracefully."""
+        logger.info("Stopping agent...")
+
+        # Stop all transports
+        for platform, transport in self.transports.items():
+            logger.info(f"Stopping {platform.value} transport...")
+            try:
+                await transport.stop()
+            except Exception as e:
+                logger.error(f"Error stopping {platform.value}: {e}")
+
+        # Cancel transport tasks
+        for task in self._transport_tasks:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+
+        logger.info("Agent stopped.")
+
+    def request_shutdown(self) -> None:
+        """Request graceful shutdown."""
+        self._shutdown_event.set()
+
+
+# Keep WhatsAppAgent for backward compatibility
+class WhatsAppAgent(MultiTransportAgent):
+    """
+    Legacy WhatsApp-only agent.
+
+    Deprecated: Use MultiTransportAgent instead.
+    """
+
+    def __init__(self, settings: Settings):
+        # Disable iMessage for backward compatibility
+        settings.imessage_enabled = False
+        super().__init__(settings)
+
+
+async def run_agent(settings: Settings | None = None) -> None:
+    """Run the agent with provided settings."""
+    # Load settings if not provided
+    if settings is None:
+        settings = Settings.load()
+
+    # Set up logging
+    setup_logging(settings.log_dir)
+
+    # Validate settings
+    errors = settings.validate()
+    if errors:
+        for error in errors:
+            logger.error(f"Configuration error: {error}")
+        sys.exit(1)
+
+    # Create agent
+    agent = MultiTransportAgent(settings)
+
+    # Set up signal handlers
+    loop = asyncio.get_event_loop()
+
+    def signal_handler():
+        logger.info("Shutdown signal received")
+        agent.request_shutdown()
+        # Cancel all tasks
+        for task in asyncio.all_tasks(loop):
+            if task is not asyncio.current_task():
+                task.cancel()
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, signal_handler)
+
+    # Run agent
+    try:
+        await agent.start()
+    except asyncio.CancelledError:
+        pass
+    finally:
+        await agent.stop()

wingman/core/ipc_handler.py

@@ -0,0 +1,124 @@
+"""IPC Handler for communication with Node.js subprocess."""
+
+import asyncio
+import json
+import logging
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+NULL_CHAR = "\0"
+
+
+@dataclass
+class IPCMessage:
+    """Message received from Node.js."""
+
+    type: str
+    data: dict | None = None
+
+
+@dataclass
+class IPCCommand:
+    """Command to send to Node.js."""
+
+    action: str
+    payload: dict | None = None
+
+
+class IPCHandler:
+    """Handles JSON IPC communication with Node.js subprocess."""
+
+    def __init__(self, stdin: asyncio.StreamWriter, stdout: asyncio.StreamReader):
+        self.stdin = stdin
+        self.stdout = stdout
+        self._buffer = ""
+        self._handlers: dict[str, Callable[[dict], Coroutine]] = {}
+        self._running = False
+
+    def register_handler(self, message_type: str, handler: Callable[[dict], Coroutine]) -> None:
+        """Register a handler for a specific message type."""
+        self._handlers[message_type] = handler
+        logger.debug(f"Registered handler for: {message_type}")
+
+    async def send_command(self, command: IPCCommand) -> None:
+        """Send a command to Node.js."""
+        try:
+            message = {
+                "action": command.action,
+                **({"payload": command.payload} if command.payload else {}),
+            }
+            json_str = json.dumps(message) + NULL_CHAR
+            self.stdin.write(json_str.encode("utf-8"))
+            await self.stdin.drain()
+            logger.debug(f"Sent command: {command.action}")
+        except Exception as e:
+            logger.error(f"Failed to send command: {e}")
+            raise
+
+    async def send_message(self, jid: str, text: str, message_id: str | None = None) -> None:
+        """Convenience method to send a WhatsApp message."""
+        await self.send_command(
+            IPCCommand(
+                action="send_message",
+                payload={
+                    "jid": jid,
+                    "text": text,
+                    **({"messageId": message_id} if message_id else {}),
+                },
+            )
+        )
+
+    async def _read_messages(self) -> None:
+        """Read and process messages from Node.js stdout."""
+        while self._running:
+            try:
+                chunk = await self.stdout.read(4096)
+                if not chunk:
+                    logger.warning("Node.js stdout closed")
+                    break
+
+                self._buffer += chunk.decode("utf-8")
+
+                # Process all complete messages
+                while NULL_CHAR in self._buffer:
+                    null_idx = self._buffer.index(NULL_CHAR)
+                    json_str = self._buffer[:null_idx]
+                    self._buffer = self._buffer[null_idx + 1 :]
+
+                    if json_str.strip():
+                        await self._process_message(json_str)
+
+            except asyncio.CancelledError:
+                logger.info("Message reader cancelled")
+                break
+            except Exception as e:
+                logger.error(f"Error reading from stdout: {e}")
+                await asyncio.sleep(0.1)
+
+    async def _process_message(self, json_str: str) -> None:
+        """Parse and dispatch a single message."""
+        try:
+            data = json.loads(json_str)
+            message = IPCMessage(type=data.get("type", "unknown"), data=data.get("data"))
+
+            handler = self._handlers.get(message.type)
+            if handler:
+                await handler(message.data or {})
+            else:
+                logger.debug(f"No handler for message type: {message.type}")
+
+        except json.JSONDecodeError as e:
+            logger.error(f"Failed to parse JSON: {e}")
+        except Exception as e:
+            logger.error(f"Error processing message: {e}")
+
+    async def start(self) -> None:
+        """Start the IPC message loop."""
+        self._running = True
+        await self._read_messages()
+
+    def stop(self) -> None:
+        """Stop the IPC message loop."""
+        self._running = False

wingman/core/llm/__init__.py

@@ -0,0 +1,5 @@
+"""LLM integration for Wingman."""
+
+from .client import LLMClient
+
+__all__ = ["LLMClient"]