feat(adaptive): add logical response cache keys (#818)

#### Overview

Adds a logical key strategy for LLM response caching so description-only edits and tool-definition reordering do not invalidate otherwise compatible cache entries.

- [x] I confirm this contribution is my own work, or I have the right to submit it under this project's license.
- [x] I searched existing issues and open pull requests, and this does not duplicate existing work.

#### Details

- Adds `key_strategy = "logical"`, which recursively removes string-valued tool-description fields and canonically sorts the request's tool definitions before keying. Tool names, parameter schemas, constraints, settings, and every non-tool request field remain key-significant.
- Keeps `logical` and `exact_request` entries in separate keyspaces.
- Exposes typed response-cache key strategy values in Rust, Python, Node.js, and Go, while preserving the existing string wire format and field-specific diagnostics for unknown values.
- Adds unit and end-to-end coverage for description changes, tool ordering, interface changes, built-in tools, parameter enums, and strategy partitioning.
- Documentation is tracked separately in #819.
- Breaking changes: the typed Rust, Python, and Go `ResponseCacheConfig.key_strategy` helpers now use a strategy type instead of a plain string; the JSON/TOML wire values remain unchanged. The Node.js TypeScript surface narrows the field from `string` to the supported strategy union.
- Validation:
  - `cargo fmt --all -- --check`
  - `cargo test -p nemo-relay-adaptive`
  - `just test-rust`
  - `cargo clippy --workspace --all-targets -- -D warnings`
  - `just test-python` (686 passed)
  - `just test-node` (391 passed)
  - `just test-go`
  - `uv run pre-commit run --all-files`
  - `uv run pre-commit run --files <changed code files>`

#### Where should the reviewer start?

Start with `build_cache_key` and `structural_tool_schema` in `crates/adaptive/src/response_cache/key.rs`, then review the logical-key cases in `crates/adaptive/tests/unit/response_cache/key_tests.rs`.

#### Related Issues: (use one of the action keywords Closes / Fixes / Resolves / Relates to)

- Relates to #597
- Relates to #598
- Relates to #819



## Summary by CodeRabbit

* **New Features**
  * Added a logical response-cache key strategy that reuses cached responses when tool descriptions or ordering change without affecting tool behavior.
  * Added typed key-strategy options across Rust, Node.js, Go, and Python integrations.
  * Added configuration support for `exact_request` and `logical`, with exact-request caching as the default.
* **Bug Fixes**
  * Unsupported strategies now produce clearer validation errors listing supported options.
* **Tests**
  * Expanded coverage for serialization, configuration, schema handling, and logical cache-key behavior.

Authors:
  - Zhongxuan (Daniel) Wang (https://github.com/zhongxuanwang-nv)
  - Will Killian (https://github.com/willkill07)
  - Zhongxuan (Daniel) Wang (https://github.com/ZhongxuanWang)

Approvers:
  - Will Killian (https://github.com/willkill07)

URL: #818

Author: zhongxuanwang-nv

crates/adaptive/src/config.rs

@@ -7,7 +7,7 @@ use nemo_relay::plugin::ConfigPolicy;
 use serde::{Deserialize, Serialize};
 use serde_json::{Map, Value as Json};
 
-use crate::response_cache::config::{BackendConfig, KEY_STRATEGY_EXACT_REQUEST, ToolCacheConfig};
+use crate::response_cache::config::{BackendConfig, ResponseCacheKeyStrategy, ToolCacheConfig};
 
 /// Canonical config document for the adaptive plugin component.
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -34,7 +34,7 @@ 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,
+    /// Opt-in LLM response and tool-result cache. When present,
     /// the adaptive plugin installs the response-cache execution intercept(s).
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub response_cache: Option<ResponseCacheConfig>,
@@ -191,7 +191,7 @@ impl Default for AcgComponentConfig {
     }
 }
 
-/// Configuration for the adaptive plugin's exact-match LLM response and
+/// Configuration for the adaptive plugin's LLM response and
 /// opt-in tool-result cache feature.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(default)]
@@ -212,8 +212,8 @@ pub struct ResponseCacheConfig {
     /// requests explicitly pinned deterministic (`temperature` = 0) — absent
     /// or unreadable temperatures count as nondeterministic.
     pub cache_nondeterministic: bool,
-    /// Key strategy. Only [`KEY_STRATEGY_EXACT_REQUEST`] is supported.
-    pub key_strategy: String,
+    /// Typed key-derivation strategy.
+    pub key_strategy: ResponseCacheKeyStrategy,
     /// Request headers (case-insensitive) folded into the key; never auth headers.
     pub header_allowlist: Vec<String>,
     /// Storage backend selection.
@@ -231,7 +231,7 @@ impl Default for ResponseCacheConfig {
             priority: 50,
             bypass_rate: 0.0,
             cache_nondeterministic: false,
-            key_strategy: KEY_STRATEGY_EXACT_REQUEST.to_string(),
+            key_strategy: ResponseCacheKeyStrategy::ExactRequest,
             header_allowlist: Vec::new(),
             backend: BackendConfig::default(),
             tools: None,
@@ -402,7 +402,7 @@ nemo_relay::editor_config! {
         priority => { label: "priority", kind: Integer },
         bypass_rate => { label: "bypass_rate", kind: Float },
         cache_nondeterministic => { label: "cache_nondeterministic", kind: Boolean },
-        key_strategy => { label: "key_strategy", kind: String },
+        key_strategy => { label: "key_strategy", kind: Enum, values: ["exact_request", "logical"] },
         header_allowlist => { label: "header_allowlist", kind: Json },
         backend => {
             label: "backend",

crates/adaptive/src/lib.rs

@@ -57,8 +57,8 @@ pub use context_helpers::{
 pub use error::{AdaptiveError, Result};
 #[cfg(feature = "redis-backend")]
 pub use redis::RedisBackend;
-pub use response_cache::RESPONSE_CACHE_MARK;
 pub use response_cache::config::{ToolCacheConfig, ToolClass, ToolOverride};
+pub use response_cache::{RESPONSE_CACHE_MARK, ResponseCacheKeyStrategy};
 pub use runtime::features::AdaptiveRuntime;
 pub use storage::erased::AnyBackend;
 pub use storage::memory::InMemoryBackend;

crates/adaptive/src/response_cache/config.rs

@@ -11,11 +11,69 @@
 
 use std::collections::BTreeMap;
 
-use serde::{Deserialize, Serialize};
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use serde_json::{Map, Value as Json};
 
-/// Exact-request key strategy identifier.
-pub const KEY_STRATEGY_EXACT_REQUEST: &str = "exact_request";
+/// Strategy for deriving an LLM response-cache key.
+///
+/// The `Unknown` variant preserves an unsupported JSON/TOML value long enough
+/// for configuration validation to report it with a field-specific diagnostic.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub enum ResponseCacheKeyStrategy {
+    /// Key on the normalized request exactly.
+    #[default]
+    ExactRequest,
+    /// Normalize tool schemas structurally while preserving their interface.
+    Logical,
+    /// A wire value not supported by this Relay build.
+    Unknown(String),
+}
+
+impl ResponseCacheKeyStrategy {
+    /// Stable JSON/TOML representation of this strategy.
+    pub fn as_str(&self) -> &str {
+        match self {
+            Self::ExactRequest => "exact_request",
+            Self::Logical => "logical",
+            Self::Unknown(value) => value,
+        }
+    }
+}
+
+impl From<&str> for ResponseCacheKeyStrategy {
+    fn from(value: &str) -> Self {
+        match value {
+            "exact_request" => Self::ExactRequest,
+            "logical" => Self::Logical,
+            _ => Self::Unknown(value.to_string()),
+        }
+    }
+}
+
+impl From<String> for ResponseCacheKeyStrategy {
+    fn from(value: String) -> Self {
+        Self::from(value.as_str())
+    }
+}
+
+impl Serialize for ResponseCacheKeyStrategy {
+    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+    where
+        S: Serializer,
+    {
+        serializer.serialize_str(self.as_str())
+    }
+}
+
+impl<'de> Deserialize<'de> for ResponseCacheKeyStrategy {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        let value = String::deserialize(deserializer)?;
+        Ok(Self::from(value))
+    }
+}
 
 /// Default in-memory byte budget: 256 MiB.
 pub const DEFAULT_MAX_BYTES: usize = 256 * 1024 * 1024;

crates/adaptive/src/response_cache/key.rs

@@ -25,6 +25,7 @@ use serde_json::{Map, Value as Json, json};
 use sha2::{Digest, Sha256};
 
 use crate::config::ResponseCacheConfig;
+use crate::response_cache::config::ResponseCacheKeyStrategy;
 use crate::response_cache::mark::CacheReason;
 use crate::response_cache::store::CACHE_SCHEMA_VERSION;
 
@@ -77,6 +78,13 @@ pub fn build_cache_key(
         normalize_tool_call_ids(object);
     }
 
+    if config.key_strategy == ResponseCacheKeyStrategy::Logical
+        && let Some(object) = body.as_object_mut()
+        && let Some(tools) = object.get("tools").cloned()
+    {
+        object.insert("tools".to_string(), structural_tool_schema(&tools));
+    }
+
     let header_allowlist = normalized_header_allowlist(&config.header_allowlist);
     let headers = cache_key_headers(&request.headers, &header_allowlist);
 
@@ -693,6 +701,48 @@ fn rewrite_id(id_value: &mut Json, mapping: &mut Map<String, Json>) {
     *id_value = Json::String(stable);
 }
 
+/// Fingerprint of the tool set for the `logical` strategy: each tool keeps its
+/// full definition minus string-valued `description` keys (stripped
+/// recursively), and the array is sorted so tool order does not key.
+fn structural_tool_schema(tools: &Json) -> Json {
+    let Some(array) = tools.as_array() else {
+        return tools.clone();
+    };
+    let mut entries: Vec<Json> = array
+        .iter()
+        .map(|tool| {
+            let mut entry = tool.clone();
+            strip_descriptions(&mut entry);
+            entry
+        })
+        .collect();
+    entries
+        .sort_by_cached_key(|entry| serde_json_canonicalizer::to_string(entry).unwrap_or_default());
+    Json::Array(entries)
+}
+
+/// Removes every string-valued `description` key, at any depth. A non-string
+/// value under that key (e.g. a schema property named `description`) is
+/// interface, not prose, and stays.
+fn strip_descriptions(value: &mut Json) {
+    match value {
+        Json::Object(object) => {
+            if object.get("description").is_some_and(Json::is_string) {
+                object.remove("description");
+            }
+            for nested in object.values_mut() {
+                strip_descriptions(nested);
+            }
+        }
+        Json::Array(items) => {
+            for item in items {
+                strip_descriptions(item);
+            }
+        }
+        _ => {}
+    }
+}
+
 #[cfg(test)]
 #[path = "../../tests/unit/response_cache/key_tests.rs"]
 mod tests;

crates/adaptive/src/response_cache/mod.rs

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-//! Opt-in exact-match cache for LLM responses and tool results: a feature of
+//! Opt-in cache for LLM responses and tool results: a feature of
 //! the adaptive plugin, configured through
 //! [`crate::config::AdaptiveConfig::response_cache`].
 //!
@@ -23,9 +23,7 @@ pub mod store;
 pub(crate) mod tool;
 
 pub use crate::config::ResponseCacheConfig;
-pub use crate::response_cache::config::{
-    BackendConfig, KEY_STRATEGY_EXACT_REQUEST, ToolCacheConfig,
-};
+pub use crate::response_cache::config::{BackendConfig, ResponseCacheKeyStrategy, ToolCacheConfig};
 pub(crate) use crate::response_cache::intercept::{make_intercept, make_stream_intercept};
 pub use crate::response_cache::mark::RESPONSE_CACHE_MARK;
 pub(crate) use crate::response_cache::store::build_store;

crates/adaptive/src/runtime/validation.rs

@@ -9,7 +9,7 @@ use nemo_relay::plugin::{
 use serde_json::Value as Json;
 
 use crate::config::{AdaptiveConfig, BackendSpec, ResponseCacheConfig};
-use crate::response_cache::config::{KEY_STRATEGY_EXACT_REQUEST, ToolCacheConfig, ToolClass};
+use crate::response_cache::config::{ResponseCacheKeyStrategy, ToolCacheConfig, ToolClass};
 use crate::response_cache::tool::{is_supported_tool_pattern, wildcard_patterns_overlap};
 
 pub fn validate_config(config: &AdaptiveConfig) -> ConfigReport {
@@ -123,11 +123,14 @@ fn validate_response_cache(report: &mut ConfigReport, config: &ResponseCacheConf
             "bypass_rate must be in [0.0, 1.0]".to_string(),
         ));
     }
-    if config.key_strategy != KEY_STRATEGY_EXACT_REQUEST {
+    if matches!(config.key_strategy, ResponseCacheKeyStrategy::Unknown(_)) {
         report.diagnostics.push(response_cache_error(
             "response_cache.unsupported_key_strategy",
             Some("key_strategy"),
-            format!("unsupported key_strategy; only \"{KEY_STRATEGY_EXACT_REQUEST}\" is supported"),
+            format!(
+                "unsupported key_strategy '{}'; supported: \"exact_request\", \"logical\"",
+                config.key_strategy.as_str()
+            ),
         ));
     }
     // Auth material must never enter the key or the stored entries.

crates/adaptive/tests/integration/response_cache_tests.rs

@@ -33,8 +33,8 @@ use nemo_relay::plugin::{
 };
 use nemo_relay_adaptive::plugin_component::{ComponentSpec, register_adaptive_component};
 use nemo_relay_adaptive::{
-    AcgComponentConfig, AdaptiveConfig, BackendSpec, ResponseCacheConfig, StateConfig,
-    ToolCacheConfig, ToolClass, ToolOverride,
+    AcgComponentConfig, AdaptiveConfig, BackendSpec, ResponseCacheConfig, ResponseCacheKeyStrategy,
+    StateConfig, ToolCacheConfig, ToolClass, ToolOverride,
 };
 use serde_json::{Value as Json, json};
 use tokio::sync::Mutex;
@@ -555,7 +555,7 @@ async fn invalid_config_is_rejected_by_validation() {
         response_cache: Some(ResponseCacheConfig {
             ttl_seconds: 0,
             bypass_rate: 2.0,
-            key_strategy: "semantic".to_string(),
+            key_strategy: ResponseCacheKeyStrategy::Unknown("semantic".to_string()),
             namespace: "invalid-config-test".to_string(),
             ..ResponseCacheConfig::default()
         }),
@@ -647,7 +647,7 @@ async fn response_cache_validation_diagnostics_identify_the_invalid_setting() {
 
     let mut cache = ResponseCacheConfig {
         namespace: "diagnostic-contract-test".to_string(),
-        key_strategy: "semantic".to_string(),
+        key_strategy: ResponseCacheKeyStrategy::Unknown("semantic".to_string()),
         tools: Some(ToolCacheConfig {
             enabled: true,
             default: ToolClass {
@@ -792,6 +792,50 @@ async fn hit_preserves_usage_on_the_end_event_and_reports_savings_on_the_mark()
     deregister_subscriber("response_cache_event_capture").unwrap();
 }
 
+#[tokio::test]
+async fn logical_strategy_reuses_across_reworded_tool_descriptions() {
+    let _guard = TEST_MUTEX.lock().await;
+    reset_global();
+    // `logical` must be accepted by validation (activate_cache asserts no
+    // diagnostics) and must reuse across a reworded tool description end-to-end.
+    activate_cache(ResponseCacheConfig {
+        namespace: "logical-key-integration-test".to_string(),
+        key_strategy: ResponseCacheKeyStrategy::Logical,
+        ..ResponseCacheConfig::default()
+    })
+    .await;
+
+    let calls = Arc::new(AtomicUsize::new(0));
+    let provider = counting_provider(Arc::clone(&calls), sample_body());
+
+    let request_with_tool = |description: &str| LlmRequest {
+        headers: serde_json::Map::new(),
+        content: json!({
+            "model": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
+            "messages": [{"role": "user", "content": "what is the weather?"}],
+            "temperature": 0.0,
+            "tools": [{"type": "function", "function": {
+                "name": "get_weather",
+                "description": description,
+                "parameters": {"type": "object", "properties": {"city": {"type": "string"}}}
+            }}]
+        }),
+    };
+
+    call(&provider, request_with_tool("Get the weather for a city.")).await;
+    call(
+        &provider,
+        request_with_tool("Look up the current weather (reworded)."),
+    )
+    .await;
+
+    assert_eq!(
+        calls.load(Ordering::SeqCst),
+        1,
+        "logical keying must serve the reworded-tool repeat from cache"
+    );
+}
+
 #[tokio::test]
 async fn errors_are_not_cached() {
     let _guard = TEST_MUTEX.lock().await;