Skip to content

The agent engineering platform.

fix(perplexity): map Responses API cache tokens into input_token_details (#39923)

Kodurdb0fb33f919dd
diff --git a/libs/partners/perplexity/langchain_perplexity/chat_models.py b/libs/partners/perplexity/langchain_perplexity/chat_models.py
index 6c42d9838c..e717c96f42 100644
--- a/libs/partners/perplexity/langchain_perplexity/chat_models.py
+++ b/libs/partners/perplexity/langchain_perplexity/chat_models.py
@@ -38,6 +38,7 @@ from langchain_core.messages import (
ToolMessageChunk,
)
from langchain_core.messages.ai import (
+ InputTokenDetails,
OutputTokenDetails,
UsageMetadata,
subtract_usage,
@@ -344,6 +345,10 @@ def _convert_responses_usage(usage: Any) -> UsageMetadata | None:
Returns `None` if `usage` itself is missing or if either token field is
absent — emitting zeroed `UsageMetadata` would silently undercount usage
in downstream cost dashboards.
+
+ Cache hits and cache writes reported under `input_tokens_details` are mapped
+ onto the standard `InputTokenDetails` slots so downstream consumers can tell
+ cached input from fresh input.
"""
if usage is None:
return None
@@ -354,10 +359,22 @@ def _convert_responses_usage(usage: Any) -> UsageMetadata | None:
total_tokens = _get_attr(usage, "total_tokens", None)
if total_tokens is None:
total_tokens = input_tokens + output_tokens
+
+ input_token_details: InputTokenDetails = {}
+ details = _get_attr(usage, "input_tokens_details", None)
+ if details is not None:
+ cache_read = _get_attr(details, "cache_read_input_tokens", None)
+ if cache_read is not None:
+ input_token_details["cache_read"] = cache_read
+ cache_creation = _get_attr(details, "cache_creation_input_tokens", None)
+ if cache_creation is not None:
+ input_token_details["cache_creation"] = cache_creation
+
return UsageMetadata(
input_tokens=input_tokens,
output_tokens=output_tokens,
total_tokens=total_tokens,
+ input_token_details=input_token_details,
)
diff --git a/libs/partners/perplexity/tests/unit_tests/test_chat_models_responses.py b/libs/partners/perplexity/tests/unit_tests/test_chat_models_responses.py
index 3faa3e26b4..6fa32d3189 100644
--- a/libs/partners/perplexity/tests/unit_tests/test_chat_models_responses.py
+++ b/libs/partners/perplexity/tests/unit_tests/test_chat_models_responses.py
@@ -850,6 +850,123 @@ def test_convert_responses_usage_derives_total_when_absent() -> None:
assert result["total_tokens"] == 12
+def test_convert_responses_usage_maps_cache_token_details() -> None:
+ details = _make_response_obj(
+ cache_read_input_tokens=800, cache_creation_input_tokens=150
+ )
+ usage = _make_response_obj(
+ input_tokens=1000,
+ output_tokens=50,
+ total_tokens=1050,
+ input_tokens_details=details,
+ )
+ result = _convert_responses_usage(usage)
+ assert result is not None
+ assert result["input_token_details"] == {"cache_read": 800, "cache_creation": 150}
+
+
+def test_convert_responses_usage_maps_cache_token_details_from_mapping() -> None:
+ """`_get_attr` accepts dict payloads, so a mapping must map identically."""
+ usage = {
+ "input_tokens": 1000,
+ "output_tokens": 50,
+ "total_tokens": 1050,
+ "input_tokens_details": {
+ "cache_read_input_tokens": 800,
+ "cache_creation_input_tokens": 150,
+ },
+ }
+ result = _convert_responses_usage(usage)
+ assert result is not None
+ assert result["input_token_details"] == {"cache_read": 800, "cache_creation": 150}
+
+
+def test_convert_responses_usage_maps_only_reported_cache_fields() -> None:
+ details = _make_response_obj(
+ cache_read_input_tokens=800, cache_creation_input_tokens=None
+ )
+ usage = _make_response_obj(
+ input_tokens=1000,
+ output_tokens=50,
+ total_tokens=1050,
+ input_tokens_details=details,
+ )
+ result = _convert_responses_usage(usage)
+ assert result is not None
+ assert result["input_token_details"] == {"cache_read": 800}
+
+
+def test_convert_responses_usage_omits_cache_details_when_not_reported() -> None:
+ usage = _make_response_obj(input_tokens=10, output_tokens=2, total_tokens=12)
+ result = _convert_responses_usage(usage)
+ assert result is not None
+ assert result["input_token_details"] == {}
+
+
+def test_convert_responses_to_chat_result_includes_cache_token_details() -> None:
+ details = _make_response_obj(
+ cache_read_input_tokens=800, cache_creation_input_tokens=150
+ )
+ usage = _make_response_obj(
+ input_tokens=1000,
+ output_tokens=50,
+ total_tokens=1050,
+ input_tokens_details=details,
+ )
+ response = _make_response_obj(
+ id="resp_cache",
+ model="sonar-pro",
+ status="completed",
+ object="response",
+ output_text="hi",
+ output=[],
+ usage=usage,
+ citations=None,
+ images=None,
+ related_questions=None,
+ search_results=None,
+ )
+
+ result = _convert_responses_to_chat_result(response)
+ message = result.generations[0].message
+
+ assert isinstance(message, AIMessage)
+ assert message.usage_metadata is not None
+ assert message.usage_metadata["input_token_details"] == {
+ "cache_read": 800,
+ "cache_creation": 150,
+ }
+
+
+def test_stream_event_conversion_for_completed_includes_cache_token_details() -> None:
+ details = _make_response_obj(
+ cache_read_input_tokens=800, cache_creation_input_tokens=150
+ )
+ usage = _make_response_obj(
+ input_tokens=1000,
+ output_tokens=50,
+ total_tokens=1050,
+ input_tokens_details=details,
+ )
+ response = _make_response_obj(
+ id="resp_cache_stream",
+ model="sonar-pro",
+ status="completed",
+ object="response",
+ usage=usage,
+ )
+ chunk = _convert_responses_stream_event_to_chunk(
+ _make_event("response.completed", response=response)
+ )
+ assert chunk is not None
+ assert isinstance(chunk.message, AIMessageChunk)
+ assert chunk.message.usage_metadata is not None
+ assert chunk.message.usage_metadata["input_token_details"] == {
+ "cache_read": 800,
+ "cache_creation": 150,
+ }
+
+
# ---------------------------------------------------------------------------
# Error and edge cases in conversion / streaming
# ---------------------------------------------------------------------------