kryten-llm 0.2.2__py3-none-any.whl

kryten_llm/__init__.py

@@ -0,0 +1,22 @@
+"""Kryten LLM Service - Chat moderation and filtering."""
+
+import os
+from pathlib import Path
+
+
+def _read_version() -> str:
+    """Read version from VERSION file."""
+    # Try package root first
+    version_file = Path(__file__).parent / "VERSION"
+    if version_file.exists():
+        return version_file.read_text().strip()
+
+    # Try repository root
+    version_file = Path(__file__).parent.parent / "VERSION"
+    if version_file.exists():
+        return version_file.read_text().strip()
+
+    return "0.0.0"
+
+
+__version__ = _read_version()

kryten_llm/__main__.py

@@ -0,0 +1,148 @@
+"""Main entry point for kryten-llm service."""
+
+import argparse
+import asyncio
+import logging
+import platform
+import signal
+import sys
+from pathlib import Path
+from typing import Callable
+
+from kryten_llm.components import ConfigReloader
+from kryten_llm.config import load_config, validate_config_file
+from kryten_llm.service import LLMService
+
+
+def setup_logging(level: str = "INFO") -> None:
+    """Configure logging for the service."""
+    logging.basicConfig(
+        level=getattr(logging, level.upper()),
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        handlers=[logging.StreamHandler(sys.stdout)],
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Kryten LLM Service - AI-powered chat bot for CyTube"
+    )
+    parser.add_argument(
+        "--config", type=Path, default=Path("config.json"), help="Path to configuration file"
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+        default="INFO",
+        help="Logging level",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true", help="Generate responses but don't send to chat"
+    )
+    parser.add_argument(
+        "--validate-config", action="store_true", help="Validate configuration file and exit"
+    )
+    return parser.parse_args()
+
+
+async def main_async() -> None:
+    """Main async entry point."""
+    args = parse_args()
+    setup_logging(args.log_level)
+
+    logger = logging.getLogger(__name__)
+
+    # Validate config mode
+    if args.validate_config:
+        logger.info(f"Validating configuration: {args.config}")
+        is_valid, errors = validate_config_file(args.config)
+
+        if is_valid:
+            logger.info("✓ Configuration is valid")
+            sys.exit(0)
+        else:
+            logger.error("✗ Configuration validation failed:")
+            for error in errors:
+                logger.error(f"  {error}")
+            sys.exit(1)
+
+    # Load configuration
+    try:
+        config = load_config(args.config)
+    except Exception as e:
+        logger.error(f"Failed to load configuration: {e}")
+        sys.exit(1)
+
+    # Override dry-run from CLI
+    if args.dry_run:
+        config.testing.dry_run = True
+        config.testing.send_to_chat = False
+        logger.info("Dry-run mode enabled via --dry-run flag")
+
+    logger.info("Starting Kryten LLM Service")
+
+    # Initialize service
+    service = LLMService(config=config)
+
+    # Phase 6: Setup config reloader for hot-reload support
+    config_reloader = ConfigReloader(
+        config_path=args.config, on_reload=service.reload_config, current_config=config
+    )
+
+    # Setup signal handlers
+    loop = asyncio.get_event_loop()
+
+    def signal_handler(sig: int) -> None:
+        logger.info(f"Received signal {sig}, shutting down...")
+        asyncio.create_task(service.stop())
+
+    # add_signal_handler is not supported on Windows, use signal.signal instead
+    if platform.system() != "Windows":
+        for sig in (signal.SIGTERM, signal.SIGINT):
+
+            def _make_handler(sig_num: int) -> Callable[[], None]:
+                return lambda: signal_handler(sig_num)
+
+            loop.add_signal_handler(sig, _make_handler(sig))
+
+        # Phase 6: Setup SIGHUP handler for config reload (POSIX only)
+        if hasattr(signal, "SIGHUP"):
+
+            def sighup_handler() -> None:
+                logger.info("Received SIGHUP, reloading configuration...")
+                asyncio.create_task(config_reloader.reload_config())
+
+            loop.add_signal_handler(signal.SIGHUP, sighup_handler)
+            logger.info("SIGHUP handler registered for config hot-reload")
+    else:
+        # Windows: Use signal.signal() for SIGINT/SIGTERM
+        def _signal_handler(sig_num: int, frame) -> None:
+            signal_handler(sig_num)
+
+        signal.signal(signal.SIGINT, _signal_handler)
+        signal.signal(signal.SIGTERM, _signal_handler)
+        logger.info("Signal handlers registered (Windows mode)")
+
+    try:
+        await service.start()
+        await service.wait_for_shutdown()
+    except KeyboardInterrupt:
+        logger.info("Keyboard interrupt received")
+    except Exception as e:
+        logger.error(f"Service error: {e}", exc_info=True)
+        sys.exit(1)
+    finally:
+        await service.stop()
+
+
+def main() -> None:
+    """Main entry point."""
+    try:
+        asyncio.run(main_async())
+    except KeyboardInterrupt:
+        pass
+
+
+if __name__ == "__main__":
+    main()

kryten_llm/components/__init__.py

@@ -0,0 +1,24 @@
+"""Components for kryten-llm message processing pipeline."""
+
+from kryten_llm.components.config_reloader import ConfigReloader
+from kryten_llm.components.context_manager import ContextManager
+from kryten_llm.components.formatter import ResponseFormatter
+from kryten_llm.components.listener import MessageListener
+from kryten_llm.components.llm_manager import LLMManager
+from kryten_llm.components.prompt_builder import PromptBuilder
+from kryten_llm.components.rate_limiter import RateLimitDecision, RateLimiter
+from kryten_llm.components.response_logger import ResponseLogger
+from kryten_llm.components.trigger_engine import TriggerEngine
+
+__all__ = [
+    "ConfigReloader",
+    "ContextManager",
+    "MessageListener",
+    "TriggerEngine",
+    "LLMManager",
+    "PromptBuilder",
+    "ResponseFormatter",
+    "RateLimiter",
+    "RateLimitDecision",
+    "ResponseLogger",
+]

kryten_llm/components/config_reloader.py

@@ -0,0 +1,286 @@
+"""Configuration hot-reload support for kryten-llm.
+
+Phase 6: Implements SIGHUP-based configuration reload without service restart.
+
+Example:
+    >>> reloader = ConfigReloader(config_path, on_reload=service.reload_config)
+    >>> reloader.setup_signal_handler()
+    >>> # Later: send SIGHUP to reload config
+    >>> # kill -HUP <pid>
+"""
+
+import asyncio
+import logging
+import signal
+from pathlib import Path
+from typing import Awaitable, Callable, Optional
+
+from kryten_llm.models.config import LLMConfig
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigReloader:
+    """Handles configuration reload on SIGHUP signal.
+
+    Implements hot-reload for configuration changes without restarting
+    the service. Only safe changes are applied; unsafe changes (like
+    NATS URL or channel changes) are logged as warnings.
+
+    Safe changes that can be hot-reloaded:
+        - Trigger configurations (probabilities, patterns, enabled status)
+        - Rate limits (global, per-user, per-trigger)
+        - Personality settings (prompts, response styles)
+        - Spam detection settings
+        - Logging configuration
+        - LLM provider settings (API keys, models, temperatures)
+
+    Unsafe changes (require restart):
+        - NATS connection settings
+        - Channel configuration
+        - Service name changes
+
+    Attributes:
+        config_path: Path to the configuration file
+        on_reload: Callback function called with new config after reload
+        current_config: Currently active configuration
+    """
+
+    def __init__(
+        self,
+        config_path: Path | str,
+        on_reload: Optional[Callable[["LLMConfig"], Awaitable[None]]] = None,
+        current_config: Optional[LLMConfig] = None,
+    ):
+        """Initialize the config reloader.
+
+        Args:
+            config_path: Path to the configuration JSON file
+            on_reload: Async callback to invoke after successful reload
+            current_config: Current configuration for change detection
+        """
+        self.config_path = Path(config_path) if isinstance(config_path, str) else config_path
+        self.on_reload = on_reload
+        self.current_config = current_config
+        self._reload_lock = asyncio.Lock()
+        self._reload_in_progress = False
+
+        logger.debug(f"ConfigReloader initialized for {self.config_path}")
+
+    def setup_signal_handler(self) -> bool:
+        """Register SIGHUP handler for config reload (POSIX only).
+
+        On Windows, SIGHUP is not available, so this method logs a warning
+        and returns False.
+
+        Returns:
+            True if signal handler was registered, False otherwise
+        """
+        if not hasattr(signal, "SIGHUP"):
+            logger.warning(
+                "SIGHUP not available on this platform (Windows). "
+                "Hot-reload via signal is disabled. Use API endpoint instead."
+            )
+            return False
+
+        # Get the current event loop to schedule async reload
+        try:
+            loop = asyncio.get_running_loop()
+
+            def sighup_handler():
+                """Handle SIGHUP signal by scheduling config reload."""
+                logger.info("Received SIGHUP signal, initiating config reload...")
+                asyncio.create_task(self.reload_config())
+
+            loop.add_signal_handler(signal.SIGHUP, sighup_handler)
+            logger.info(f"SIGHUP handler registered for config reload from {self.config_path}")
+            return True
+
+        except RuntimeError:
+            # No running event loop
+            logger.warning("No running event loop, cannot register SIGHUP handler")
+            return False
+
+    async def reload_config(self) -> dict:
+        """Reload configuration from file.
+
+        Steps:
+        1. Load new configuration file
+        2. Validate the new configuration
+        3. Detect safe vs unsafe changes
+        4. Apply new configuration if valid
+        5. Call on_reload callback with new config
+
+        Returns:
+            Dictionary with:
+                - success (bool): Whether reload succeeded
+                - message (str): Human-readable result
+                - changes (dict): What changed (field: "old -> new")
+                - warnings (list): Unsafe changes that require restart
+                - errors (list): Validation errors if failed
+        """
+        if self._reload_in_progress:
+            return {
+                "success": False,
+                "message": "Reload already in progress",
+                "changes": {},
+                "warnings": [],
+                "errors": ["Another reload operation is in progress"],
+            }
+
+        async with self._reload_lock:
+            self._reload_in_progress = True
+            try:
+                return await self._do_reload()
+            finally:
+                self._reload_in_progress = False
+
+    async def _do_reload(self) -> dict:
+        """Internal reload implementation."""
+        changes: dict[str, str] = {}
+        warnings: list[str] = []
+
+        # Step 1: Load new config file
+        try:
+            logger.info(f"Loading configuration from {self.config_path}")
+            new_config = LLMConfig.load(self.config_path)
+        except FileNotFoundError:
+            error_msg = f"Configuration file not found: {self.config_path}"
+            logger.error(error_msg)
+            return {
+                "success": False,
+                "message": "Configuration file not found",
+                "changes": {},
+                "warnings": [],
+                "errors": [error_msg],
+            }
+        except Exception as e:
+            error_msg = f"Failed to load configuration: {e}"
+            logger.error(error_msg, exc_info=True)
+            return {
+                "success": False,
+                "message": "Configuration validation failed",
+                "changes": {},
+                "warnings": [],
+                "errors": [error_msg],
+            }
+
+        # Step 2: Detect changes
+        if self.current_config:
+            changes, warnings = self._detect_changes(self.current_config, new_config)
+
+        # Step 3: Check for unsafe changes
+        if warnings:
+            logger.warning(f"Unsafe changes detected (require restart): {warnings}")
+
+        # Step 4: Apply new configuration
+        old_config = self.current_config
+        self.current_config = new_config
+
+        # Step 5: Call callback
+        if self.on_reload:
+            try:
+                if asyncio.iscoroutinefunction(self.on_reload):
+                    await self.on_reload(new_config)
+                else:
+                    self.on_reload(new_config)
+            except Exception as e:
+                # Rollback on callback error
+                self.current_config = old_config
+                error_msg = f"Reload callback failed: {e}"
+                logger.error(error_msg, exc_info=True)
+                return {
+                    "success": False,
+                    "message": "Reload callback failed, configuration rolled back",
+                    "changes": {},
+                    "warnings": warnings,
+                    "errors": [error_msg],
+                }
+
+        # Log success
+        if changes:
+            logger.info(f"Configuration reloaded with changes: {changes}")
+        else:
+            logger.info("Configuration reloaded (no changes detected)")
+
+        return {
+            "success": True,
+            "message": "Configuration reloaded successfully",
+            "changes": changes,
+            "warnings": warnings,
+            "errors": [],
+        }
+
+    def _detect_changes(
+        self, old_config: LLMConfig, new_config: LLMConfig
+    ) -> tuple[dict[str, str], list[str]]:
+        """Detect changes between old and new configuration.
+
+        Args:
+            old_config: Previous configuration
+            new_config: New configuration
+
+        Returns:
+            Tuple of (changes dict, warnings list)
+        """
+        changes: dict[str, str] = {}
+        warnings: list[str] = []
+
+        # Check unsafe changes (require restart)
+        if old_config.nats.url != new_config.nats.url:
+            warnings.append(
+                f"nats.url changed ({old_config.nats.url} -> {new_config.nats.url}), "
+                "requires restart to apply"
+            )
+
+        old_channels = old_config.channels
+        new_channels = new_config.channels
+        if old_channels != new_channels:
+            warnings.append("channels configuration changed, requires restart to apply")
+
+        if old_config.service_metadata.service_name != new_config.service_metadata.service_name:
+            warnings.append("service_name changed, requires restart to apply")
+
+        # Check safe changes
+        if old_config.default_provider != new_config.default_provider:
+            changes["default_provider"] = (
+                f"{old_config.default_provider} -> {new_config.default_provider}"
+            )
+
+        # Trigger changes
+        old_trigger_names = {t.name for t in old_config.triggers}
+        new_trigger_names = {t.name for t in new_config.triggers}
+
+        added_triggers = new_trigger_names - old_trigger_names
+        removed_triggers = old_trigger_names - new_trigger_names
+
+        if added_triggers:
+            changes["triggers_added"] = ", ".join(sorted(added_triggers))
+        if removed_triggers:
+            changes["triggers_removed"] = ", ".join(sorted(removed_triggers))
+
+        # Rate limit changes
+        if old_config.rate_limits != new_config.rate_limits:
+            changes["rate_limits"] = "updated"
+
+        # Spam detection changes
+        if old_config.spam_detection != new_config.spam_detection:
+            changes["spam_detection"] = "updated"
+
+        # Personality changes
+        if old_config.personality != new_config.personality:
+            changes["personality"] = "updated"
+
+        # LLM provider changes
+        old_providers = set(old_config.llm_providers.keys())
+        new_providers = set(new_config.llm_providers.keys())
+
+        if old_providers != new_providers:
+            added = new_providers - old_providers
+            removed = old_providers - new_providers
+            if added:
+                changes["llm_providers_added"] = ", ".join(sorted(added))
+            if removed:
+                changes["llm_providers_removed"] = ", ".join(sorted(removed))
+
+        return changes, warnings

kryten_llm/components/context_manager.py

@@ -0,0 +1,186 @@
+"""Context manager for video and chat history tracking.
+
+Phase 3: Implements REQ-008 through REQ-013 for context-aware responses.
+"""
+
+import logging
+from collections import deque
+from datetime import datetime
+from typing import Any, Dict, Optional
+
+from kryten import ChangeMediaEvent  # type: ignore[import-untyped]
+
+from kryten_llm.models.config import LLMConfig
+from kryten_llm.models.phase3 import ChatMessage, VideoMetadata
+
+logger = logging.getLogger(__name__)
+
+
+class ContextManager:
+    """Manages video and chat context for LLM prompts.
+
+    Phase 3 component that:
+    - Subscribes to CyTube video change events (REQ-008)
+    - Maintains current video state (REQ-009)
+    - Maintains rolling chat history buffer (REQ-010)
+    - Provides context dict for prompt building (REQ-011)
+    - Handles edge cases and privacy constraints (REQ-012, REQ-013)
+    """
+
+    def __init__(self, config: LLMConfig):
+        """Initialize with configuration.
+
+        Args:
+            config: LLM configuration with context settings
+        """
+        self.config = config
+        self.current_video: Optional[VideoMetadata] = None
+
+        # REQ-010: Rolling buffer with configurable size
+        self.chat_history: deque[ChatMessage] = deque(maxlen=config.context.chat_history_size)
+
+        logger.info(
+            f"ContextManager initialized: chat_history_size={config.context.chat_history_size}, "
+            f"include_video={config.context.include_video_context}, "
+            f"include_chat={config.context.include_chat_history}"
+        )
+
+    async def start(self, kryten_client) -> None:
+        """Start subscribing to context events.
+
+        Args:
+            kryten_client: KrytenClient instance for subscriptions
+        """
+        # REQ-008: Subscribe to video change events
+        # Use first configured channel
+        channel_config = self.config.channels[0]
+        channel = (
+            channel_config.channel
+            if hasattr(channel_config, "channel")
+            else channel_config.get("channel", "unknown")
+        )
+        subject = f"kryten.events.cytube.{channel}.changemedia"
+
+        await kryten_client.subscribe(subject, self._handle_video_change)
+        logger.info(f"ContextManager subscribed to: {subject}")
+
+    async def _handle_video_change(self, event: ChangeMediaEvent) -> None:
+        """Handle video change event from CyTube.
+
+        REQ-009: Update current video state atomically.
+        REQ-012: Handle edge cases (long titles, missing fields, special chars).
+
+        Args:
+            event: ChangeMediaEvent from kryten-py with video metadata
+        """
+        try:
+            # Extract title from event
+            title = str(event.title or "Unknown")
+
+            # REQ-012: Truncate long titles
+            if len(title) > self.config.context.max_video_title_length:
+                title = title[: self.config.context.max_video_title_length]
+                logger.debug(
+                    f"Truncated video title to {self.config.context.max_video_title_length} chars"
+                )
+
+            # REQ-009: Atomic update
+            self.current_video = VideoMetadata(
+                title=title,
+                duration=event.duration or 0,
+                type=event.media_type or "unknown",
+                queued_by="system",  # ChangeMediaEvent doesn't have queued_by field
+                timestamp=datetime.now(),
+            )
+
+            logger.info(
+                f"Video changed: '{self.current_video.title}' "
+                f"({self.current_video.type}, {self.current_video.duration}s) "
+                f"queued by {self.current_video.queued_by}"
+            )
+
+        except Exception as e:
+            # REQ-033: Context errors should not block responses
+            logger.warning(f"Error handling video change: {e}", exc_info=True)
+
+    def add_chat_message(self, username: str, message: str) -> None:
+        """Add a message to chat history buffer.
+
+        REQ-010: Maintain rolling buffer excluding bot's own messages.
+        REQ-013: Only store configured number of messages.
+
+        Args:
+            username: User who sent the message
+            message: Message content
+        """
+        # REQ-010: Don't store bot's own messages
+        if username == self.config.personality.character_name:
+            return
+
+        # REQ-013: Deque automatically maintains size limit
+        self.chat_history.append(
+            ChatMessage(username=username, message=message, timestamp=datetime.now())
+        )
+
+        logger.debug(
+            f"Added message to history: {username}: {message[:50]}... "
+            f"(buffer size: {len(self.chat_history)})"
+        )
+
+    def get_context(self) -> Dict[str, Any]:
+        """Get current context for prompt building.
+
+        REQ-011: Provide context dict with current_video and recent_messages.
+        REQ-012: Handle None state for no video playing.
+
+        Returns:
+            Context dictionary with video and chat history
+        """
+        context: Dict[str, Any] = {}
+
+        # Include video context if enabled and available
+        if self.config.context.include_video_context and self.current_video:
+            context["current_video"] = {
+                "title": self.current_video.title,
+                "duration": self.current_video.duration,
+                "type": self.current_video.type,
+                "queued_by": self.current_video.queued_by,
+            }
+        else:
+            # REQ-012: No video playing
+            context["current_video"] = None
+
+        # Include chat history if enabled
+        if self.config.context.include_chat_history:
+            # REQ-016: Limit to most recent N messages for prompt
+            max_messages = self.config.context.max_chat_history_in_prompt
+            recent = list(self.chat_history)[-max_messages:] if self.chat_history else []
+
+            context["recent_messages"] = [
+                {"username": msg.username, "message": msg.message} for msg in recent
+            ]
+        else:
+            context["recent_messages"] = []
+
+        return context
+
+    def clear_chat_history(self) -> None:
+        """Clear chat history buffer.
+
+        REQ-013: Support clearing on service restart or for privacy.
+        """
+        self.chat_history.clear()
+        logger.info("Chat history buffer cleared")
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get context manager statistics.
+
+        Returns:
+            Statistics dict with buffer sizes and current state
+        """
+        return {
+            "chat_history_size": len(self.chat_history),
+            "chat_history_max": self.chat_history.maxlen,
+            "has_video": self.current_video is not None,
+            "current_video_title": self.current_video.title if self.current_video else None,
+        }