feat(adaptive): add logical response cache keys

[zhongxuanwang-nv]

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.

• I confirm this contribution is my own work, or I have the right to submit it under this project's license.
• 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 docs(adaptive): document logical response cache keys #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 feat(adaptive): add opt-in caching for tool results #597
• Relates to docs(adaptive): document opt-in tool result caching #598
• Relates to docs(adaptive): document logical response cache keys #819

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Enterprise

Run ID: 307ef1c3-dd66-48e8-9a54-e8a9bd6637f7

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Fern docs preview: https://nvidia-preview-pull-request-818.docs.buildwithfern.com/nemo/relay/dev