docs(adaptive): describe logical keying; keep string key_strategy inputs

Address CodeRabbit review on #818.

- Replace the stale "exact-match" wording on `AdaptiveConfig.response_cache`,
  `ResponseCacheConfig`, `KeyOutcome::Key`, and the `response_cache` module
  doc, and add a TOML `key_strategy = "logical"` example to the
  `ResponseCacheConfig` doc comment.
- `ResponseCacheConfig.to_dict()` in Python no longer raises `AttributeError`
  when `key_strategy` is a plain wire string. Enum members serialize through
  `.value`; strings pass through unchanged so unsupported values reach native
  validation with the `response_cache.unsupported_key_strategy` diagnostic,
  matching the Go string alias and the Node.js runtime.
- Add Python regression coverage for the string and unsupported-string paths.

The user-facing docs under `docs/configure-plugins/adaptive/response-cache.mdx`
stay deferred to #819, which is open for exactly that.

Signed-off-by: Zhongxuan (Daniel) Wang <52872691+ZhongxuanWang@users.noreply.github.com>

Author: ZhongxuanWang

crates/adaptive/src/config.rs

@@ -34,8 +34,11 @@ pub struct AdaptiveConfig {
     /// Adaptive Cache Governor settings.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub acg: Option<AcgComponentConfig>,
-    /// Opt-in exact-match LLM response and tool-result cache. When present,
-    /// the adaptive plugin installs the response-cache execution intercept(s).
+    /// Opt-in LLM response and tool-result cache. When present, the adaptive
+    /// plugin installs the response-cache execution intercept(s). Reuse
+    /// requires the same normalized request under the default
+    /// `key_strategy = "exact_request"`; `"logical"` additionally ignores
+    /// tool-description wording and tool ordering.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub response_cache: Option<ResponseCacheConfig>,
     /// Adaptive-local unsupported-config policy.
@@ -191,8 +194,21 @@ impl Default for AcgComponentConfig {
     }
 }
 
-/// Configuration for the adaptive plugin's exact-match LLM response and
-/// opt-in tool-result cache feature.
+/// Configuration for the adaptive plugin's LLM response and opt-in
+/// tool-result cache feature.
+///
+/// Keys derive from the normalized request. `key_strategy` selects how much
+/// of that request stays key-significant:
+///
+/// ```toml
+/// [components.config.response_cache]
+/// namespace = "dev-harness"
+/// # "exact_request" (the default) requires the same normalized request.
+/// # "logical" additionally lets reuse survive tool-description edits and
+/// # tool reordering; tool names, parameter schemas, and every other request
+/// # field stay key-significant. The two strategies never share entries.
+/// key_strategy = "logical"
+/// ```
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(default)]
 pub struct ResponseCacheConfig {

crates/adaptive/src/lib.rs

@@ -34,7 +34,7 @@ pub mod learner;
 pub mod plugin_component;
 #[cfg(feature = "redis-backend")]
 pub mod redis;
-/// Opt-in exact-match LLM response and tool-result cache.
+/// Opt-in LLM response and tool-result cache with exact-request or logical keying.
 pub mod response_cache;
 mod runtime;
 /// Storage backends and backend traits for adaptive state persistence.

crates/adaptive/src/response_cache/key.rs

@@ -40,7 +40,7 @@ const INTERNAL_DISPATCH_BACKEND_HEADER: &str = "x-nemo-relay-internal-dispatch-b
 /// Result of deriving a cache key for a request.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub enum KeyOutcome {
-    /// A usable exact-match key fingerprint (`"sha256:…"`).
+    /// A usable key fingerprint (`"sha256:…"`).
     Key(String),
     /// The request is intentionally not cacheable; the reason is a short,
     /// stable label suitable for telemetry.

python/nemo_relay/adaptive.py

@@ -394,7 +394,9 @@ class ResponseCacheConfig:
         bypass_rate: Probability in ``[0.0, 1.0]`` of skipping the cache and running live.
         cache_nondeterministic: Cache nondeterministic requests too; ``False``
             caches only requests explicitly pinned deterministic (``temperature`` = 0).
-        key_strategy: Typed key derivation strategy.
+        key_strategy: Typed key derivation strategy. A plain wire string is
+            passed through unchanged so unsupported values reach validation
+            with a field-specific diagnostic.
         header_allowlist: Request headers folded into the key; never auth headers.
         backend: Cache storage backend (``in_memory`` or ``redis``).
         tools: Opt-in tool-result cache; ``None`` leaves it off.
@@ -419,7 +421,11 @@ def to_dict(self) -> JsonObject:
                 "priority": self.priority,
                 "bypass_rate": self.bypass_rate,
                 "cache_nondeterministic": self.cache_nondeterministic,
-                "key_strategy": self.key_strategy.value,
+                "key_strategy": (
+                    self.key_strategy.value
+                    if isinstance(self.key_strategy, ResponseCacheKeyStrategy)
+                    else self.key_strategy
+                ),
                 "header_allowlist": self.header_allowlist,
                 "backend": _normalize(self.backend),
                 "tools": _normalize(self.tools),

python/nemo_relay/adaptive.pyi

@@ -247,7 +247,9 @@ class ResponseCacheConfig:
         bypass_rate: Probability in ``[0.0, 1.0]`` of skipping the cache and running live.
         cache_nondeterministic: Cache nondeterministic requests too; ``False``
             caches only requests explicitly pinned deterministic (``temperature`` = 0).
-        key_strategy: Typed key derivation strategy.
+        key_strategy: Typed key derivation strategy. A plain wire string is
+            passed through unchanged so unsupported values reach validation
+            with a field-specific diagnostic.
         header_allowlist: Request headers folded into the key.
         backend: Cache storage backend (``in_memory`` or ``redis``).
         tools: Opt-in tool-result cache; ``None`` leaves the tool surface off.

python/tests/test_adaptive_config.py

@@ -181,6 +181,26 @@ def test_response_cache_key_strategy_enum_serializes(self):
 
         assert config.to_dict()["key_strategy"] == "logical"
 
+    def test_response_cache_key_strategy_string_serializes(self):
+        config = ResponseCacheConfig(
+            namespace="logical-cache",
+            key_strategy=cast(ResponseCacheKeyStrategy, "logical"),
+        )
+
+        assert config.to_dict()["key_strategy"] == "logical"
+
+    def test_response_cache_unsupported_key_strategy_string_reaches_validation(self):
+        config = ResponseCacheConfig(
+            namespace="unsupported-strategy",
+            key_strategy=cast(ResponseCacheKeyStrategy, "semantic"),
+        )
+
+        assert config.to_dict()["key_strategy"] == "semantic"
+
+        report = plugin.validate(plugin.PluginConfig(components=[ComponentSpec(AdaptiveConfig(response_cache=config))]))
+        codes = {diag["code"] for diag in report["diagnostics"]}
+        assert "response_cache.unsupported_key_strategy" in codes
+
     def test_response_cache_default_preserves_positional_policy_argument(self):
         policy = ConfigPolicy(unknown_field="error")
         config = AdaptiveConfig(1, None, None, None, None, None, None, policy)