Implement full support for @guard("step_name") decorator syntax

This commit adds complete support for the @guard("step_name") decorator syntax,
allowing guards to be defined as separate methods that reference a step by name.

Changes:
- Enhanced model.py to discover and use @guard("step_name") decorated methods
- Fixed decorators.py to properly handle inline lambda guards with @guard(lambda...)
- Added support for the 'invert' parameter in both decorator-based guards
- Implemented _find_decorator_guard() to search for guards targeting specific steps
- Added comprehensive tests for all guard decorator variations

The implementation now supports three guard styles:
1. Naming convention: guard_step_name() methods
2. Inline guards: @guard(lambda self: condition)
3. Decorator-based: @guard("step_name") on separate methods

All 63 existing tests pass with the new implementation.

Author: claude

pyosmo/decorators.py

@@ -98,11 +98,15 @@ def can_process(self) -> bool:
         Decorated function
     """
     if callable(step_name_or_func):
-        # Inline guard
-        func = step_name_or_func
-        func._osmo_guard_inline = True  # type: ignore[attr-defined]
-        func._osmo_guard_invert = invert  # type: ignore[attr-defined]
-        return func
+        # Inline guard - return a decorator that attaches the guard to the step
+        guard_func = step_name_or_func
+
+        def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+            func._osmo_guard_inline = guard_func  # type: ignore[attr-defined]
+            func._osmo_guard_invert = invert  # type: ignore[attr-defined]
+            return func
+
+        return decorator
 
     # Named guard
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:

pyosmo/model.py

@@ -85,11 +85,35 @@ def is_available(self) -> bool:
 
         # Check for inline guard (decorator-based)
         if hasattr(self.func, '_osmo_guard_inline'):
-            return bool(self.func._osmo_guard_inline(self.object_instance))
-
-        # Check for named guard function
+            result = bool(self.func._osmo_guard_inline(self.object_instance))
+            # Apply invert if specified
+            if hasattr(self.func, '_osmo_guard_invert') and self.func._osmo_guard_invert:
+                result = not result
+            return result
+
+        # Check for decorator-based guard (@guard("step_name"))
+        decorator_guard = self._find_decorator_guard()
+        if decorator_guard is not None:
+            result = bool(decorator_guard.execute())
+            # Check if guard should be inverted
+            guard_func = decorator_guard.func
+            if hasattr(guard_func, '_osmo_guard_invert') and guard_func._osmo_guard_invert:
+                result = not result
+            return result
+
+        # Check for named guard function (naming convention)
         return True if self.guard_function is None else bool(self.guard_function.execute())
 
+    def _find_decorator_guard(self) -> Optional['ModelFunction']:
+        """Find a guard method decorated with @guard("step_name") for this step."""
+        for attr_name in dir(self.object_instance):
+            method = getattr(self.object_instance, attr_name)
+            if callable(method) and hasattr(method, '_osmo_guard') and hasattr(method, '_osmo_guard_for'):
+                # Check if this guard is for our step
+                if method._osmo_guard_for == self.name:
+                    return ModelFunction(attr_name, self.object_instance)
+        return None
+
     @property
     def guard_function(self) -> Optional['ModelFunction']:
         """Return guard function if it exists, otherwise None."""

pyosmo/tests/test_decorators.py

@@ -1,6 +1,6 @@
 """Test decorator-based API"""
 
-from pyosmo import Osmo, post, pre, requires, step, weight
+from pyosmo import Osmo, guard, post, pre, requires, step, weight
 from pyosmo.end_conditions import Length
 
 
@@ -147,3 +147,194 @@ def weight_action(self):
 
     # Weight function should be called
     assert action_step.weight == 20
+
+
+def test_guard_decorator_with_step_name():
+    """Test @guard("step_name") decorator"""
+
+    class GuardModel:
+        def __init__(self):
+            self.ready = False
+            self.process_called = False
+            self.other_called = False
+
+        @step
+        def process(self):
+            self.process_called = True
+
+        @guard("process")
+        def can_process(self) -> bool:
+            return self.ready
+
+        @step
+        def other_step(self):
+            self.other_called = True
+
+    model = GuardModel()
+    osmo = Osmo(model)
+
+    # Process should not be available initially
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'process' not in step_names
+    assert 'other_step' in step_names
+
+    # Make process available
+    model.ready = True
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'process' in step_names
+
+
+def test_guard_decorator_inline():
+    """Test @guard with inline lambda"""
+
+    class InlineGuardModel:
+        def __init__(self):
+            self.counter = 0
+            self.limit_reached = False
+
+        @step
+        @guard(lambda self: not self.limit_reached)
+        def increment(self):
+            self.counter += 1
+            if self.counter >= 5:
+                self.limit_reached = True
+
+        @step
+        def other_action(self):
+            pass
+
+    model = InlineGuardModel()
+    osmo = Osmo(model)
+    osmo.test_end_condition = Length(10)
+
+    osmo.run()
+
+    # Should reach 5 and then stop incrementing due to guard
+    assert model.counter == 5
+
+
+def test_guard_decorator_with_invert():
+    """Test @guard with invert parameter"""
+
+    class InvertGuardModel:
+        def __init__(self):
+            self.blocked = True
+            self.action_called = False
+
+        @step
+        def action(self):
+            self.action_called = True
+
+        @guard("action", invert=True)
+        def is_blocked(self) -> bool:
+            return self.blocked
+
+    model = InvertGuardModel()
+    osmo = Osmo(model)
+
+    # Action should not be available when blocked=True (inverted)
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'action' not in step_names
+
+    # Make action available by setting blocked=False
+    model.blocked = False
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'action' in step_names
+
+
+def test_guard_decorator_multiple_steps():
+    """Test multiple guards for different steps"""
+
+    class MultiGuardModel:
+        def __init__(self):
+            self.logged_in = False
+            self.has_items = False
+
+        @step
+        def login(self):
+            self.logged_in = True
+
+        @step
+        def checkout(self):
+            pass
+
+        @guard("login")
+        def can_login(self) -> bool:
+            return not self.logged_in
+
+        @guard("checkout")
+        def can_checkout(self) -> bool:
+            return self.logged_in and self.has_items
+
+    model = MultiGuardModel()
+    osmo = Osmo(model)
+
+    # Initially, only login is available
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'login' in step_names
+    assert 'checkout' not in step_names
+
+    # After login, checkout still not available (no items)
+    model.logged_in = True
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'login' not in step_names  # Can't login again
+    assert 'checkout' not in step_names
+
+    # After adding items, checkout is available
+    model.has_items = True
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'checkout' in step_names
+
+
+def test_guard_mixing_decorator_and_naming_convention():
+    """Test that decorator guards work alongside naming convention guards"""
+
+    class MixedGuardModel:
+        def __init__(self):
+            self.flag_a = True
+            self.flag_b = True
+
+        @step
+        def action_a(self):
+            pass
+
+        @guard("action_a")
+        def guard_for_a(self) -> bool:
+            return self.flag_a
+
+        def step_action_b(self):
+            pass
+
+        def guard_action_b(self) -> bool:
+            return self.flag_b
+
+    model = MixedGuardModel()
+    osmo = Osmo(model)
+
+    # Both should be available initially
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'action_a' in step_names
+    assert 'action_b' in step_names
+
+    # Disable decorator-guarded step
+    model.flag_a = False
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'action_a' not in step_names
+    assert 'action_b' in step_names
+
+    # Disable naming-convention-guarded step
+    model.flag_a = True
+    model.flag_b = False
+    available_steps = osmo.model.available_steps
+    step_names = [s.name for s in available_steps]
+    assert 'action_a' in step_names
+    assert 'action_b' not in step_names