chore(caching): distributes responsibilities between CacheWriter and ParameterHandler more consistently and renames placeholder to caching_parameter.

Author: philipph-askui

docs/caching.md

@@ -18,7 +18,7 @@
 COMPUTER_USE_20251124_BETA_FLAG = "computer-use-2025-11-24"
 
 CACHING_STRATEGY = Literal["read", "write", "both", "no"]
-PLACEHOLDER_IDENTIFICATION_STRATEGY = Literal["llm", "preset"]
+CACHE_PARAMETER_IDENTIFICATION_STRATEGY = Literal["llm", "preset"]
 
 
 class MessageSettings(BaseModel):
@@ -43,8 +43,8 @@ class CachedExecutionToolSettings(BaseModel):
 
 
 class CacheWriterSettings(BaseModel):
-    placeholder_identification_strategy: PLACEHOLDER_IDENTIFICATION_STRATEGY = "llm"
-    llm_placeholder_id_api_provider: AnthropicApiProvider = "askui"
+    parameter_identification_strategy: CACHE_PARAMETER_IDENTIFICATION_STRATEGY = "llm"
+    llm_parameter_id_api_provider: AnthropicApiProvider = "askui"
 
 
 class CachingSettings(BaseModel):
@@ -81,4 +81,4 @@ class CacheFile(BaseModel):
 
     metadata: CacheMetadata
     trajectory: list[ToolUseBlockParam]
-    placeholders: dict[str, str] = Field(default_factory=dict)
+    cache_parameters: dict[str, str] = Field(default_factory=dict)

src/askui/models/shared/settings.py

@@ -19,16 +19,16 @@
     "    - If execution fails partway, you'll see exactly where it failed "
     "and can decide how to proceed\n"
     "\n"
-    "    PLACEHOLDERS:\n"
-    "    - Trajectories may contain dynamic placeholders like "
+    "    CACHING_PARAMETERS:\n"
+    "    - Trajectories may contain dynamic parameters like "
     "{{current_date}} or {{user_name}}\n"
     "    - When executing a trajectory, check if it requires "
-    "placeholder values\n"
-    "    - Provide placeholder values using the placeholder_values "
+    "parameter values\n"
+    "    - Provide parameter values using the parameter_values "
     "parameter as a dictionary\n"
     "    - Example: ExecuteCachedTrajectory(trajectory_file='test.json', "
-    "placeholder_values={'current_date': '2025-12-11'})\n"
-    "    - If required placeholders are missing, execution will fail with "
+    "parameter_values={'current_date': '2025-12-11'})\n"
+    "    - If required parameters are missing, execution will fail with "
     "a clear error message\n"
     "\n"
     "    NON-CACHEABLE STEPS:\n"
@@ -49,7 +49,7 @@
     "    - Provide the same trajectory file and the step index where "
     "execution should continue\n"
     "    - Example: ExecuteCachedTrajectory(trajectory_file='test.json', "
-    "start_from_step_index=5, placeholder_values={...})\n"
+    "start_from_step_index=5, parameter_values={...})\n"
     "    - The tool will execute remaining steps from that index onwards\n"
     "\n"
     "    FAILURE HANDLING:\n"
@@ -83,8 +83,8 @@
     "    </TRAJECTORY DETAILS>\n"
 )
 
-PLACEHOLDER_IDENTIFIER_SYSTEM_PROMPT = """You are analyzing UI automation trajectories \
-to identify values that should be parameterized as placeholders.
+CACHING_PARAMETER_IDENTIFIER_SYSTEM_PROMPT = """You are analyzing UI automation \
+trajectories to identify values that should be parameterized as parameters.
 
 Identify values that are likely to change between executions, such as:
 - Dates and timestamps (e.g., "2025-12-11", "10:30 AM", "2025-12-11T14:30:00Z")
@@ -94,22 +94,22 @@
 - File paths with user-specific or time-specific components
 - Temporary or generated identifiers
 
-DO NOT mark as placeholders:
+DO NOT mark as parameters:
 - UI element coordinates (x, y positions)
 - Fixed button labels or static UI text
 - Configuration values that don't change (e.g., timeouts, retry counts)
 - Generic action names like "click", "type", "scroll"
 - Tool names
 - Boolean values or common constants
 
-For each placeholder, provide:
+For each parameter, provide:
 1. A descriptive name in snake_case (e.g., "current_date", "user_email")
 2. The actual value found in the trajectory
 3. A brief description of what it represents
 
 Return your analysis as a JSON object with this structure:
 {
-  "placeholders": [
+  "parameters": [
     {
       "name": "current_date",
       "value": "2025-12-11",
@@ -118,4 +118,4 @@
   ]
 }
 
-If no placeholders are found, return an empty placeholders array."""
+If no parameters are found, return an empty parameters array."""

src/askui/prompts/caching.py

@@ -8,10 +8,10 @@
 
 from ..models.shared.settings import CachedExecutionToolSettings
 from ..models.shared.tools import Tool, ToolCollection
+from ..utils.cache_parameter_handler import CacheParameterHandler
 from ..utils.caching.cache_execution_manager import CacheExecutionManager
 from ..utils.caching.cache_manager import CacheManager
 from ..utils.caching.cache_writer import CacheWriter
-from ..utils.placeholder_handler import PlaceholderHandler
 
 if TYPE_CHECKING:
     from ..models.shared.agent_message_param import ToolUseBlockParam
@@ -149,14 +149,14 @@ def __init__(
                 "trajectory files are available\n"
                 "2. Select the appropriate trajectory file path from the "
                 "returned list\n"
-                "3. If the trajectory contains placeholders (e.g., "
+                "3. If the trajectory contains parameters (e.g., "
                 "{{current_date}}), provide values for them in the "
-                "placeholder_values parameter\n"
+                "parameter_values parameter\n"
                 "4. Pass the full file path to this tool\n\n"
-                "Placeholders allow dynamic values to be injected during "
+                "Cache parameters allow dynamic values to be injected during "
                 "execution. For example, if a trajectory types "
                 "'{{current_date}}', you must provide "
-                "placeholder_values={'current_date': '2025-12-11'}.\n\n"
+                "parameter_values={'current_date': '2025-12-11'}.\n\n"
                 "To continue from a specific step (e.g., after manually "
                 "handling a non-cacheable step), use the start_from_step_index "
                 "parameter. By default, execution starts from the beginning "
@@ -188,12 +188,12 @@ def __init__(
                         ),
                         "default": 0,
                     },
-                    "placeholder_values": {
+                    "parameter_values": {
                         "type": "object",
                         "description": (
-                            "Optional dictionary mapping placeholder names to "
+                            "Optional dictionary mapping parameter names to "
                             "their values. Required if the trajectory contains "
-                            "placeholders like {{variable}}. Example: "
+                            "parameters like {{variable}}. Example: "
                             "{'current_date': '2025-12-11', 'user_name': 'Alice'}"
                         ),
                         "additionalProperties": {"type": "string"},
@@ -265,33 +265,33 @@ def _validate_step_index(
             return error_msg
         return None
 
-    def _validate_placeholders(
+    def _validate_parameters(
         self,
         trajectory: list["ToolUseBlockParam"],
-        placeholder_values: dict[str, str],
-        cache_placeholders: dict[str, str],
+        parameter_values: dict[str, str],
+        cache_parameters: dict[str, str],
     ) -> str | None:
-        """Validate placeholder values.
+        """Validate parameter values.
 
         Args:
             trajectory: The cached trajectory
-            placeholder_values: User-provided placeholder values
-            cache_placeholders: Placeholders defined in cache file
+            parameter_values: User-provided parameter values
+            cache_parameters: Parameters defined in cache file
 
         Returns:
             Error message if validation fails, None otherwise
         """
-        logger.debug("Validating placeholder values")
-        is_valid, missing = PlaceholderHandler.validate_placeholders(
-            trajectory, placeholder_values
+        logger.debug("Validating parameter values")
+        is_valid, missing = CacheParameterHandler.validate_parameters(
+            trajectory, parameter_values
         )
         if not is_valid:
             error_msg = (
-                f"Missing required placeholder values: {', '.join(missing)}\n"
-                f"The trajectory contains the following placeholders: "
-                f"{', '.join(cache_placeholders.keys())}\n"
-                f"Please provide values for all placeholders in the "
-                f"placeholder_values parameter."
+                f"Missing required parameter values: {', '.join(missing)}\n"
+                f"The trajectory contains the following parameters: "
+                f"{', '.join(cache_parameters.keys())}\n"
+                f"Please provide values for all parameters in the "
+                f"parameter_values parameter."
             )
             logger.error(error_msg)
             return error_msg
@@ -300,14 +300,14 @@ def _validate_placeholders(
     def _create_executor(
         self,
         cache_file: "CacheFile",
-        placeholder_values: dict[str, str],
+        parameter_values: dict[str, str],
         start_from_step_index: int,
     ) -> "TrajectoryExecutor":
         """Create and configure trajectory executor.
 
         Args:
             cache_file: The cache file to execute
-            placeholder_values: Placeholder values to use
+            parameter_values: Parameter values to use
             start_from_step_index: Index to start execution from
 
         Returns:
@@ -324,7 +324,7 @@ def _create_executor(
         executor = TrajectoryExecutor(
             trajectory=cache_file.trajectory,
             toolbox=self._toolbox,
-            placeholder_values=placeholder_values,
+            parameter_values=parameter_values,
             delay_time=self._settings.delay_time_between_action,
         )
 
@@ -342,15 +342,15 @@ def _format_success_message(
         trajectory_file: str,
         trajectory_length: int,
         start_from_step_index: int,
-        placeholder_count: int,
+        parameter_count: int,
     ) -> str:
         """Format success message.
 
         Args:
             trajectory_file: Path to trajectory file
             trajectory_length: Total steps in trajectory
             start_from_step_index: Starting step index
-            placeholder_count: Number of placeholders used
+            parameter_count: Number of parameters used
 
         Returns:
             Formatted success message
@@ -369,8 +369,8 @@ def _format_success_message(
                 f"Will execute {remaining_steps} remaining cached steps."
             )
 
-        if placeholder_count > 0:
-            success_msg += f" Using {placeholder_count} placeholder value(s)."
+        if parameter_count > 0:
+            success_msg += f" Using {parameter_count} parameter value(s)."
 
         return success_msg
 
@@ -380,7 +380,7 @@ def __call__(
         self,
         trajectory_file: str,
         start_from_step_index: int = 0,
-        placeholder_values: dict[str, str] | None = None,
+        parameter_values: dict[str, str] | None = None,
     ) -> str:
         """Activate cache execution mode for the agent.
 
@@ -390,8 +390,8 @@ def __call__(
         Returns:
             Success message indicating cache mode has been activated
         """
-        if placeholder_values is None:
-            placeholder_values = {}
+        if parameter_values is None:
+            parameter_values = {}
 
         logger.info(
             "Activating cache execution mode: %s (start_from_step=%d)",
@@ -417,9 +417,9 @@ def __call__(
         cache_file = CacheWriter.read_cache_file(Path(trajectory_file))
 
         logger.debug(
-            "Cache loaded: %d steps, %d placeholders, valid=%s",
+            "Cache loaded: %d steps, %d parameters, valid=%s",
             len(cache_file.trajectory),
-            len(cache_file.placeholders),
+            len(cache_file.cache_parameters),
             cache_file.metadata.is_valid,
         )
 
@@ -439,15 +439,15 @@ def __call__(
         ):
             return error
 
-        # Validate placeholders
-        if error := self._validate_placeholders(
-            cache_file.trajectory, placeholder_values, cache_file.placeholders
+        # Validate parameters
+        if error := self._validate_parameters(
+            cache_file.trajectory, parameter_values, cache_file.cache_parameters
         ):
             return error
 
         # Create and configure executor
         executor = self._create_executor(
-            cache_file, placeholder_values, start_from_step_index
+            cache_file, parameter_values, start_from_step_index
         )
 
         # Store executor and cache info in agent state
@@ -462,7 +462,7 @@ def __call__(
             trajectory_file,
             len(cache_file.trajectory),
             start_from_step_index,
-            len(placeholder_values),
+            len(parameter_values),
         )
         logger.info(success_msg)
         return success_msg
@@ -483,7 +483,7 @@ def __init__(self) -> None:
                 "- Execution statistics (attempts, last execution time)\n"
                 "- Validity status and invalidation reason (if invalid)\n"
                 "- Failure history with timestamps and error messages\n"
-                "- Placeholders and trajectory step count\n\n"
+                "- Parameters and trajectory step count\n\n"
                 "Use this tool to debug cache issues or understand why a cache "
                 "might be failing or invalidated."
             ),
@@ -556,10 +556,10 @@ def __call__(self, trajectory_file: str) -> str:
         lines.append("")
         lines.append("--- Trajectory Info ---")
         lines.append(f"Total Steps: {len(cache_file.trajectory)}")
-        lines.append(f"Placeholders: {len(cache_file.placeholders)}")
-        if cache_file.placeholders:
+        lines.append(f"Parameters: {len(cache_file.cache_parameters)}")
+        if cache_file.cache_parameters:
             lines.append(
-                f"Placeholder Names: {', '.join(cache_file.placeholders.keys())}"
+                f"Parameter Names: {', '.join(cache_file.cache_parameters.keys())}"
             )
 
         if metadata.failures: