Add timeout support for model function calls and enhance validation

- Introduce per-function timeout with `_call_with_timeout` utility.
- Update `ModelFunction`, `TestStep`, and `Osmo` to allow configurable timeouts.
- Add timeout propagation and revalidation in model discovery.
- Implement timeout validation in `ConfigValidator`.

Author: OPpuolitaival

pyosmo/config.py

@@ -65,6 +65,23 @@ def validate_error_strategy(strategy: Any, name: str = 'Error strategy') -> None
             'AlwaysRaise, AlwaysIgnore, IgnoreAsserts, AllowCount',
         )
 
+    @staticmethod
+    def validate_timeout(timeout: Any) -> None:
+        """Validate timeout value.
+
+        Args:
+            timeout: Timeout value to validate (positive number or None)
+
+        Raises:
+            ConfigurationError: If timeout is invalid
+        """
+        if timeout is None:
+            return
+        if not isinstance(timeout, (int, float)):
+            raise ConfigurationError(f'Timeout must be a positive number or None, got {type(timeout).__name__}.')
+        if timeout <= 0:
+            raise ConfigurationError(f'Timeout must be a positive number, got {timeout}.')
+
     @staticmethod
     def validate_seed(seed: Any) -> None:
         """Validate random seed value.
@@ -98,6 +115,7 @@ def __init__(self) -> None:
         self._test_suite_end_condition: OsmoEndCondition = Length(1)  # pragma: no mutate
         self._test_error_strategy: OsmoErrorStrategy = AlwaysRaise()
         self._test_suite_error_strategy: OsmoErrorStrategy = AlwaysRaise()
+        self._timeout: float | None = 60.0
 
     @property
     def random(self) -> Random:
@@ -187,3 +205,20 @@ def test_suite_error_strategy(self, value: OsmoErrorStrategy) -> None:
         """
         ConfigValidator.validate_error_strategy(value, 'Test suite error strategy')
         self._test_suite_error_strategy = value
+
+    @property
+    def timeout(self) -> float | None:
+        return self._timeout
+
+    @timeout.setter
+    def timeout(self, value: float | None) -> None:
+        """Set timeout for model function calls with validation.
+
+        Args:
+            value: Timeout in seconds (positive number) or None to disable
+
+        Raises:
+            ConfigurationError: If timeout is invalid
+        """
+        ConfigValidator.validate_timeout(value)
+        self._timeout = value

pyosmo/model.py

@@ -1,17 +1,55 @@
 import inspect
 import logging
+import threading
 from collections.abc import Callable, Iterator
 from typing import Any, Optional
 
 logger = logging.getLogger('osmo')
 
 
+def _call_with_timeout(func: Callable[[], Any], timeout: float, description: str) -> Any:
+    """Call a function with a timeout using a daemon thread.
+
+    Args:
+        func: Zero-argument callable to execute
+        timeout: Maximum seconds to wait
+        description: Human-readable description for error messages
+
+    Returns:
+        The function's return value
+
+    Raises:
+        TimeoutError: If the function exceeds the timeout
+        Any exception raised by the function
+    """
+    result: list[Any] = []
+    error: list[BaseException] = []
+    completed = threading.Event()
+
+    def wrapper() -> None:
+        try:
+            result.append(func())
+        except BaseException as e:
+            error.append(e)
+        finally:
+            completed.set()
+
+    thread = threading.Thread(target=wrapper, daemon=True)
+    thread.start()
+    if not completed.wait(timeout=timeout):
+        raise TimeoutError(f'{description} timed out after {timeout} seconds')
+    if error:
+        raise error[0]
+    return result[0] if result else None
+
+
 class ModelFunction:
     """Generic function class containing basic functionality of model functions"""
 
-    def __init__(self, function_name: str, object_instance: object) -> None:
+    def __init__(self, function_name: str, object_instance: object, timeout: float | None = 60.0) -> None:
         self.function_name = function_name
         self.object_instance = object_instance  # Instance of model class
+        self.timeout = timeout
 
     @property
     def default_weight(self) -> float:
@@ -24,9 +62,15 @@ def default_weight(self) -> float:
     def func(self) -> Callable[[], Any]:
         return getattr(self.object_instance, self.function_name)
 
+    def _with_timeout(self, func: Callable[[], Any], description: str) -> Any:
+        """Call func with timeout if configured, otherwise call directly."""
+        if self.timeout is not None:
+            return _call_with_timeout(func, self.timeout, description)
+        return func()
+
     def execute(self) -> Any:
         try:
-            return self.func()
+            return self._with_timeout(self.func, str(self))
         except AttributeError as e:
             raise Exception(f'Osmo cannot find function {self.object_instance}.{self.function_name} from model') from e
 
@@ -44,10 +88,11 @@ def __init__(
         object_instance: object,
         step_name: str | None = None,
         is_decorator_based: bool = False,
+        timeout: float | None = 60.0,
     ) -> None:
         if not is_decorator_based:
             assert function_name.startswith('step_'), 'Wrong name function'
-        super().__init__(function_name, object_instance)
+        super().__init__(function_name, object_instance, timeout=timeout)
         self._step_name = step_name
         self._is_decorator_based = is_decorator_based
         self._decorator_guard_cache: ModelFunction | None | object = _GUARD_NOT_CACHED
@@ -85,16 +130,25 @@ def is_available(self) -> bool:
         """Check if step is available right now"""
         # Check model-level guard first (guard_all)
         guard_all_func = getattr(self.object_instance, 'guard_all', None)
-        if guard_all_func is not None and callable(guard_all_func) and not guard_all_func():
-            return False
+        if guard_all_func is not None and callable(guard_all_func):
+            guard_all_result = self._with_timeout(guard_all_func, f'{type(self.object_instance).__name__}.guard_all()')
+            if not guard_all_result:
+                return False
 
         # Check if step is disabled by decorator
         if hasattr(self.func, '_osmo_enabled') and not self.func._osmo_enabled:
             return False
 
         # Check for inline guard (decorator-based)
         if hasattr(self.func, '_osmo_guard_inline'):
-            result = bool(self.func._osmo_guard_inline(self.object_instance))  # type: ignore[operator]
+            inline_guard = self.func._osmo_guard_inline
+            instance = self.object_instance
+            result = bool(
+                self._with_timeout(
+                    lambda: inline_guard(instance),  # type: ignore[operator]
+                    f'{type(self.object_instance).__name__}.{self.function_name}() inline guard',
+                )
+            )
             # Apply invert if specified
             if hasattr(self.func, '_osmo_guard_invert') and self.func._osmo_guard_invert:
                 result = not result
@@ -133,7 +187,7 @@ def _find_decorator_guard(self) -> Optional['ModelFunction']:
                 and hasattr(method, '_osmo_guard_for')
                 and method._osmo_guard_for == self.name
             ):
-                self._decorator_guard_cache = ModelFunction(attr_name, self.object_instance)
+                self._decorator_guard_cache = ModelFunction(attr_name, self.object_instance, timeout=self.timeout)
                 return self._decorator_guard_cache
 
         self._decorator_guard_cache = None
@@ -152,7 +206,7 @@ def return_function_if_exists(self, name: str) -> Optional['ModelFunction']:
         if hasattr(self.object_instance, name):
             attr = getattr(self.object_instance, name)
             if callable(attr):
-                return ModelFunction(name, self.object_instance)
+                return ModelFunction(name, self.object_instance, timeout=self.timeout)
         return None
 
 
@@ -163,6 +217,7 @@ def __init__(self) -> None:
         # Format: functions[function_name] = link_of_instance
         self.sub_models: list[object] = []
         self.debug: bool = False
+        self.timeout: float | None = 60.0
         # Performance optimization: cache discovered steps
         self._steps_cache: list[TestStep] | None = None
         self._cache_valid: bool = False
@@ -185,7 +240,7 @@ def _discover_steps(self, sub_model: object) -> Iterator[TestStep]:
             if hasattr(method, '_osmo_step'):
                 step_name = method._osmo_step_name  # type: ignore[attr-defined]
                 discovered_step_names.add(attr_name)
-                yield TestStep(attr_name, sub_model, step_name, is_decorator_based=True)
+                yield TestStep(attr_name, sub_model, step_name, is_decorator_based=True, timeout=self.timeout)
 
         # Then, discover naming convention steps (skip if already found via decorator)
         for attr_name, _method in inspect.getmembers(sub_model, predicate=callable):
@@ -194,7 +249,7 @@ def _discover_steps(self, sub_model: object) -> Iterator[TestStep]:
                 continue
 
             if attr_name.startswith('step_'):
-                yield TestStep(attr_name, sub_model)
+                yield TestStep(attr_name, sub_model, timeout=self.timeout)
 
     @property
     def all_steps(self) -> Iterator[TestStep]:
@@ -231,7 +286,7 @@ def functions_by_name(self, name: str) -> Iterator[ModelFunction]:
         for sub_model in self.sub_models:
             for attr_name, _method in inspect.getmembers(sub_model, predicate=callable):
                 if attr_name == name:
-                    yield ModelFunction(attr_name, sub_model)
+                    yield ModelFunction(attr_name, sub_model, timeout=self.timeout)
 
     def add_model(self, model: object) -> None:
         """Add model for osmo.

pyosmo/osmo.py

@@ -135,6 +135,9 @@ def generate(self) -> None:
         # Re-inject osmo_history into all models
         for sub_model in self.model.sub_models:
             sub_model.osmo_history = self.history  # type: ignore[attr-defined]
+        # Propagate timeout to model collector and cached steps
+        self.model.timeout = self._timeout
+        self.model._cache_valid = False  # Force step re-discovery with new timeout
         logger.debug('Start generation..')
         logger.info(f'Using seed: {self.seed}')
         # Initialize algorithm
@@ -522,3 +525,16 @@ def ignore_asserts(self) -> 'Osmo':
         from pyosmo.error_strategy import IgnoreAsserts
 
         return self.on_error(IgnoreAsserts())
+
+    def with_timeout(self, seconds: float | None) -> 'Osmo':
+        """
+        Set timeout for model function calls (fluent API).
+
+        Args:
+            seconds: Timeout in seconds (positive number) or None to disable
+
+        Returns:
+            Self for method chaining
+        """
+        self.timeout = seconds
+        return self

pyosmo/tests/test_timeout.py

@@ -0,0 +1,104 @@
+import time
+
+import pytest
+
+from pyosmo.config import ConfigurationError
+from pyosmo.osmo import Osmo
+
+
+class HangingStepModel:
+    def step_hang(self):
+        time.sleep(10)
+
+    def step_fast(self):
+        pass
+
+
+class HangingGuardModel:
+    def step_action(self):
+        pass
+
+    def guard_action(self):
+        time.sleep(10)
+        return True
+
+
+class FastModel:
+    def step_one(self):
+        pass
+
+    def step_two(self):
+        pass
+
+
+class ErrorStepModel:
+    def step_fail(self):
+        raise ValueError('step error')
+
+
+def test_hanging_step_raises_timeout():
+    osmo = Osmo(HangingStepModel()).with_timeout(0.1).stop_after_steps(1).run_tests(1)
+    with pytest.raises(TimeoutError, match='timed out after 0.1 seconds'):
+        osmo.generate()
+
+
+def test_hanging_guard_raises_timeout():
+    osmo = Osmo(HangingGuardModel()).with_timeout(0.1).stop_after_steps(1).run_tests(1)
+    with pytest.raises(TimeoutError, match='timed out after 0.1 seconds'):
+        osmo.generate()
+
+
+def test_timeout_none_disables_timeout():
+    """With timeout=None, no timeout is applied (function runs normally)."""
+    osmo = Osmo(FastModel()).with_timeout(None).stop_after_steps(5).run_tests(1)
+    osmo.generate()
+    assert len(osmo.history.test_cases) == 1
+
+
+def test_with_timeout_returns_self():
+    osmo = Osmo(FastModel())
+    result = osmo.with_timeout(30)
+    assert result is osmo
+
+
+def test_fast_functions_work_with_timeout():
+    osmo = Osmo(FastModel()).with_timeout(5.0).stop_after_steps(10).run_tests(1)
+    osmo.generate()
+    assert len(osmo.history.test_cases) == 1
+    assert len(osmo.history.test_cases[0].steps_log) == 10
+
+
+def test_timeout_propagates_to_model():
+    osmo = Osmo(FastModel()).with_timeout(42.0)
+    osmo.generate()
+    assert osmo.model.timeout == 42.0
+
+
+def test_default_timeout_is_60():
+    osmo = Osmo(FastModel())
+    assert osmo.timeout == 60.0
+
+
+def test_timeout_validation_rejects_negative():
+    osmo = Osmo(FastModel())
+    with pytest.raises(ConfigurationError, match='positive number'):
+        osmo.with_timeout(-1)
+
+
+def test_timeout_validation_rejects_zero():
+    osmo = Osmo(FastModel())
+    with pytest.raises(ConfigurationError, match='positive number'):
+        osmo.with_timeout(0)
+
+
+def test_timeout_validation_rejects_string():
+    osmo = Osmo(FastModel())
+    with pytest.raises(ConfigurationError, match='positive number or None'):
+        osmo.with_timeout('fast')  # type: ignore[arg-type]
+
+
+def test_step_error_preserved_through_timeout():
+    """Original exceptions should propagate through the timeout wrapper."""
+    osmo = Osmo(ErrorStepModel()).with_timeout(5.0).stop_after_steps(1).run_tests(1)
+    with pytest.raises(ValueError, match='step error'):
+        osmo.generate()