statemachine-engine 0.0.2__py3-none-any.whl

statemachine_engine/__init__.py

@@ -0,0 +1,17 @@
+"""State Machine Engine - Event-driven workflow framework"""
+
+__version__ = "1.0.0"
+
+from .core.engine import StateMachineEngine
+from .core.action_loader import ActionLoader
+from .actions.base import BaseAction
+from .database.models.base import Database
+from .database.models.job import JobModel
+
+__all__ = [
+    "StateMachineEngine",
+    "ActionLoader",
+    "BaseAction",
+    "Database",
+    "JobModel",
+]

statemachine_engine/actions/__init__.py

@@ -0,0 +1,3 @@
+from .base import BaseAction
+
+__all__ = ["BaseAction"]

statemachine_engine/actions/base.py

@@ -0,0 +1,64 @@
+"""
+BaseAction - Abstract base class for pluggable state machine actions
+
+IMPORTANT: Changes via Change Management, see CLAUDE.md
+
+Defines the standard interface for all state machine actions loaded dynamically from YAML configuration. 
+Actions receive config parameters from YAML and execution context from the state machine, then return 
+event names to trigger state transitions. Provides common functionality for configuration access, 
+logging setup, and description handling across all action implementations.
+
+KEY FILES:
+- src/actions/bash_action.py - Shell command execution implementation  
+- src/actions/check_queue_action.py - Job queue monitoring implementation
+- src/state_machine/engine.py - Dynamic action loading and execution
+
+KEY FUNCTIONS:
+- execute(context) - Abstract method for action execution, returns event name
+- get_description() - Get action description from config or generate default  
+- get_config_value(key, default) - Retrieve configuration values with fallbacks
+"""
+
+import asyncio
+import logging
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Optional
+
+
+class BaseAction(ABC):
+    """Base class for all state machine actions."""
+    
+    def __init__(self, action_config: Dict[str, Any]):
+        """
+        Initialize action with configuration.
+        
+        Args:
+            action_config: Configuration dictionary from YAML
+        """
+        self.config = action_config
+        self.logger = logging.getLogger(f"{self.__class__.__module__}.{self.__class__.__name__}")
+    
+    @abstractmethod
+    async def execute(self, context: Dict[str, Any]) -> str:
+        """
+        Execute the action.
+        
+        Args:
+            context: State machine context
+            
+        Returns:
+            Event name to trigger next state transition
+        """
+        pass
+    
+    def get_description(self) -> str:
+        """Get action description from config or default."""
+        return self.config.get('description', f"{self.__class__.__name__} action")
+    
+    def get_config_value(self, key: str, default: Any = None) -> Any:
+        """Get configuration value with optional default."""
+        return self.config.get(key, default)
+    
+    def get_machine_name(self, context: Dict[str, Any]) -> str:
+        """Get machine name from context for logging."""
+        return context.get('machine_name', 'unknown')

statemachine_engine/actions/builtin/__init__.py

@@ -0,0 +1,17 @@
+"""Built-in Actions for State Machine Engine"""
+
+from .bash_action import BashAction
+from .check_database_queue_action import CheckDatabaseQueueAction
+from .check_machine_state_action import CheckMachineStateAction
+from .clear_events_action import ClearEventsAction
+from .log_action import LogAction
+from .send_event_action import SendEventAction
+
+__all__ = [
+    'BashAction',
+    'CheckDatabaseQueueAction',
+    'CheckMachineStateAction',
+    'ClearEventsAction',
+    'LogAction',
+    'SendEventAction',
+]

statemachine_engine/actions/builtin/bash_action.py

@@ -0,0 +1,313 @@
+"""
+BashAction - Execute shell commands with template parameter substitution and error mapping
+
+IMPORTANT: Changes via Change Management, see CLAUDE.md
+
+Executes bash commands defined in YAML configuration, substituting template parameters from job data
+using {param_name} placeholders. Commands run with configurable timeout, and the action returns 
+custom success events or mapped error events based on exit codes. Supports error mapping to specific 
+events (e.g., exit code 1 → 'no_faces_detected') and prevents automatic job removal for recoverable 
+errors that should be handled by state machine transitions.
+
+KEY FILES:
+- config/face_changer_database.yaml - YAML configuration with bash actions, error_mappings, and success events
+- src/database/ - Database-backed job storage and management
+- working/ - Temporary directory for safe file processing
+
+KEY FUNCTIONS:
+- execute(context) - Main action execution with parameter substitution, command running, and error mapping
+- get_config_value() - Retrieve configuration values including error_mappings and success events
+
+NEW FEATURES:
+- error_mappings: Map exit codes to specific error events (e.g., "1": "no_faces_detected")
+- success: Custom success event names instead of default 'job_done'
+- Conditional job removal: Specific errors like 'no_faces_detected' bypass auto-removal
+"""
+
+import asyncio
+import logging
+from typing import Dict, Any
+from ..base import BaseAction
+
+logger = logging.getLogger(__name__)
+
+
+class BashAction(BaseAction):
+    """
+    Action that executes bash commands with error mapping support.
+    
+    Returns:
+    - Custom success event (from 'success' config) or 'job_done' on exit code 0
+    - Mapped error event (from 'error_mappings' config) on specific exit codes  
+    - Default 'error' event on unmapped failures
+    
+    Error Mapping Example:
+    error_mappings:
+      "1": "no_faces_detected"  # Exit code 1 → no_faces_detected event
+      "2": "invalid_image"      # Exit code 2 → invalid_image event
+    """
+    
+    async def execute(self, context: Dict[str, Any]) -> str:
+        """
+        Execute bash command and return event based on exit code.
+        
+        Args:
+            context: State machine context containing current_job and queue
+            
+        Returns:
+            - success event (config 'success' or 'job_done') on exit code 0
+            - mapped error event (from 'error_mappings') on specific exit codes
+            - 'error' on unmapped failures
+            
+        Error Handling:
+            - Mapped errors (e.g., 'no_faces_detected') preserve job for state machine handling
+            - Unmapped errors auto-remove job to prevent infinite retries
+            - Timeouts and exceptions also auto-remove job
+        """
+        # Get command from job data first, fall back to config with parameter substitution
+        job = context.get('current_job')
+        command = None
+        
+        if job and isinstance(job.get('data'), dict):
+            job_data = job['data']
+            command = job_data.get('command')
+        
+        # Use config command and substitute parameters from job data (assumes add-job.sh usage)
+        if not command:
+            command = self.get_config_value('command')
+            if command and job and isinstance(job.get('data'), dict):
+                job_data = job['data']
+                
+                # Get context values for fallback substitution
+                # Start with ALL context (includes id, last_error, etc.), then overlay job_data
+                context_data = {**context}  # Start with full context (includes propagated job fields)
+                
+                # Overlay job_data (so job_data takes precedence over propagated context)
+                context_data.update(job_data)
+                
+                # Add event payload data if available (for machine-to-machine communication)
+                event_data = context.get('event_data', {})
+                if event_data and isinstance(event_data, dict):
+                    event_payload = event_data.get('payload', {})
+                    if event_payload and isinstance(event_payload, dict):
+                        # Merge event payload fields into context_data
+                        for key, value in event_payload.items():
+                            if key not in job_data:  # Don't override job data
+                                context_data[key] = value
+                
+                # Handle fallback syntax first (e.g., {enhanced_prompt|pony_prompt})
+                import re
+                fallback_pattern = r'\{([^|}]+)\|([^}]+)\}'
+                fallback_matches = re.findall(fallback_pattern, command)
+                
+                for primary_key, fallback_key in fallback_matches:
+                    placeholder = f"{{{primary_key}|{fallback_key}}}"
+                    quoted_placeholder = f"'{{{primary_key}|{fallback_key}}}'"
+
+                    # Try primary key first, then fallback
+                    value = context_data.get(primary_key)
+                    if value is None:
+                        value = context_data.get(fallback_key)
+
+                    if value is not None:
+                        # Handle quoted version - escape internal single quotes and wrap in single quotes
+                        if quoted_placeholder in command:
+                            # Escape single quotes in value for bash single-quote context
+                            escaped_value = str(value).replace("'", "'\\''")
+                            command = command.replace(quoted_placeholder, f"'{escaped_value}'")
+                            machine_name = self.get_machine_name(context)
+                            logger.debug(f"[{machine_name}] Substituted {quoted_placeholder} with '{escaped_value}' (using {primary_key if primary_key in context_data else fallback_key})")
+
+                        # Handle unquoted version (separate from quoted, both can occur in same command)
+                        if placeholder in command:
+                            if isinstance(value, str) and ('/' in value or ' ' in value):
+                                quoted_value = f'"{value}"'
+                            else:
+                                quoted_value = str(value)
+                            command = command.replace(placeholder, quoted_value)
+                            machine_name = self.get_machine_name(context)
+                            logger.debug(f"[{machine_name}] Substituted {placeholder} with {quoted_value} (using {primary_key if primary_key in context_data else fallback_key})")
+                
+                # Substitute regular parameters using {param_name} placeholders
+                for key, value in context_data.items():
+                    if key != 'event':  # Skip event field
+                        placeholder = f"{{{key}}}"
+                        quoted_placeholder = f"'{{{key}}}'"
+
+                        # First handle quoted placeholders - escape internal single quotes and wrap in single quotes
+                        if quoted_placeholder in command:
+                            # Escape single quotes in value for bash single-quote context
+                            escaped_value = str(value).replace("'", "'\\''")
+                            command = command.replace(quoted_placeholder, f"'{escaped_value}'")
+                            machine_name = self.get_machine_name(context)
+                            logger.debug(f"[{machine_name}] Substituted {quoted_placeholder} with '{escaped_value}'")
+
+                        # Then handle unquoted placeholders (separate from quoted, both can occur in same command)
+                        if placeholder in command:
+                            # For unquoted placeholders, add quotes for paths/strings with spaces
+                            if isinstance(value, str) and ('/' in value or ' ' in value):
+                                quoted_value = f'"{value}"'
+                            else:
+                                quoted_value = str(value)
+                            command = command.replace(placeholder, quoted_value)
+                            machine_name = self.get_machine_name(context)
+                            logger.debug(f"[{machine_name}] Substituted {placeholder} with {quoted_value}")
+                
+                # Check for any remaining unsubstituted placeholders
+                remaining_placeholders = re.findall(r'\{[^}]+\}', command)
+                if remaining_placeholders:
+                    machine_name = self.get_machine_name(context)
+                    logger.warning(f"[{machine_name}] Unsubstituted placeholders found: {remaining_placeholders}")
+            
+        if not command:
+            machine_name = self.get_machine_name(context)
+            logger.error(f"[{machine_name}] No command specified in job data or bash action config")
+            return 'error'
+        
+        timeout = self.get_config_value('timeout', 30)
+        job_id = job['id'] if job else 'unknown'
+        
+        # Use description for user-facing messages (INFO level), command details only at DEBUG
+        description = self.get_config_value('description')
+        machine_name = self.get_machine_name(context)
+        if description:
+            # User-facing descriptions logged at INFO (but skip repetitive/routine ones)
+            # Suppress: Initialize, Check, Reset (cleanup), mkdir operations
+            skip_prefixes = ['🔄 Initialize', '📋 Check', '🔄 Reset']
+            if not any(description.startswith(prefix) for prefix in skip_prefixes):
+                logger.info(f"[{machine_name}] {description[:60]}")
+        
+        # Command details only at DEBUG level (but skip simple mkdir commands)
+        # Add rate limiting for frequently executed commands
+        if not hasattr(self.__class__, '_cmd_count'):
+            self.__class__._cmd_count = {}
+        
+        cmd_key = command[:50]  # Use first 50 chars as key
+        if cmd_key not in self.__class__._cmd_count:
+            self.__class__._cmd_count[cmd_key] = 0
+        self.__class__._cmd_count[cmd_key] += 1
+        
+        if not command.startswith('mkdir -p'):
+            # Log first occurrence and every 100th to track frequency
+            if self.__class__._cmd_count[cmd_key] == 1:
+                logger.info(f"[{machine_name}] [BASH FREQUENCY TRACKER] First execution: {command}")
+            elif self.__class__._cmd_count[cmd_key] % 100 == 0:
+                logger.warning(f"[{machine_name}] [BASH FREQUENCY TRACKER] Command executed {self.__class__._cmd_count[cmd_key]} times: {command}")
+            
+            logger.debug(f"[{machine_name}] Executing command for job {job_id}: {command}")
+        
+        try:
+            # Execute command with timeout
+            process = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE
+            )
+            
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(), 
+                timeout=timeout
+            )
+            
+            # Only log output if non-empty and meaningful (skip routine messages)
+            stdout_text = stdout.decode().strip() if stdout else ""
+            stderr_text = stderr.decode().strip() if stderr else ""
+            
+            routine_messages = [
+                "No stuck processing jobs found",
+                "Successfully",
+                "Job created:",
+            ]
+            
+            is_routine = any(msg in stdout_text for msg in routine_messages)
+            
+            if stdout_text and not is_routine:
+                logger.debug(f"[{machine_name}] Output: {stdout_text[:200]}")  # Truncate long output
+            if stderr_text:
+                logger.warning(f"[{machine_name}] Error output: {stderr_text[:200]}")
+            
+            # Check exit code (don't log success for every command)
+            if process.returncode == 0:
+                # Include command context in completion log
+                cmd_summary = command[:50] + "..." if len(command) > 50 else command
+                logger.debug(f"[{machine_name}] Command completed (exit 0): {cmd_summary}")
+                
+                # Don't auto-complete jobs here - let the state machine handle job completion
+                # when the entire pipeline is done
+                
+                # Don't clear current job here - it may be needed by subsequent actions in the same state
+                
+                # Return custom success event if specified, otherwise 'job_done'
+                success_event = self.get_config_value('success', 'job_done')
+                return success_event
+            else:
+                error_output = stderr.decode().strip() if stderr else "No error output"
+                logger.error(f"[{machine_name}] Command failed with exit code {process.returncode} for job {job_id}")
+                logger.error(f"[{machine_name}] Failed command: {command}")
+                logger.error(f"[{machine_name}] Error output: {error_output}")
+
+                # Store error details in context for error_cleanup state with improved formatting
+                # Include command on separate line for better readability in logs
+                context['last_error'] = f"Command failed (exit {process.returncode}): {error_output}\nCommand: {command}"
+                context['last_error_action'] = 'bash'
+                context['last_error_command'] = command
+                context['last_error_exit_code'] = process.returncode
+
+                # Check for error mapping based on exit code
+                error_mappings = self.get_config_value('error_mappings', {})
+                if str(process.returncode) in error_mappings:
+                    mapped_error = error_mappings[str(process.returncode)]
+                    logger.info(f"[{machine_name}] Mapping exit code {process.returncode} to event: {mapped_error}")
+                    
+                    # For specific error types like no_faces_detected, don't auto-remove job
+                    # Let the state machine handle it through proper transitions
+                    if mapped_error in ['no_faces_detected']:
+                        return mapped_error
+                
+                # For unmapped errors, let the state machine handle job failure via error event
+                # Don't auto-remove jobs here - the state machine will handle proper cleanup
+                # and status updates via error_cleanup state
+                
+                # Clear current job on error to prevent infinite loops
+                context.pop('current_job', None)
+                
+                # Return mapped error event if available, otherwise default 'error'
+                return error_mappings.get(str(process.returncode), 'error')
+                
+        except asyncio.TimeoutError:
+            machine_name = self.get_machine_name(context)
+            timeout_msg = f"Command timed out after {timeout} seconds"
+            logger.error(f"[{machine_name}] {timeout_msg} for job {job_id}")
+            logger.error(f"[{machine_name}] Timed out command: {command}")
+
+            # Store timeout error in context with improved formatting
+            context['last_error'] = f"{timeout_msg}\nCommand: {command}"
+            context['last_error_action'] = 'bash'
+            context['last_error_command'] = command
+            
+            # Let the state machine handle job failure via error event
+            # Don't auto-remove jobs here - the state machine will handle proper cleanup
+            # and status updates via error_cleanup state
+            
+            # Clear current job on timeout to prevent infinite loops
+            context.pop('current_job', None)
+            return 'error'
+            
+        except Exception as e:
+            machine_name = self.get_machine_name(context)
+            error_msg = f"Command execution exception: {str(e)}"
+            logger.error(f"[{machine_name}] {error_msg} for job {job_id}")
+            logger.error(f"[{machine_name}] Failed command: {command}")
+
+            # Store exception details in context with improved formatting
+            context['last_error'] = f"{error_msg}\nCommand: {command}"
+            context['last_error_action'] = 'bash'
+            context['last_error_command'] = command
+
+            # Let the state machine handle job failure via error event
+            # Don't auto-remove jobs here - the state machine will handle proper cleanup
+            # and status updates via error_cleanup state
+
+            # Clear current job on exception to prevent infinite loops
+            context.pop('current_job', None)
+            return 'error'

statemachine_engine/actions/builtin/check_database_queue_action.py

@@ -0,0 +1,103 @@
+"""
+Unified database queue checking action
+
+IMPORTANT: Changes via Change Management, see CLAUDE.md
+
+Supports both face_processing and pony_flux job types in a single unified action
+"""
+import logging
+from typing import Dict, Any, Optional
+import sys
+from pathlib import Path
+
+# Add src to path for imports
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from ..base import BaseAction
+from statemachine_engine.database.models import get_job_model
+
+logger = logging.getLogger(__name__)
+
+class CheckDatabaseQueueAction(BaseAction):
+    """
+    Unified action to check database queue for jobs of any type
+    Supports both face_processing and pony_flux job types
+    """
+    
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.job_model = get_job_model()
+        # Get job type from config, default to face_processing for backward compatibility
+        self.job_type = config.get('job_type', 'face_processing')
+        # Get machine type for concurrent architecture
+        self.machine_type = config.get('machine_type', None)
+    
+    async def execute(self, context: Dict[str, Any]) -> str:
+        """Check database queue for next job of specified type"""
+        try:
+            # First, fail any processing jobs with missing input files (for face_processing only)
+            if self.job_type == 'face_processing':
+                self._fail_jobs_with_missing_files()
+            
+            job = self.job_model.get_next_job(job_type=self.job_type, machine_type=self.machine_type)
+            
+            if job:
+                # Extract data from JSON field (get_next_job() already parsed it)
+                job_data = job.get('data', {})
+                
+                # Store job in context - data is already in the right format
+                # Engine will propagate job_data to context automatically
+                context['current_job'] = {
+                    'id': job['job_id'],
+                    'source_job_id': job.get('source_job_id'),
+                    'job_type': job['job_type'],
+                    'data': job_data  # Already parsed by JobModel.get_next_job()
+                }
+                
+                # Store job model in context for job completion
+                context['job_model'] = self.job_model
+                
+                machine_name = context.get('machine_name', 'unknown')
+                logger.info(f"[{machine_name}] {job['job_type']} job {job['job_id']} retrieved from queue (data keys: {list(job_data.keys())})")
+                
+                return "new_job"
+            else:
+                return "no_jobs"
+                
+        except Exception as e:
+            machine_name = context.get('machine_name', 'unknown')
+            logger.error(f"[{machine_name}] Error checking database queue: {e}")
+            return "error"
+    
+    def _fail_jobs_with_missing_files(self):
+        """Mark processing jobs as failed when they reference non-existent files"""
+        try:
+            # Only clean up jobs for this machine type
+            machine_type = self.config.get('machine_type')
+            problem_jobs = self.job_model.get_processing_jobs_with_missing_files(machine_type)
+            
+            for job in problem_jobs:
+                job_id = job['job_id']
+                # get_processing_jobs_with_missing_files returns jobs with data already parsed
+                job_data = job.get('data', {})
+                input_path = job_data.get('input_image_path')
+                
+                # Additional safety check for None values
+                if input_path is None:
+                    machine_name = self.config.get('machine_type', 'unknown')
+                    logger.warning(f"[{machine_name}] Skipping job {job_id} - no input image path")
+                    continue
+                    
+                reason = f"Input file not found: {input_path}"
+                
+                machine_name = self.config.get('machine_type', 'unknown')
+                logger.warning(f"[{machine_name}] Marking job {job_id} as failed - {reason}")
+                self.job_model.fail_job(job_id, reason)
+                
+            if problem_jobs:
+                machine_name = self.config.get('machine_type', 'unknown')
+                logger.info(f"[{machine_name}] Marked {len(problem_jobs)} jobs with missing input files as failed")
+                
+        except Exception as e:
+            machine_name = self.config.get('machine_type', 'unknown')
+            logger.error(f"[{machine_name}] Error during job cleanup: {e}")

statemachine_engine/actions/builtin/check_machine_state_action.py

@@ -0,0 +1,138 @@
+"""
+CheckMachineStateAction - Validate target machine state
+
+IMPORTANT: Changes via Change Management, see CLAUDE.md
+
+Queries pipeline_results table to get target machine's current state
+and validates it against expected states.
+"""
+import logging
+import subprocess
+import asyncio
+from typing import Dict, Any, List, Optional
+from datetime import datetime
+
+from ..base import BaseAction
+from statemachine_engine.database.models import get_job_model
+
+logger = logging.getLogger(__name__)
+
+class CheckMachineStateAction(BaseAction):
+    """
+    Action to check another machine's current state and validate it.
+
+    Returns:
+        - in_expected_state: Machine is running and in expected state
+        - unexpected_state: Machine is running but in wrong state
+        - not_running: Machine process not found or state data stale
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        super().__init__(config)
+        self.target_machine = config.get('target_machine', 'unknown')
+        self.expected_states = config.get('expected_states', [])
+        self.timeout_seconds = config.get('timeout_seconds', 60)
+        self.job_model = get_job_model()
+
+    async def execute(self, context: Dict[str, Any]) -> str:
+        """Check target machine state and validate"""
+        try:
+            # 1. Check if machine process is running
+            machine_name = self.get_machine_name(context)
+            is_running = await self._is_process_running(self.target_machine)
+            if not is_running:
+                logger.warning(f"[{machine_name}] Machine {self.target_machine} process not found")
+                return 'not_running'
+
+            # 2. Get current state from database
+            current_state = self._get_current_state(self.target_machine)
+
+            if not current_state:
+                logger.warning(f"[{machine_name}] No recent state data for {self.target_machine}")
+                return 'not_running'
+
+            # 3. Validate against expected states
+            if current_state in self.expected_states:
+                logger.info(f"[{machine_name}] Machine {self.target_machine} in expected state: {current_state}")
+                return 'in_expected_state'
+            else:
+                logger.info(f"[{machine_name}] Machine {self.target_machine} in unexpected state: {current_state} (expected: {self.expected_states})")
+                # Store unexpected state in context for debugging
+                context['unexpected_machine_state'] = current_state
+                return 'unexpected_state'
+
+        except Exception as e:
+            machine_name = self.get_machine_name(context)
+            logger.error(f"[{machine_name}] Error checking machine state: {e}")
+            return 'error'
+
+    async def _is_process_running(self, machine_name: str) -> bool:
+        """Check if target machine process is running"""
+        try:
+            # Run ps command asynchronously
+            process = await asyncio.create_subprocess_exec(
+                'ps', 'aux',
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE
+            )
+
+            stdout, stderr = await asyncio.wait_for(
+                process.communicate(),
+                timeout=5
+            )
+
+            output = stdout.decode('utf-8')
+
+            # Look for state_machine/cli.py with machine name
+            is_running = ('state_machine/cli.py' in output and
+                         machine_name in output)
+
+            logger.debug(f"Process check for {machine_name}: {'running' if is_running else 'not found'}")
+            return is_running
+
+        except asyncio.TimeoutError:
+            logger.error("Process check timed out")  # No context available in helper method
+            return False
+        except Exception as e:
+            logger.error(f"Error checking process: {e}")  # No context available in helper method
+            return False
+
+    def _get_current_state(self, machine_name: str) -> Optional[str]:
+        """Get current state from pipeline_results table"""
+        try:
+            with self.job_model.db._get_connection() as conn:
+                row = conn.execute("""
+                    SELECT
+                        json_extract(metadata, '$.state') as current_state,
+                        completed_at
+                    FROM pipeline_results
+                    WHERE step_name = 'state_change'
+                      AND json_extract(metadata, '$.machine') = ?
+                    ORDER BY completed_at DESC
+                    LIMIT 1
+                """, (machine_name,)).fetchone()
+
+                if not row:
+                    logger.debug(f"No state data found for {machine_name}")  # Keep without prefix - debug level
+                    return None
+
+                # Check if state data is fresh
+                completed_at_str = row['completed_at']
+                state_time = datetime.fromisoformat(completed_at_str)
+                # Database stores UTC timestamps, use utcnow() for comparison
+                now = datetime.utcnow()
+                age = (now - state_time).total_seconds()
+
+                logger.debug(f"State timestamp for {machine_name}: completed_at={completed_at_str}, parsed={state_time}, now={now}, age={age:.1f}s")  # Keep without prefix - debug level
+
+                if age > self.timeout_seconds:
+                    logger.warning(f"State data for {machine_name} is stale ({age:.0f}s old, limit {self.timeout_seconds}s)")  # Keep without prefix - internal helper
+                    return None
+
+                state = row['current_state']
+                logger.debug(f"Current state for {machine_name}: {state} (age: {age:.1f}s)")  # Keep without prefix - debug level
+                return state
+
+        except Exception as e:
+            logger.error(f"Error querying state for {machine_name}: {e}")  # Keep without prefix - internal helper
+            return None