Skip to content

Automate browser based workflows with AI

Cache extract-information results per workflow run (SKY-8819) (#5459)

Aaron Perez5348ff6b09be
diff --git a/skyvern/core/script_generations/real_skyvern_page_ai.py b/skyvern/core/script_generations/real_skyvern_page_ai.py
index 143425725..e51db3901 100644
--- a/skyvern/core/script_generations/real_skyvern_page_ai.py
+++ b/skyvern/core/script_generations/real_skyvern_page_ai.py
@@ -16,6 +16,7 @@ from skyvern.forge import app
from skyvern.forge.prompts import prompt_engine
from skyvern.forge.sdk.api.files import validate_download_url
from skyvern.forge.sdk.api.llm.schema_validator import validate_and_fill_extraction_result
+from skyvern.forge.sdk.cache import extraction_cache
from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.schemas.totp_codes import OTPType
from skyvern.schemas.workflows import BlockStatus
@@ -910,6 +911,11 @@ class RealSkyvernPageAi(SkyvernPageAi):
if context and context.tz_info:
tz_info = context.tz_info
prompt = _render_template_with_label(prompt, label=self.current_label)
+ local_datetime_str = datetime.now(tz_info).isoformat()
+
+ # Render the prompt FIRST so the cache key hashes the exact string
+ # that will be sent to the LLM (captures economy-tree swaps and 2/3
+ # truncation inside load_prompt_with_elements).
extract_information_prompt = load_prompt_with_elements(
element_tree_builder=self.scraped_page,
prompt_engine=prompt_engine,
@@ -920,8 +926,30 @@ class RealSkyvernPageAi(SkyvernPageAi):
current_url=self.scraped_page.url,
extracted_text=self.scraped_page.extracted_text,
error_code_mapping_str=(json.dumps(error_code_mapping) if error_code_mapping else None),
- local_datetime=datetime.now(tz_info).isoformat(),
+ local_datetime=local_datetime_str,
)
+
+ # Share the extract-information cache with the agent path. Best-effort
+ # per the RFC review — any exception falls through to the full LLM
+ # call below.
+ workflow_run_id = context.workflow_run_id if context else None
+ cache_key: str | None = None
+ try:
+ cache_key = extraction_cache.compute_cache_key(
+ rendered_prompt=extract_information_prompt,
+ llm_key=None,
+ )
+ cached = extraction_cache.get(workflow_run_id, cache_key)
+ if cached is not None:
+ LOG.info(
+ "ai_extract cache hit — skipping LLM call",
+ workflow_run_id=workflow_run_id,
+ cache_key=cache_key,
+ )
+ return cached # type: ignore[return-value]
+ except Exception:
+ LOG.warning("ai_extract cache lookup failed; falling through to LLM", exc_info=True)
+ cache_key = None
step = None
if context and context.organization_id and context.task_id and context.step_id:
step = await app.DATABASE.tasks.get_step(
@@ -944,6 +972,14 @@ class RealSkyvernPageAi(SkyvernPageAi):
schema=schema,
)
+ # Cache the post-validation result so cache hits return the same
+ # schema-validated shape as a fresh LLM call.
+ if cache_key is not None and result is not None:
+ try:
+ extraction_cache.store(workflow_run_id, cache_key, result)
+ except Exception:
+ LOG.warning("ai_extract cache store failed; ignoring", exc_info=True)
+
if context and context.script_mode:
print(f"\n✨ 📊 Extracted Information:\n{'-' * 50}")
diff --git a/skyvern/forge/sdk/cache/extraction_cache.py b/skyvern/forge/sdk/cache/extraction_cache.py
new file mode 100644
index 000000000..70292e85e
--- /dev/null
+++ b/skyvern/forge/sdk/cache/extraction_cache.py
@@ -0,0 +1,239 @@
+"""
+In-memory extraction-result cache for `extract-information` LLM calls.
+
+Context: several workflows call `extract-information` repeatedly on
+the same page (e.g. a loop that re-navigates to the same list page for every
+document it needs to download). The page content, data-extraction goal, and
+output schema are identical across iterations, but we still pay the full LLM
+cost each time. This cache keys on the content that actually affects the
+extraction output and skips the LLM call on a hit.
+
+Scope and lifetime:
+- Scoped by `workflow_run_id`. Cache entries for a different run are isolated,
+ and a run's entries can be cleared via `clear_workflow_run` (e.g. at run end).
+- Purely in-memory, per-process. A workflow run that spans multiple workers
+ will still pay the LLM cost the first time each worker sees the page.
+- Two-tier eviction:
+ - **Outer** (workflow runs): LRU with a cap of `_MAX_WORKFLOW_RUNS`.
+ Reads and writes refresh the run's position via `move_to_end`.
+ - **Inner** (entries per run): FIFO with a cap of `_MAX_ENTRIES_PER_RUN`.
+ Oldest entry is popped when the limit is exceeded.
+
+Key derivation:
+- Hashes the inputs that determine the LLM's output:
+ - element tree (HTML)
+ - extracted page text
+ - current URL
+ - data extraction goal
+ - extracted information schema (JSON-normalized)
+ - navigation payload (JSON-normalized)
+ - error_code_mapping (JSON-normalized) — changes the rendered prompt
+ - previous_extracted_information (JSON-normalized) — rendered in the prompt
+ as prior context. Within a single loop iteration this is None on the
+ first step of each task, so cache hits still land across iterations of
+ a "list -> click row -> list again" loop. Including it keeps
+ correctness if an intra-task second-step extraction happens.
+ - llm_key — the caller's model override. Cheap to include today (one key
+ per block type per run) and prevents stale hits if we later move this
+ cache off-process and a user changes models to retune quality.
+- Two calls with identical values hash to the same key. Any meaningful change
+ (new page content, different schema, etc.) produces a fresh key and a miss.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from collections import OrderedDict
+from typing import Any
+
+import structlog
+
+LOG = structlog.get_logger()
+
+_MAX_ENTRIES_PER_RUN = 64
+_MAX_WORKFLOW_RUNS = 256
+# Sentinel hashed in place of None so that None and "" produce different keys.
+_NULL_SENTINEL = "\x00__NULL__"
+
+# workflow_run_id -> ordered dict of {cache_key: extraction_result}
+_CACHE: OrderedDict[str, OrderedDict[str, Any]] = OrderedDict()
+
+# Simple hit/miss counters for post-deploy observability.
+_hits = 0
+_misses = 0
+_HIT_RATE_LOG_INTERVAL = 50 # log hit rate every N lookups
+
+
+# Matches an ISO-8601 timestamp like 2026-04-10T15:30:45.123456+00:00 on
+# its own line. We replace it with the date-only prefix so two calls on the
+# same day hash identically.
+_ISO_LINE_RE = re.compile(r"^(\d{4}-\d{2}-\d{2})T[\d:.+\-]+$", re.MULTILINE)
+
+
+def _normalize_prompt_datetime(prompt: str) -> str:
+ """Replace ISO timestamp lines in the prompt with their date-only prefix.
+
+ This lets us hash the rendered prompt directly without microsecond-level
+ timestamp churn defeating the cache. The actual prompt sent to the LLM is
+ unchanged; only the key-derivation copy is normalized.
+ """
+ return _ISO_LINE_RE.sub(lambda m: m.group(1), prompt)
+
+
+def _normalize(value: Any) -> str:
+ """Stable JSON serialization for hashing — sorted keys, no whitespace churn."""
+ if value is None:
+ return _NULL_SENTINEL
+ if isinstance(value, str):
+ return value
+ try:
+ return json.dumps(value, sort_keys=True, default=str)
+ except (TypeError, ValueError):
+ return str(value)
+
+
+def compute_cache_key(
+ *,
+ element_tree: str | None = None,
+ extracted_text: str | None = None,
+ current_url: str | None = None,
+ data_extraction_goal: str | None = None,
+ extracted_information_schema: Any = None,
+ navigation_payload: Any = None,
+ error_code_mapping: Any = None,
+ previous_extracted_information: Any = None,
+ llm_key: str | None = None,
+ local_datetime: str | None = None,
+ rendered_prompt: str | None = None,
+) -> str:
+ """Return a stable sha256 hex digest for the inputs that affect extraction output.
+
+ Preferred usage: pass `rendered_prompt` (the fully-rendered extract-information
+ prompt string) together with `llm_key` and `local_datetime`. This captures
+ any prompt transformations (economy element tree, 2/3 truncation) applied
+ inside `load_prompt_with_elements`, so the cache key matches exactly what
+ goes to the LLM.
+
+ Legacy usage: the loose-field parameters (element_tree, extracted_text, …)
+ are retained for tests and backward compatibility. They are ignored when
+ `rendered_prompt` is provided.
+
+ Note: screenshots are passed to the LLM as multimodal input but are NOT
+ included in the cache key. For the target loop pattern (same URL, same DOM
+ on each re-visit), screenshots are expected to be visually identical when
+ the element tree and extracted text match. If this assumption proves wrong
+ (e.g. dynamic overlays), we can add a SHA-256 of the screenshot bytes as
+ a follow-up.
+ """
+
+ def _s(v: str | None) -> str:
+ """Map None to a sentinel so None and '' hash differently."""
+ return _NULL_SENTINEL if v is None else v
+
+ # Truncate local_datetime to date-only (YYYY-MM-DD) so the key is stable
+ # within a single run but changes across midnight for date-relative goals.
+ date_only = local_datetime[:10] if local_datetime and len(local_datetime) >= 10 else _s(local_datetime)
+
+ if rendered_prompt is not None:
+ # Normalize the local_datetime line inside the rendered prompt so that
+ # two calls on the same day produce the same hash. The template emits
+ # the full ISO timestamp on its own line; strip sub-date precision
+ # before hashing.
+ normalized_prompt = _normalize_prompt_datetime(rendered_prompt)
+ parts = [normalized_prompt, _s(llm_key)]
+ else:
+ parts = [
+ _s(element_tree),
+ _s(extracted_text),
+ _s(current_url),
+ _s(data_extraction_goal),
+ _normalize(extracted_information_schema),
+ _normalize(navigation_payload),
+ _normalize(error_code_mapping),
+ _normalize(previous_extracted_information),
+ _s(llm_key),
+ date_only,
+ ]
+ # Use a delimiter that cannot appear inside any part naturally.
+ joined = "\x1f".join(parts).encode("utf-8", errors="replace")
+ return hashlib.sha256(joined).hexdigest()
+
+
+def get(workflow_run_id: str | None, cache_key: str) -> Any | None:
+ """Return a cached extraction result, or None on miss."""
+ global _hits, _misses # noqa: PLW0603
+
+ if not workflow_run_id:
+ return None
+ run_cache = _CACHE.get(workflow_run_id)
+ if not run_cache:
+ _misses += 1
+ LOG.debug("extraction_cache.miss", workflow_run_id=workflow_run_id, cache_key=cache_key)
+ _maybe_log_hit_rate()
+ return None
+ result = run_cache.get(cache_key)
+ if result is not None:
+ _hits += 1
+ # Refresh LRU position so actively-read runs aren't evicted.
+ _CACHE.move_to_end(workflow_run_id)
+ else:
+ _misses += 1
+ LOG.debug("extraction_cache.miss", workflow_run_id=workflow_run_id, cache_key=cache_key)
+ _maybe_log_hit_rate()
+ return result
+
+
+def _maybe_log_hit_rate() -> None:
+ """Log cumulative hit rate every _HIT_RATE_LOG_INTERVAL lookups."""
+ total = _hits + _misses
+ if total > 0 and total % _HIT_RATE_LOG_INTERVAL == 0:
+ LOG.info(
+ "extraction_cache.hit_rate",
+ hits=_hits,
+ misses=_misses,
+ total=total,
+ hit_rate=round(_hits / total, 3),
+ )
+
+
+def store(workflow_run_id: str | None, cache_key: str, result: Any) -> None:
+ """Store an extraction result for later reuse within the same workflow run."""
+ if not workflow_run_id:
+ return
+ if workflow_run_id in _CACHE:
+ run_cache = _CACHE[workflow_run_id]
+ _CACHE.move_to_end(workflow_run_id)
+ else:
+ run_cache = OrderedDict()
+ _CACHE[workflow_run_id] = run_cache
+ if cache_key in run_cache:
+ run_cache.move_to_end(cache_key)
+ run_cache[cache_key] = result
+ while len(run_cache) > _MAX_ENTRIES_PER_RUN:
+ evicted_key, _ = run_cache.popitem(last=False)
+ LOG.debug(
+ "extraction_cache.evicted",
+ workflow_run_id=workflow_run_id,
+ cache_key=evicted_key,
+ )
+ # Evict oldest workflow runs if the global cache grows too large.
+ while len(_CACHE) > _MAX_WORKFLOW_RUNS:
+ evicted_run_id, _ = _CACHE.popitem(last=False)
+ LOG.debug("extraction_cache.run_evicted", workflow_run_id=evicted_run_id)
+
+
+def clear_workflow_run(workflow_run_id: str | None) -> None:
+ """Drop all cached entries for the given workflow run. Safe to call on unknown IDs."""
+ if not workflow_run_id:
+ return
+ _CACHE.pop(workflow_run_id, None)
+
+
+def _reset_for_tests() -> None:
+ """Test-only: wipe the global cache and counters between unit tests."""
+ global _hits, _misses # noqa: PLW0603
+ _CACHE.clear()
+ _hits = 0
+ _misses = 0
diff --git a/skyvern/forge/sdk/workflow/service.py b/skyvern/forge/sdk/workflow/service.py
index 5d0eaa67a..1601b10ca 100644
--- a/skyvern/forge/sdk/workflow/service.py
+++ b/skyvern/forge/sdk/workflow/service.py
@@ -53,6 +53,7 @@ from skyvern.forge import app
from skyvern.forge.failure_classifier import classify_from_failure_reason
from skyvern.forge.prompts import prompt_engine
from skyvern.forge.sdk.artifact.models import Artifact, ArtifactType
+from skyvern.forge.sdk.cache import extraction_cache
from skyvern.forge.sdk.cache.factory import CacheFactory
from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.core.security import generate_skyvern_webhook_signature
@@ -3720,7 +3721,9 @@ class WorkflowService:
ai_fallback=ai_fallback,
failure_category=failure_category,
)
- if status in [WorkflowRunStatus.completed, WorkflowRunStatus.failed, WorkflowRunStatus.terminated]:
+ if status.is_final():
+ # Free extraction-cache entries for this run.
+ extraction_cache.clear_workflow_run(workflow_run_id)
start_time = (
workflow_run.started_at.replace(tzinfo=UTC)
if workflow_run.started_at
diff --git a/skyvern/webeye/actions/handler.py b/skyvern/webeye/actions/handler.py
index 82fc6605f..f297843eb 100644
--- a/skyvern/webeye/actions/handler.py
+++ b/skyvern/webeye/actions/handler.py
@@ -67,6 +67,7 @@ from skyvern.forge.sdk.api.files import (
from skyvern.forge.sdk.api.llm.api_handler_factory import LLMAPIHandlerFactory, LLMCallerManager
from skyvern.forge.sdk.api.llm.exceptions import LLMProviderError
from skyvern.forge.sdk.api.llm.schema_validator import validate_and_fill_extraction_result
+from skyvern.forge.sdk.cache import extraction_cache
from skyvern.forge.sdk.core import skyvern_context
from skyvern.forge.sdk.core.skyvern_context import current as skyvern_current
from skyvern.forge.sdk.core.skyvern_context import ensure_context
@@ -4182,9 +4183,31 @@ async def extract_information_for_navigation_goal(
Scrapes a webpage and returns the scraped response, including:
1. JSON representation of what the user is seeing
2. The scraped page
+
+ Extraction-result cache
+ --------------------------------
+ Many workflows re-extract the same page on every iteration of a loop
+ (e.g. navigate back to a documents list, extract, click one row, repeat).
+ When the page content, data-extraction goal, and output schema are
+ identical to a previous call within the same workflow run, reuse the
+ prior LLM result instead of paying for another extract-information call.
"""
scraped_page_refreshed = await scraped_page.refresh()
context = ensure_context()
+
+ # Compute llm key up-front so the cache key includes it.
+ llm_key_override = task.llm_key
+ if await service_utils.is_cua_task(task=task):
+ # CUA tasks should use the default data extraction llm key
+ llm_key_override = None
+
+ # Compute local_datetime once so both the cache key and the prompt use the
+ # same value (avoids stale hits when date-relative extraction goals cross midnight).
+ local_datetime_str = datetime.now(context.tz_info).isoformat()
+
+ # Render the prompt FIRST so the cache key hashes the exact string that
+ # will be sent to the LLM (captures economy-tree swaps and 2/3 truncation
+ # inside load_prompt_with_elements).
extract_information_prompt = load_prompt_with_elements(
element_tree_builder=scraped_page_refreshed,
prompt_engine=prompt_engine,
@@ -4198,13 +4221,28 @@ async def extract_information_for_navigation_goal(
current_url=scraped_page_refreshed.url,
extracted_text=scraped_page_refreshed.extracted_text,
error_code_mapping_str=(json.dumps(task.error_code_mapping) if task.error_code_mapping else None),
- local_datetime=datetime.now(context.tz_info).isoformat(),
+ local_datetime=local_datetime_str,
)
- llm_key_override = task.llm_key
- if await service_utils.is_cua_task(task=task):
- # CUA tasks should use the default data extraction llm key
- llm_key_override = None
+ # Best-effort cache lookup — any failure falls through to LLM.
+ cache_key: str | None = None
+ try:
+ cache_key = extraction_cache.compute_cache_key(
+ rendered_prompt=extract_information_prompt,
+ llm_key=llm_key_override,
+ )
+ cached = extraction_cache.get(task.workflow_run_id, cache_key)
+ if cached is not None:
+ LOG.info(
+ "extract_information cache hit — skipping LLM call",
+ task_id=task.task_id,
+ workflow_run_id=task.workflow_run_id,
+ cache_key=cache_key,
+ )
+ return ScrapeResult(scraped_data=cached)
+ except Exception:
+ LOG.warning("extract_information cache lookup failed; falling through to LLM", exc_info=True)
+ cache_key = None
# Use the appropriate LLM handler based on the feature flag
llm_api_handler = LLMAPIHandlerFactory.get_override_llm_api_handler(
@@ -4225,6 +4263,14 @@ async def extract_information_for_navigation_goal(
schema=task.extracted_information_schema,
)
+ # Cache the post-validation result so cache hits return the same shape as
+ # a fresh LLM call (schema-validated with missing fields filled).
+ if cache_key is not None and json_response is not None:
+ try:
+ extraction_cache.store(task.workflow_run_id, cache_key, json_response)
+ except Exception:
+ LOG.warning("extract_information cache store failed; ignoring", exc_info=True)
+
return ScrapeResult(
scraped_data=json_response,
)
diff --git a/tests/unit/test_extraction_cache.py b/tests/unit/test_extraction_cache.py
new file mode 100644
index 000000000..93e09a21f
--- /dev/null
+++ b/tests/unit/test_extraction_cache.py
@@ -0,0 +1,212 @@
+"""Unit tests for the extract-information result cache."""
+
+from __future__ import annotations
+
+import pytest
+
+from skyvern.forge.sdk.cache import extraction_cache
+
+
[email protected](autouse=True)
+def _reset_cache() -> None:
+ extraction_cache._reset_for_tests()
+ yield
+ extraction_cache._reset_for_tests()
+
+
+def _key(**overrides: object) -> str:
+ defaults: dict[str, object] = {
+ "element_tree": "<html><body>docs</body></html>",
+ "extracted_text": "Document list",
+ "current_url": "https://example.com/docs",
+ "data_extraction_goal": "Extract document list",
+ "extracted_information_schema": {"type": "object", "properties": {"docs": {"type": "array"}}},
+ "navigation_payload": {"user": "alice"},
+ }
+ defaults.update(overrides)
+ return extraction_cache.compute_cache_key(**defaults) # type: ignore[arg-type]
+
+
+def test_identical_inputs_produce_identical_key() -> None:
+ assert _key() == _key()
+
+
+def test_key_changes_when_element_tree_changes() -> None:
+ assert _key() != _key(element_tree="<html><body>different</body></html>")
+
+
+def test_key_changes_when_schema_changes() -> None:
+ assert _key() != _key(extracted_information_schema={"type": "object", "properties": {}})
+
+
+def test_key_changes_when_extracted_text_changes() -> None:
+ assert _key() != _key(extracted_text="Something else entirely")
+
+
+def test_key_changes_when_url_changes() -> None:
+ assert _key() != _key(current_url="https://example.com/other")
+
+
+def test_key_changes_when_error_code_mapping_changes() -> None:
+ # RFC review: error_code_mapping is rendered into the prompt,
+ # so it must be part of the key.
+ assert _key(error_code_mapping={"E1": "oops"}) != _key(error_code_mapping={"E1": "different"})
+
+
+def test_key_changes_when_previous_extracted_information_changes() -> None:
+ # RFC review: previous_extracted_information is rendered into the prompt as
+ # prior context. In a loop where each iteration is a fresh task so
+ # this is None on step 1 — the cross-iteration cache hits still land —
+ # but if an intra-task second-step extraction happens, the key must change.
+ assert _key(previous_extracted_information=None) != _key(previous_extracted_information={"prior": "value"})
+
+
+def test_key_changes_when_llm_key_changes() -> None:
+ # RFC review: include llm_key so swapping models forces a fresh extraction
+ # once this cache is backed by an off-process store.
+ assert _key(llm_key="gpt-4o") != _key(llm_key="claude-sonnet-4-6")
+
+
+def test_key_is_stable_across_equivalent_schema_dict_orderings() -> None:
+ schema_a = {"type": "object", "properties": {"a": {"type": "string"}, "b": {"type": "string"}}}
+ schema_b = {"properties": {"b": {"type": "string"}, "a": {"type": "string"}}, "type": "object"}
+ assert _key(extracted_information_schema=schema_a) == _key(extracted_information_schema=schema_b)
+
+
+def test_get_returns_none_on_miss() -> None:
+ assert extraction_cache.get("wfr_1", _key()) is None
+
+
+def test_set_then_get_returns_stored_value() -> None:
+ key = _key()
+ extraction_cache.store("wfr_1", key, {"docs": ["a.pdf"]})
+ assert extraction_cache.get("wfr_1", key) == {"docs": ["a.pdf"]}
+
+
+def test_cache_is_isolated_per_workflow_run_id() -> None:
+ key = _key()
+ extraction_cache.store("wfr_1", key, {"docs": ["a.pdf"]})
+ assert extraction_cache.get("wfr_2", key) is None
+
+
+def test_empty_workflow_run_id_bypasses_cache() -> None:
+ key = _key()
+ extraction_cache.store(None, key, {"docs": ["a.pdf"]})
+ assert extraction_cache.get(None, key) is None
+
+
+def test_clear_workflow_run_drops_entries() -> None:
+ key = _key()
+ extraction_cache.store("wfr_1", key, {"docs": ["a.pdf"]})
+ extraction_cache.clear_workflow_run("wfr_1")
+ assert extraction_cache.get("wfr_1", key) is None
+
+
+def test_fifo_eviction_when_run_cache_is_full() -> None:
+ # Insert MAX + 1 distinct entries; the oldest should be evicted.
+ max_entries = extraction_cache._MAX_ENTRIES_PER_RUN
+ first_key = _key(current_url="https://example.com/0")
+ extraction_cache.store("wfr_1", first_key, {"i": 0})
+ for i in range(1, max_entries + 1):
+ k = _key(current_url=f"https://example.com/{i}")
+ extraction_cache.store("wfr_1", k, {"i": i})
+
+ assert extraction_cache.get("wfr_1", first_key) is None
+ last_key = _key(current_url=f"https://example.com/{max_entries}")
+ assert extraction_cache.get("wfr_1", last_key) == {"i": max_entries}
+
+
+def test_store_and_get_list_result() -> None:
+ """Extraction schemas with array roots produce list results — these must be cached too."""
+ key = _key()
+ extraction_cache.store("wfr_1", key, [{"doc": "a.pdf"}, {"doc": "b.pdf"}])
+ assert extraction_cache.get("wfr_1", key) == [{"doc": "a.pdf"}, {"doc": "b.pdf"}]
+
+
+def test_store_and_get_string_result() -> None:
+ """Some extractions return a plain string — these must be cached too."""
+ key = _key()
+ extraction_cache.store("wfr_1", key, "plain text extraction")
+ assert extraction_cache.get("wfr_1", key) == "plain text extraction"
+
+
+def test_key_changes_when_local_date_changes() -> None:
+ """Date-relative extraction goals must miss when the date changes (midnight boundary)."""
+ assert _key(local_datetime="2026-04-10T00:00:00") != _key(local_datetime="2026-04-11T00:00:00")
+
+
+def test_key_stable_across_same_date_different_times() -> None:
+ """Same date with different timestamps should produce the same key (truncated to date)."""
+ assert _key(local_datetime="2026-04-10T08:30:00.123456") == _key(local_datetime="2026-04-10T23:59:59.999999")
+
+
+def test_none_and_empty_string_produce_different_keys() -> None:
+ """None and '' are distinct states and must not collide in the cache key."""
+ assert _key(extracted_text=None) != _key(extracted_text="")
+ assert _key(current_url=None) != _key(current_url="")
+ assert _key(data_extraction_goal=None) != _key(data_extraction_goal="")
+
+
+def test_rendered_prompt_path_identical_prompts_hit() -> None:
+ """Two calls with the same rendered prompt should produce the same key."""
+ prompt = "Extract docs.\nCurrent datetime, ISO format:\n2026-04-10T08:00:00\nDone."
+ key1 = extraction_cache.compute_cache_key(rendered_prompt=prompt, llm_key="gpt-4o")
+ key2 = extraction_cache.compute_cache_key(rendered_prompt=prompt, llm_key="gpt-4o")
+ assert key1 == key2
+
+
+def test_rendered_prompt_path_different_prompts_miss() -> None:
+ """Different rendered prompts must produce different keys."""
+ p1 = "Extract docs from list A\n2026-04-10T08:00:00"
+ p2 = "Extract docs from list B\n2026-04-10T08:00:00"
+ assert extraction_cache.compute_cache_key(rendered_prompt=p1) != extraction_cache.compute_cache_key(
+ rendered_prompt=p2
+ )
+
+
+def test_rendered_prompt_normalizes_timestamp_line() -> None:
+ """Same-day prompts with different ISO timestamps should hash identically."""
+ p1 = "Header\n2026-04-10T08:30:15.123456\nFooter"
+ p2 = "Header\n2026-04-10T23:59:59.999999\nFooter"
+ assert extraction_cache.compute_cache_key(rendered_prompt=p1) == extraction_cache.compute_cache_key(
+ rendered_prompt=p2
+ )
+
+
+def test_rendered_prompt_midnight_crossing_produces_miss() -> None:
+ """Different dates in the rendered prompt timestamp must produce different keys."""
+ p1 = "Header\n2026-04-10T23:59:59\nFooter"
+ p2 = "Header\n2026-04-11T00:00:01\nFooter"
+ assert extraction_cache.compute_cache_key(rendered_prompt=p1) != extraction_cache.compute_cache_key(
+ rendered_prompt=p2
+ )
+
+
+def test_rendered_prompt_llm_key_affects_hash() -> None:
+ """Same rendered prompt with different llm_key should produce different keys."""
+ prompt = "Extract docs\n2026-04-10T08:00:00"
+ k1 = extraction_cache.compute_cache_key(rendered_prompt=prompt, llm_key="gpt-4o")
+ k2 = extraction_cache.compute_cache_key(rendered_prompt=prompt, llm_key="claude-sonnet-4-6")
+ assert k1 != k2
+
+
+def test_get_refreshes_lru_position() -> None:
+ """A cache hit should refresh the run's LRU position, preventing eviction."""
+ max_runs = extraction_cache._MAX_WORKFLOW_RUNS
+ key = _key()
+
+ # Fill the global cache to capacity: wfr_oldest first, then wfr_1..wfr_(N-1).
+ extraction_cache.store("wfr_oldest", key, {"v": 0})
+ for i in range(1, max_runs):
+ extraction_cache.store(f"wfr_{i}", key, {"v": i})
+
+ # Cache is at capacity. wfr_oldest is the LRU candidate.
+ # A get() hit should refresh its position to most-recent.
+ assert extraction_cache.get("wfr_oldest", key) == {"v": 0}
+
+ # Adding one more run triggers eviction. Without the LRU refresh,
+ # wfr_oldest would be evicted; with it, wfr_1 (now the oldest) goes.
+ extraction_cache.store("wfr_new", key, {"v": 999})
+
+ assert extraction_cache.get("wfr_oldest", key) == {"v": 0}
+ assert extraction_cache.get("wfr_1", key) is None # evicted