kryten-llm 0.2.2__py3-none-any.whl

kryten_llm/components/heartbeat.py

@@ -0,0 +1,122 @@
+"""Heartbeat publishing for Phase 5.
+
+Publishes periodic health status to NATS.
+"""
+
+import asyncio
+import json
+import logging
+from typing import Optional
+
+from nats.aio.client import Client as NATSClient
+
+from kryten_llm.components.health_monitor import ServiceHealthMonitor
+from kryten_llm.models.config import ServiceMetadata
+
+
+class HeartbeatPublisher:
+    """Publish periodic heartbeat messages.
+
+    Publishes service health status to kryten.service.heartbeat.llm subject
+    at configured interval.
+
+    Phase 5 Implementation (REQ-002).
+    """
+
+    def __init__(
+        self,
+        config: ServiceMetadata,
+        health_monitor: ServiceHealthMonitor,
+        nats_client: NATSClient,
+        logger: logging.Logger,
+        start_time: float,
+    ):
+        """Initialize heartbeat publisher.
+
+        Args:
+            config: Service metadata configuration
+            health_monitor: Health monitoring component
+            nats_client: NATS client for publishing
+            logger: Logger instance
+            start_time: Service start timestamp
+        """
+        self.config = config
+        self.health_monitor = health_monitor
+        self.nats = nats_client
+        self.logger = logger
+        self.start_time = start_time
+
+        self._heartbeat_task: Optional[asyncio.Task] = None
+        self._running = False
+
+    async def start(self) -> None:
+        """Start heartbeat publishing loop."""
+        if not self.config.enable_heartbeats:
+            self.logger.info("Heartbeats disabled in configuration")
+            return
+
+        if self._running:
+            self.logger.warning("Heartbeat publisher already running")
+            return
+
+        self._running = True
+        self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
+        self.logger.info(
+            f"Heartbeat publisher started (interval: {self.config.heartbeat_interval_seconds}s)"
+        )
+
+    async def stop(self) -> None:
+        """Stop heartbeat publishing loop."""
+        if not self._running:
+            return
+
+        self._running = False
+
+        if self._heartbeat_task:
+            self._heartbeat_task.cancel()
+            try:
+                await self._heartbeat_task
+            except asyncio.CancelledError:
+                pass
+
+        self.logger.info("Heartbeat publisher stopped")
+
+    async def _heartbeat_loop(self) -> None:
+        """Main heartbeat publishing loop."""
+        while self._running:
+            try:
+                await self._publish_heartbeat()
+                await asyncio.sleep(self.config.heartbeat_interval_seconds)
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                self.logger.error(f"Error in heartbeat loop: {e}", exc_info=True)
+                await asyncio.sleep(self.config.heartbeat_interval_seconds)
+
+    async def _publish_heartbeat(self) -> None:
+        """Publish single heartbeat message.
+
+        Implements REQ-002 heartbeat publishing.
+        """
+        try:
+            # Calculate uptime
+            import time
+
+            uptime = time.time() - self.start_time
+
+            # Build payload from health monitor
+            payload = self.health_monitor.get_heartbeat_payload(uptime)
+
+            # Publish to NATS
+            subject = f"kryten.service.heartbeat.{self.config.service_name}"
+            data = json.dumps(payload).encode("utf-8")
+
+            await self.nats.publish(subject, data)
+
+            self.logger.debug(
+                f"Published heartbeat: {payload['health']} "
+                f"({payload['status']['messages_processed']} messages processed)"
+            )
+
+        except Exception as e:
+            self.logger.error(f"Failed to publish heartbeat: {e}", exc_info=True)

kryten_llm/components/listener.py

@@ -0,0 +1,79 @@
+"""Message listener and filter for chat messages."""
+
+import logging
+from typing import Optional
+
+from kryten_llm.models.config import LLMConfig
+
+logger = logging.getLogger(__name__)
+
+
+class MessageListener:
+    """Filters and validates incoming chat messages.
+
+    Implements REQ-001, REQ-002, REQ-003 from Phase 1 specification:
+    - Filter spam messages (commands starting with !, /, .)
+    - Filter system users ([server], [bot], [system])
+    - Validate required fields (username, msg, time)
+    """
+
+    # System usernames to ignore
+    SYSTEM_USERS = {"[server]", "[bot]", "[system]"}
+
+    # Command prefixes to filter
+    COMMAND_PREFIXES = ("!", "/", ".")
+
+    def __init__(self, config: LLMConfig):
+        """Initialize with configuration.
+
+        Args:
+            config: LLM configuration containing filtering rules
+        """
+        self.config = config
+        logger.info("MessageListener initialized")
+
+    async def filter_message(self, data: dict) -> Optional[dict]:
+        """Filter and validate a chatMsg event.
+
+        Implements filtering logic per specification:
+        1. Check required fields exist
+        2. Filter spam/command messages
+        3. Filter system users
+
+        Args:
+            data: Raw chatMsg event data from NATS
+
+        Returns:
+            Filtered message dict or None if message should be ignored
+
+        Message dict structure:
+            {
+                "username": str,      # Username of sender
+                "msg": str,          # Message text
+                "time": int,         # Timestamp
+                "meta": dict,        # Metadata (rank, etc.)
+            }
+        """
+        # REQ-003: Validate required fields
+        required_fields = ["username", "msg", "time"]
+        for field in required_fields:
+            if field not in data:
+                logger.debug(f"Invalid message format: missing required field '{field}'")
+                return None
+
+        username = data["username"]
+        msg = data["msg"]
+
+        # REQ-002: Filter system users
+        if username in self.SYSTEM_USERS:
+            logger.debug(f"Filtered system user message from: {username}")
+            return None
+
+        # REQ-001: Filter spam messages (commands)
+        if msg.startswith(self.COMMAND_PREFIXES):
+            logger.debug(f"Filtered command message: {msg[:20]}...")
+            return None
+
+        # Message passed all filters
+        logger.debug(f"Accepted message from {username}: {msg[:50]}...")
+        return data

kryten_llm/components/llm_manager.py

@@ -0,0 +1,349 @@
+"""Enhanced LLM API manager with multi-provider support and fallback.
+
+Phase 3: Implements REQ-001 through REQ-007 and REQ-025 through REQ-032 for
+resilient multi-provider LLM interactions with automatic fallback.
+"""
+
+import asyncio
+import logging
+import os
+import time
+from typing import Dict, List, Optional
+
+import aiohttp
+
+from kryten_llm.models.config import LLMConfig, LLMProvider
+from kryten_llm.models.phase3 import LLMRequest, LLMResponse
+
+logger = logging.getLogger(__name__)
+
+
+class LLMManager:
+    """Enhanced LLM manager with multi-provider support.
+
+    Phase 3 enhancements:
+    - Support multiple provider configurations (REQ-001)
+    - Attempt providers in priority order with fallback (REQ-002)
+    - Implement exponential backoff for retries (REQ-003)
+    - Support provider selection by trigger (REQ-004)
+    - Handle provider-specific errors gracefully (REQ-005)
+    - Log provider selection and fallback decisions (REQ-006)
+    - Support different provider types (REQ-007)
+    """
+
+    def __init__(self, config: LLMConfig):
+        """Initialize with provider configurations.
+
+        Args:
+            config: LLM configuration containing provider settings
+        """
+        self.config = config
+        self.providers: Dict[str, LLMProvider] = {}
+        self._load_providers()
+
+        logger.info(
+            f"LLMManager initialized with {len(self.providers)} providers: "
+            f"{list(self.providers.keys())}"
+        )
+
+    def _load_providers(self) -> None:
+        """Load and validate provider configurations.
+
+        REQ-001: Support multiple provider configurations.
+        SEC-001: Resolve environment variable references in API keys.
+        """
+        for provider_name, provider_config in self.config.llm_providers.items():
+            # SEC-001: Resolve API key environment variables
+            api_key = self._resolve_api_key(provider_config.api_key)
+
+            # Store resolved provider
+            provider_config.api_key = api_key
+            self.providers[provider_name] = provider_config
+
+            logger.debug(
+                f"Loaded provider: {provider_name} "
+                f"(type={provider_config.type}, model={provider_config.model}, "
+                f"priority={provider_config.priority})"
+            )
+
+    def _resolve_api_key(self, api_key: str) -> str:
+        """Resolve environment variable references in API key.
+
+        SEC-001: Support ${ENV_VAR} syntax for secure key storage.
+
+        Args:
+            api_key: API key string (may contain ${ENV_VAR})
+
+        Returns:
+            Resolved API key value
+        """
+        if api_key.startswith("${") and api_key.endswith("}"):
+            env_var = api_key[2:-1]
+            resolved = os.getenv(env_var, "")
+            if not resolved:
+                logger.warning(f"Environment variable {env_var} not set, using empty string")
+            return resolved
+        return api_key
+
+    def _get_provider_priority(self, preferred_provider: Optional[str]) -> List[str]:
+        """Get ordered list of providers to try.
+
+        REQ-002: Attempt providers in priority order.
+        REQ-004: Support preferred provider for triggers.
+
+        Args:
+            preferred_provider: Preferred provider name (from trigger)
+
+        Returns:
+            Ordered list of provider names to attempt
+        """
+        # REQ-004: If preferred provider specified and exists, try it first
+        if preferred_provider and preferred_provider in self.providers:
+            # Preferred first, then others by priority
+            others = [
+                name
+                for name, p in sorted(self.providers.items(), key=lambda x: x[1].priority)
+                if name != preferred_provider
+            ]
+            return [preferred_provider] + others
+
+        # REQ-002: Use configured priority order or sort by priority
+        if self.config.default_provider_priority:
+            # Use configured order, filter to existing providers
+            priority_order = [
+                name for name in self.config.default_provider_priority if name in self.providers
+            ]
+            # Add any providers not in configured order
+            remaining = [name for name in self.providers if name not in priority_order]
+            return priority_order + sorted(remaining, key=lambda x: self.providers[x].priority)
+        else:
+            # Sort all providers by priority field
+            return [name for name, _ in sorted(self.providers.items(), key=lambda x: x[1].priority)]
+
+    async def generate_response(self, request: LLMRequest) -> Optional[LLMResponse]:
+        """Generate response with automatic provider fallback.
+
+        REQ-002: Attempt providers in priority order until success.
+        REQ-006: Log provider selection and fallback decisions.
+        REQ-032: Graceful degradation when all providers fail.
+
+        Args:
+            request: LLM request with prompts and optional preferred provider
+
+        Returns:
+            LLM response or None if all providers failed
+        """
+        provider_order = self._get_provider_priority(request.preferred_provider)
+        errors = []
+
+        # REQ-006: Log provider selection
+        logger.info(f"Attempting {len(provider_order)} providers in order: {provider_order}")
+
+        for provider_name in provider_order:
+            if provider_name not in self.providers:
+                logger.warning(f"Provider {provider_name} not found, skipping")
+                continue
+
+            provider = self.providers[provider_name]
+
+            try:
+                # REQ-003: Try provider with retries and exponential backoff
+                response = await self._try_provider(provider, provider_name, request)
+
+                # REQ-006: Log successful provider
+                logger.info(
+                    f"LLM response generated using provider: {provider_name} "
+                    f"(model={response.model_used}, time={response.response_time:.2f}s, "
+                    f"tokens={response.tokens_used})"
+                )
+
+                return response
+
+            except Exception as e:
+                # REQ-031: Log provider failure with context
+                error_msg = f"Provider {provider_name} failed: {type(e).__name__}: {str(e)}"
+                logger.warning(error_msg)
+                errors.append(error_msg)
+
+                # Continue to next provider (fallback)
+                continue
+
+        # REQ-032: All providers failed - log comprehensive error
+        logger.error(
+            f"All {len(provider_order)} LLM providers failed. " f"Errors: {'; '.join(errors)}"
+        )
+        return None
+
+    async def _try_provider(
+        self, provider: LLMProvider, provider_name: str, request: LLMRequest
+    ) -> LLMResponse:
+        """Attempt to get response from a single provider with retries.
+
+        REQ-003: Implement exponential backoff for retries.
+        REQ-005: Handle provider-specific errors gracefully.
+
+        Args:
+            provider: Provider configuration
+            provider_name: Provider identifier
+            request: LLM request
+
+        Returns:
+            LLM response
+
+        Raises:
+            Exception: If all retry attempts fail
+        """
+        retry_delay = self.config.retry_strategy.initial_delay
+        last_exception = None
+
+        for attempt in range(provider.max_retries + 1):  # +1 for initial attempt
+            try:
+                # Attempt the request
+                response = await self._call_provider(provider, provider_name, request)
+
+                # Success
+                if attempt > 0:
+                    logger.info(f"Provider {provider_name} succeeded on attempt {attempt + 1}")
+                return response
+
+            except (aiohttp.ClientError, asyncio.TimeoutError) as e:
+                # REQ-005: Handle transient errors with retry
+                last_exception = e
+
+                if attempt < provider.max_retries:
+                    # REQ-003: Exponential backoff
+                    logger.debug(
+                        f"Provider {provider_name} attempt {attempt + 1} failed: {e}. "
+                        f"Retrying in {retry_delay:.1f}s..."
+                    )
+
+                    await asyncio.sleep(retry_delay)
+
+                    # Calculate next delay with exponential backoff
+                    retry_delay = min(
+                        retry_delay * self.config.retry_strategy.multiplier,
+                        self.config.retry_strategy.max_delay,
+                    )
+                else:
+                    # Max retries exceeded
+                    logger.warning(f"Provider {provider_name} failed after {attempt + 1} attempts")
+                    raise
+
+            except Exception as e:
+                # REQ-005: Non-retryable errors (auth, invalid config, etc.)
+                logger.error(
+                    f"Provider {provider_name} non-retryable error: "
+                    f"{type(e).__name__}: {str(e)}"
+                )
+                raise
+
+        # Should not reach here, but handle edge case
+        if last_exception:
+            raise last_exception
+        raise RuntimeError(f"Provider {provider_name} failed with unknown error")
+
+    async def _call_provider(
+        self, provider: LLMProvider, provider_name: str, request: LLMRequest
+    ) -> LLMResponse:
+        """Call LLM provider API.
+
+        REQ-007: Support different provider types.
+
+        Args:
+            provider: Provider configuration
+            provider_name: Provider identifier
+            request: LLM request
+
+        Returns:
+            LLM response
+
+        Raises:
+            Exception: On API errors
+        """
+        start_time = time.time()
+
+        # REQ-007: Route to provider-specific implementation
+        if provider.type in ("openai", "openai_compatible", "openrouter"):
+            response = await self._call_openai_provider(provider, provider_name, request)
+        else:
+            raise ValueError(f"Unsupported provider type: {provider.type}")
+
+        response_time = time.time() - start_time
+        response.response_time = response_time
+
+        return response
+
+    async def _call_openai_provider(
+        self, provider: LLMProvider, provider_name: str, request: LLMRequest
+    ) -> LLMResponse:
+        """Call OpenAI-compatible provider API.
+
+        REQ-007: Support OpenAI-compatible providers.
+        REQ-024: Support provider-specific headers.
+        SEC-001: Never log API keys.
+
+        Args:
+            provider: Provider configuration
+            provider_name: Provider identifier
+            request: LLM request
+
+        Returns:
+            LLM response
+
+        Raises:
+            aiohttp.ClientError: On HTTP errors
+            asyncio.TimeoutError: On timeout
+        """
+        # Build request
+        url = f"{provider.base_url.rstrip('/')}/chat/completions"
+
+        # REQ-024: Support custom headers
+        headers = {
+            "Authorization": f"Bearer {provider.api_key}",
+            "Content-Type": "application/json",
+        }
+        if provider.custom_headers:
+            headers.update(provider.custom_headers)
+
+        payload = {
+            "model": provider.model,
+            "messages": [
+                {"role": "system", "content": request.system_prompt},
+                {"role": "user", "content": request.user_prompt},
+            ],
+            "temperature": request.temperature,
+            "max_tokens": request.max_tokens,
+        }
+
+        # SEC-001: Log without exposing API key
+        logger.debug(
+            f"Calling {provider_name}: model={provider.model}, "
+            f"temp={request.temperature}, max_tokens={request.max_tokens}"
+        )
+
+        # Make API call
+        timeout = aiohttp.ClientTimeout(total=provider.timeout_seconds)
+
+        async with aiohttp.ClientSession(timeout=timeout) as session:
+            async with session.post(url, headers=headers, json=payload) as response:
+                # REQ-005: Handle HTTP errors
+                if response.status != 200:
+                    error_text = await response.text()
+                    # SEC-001: Don't log full error (may contain keys)
+                    raise aiohttp.ClientError(f"HTTP {response.status}: {error_text[:200]}")
+
+                data = await response.json()
+
+                # Validate response format
+                if "choices" not in data or len(data["choices"]) == 0:
+                    raise ValueError("Invalid API response: no choices returned")
+
+                content = data["choices"][0]["message"]["content"]
+                tokens = data.get("usage", {}).get("total_tokens")
+
+                return LLMResponse(
+                    content=content,
+                    provider_used=provider_name,
+                    model_used=provider.model,
+                    tokens_used=tokens,
+                )

kryten_llm/components/prompt_builder.py

@@ -0,0 +1,148 @@
+"""Prompt builder for LLM requests."""
+
+import logging
+
+from kryten_llm.models.config import LLMConfig
+
+logger = logging.getLogger(__name__)
+
+
+class PromptBuilder:
+    """Constructs prompts for LLM generation.
+
+    Implements REQ-011, REQ-012, REQ-013 from Phase 1 specification:
+    - Construct system prompts from PersonalityConfig
+    - Include character name, description, traits, and response style
+    - Construct user prompts with username and cleaned message
+
+    Phase 1: Basic prompt construction
+    Phase 2: Add trigger context injection (REQ-034)
+    Phase 3: Add video and chat history context
+    """
+
+    def __init__(self, config: LLMConfig):
+        """Initialize with configuration.
+
+        Args:
+            config: LLM configuration containing personality settings
+        """
+        self.config = config
+        self.personality = config.personality
+        logger.info(f"PromptBuilder initialized for character: {self.personality.character_name}")
+
+    def build_system_prompt(self) -> str:
+        """Build system prompt from personality configuration.
+
+        Implements REQ-011, REQ-012: Include all personality attributes
+        in a structured system prompt.
+
+        Returns:
+            System prompt text
+        """
+        # Format personality traits and expertise as comma-separated lists
+        traits = ", ".join(self.personality.personality_traits)
+        expertise = ", ".join(self.personality.expertise)
+
+        # Build system prompt following specification template
+        prompt = f"""You are {self.personality.character_name}, \
+{self.personality.character_description}.
+
+Personality traits: {traits}
+Areas of expertise: {expertise}
+
+Response style: {self.personality.response_style}
+
+Important rules:
+- Keep responses under 240 characters
+- Stay in character
+- Be natural and conversational
+- Do not use markdown formatting
+- Do not start responses with your character name"""
+
+        logger.debug(f"Built system prompt ({len(prompt)} chars)")
+        return prompt
+
+    def build_user_prompt(
+        self,
+        username: str,
+        message: str,
+        trigger_context: str | None = None,
+        context: dict | None = None,
+    ) -> str:
+        """Build user prompt with context injection.
+
+        Implements REQ-013 (Phase 1): Simple user prompt with username and message.
+        Implements REQ-034 (Phase 2): Optionally inject trigger context.
+        Phase 3 enhancements (REQ-014 through REQ-018):
+        - Accept context dict from ContextManager
+        - Inject current video when available
+        - Inject recent chat history when available
+        - Manage prompt length to fit context window
+
+        Args:
+            username: Username of message sender
+            message: Cleaned message text (bot name already removed)
+            trigger_context: Optional context from trigger (Phase 2)
+            context: Optional context dict from ContextManager (Phase 3)
+
+        Returns:
+            User prompt text with injected context
+        """
+        # Build prompt parts in priority order
+        parts = [f"{username} says: {message}"]
+
+        # REQ-015: Add current video context if available
+        if context and context.get("current_video"):
+            video = context["current_video"]
+            parts.append(
+                f"\n\nCurrently playing: {video['title']} " f"(queued by {video['queued_by']})"
+            )
+
+        # REQ-016: Add chat history context if available
+        if context and context.get("recent_messages"):
+            messages = context["recent_messages"]
+            if messages:
+                # Limit to last 5-10 messages to avoid token bloat
+                recent = messages[-5:]
+                history_lines = [f"- {msg['username']}: {msg['message']}" for msg in recent]
+                parts.append("\n\nRecent conversation:\n" + "\n".join(history_lines))
+
+        # REQ-017: Add trigger context if provided (highest priority)
+        if trigger_context:
+            parts.append(f"\n\nContext: {trigger_context}")
+
+        prompt = "".join(parts)
+
+        # REQ-018: Manage prompt length
+        max_chars = self.config.context.context_window_chars
+        if len(prompt) > max_chars:
+            # Truncate chat history first to preserve essential context
+            prompt = self._truncate_prompt(prompt, max_chars, trigger_context)
+
+        logger.debug(
+            f"Built user prompt for {username} ({len(prompt)} chars)"
+            + (" with video context" if context and context.get("current_video") else "")
+            + (" with chat history" if context and context.get("recent_messages") else "")
+            + (" with trigger context" if trigger_context else "")
+        )
+        return prompt
+
+    def _truncate_prompt(self, prompt: str, max_chars: int, trigger_context: str | None) -> str:
+        """Truncate prompt intelligently to fit context window.
+
+        REQ-018: Priority order - keep trigger context > video > chat history.
+        Simple truncation for Phase 3, can be enhanced later.
+
+        Args:
+            prompt: Full prompt text
+            max_chars: Maximum allowed characters
+            trigger_context: Trigger context to preserve
+
+        Returns:
+            Truncated prompt
+        """
+        logger.warning(f"Prompt too long ({len(prompt)} chars), truncating to {max_chars}")
+
+        # Simple truncation - just cut off excess
+        # TODO Phase 4: Implement smarter truncation that removes chat history first
+        return prompt[:max_chars]