fix: change name of caching strategies to match new pattern from caching_v02

Author: philipph-askui

docs/06_caching.md

@@ -8,12 +8,12 @@ The caching system works by recording all tool use actions (mouse movements, cli
 
 ## Caching Strategies
 
-The caching mechanism supports four strategies, configured via the `caching_settings` parameter in the `act()` method:
+The caching mechanism supports three strategies, configured via the `caching_settings` parameter in the `act()` method:
 
-- **`"no"`** (default): No caching is used. The agent executes normally without recording or replaying actions.
-- **`"write"`**: Records all agent actions to a cache file for future replay.
-- **`"read"`**: Provides tools to the agent to list and execute previously cached trajectories.
-- **`"both"`**: Combines read and write modes - the agent can use existing cached trajectories and will also record new ones.
+- **`None`** (default): No caching is used. The agent executes normally without recording or replaying actions.
+- **`"record"`**: Records all agent actions to a cache file for future replay.
+- **`"execute"`**: Provides tools to the agent to list and execute previously cached trajectories.
+- **`"both"`**: Combines execute and record modes - the agent can use existing cached trajectories and will also record new ones.
 
 ## Configuration
 
@@ -23,9 +23,9 @@ Caching is configured using the `CachingSettings` class:
 from askui.models.shared.settings import CachingSettings, CachedExecutionToolSettings
 
 caching_settings = CachingSettings(
-    strategy="write",        # One of: "read", "write", "both", "no"
+    strategy="record",       # One of: "execute", "record", "both", or None
     cache_dir=".cache",      # Directory to store cache files
-    filename="my_test.json", # Filename for the cache file (optional for write mode)
+    filename="my_test.json", # Filename for the cache file (optional for record mode)
     execute_cached_trajectory_tool_settings=CachedExecutionToolSettings(
         delay_time_between_actions=0.5  # Delay in seconds between each cached action
     )
@@ -34,9 +34,9 @@ caching_settings = CachingSettings(
 
 ### Parameters
 
-- **`strategy`**: The caching strategy to use (`"read"`, `"write"`, `"both"`, or `"no"`).
+- **`strategy`**: The caching strategy to use (`"execute"`, `"record"`, `"both"`, or `None`).
 - **`cache_dir`**: Directory where cache files are stored. Defaults to `".cache"`.
-- **`filename`**: Name of the cache file to write to or read from. If not specified in write mode, a timestamped filename will be generated automatically (format: `cached_trajectory_YYYYMMDDHHMMSSffffff.json`).
+- **`filename`**: Name of the cache file to write to or read from. If not specified in record mode, a timestamped filename will be generated automatically (format: `cached_trajectory_YYYYMMDDHHMMSSffffff.json`).
 - **`execute_cached_trajectory_tool_settings`**: Configuration for the trajectory execution tool (optional). See [Execution Settings](#execution-settings) below.
 
 ### Execution Settings
@@ -61,7 +61,7 @@ You can adjust this value based on your application's responsiveness:
 
 ## Usage Examples
 
-### Writing a Cache (Recording)
+### Recording a Cache
 
 Record agent actions to a cache file for later replay:
 
@@ -73,7 +73,7 @@ with ComputerAgent() as agent:
     agent.act(
         goal="Fill out the login form with username 'admin' and password 'secret123'",
         caching_settings=CachingSettings(
-            strategy="write", # you could also use "both" here
+            strategy="record", # you could also use "both" here
             cache_dir=".cache",
             filename="login_test.json"
         )
@@ -82,7 +82,7 @@ with ComputerAgent() as agent:
 
 After execution, a cache file will be created at `.cache/login_test.json` containing all the tool use actions performed by the agent.
 
-### Reading from Cache (Replaying)
+### Executing from Cache (Replaying)
 
 Provide the agent with access to previously recorded trajectories:
 
@@ -94,13 +94,13 @@ with ComputerAgent() as agent:
     agent.act(
         goal="Fill out the login form",
         caching_settings=CachingSettings(
-            strategy="read", # you could also use "both" here
+            strategy="execute", # you could also use "both" here
             cache_dir=".cache"
         )
     )
 ```
 
-When using `strategy="read"`, the agent receives two additional tools:
+When using `strategy="execute"`, the agent receives two additional tools:
 
 1. **`retrieve_available_trajectories_tool`**: Lists all available cache files in the cache directory
 2. **`execute_cached_executions_tool`**: Executes a specific cached trajectory
@@ -109,7 +109,7 @@ The agent will automatically check if a relevant cached trajectory exists and us
 
 ### Referencing Cache Files in Goal Prompts
 
-When using `strategy="read"` or `strategy="both"`, **you need to inform the agent about which cache files are available and when to use them**. This is done by including cache file information directly in your goal prompt.
+When using `strategy="execute"` or `strategy="both"`, **you need to inform the agent about which cache files are available and when to use them**. This is done by including cache file information directly in your goal prompt.
 
 #### Explicit Cache File References
 
@@ -126,7 +126,7 @@ with ComputerAgent() as agent:
         If the cache file "open_website_in_chrome.json" is available, please use it
         for this execution. It will open a new window in Chrome and navigate to the website.""",
         caching_settings=CachingSettings(
-            strategy="read",
+            strategy="execute",
             cache_dir=".cache"
         )
     )
@@ -149,7 +149,7 @@ with ComputerAgent() as agent:
         Check if a cache file named "{test_id}.json" exists. If it does, use it to
         replay the test actions, then verify the results.""",
         caching_settings=CachingSettings(
-            strategy="read",
+            strategy="execute",
             cache_dir="test_cache"
         )
     )
@@ -171,7 +171,7 @@ with ComputerAgent() as agent:
         Choose the most recent one if multiple are available, as it likely contains
         the most up-to-date interaction sequence.""",
         caching_settings=CachingSettings(
-            strategy="read",
+            strategy="execute",
             cache_dir=".cache"
         )
     )
@@ -195,7 +195,7 @@ with ComputerAgent() as agent:
 
         After each cached execution, verify the step completed successfully before proceeding.""",
         caching_settings=CachingSettings(
-            strategy="read",
+            strategy="execute",
             cache_dir=".cache"
         )
     )
@@ -219,7 +219,7 @@ with ComputerAgent() as agent:
     agent.act(
         goal="Fill out the login form",
         caching_settings=CachingSettings(
-            strategy="read",
+            strategy="execute",
             cache_dir=".cache",
             execute_cached_trajectory_tool_settings=CachedExecutionToolSettings(
                 delay_time_between_actions=1.0  # Wait 1 second between each action
@@ -323,7 +323,7 @@ The delay between actions can be customized using `CachedExecutionToolSettings`
 ## Limitations
 
 - **UI State Sensitivity**: Cached trajectories assume the UI is in the same state as when they were recorded. If the UI has changed, the replay may fail or produce incorrect results.
-- **No on_message Callback**: When using `strategy="write"` or `strategy="both"`, you cannot provide a custom `on_message` callback, as the caching system uses this callback to record actions.
+- **No on_message Callback**: When using `strategy="record"` or `strategy="both"`, you cannot provide a custom `on_message` callback, as the caching system uses this callback to record actions.
 - **Verification Required**: After executing a cached trajectory, the agent should verify that the results are correct, as UI changes may cause partial failures.
 
 ## Example: Complete Test Workflow
@@ -340,7 +340,7 @@ with ComputerAgent() as agent:
     agent.act(
         goal="Navigate to the login page and log in with username 'testuser' and password 'testpass123'",
         caching_settings=CachingSettings(
-            strategy="write",
+            strategy="record",
             cache_dir="test_cache",
             filename="user_login.json"
         )
@@ -356,7 +356,7 @@ with ComputerAgent() as agent:
         the login sequence. It contains the steps to navigate to the login page and
         authenticate with the test credentials.""",
         caching_settings=CachingSettings(
-            strategy="read",
+            strategy="execute",
             cache_dir="test_cache",
             execute_cached_trajectory_tool_settings=CachedExecutionToolSettings(
                 delay_time_between_actions=1.0

src/askui/agent_base.py

@@ -135,14 +135,15 @@ def act(
                 Overrides the agent's default model if provided.
             on_message (OnMessageCb | None, optional): Callback for new messages. If
                 it returns `None`, stops and does not add the message. Cannot be used
-                with caching_settings strategy "write" or "both".
+                with caching_settings strategy "record" or "both".
             tools (list[Tool] | ToolCollection | None, optional): The tools for the
                 agent. Defaults to default tools depending on the selected model.
             caching_settings (CachingSettings | None, optional): The caching settings
                 for the act execution. Controls recording and replaying of action
-                sequences (trajectories). Available strategies: "no" (default, no
-                caching), "write" (record actions to cache file), "read" (replay from
-                cached trajectories), "both" (read and write). Defaults to no caching.
+                sequences (trajectories). Available strategies: None (default, no
+                caching), "record" (record actions to cache file), "execute" (replay
+                from cached trajectories), "both" (execute and record). Defaults to
+                no caching.
 
         Returns:
             None
@@ -152,7 +153,7 @@ def act(
                 defined in the agent settings.
             ModelRefusalError: If the model refuses to process the request.
             ValueError: If on_message callback is provided with caching strategy
-                "write" or "both".
+                "record" or "both".
 
         Example:
             Basic usage without caching:
@@ -177,14 +178,14 @@ def act(
                         "username 'admin' and password 'secret123'"
                     ),
                     caching_settings=CachingSettings(
-                        strategy="write",
+                        strategy="record",
                         cache_dir=".cache",
                         filename="login_flow.json"
                     )
                 )
             ```
 
-            Replaying cached actions:
+            Executing cached actions:
             ```python
             from askui import ComputerAgent
             from askui.models.shared.settings import CachingSettings
@@ -193,14 +194,14 @@ def act(
                 agent.act(
                     goal="Log in to the application",
                     caching_settings=CachingSettings(
-                        strategy="read",
+                        strategy="execute",
                         cache_dir=".cache"
                     )
                 )
                 # Agent will automatically find and use "login_flow.json"
             ```
 
-            Using both read and write modes:
+            Using both execute and record modes:
             ```python
             from askui import ComputerAgent
             from askui.models.shared.settings import CachingSettings
@@ -287,8 +288,8 @@ def _patch_act_with_cache(
         cached_execution_tool: ExecuteCachedTrajectory | None = None
         cache_manager: CacheManager | None = None
 
-        # Setup read mode: add caching tools and modify system prompt
-        if caching_settings.strategy in ["read", "both"]:
+        # Setup execute mode: add caching tools and modify system prompt
+        if caching_settings.strategy in ["execute", "both"]:
             # Create CacheExecutor with execution settings and add to speakers
             cache_executor = CacheExecutor(caching_settings.execution_settings)
             self._conversation.speakers.add_speaker(cache_executor)
@@ -315,8 +316,8 @@ def _patch_act_with_cache(
         else:
             tools = caching_tools
 
-        # Setup write mode: create cache manager for recording
-        if caching_settings.strategy in ["write", "both"]:
+        # Setup record mode: create cache manager for recording
+        if caching_settings.strategy in ["record", "both"]:
             cache_writer_settings = (
                 caching_settings.writing_settings or CacheWritingSettings()
             )

src/askui/models/shared/settings.py

@@ -34,7 +34,7 @@ class Resolution(NamedTuple):
 DEFAULT_LOCATE_RESOLUTION = Resolution(1280, 800)
 DEFAULT_GET_RESOLUTION = Resolution(1280, 800)
 
-CACHING_STRATEGY = Literal["read", "write", "both", "no"]
+CACHING_STRATEGY = Literal["execute", "record", "both"]
 CACHE_PARAMETER_IDENTIFICATION_STRATEGY = Literal["llm", "preset"]
 CACHING_VISUAL_VERIFICATION_METHOD = Literal["phash", "ahash", "none"]
 
@@ -259,18 +259,18 @@ class CachingSettings(BaseModel):
     performance optimization.
 
     Args:
-        strategy (CACHING_STRATEGY): Caching mode. Options:
-            - "no": Caching disabled (default)
-            - "read": Replay actions from cache
-            - "write": Record actions to cache
-            - "both": Read from cache if available, otherwise record
+        strategy (CACHING_STRATEGY | None): Caching mode. Options:
+            - None: Caching disabled (default)
+            - "execute": Replay actions from cache
+            - "record": Record actions to cache
+            - "both": Execute from cache if available, otherwise record
         cache_dir (str): Directory path for storing cache files.
             Default: ".askui_cache".
-        writing_settings: Settings for cache recording (used in "write"/"both" modes)
-        execution_settings: Settings for cache playback (used in "read"/"both" modes)
+        writing_settings: Settings for cache recording (used in "record"/"both" modes)
+        execution_settings: Settings for cache playback (used in "execute"/"both" modes)
     """
 
-    strategy: CACHING_STRATEGY = "no"
+    strategy: CACHING_STRATEGY | None = None
     cache_dir: str = ".askui_cache"
     writing_settings: CacheWritingSettings | None = None
     execution_settings: CacheExecutionSettings | None = None