Add cached field to response and improve metrics

- Add 'cached' boolean field to ExplainResponse to indicate cache hits
- Fix get_cached_response to properly mark responses as cached
- Add metrics to distinguish cached vs fresh responses:
  - ClaudeExplainCachedResponse for cache hits
  - ClaudeExplainFreshResponse for API calls
  - 'cached' property on all requests for filtering
- Update documentation to show cached field in response

This allows monitoring cache effectiveness and helps users understand
when responses are served from cache.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: mattgodbolt

README.md

@@ -142,7 +142,8 @@ uv run ruff format
     "input_cost": 0.000123,
     "output_cost": 0.000456,
     "total_cost": 0.000579
-  }
+  },
+  "cached": false
 }
 ```
 

app/cache.py

@@ -185,7 +185,10 @@ async def get_cached_response(
 
     try:
         # Convert cached dict back to ExplainResponse
-        return ExplainResponse(**cached_data)
+        response = ExplainResponse(**cached_data)
+        # Mark this response as cached
+        response.cached = True
+        return response
     except Exception as e:
         LOGGER.warning(f"Error deserializing cached response: {e}")
         return None

app/explain.py

@@ -50,7 +50,9 @@ async def process_request(
             metrics_provider.set_property("language", body.language)
             metrics_provider.set_property("compiler", body.compiler)
             metrics_provider.set_property("instructionSet", body.instructionSet or "unknown")
+            metrics_provider.set_property("cached", "true")
             metrics_provider.put_metric("ClaudeExplainRequest", 1)
+            metrics_provider.put_metric("ClaudeExplainCachedResponse", 1)
 
             return cached_response
 
@@ -107,7 +109,9 @@ async def _call_anthropic_api(
     metrics_provider.set_property("language", body.language)
     metrics_provider.set_property("compiler", body.compiler)
     metrics_provider.set_property("instructionSet", body.instructionSet or "unknown")
+    metrics_provider.set_property("cached", "false")
     metrics_provider.put_metric("ClaudeExplainRequest", 1)
+    metrics_provider.put_metric("ClaudeExplainFreshResponse", 1)
 
     # Track token usage
     metrics_provider.put_metric("ClaudeExplainInputTokens", input_tokens)
@@ -129,4 +133,5 @@ async def _call_anthropic_api(
             output_cost=round(output_cost, 6),
             total_cost=round(total_cost, 6),
         ),
+        cached=False,  # This is a fresh response from the API
     )

app/explain_api.py

@@ -84,6 +84,7 @@ class ExplainResponse(BaseModel):
     model: str | None = Field(None, description="The Claude model used")
     usage: TokenUsage | None = Field(None, description="Token usage information")
     cost: CostBreakdown | None = Field(None, description="Cost breakdown")
+    cached: bool = Field(default=False, description="Whether this response was served from cache")
 
 
 class ExplainErrorResponse(BaseModel):

app/test_cache.py

@@ -292,6 +292,7 @@ async def test_get_cached_response_cache_hit(self, sample_request, test_prompt,
         assert result is not None
         assert result.status == "success"
         assert result.explanation == "This function implements a square operation..."
+        assert result.cached is True
         mock_cache.get.assert_called_once()
 
     @pytest.mark.asyncio

app/test_explain.py

@@ -102,6 +102,9 @@ async def test_process_request_success(self, sample_request, mock_anthropic_clie
         assert isinstance(response.cost.output_cost, float)
         assert isinstance(response.cost.total_cost, float)
 
+        # Check cached flag
+        assert response.cached is False  # Should not be cached on first request
+
         # Verify the mock was called correctly
         mock_anthropic_client.messages.create.assert_called_once()
         args, kwargs = mock_anthropic_client.messages.create.call_args