Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(learn/gemini): stop double-counting session tokens (#2230)

Abhay Singh29d8a5e563cf
diff --git a/headroom/learn/plugins/gemini.py b/headroom/learn/plugins/gemini.py
index 9aac4116e..fd4722aa8 100644
--- a/headroom/learn/plugins/gemini.py
+++ b/headroom/learn/plugins/gemini.py
@@ -216,14 +216,15 @@ class GeminiPlugin(LearnPlugin, ConversationScanner):
usage = msg.get("usageMetadata", msg.get("usage", {}))
if isinstance(usage, dict):
+ # Gemini's promptTokenCount is the FULL input token count and
+ # cachedContentTokenCount is the cached SUBSET of it, so adding
+ # both double-counts the cached input. Likewise totalTokenCount
+ # == promptTokenCount + candidatesTokenCount, so
+ # (totalTokenCount - promptTokenCount) is just candidatesTokenCount
+ # again — adding it on top double-counts the output. Count the
+ # prompt as input and the candidates as output, once each.
total_input_tokens += usage.get("promptTokenCount", 0)
- total_input_tokens += usage.get("cachedContentTokenCount", 0)
total_output_tokens += usage.get("candidatesTokenCount", 0)
- total_output_tokens += (
- usage.get("totalTokenCount", 0) - usage.get("promptTokenCount", 0)
- if usage.get("totalTokenCount")
- else 0
- )
if not isinstance(parts, list):
continue
diff --git a/tests/test_learn/test_gemini_scanner.py b/tests/test_learn/test_gemini_scanner.py
index 441d0b9a5..fb04e0277 100644
--- a/tests/test_learn/test_gemini_scanner.py
+++ b/tests/test_learn/test_gemini_scanner.py
@@ -173,6 +173,30 @@ class TestJsonSessionParsing:
assert tc.output == "port: 8080\nhost: localhost"
assert not tc.is_error
+ def test_token_counts_not_double_counted(self, tmp_path):
+ # promptTokenCount is the full input (cachedContentTokenCount is a subset
+ # of it) and totalTokenCount == prompt + candidates, so the input must be
+ # promptTokenCount and the output candidatesTokenCount, each once.
+ gemini_dir, _ = _setup_gemini_dir(tmp_path)
+ scanner = GeminiScanner(gemini_dir=gemini_dir)
+ messages = [
+ {
+ "role": "model",
+ "parts": [{"text": "ok"}],
+ "usageMetadata": {
+ "promptTokenCount": 1000,
+ "cachedContentTokenCount": 300,
+ "candidatesTokenCount": 500,
+ "totalTokenCount": 1500,
+ },
+ },
+ ]
+
+ session = scanner._parse_messages("s1", messages)
+
+ assert session.total_input_tokens == 1000
+ assert session.total_output_tokens == 500
+
def test_multiple_tool_calls(self, tmp_path):
gemini_dir, chats_dir = _setup_gemini_dir(tmp_path)
session = _make_gemini_session(