ActionRecipe
============

Action-based recipe format for step-by-step execution.

Unlike function-based recipes (Recipe.py) which execute all-at-once,
ActionRecipe stores a list of discrete actions that can be:
- Stepped through one at a time
- Rewound to previous states
- Branched to create new variations

See ADR-014 for architecture decisions.

Classes
-------

.. py:class:: RecipeAction

   A single discrete action in a recipe.
   
   Attributes:
       type: Action type ("paint", "erase", "set_param", "set_algorithm").
       ras: World coordinates (R, A, S) for paint/erase actions.
       params: Parameters for the action.
       timestamp: When the action was recorded (seconds since epoch).
       description: Human-readable description.

   **Methods:**

   .. py:method:: to_dict()

      Convert to dictionary for JSON serialization.

   .. py:method:: from_dict()

      Create from dictionary.

   .. py:method:: paint()

      Create a paint action.

   .. py:method:: erase()

      Create an erase action.

   .. py:method:: set_param()

      Create a parameter change action.

   .. py:method:: set_algorithm()

      Create an algorithm change action.


.. py:class:: ActionRecipe

   A recipe as a list of discrete actions.
   
   This format supports step-by-step execution, rewinding, and branching.
   
   Attributes:
       name: Recipe name.
       sample_data: Slicer SampleData name to load.
       segment_name: Name for the segment to create.
       actions: List of actions to execute.
       gold_standard: Name of gold standard to compare against (optional).
       description: Human-readable description.
       metadata: Additional metadata (e.g., source recipe, creation date).

   **Methods:**

   .. py:method:: to_dict()

      Convert to dictionary for JSON serialization.

   .. py:method:: save()

      Save recipe to JSON file.

   .. py:method:: load()

      Load recipe from JSON file.

   .. py:method:: from_function_recipe()

      Convert a function-based Recipe to ActionRecipe by recording execution.

   .. py:method:: slice_to()

      Create a new recipe with actions up to the given step.

   .. py:method:: append_actions()

      Create a new recipe with additional actions appended.


.. py:class:: RecordingEffectProxy

   Proxy that records calls to the effect.

   **Methods:**

   .. py:method:: __init__()

   .. py:method:: paintAt()

      Record paint action.

   .. py:method:: eraseAt()

      Record erase action.


Functions
---------

.. py:function:: to_dict()

   Convert to dictionary for JSON serialization.

.. py:function:: from_dict()

   Create from dictionary.

.. py:function:: paint()

   Create a paint action.
   
   Args:
       ras: World coordinates (R, A, S).
       algorithm: Algorithm to use (e.g., "watershed").
       brush_radius_mm: Brush radius in mm.
       edge_sensitivity: Edge sensitivity (0-100).
       **kwargs: Additional algorithm-specific parameters.
   
   Returns:
       A paint RecipeAction.

.. py:function:: erase()

   Create an erase action.
   
   Args:
       ras: World coordinates (R, A, S).
       algorithm: Algorithm to use (e.g., "watershed").
       brush_radius_mm: Brush radius in mm.
       edge_sensitivity: Edge sensitivity (0-100).
       **kwargs: Additional algorithm-specific parameters.
   
   Returns:
       An erase RecipeAction.

.. py:function:: set_param()

   Create a parameter change action.
   
   Args:
       name: Parameter name.
       value: New value.
       description: Human-readable description.
   
   Returns:
       A set_param RecipeAction.

.. py:function:: set_algorithm()

   Create an algorithm change action.
   
   Args:
       algorithm: Algorithm name.
       description: Human-readable description.
   
   Returns:
       A set_algorithm RecipeAction.

.. py:function:: to_dict()

   Convert to dictionary for JSON serialization.

.. py:function:: save()

   Save recipe to JSON file.
   
   Args:
       path: Path to save to (will add .json extension if missing).

.. py:function:: load()

   Load recipe from JSON file.
   
   Args:
       path: Path to the JSON file.
   
   Returns:
       Loaded ActionRecipe.
   
   Raises:
       FileNotFoundError: If file doesn't exist.
       json.JSONDecodeError: If file is not valid JSON.

.. py:function:: from_function_recipe()

   Convert a function-based Recipe to ActionRecipe by recording execution.
   
   This executes the recipe's run() function with a proxy effect that
   records all paint operations as actions.
   
   Args:
       recipe: The function-based Recipe to convert.
   
   Returns:
       ActionRecipe with recorded actions.
   
   Note:
       This requires Slicer to be running as it needs the effect API.

.. py:function:: paintAt()

   Record paint action.

.. py:function:: eraseAt()

   Record erase action.

.. py:function:: slice_to()

   Create a new recipe with actions up to the given step.
   
   Args:
       step_index: Last step to include (inclusive).
   
   Returns:
       New ActionRecipe with actions[0:step_index+1].

.. py:function:: append_actions()

   Create a new recipe with additional actions appended.
   
   Args:
       new_actions: Actions to append.
   
   Returns:
       New ActionRecipe with additional actions.

.. py:function:: list_action_recipes()

   List available action recipe files (JSON format).
   
   Args:
       recipes_dir: Directory to search. If None, uses default location.
   
   Returns:
       List of recipe file paths.