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(toin): skip a malformed pattern instead of aborting the store load (#4484)

Ayush Kumar Jha8b628d968574
diff --git a/headroom/telemetry/toin.py b/headroom/telemetry/toin.py
index ccf62f2d1..acabba41c 100644
--- a/headroom/telemetry/toin.py
+++ b/headroom/telemetry/toin.py
@@ -68,7 +68,7 @@ import threading
import time
import warnings
from collections.abc import Callable
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, fields
from typing import Any, Final
from .models import FieldSemantics, ToolSignature
@@ -409,9 +409,16 @@ class ToolPattern:
"last_updated",
}
filtered = {k: v for k, v in data.items() if k in valid_fields}
+ # A value of the wrong kind (a string where a list belongs) would be
+ # accepted as-is and then iterated or added to when patterns merge.
+ for name, value in filtered.items():
+ if not isinstance(value, _PATTERN_FIELD_KINDS.get(name, object)):
+ raise TypeError(f"{name} is a {type(value).__name__}")
# Handle seen_instance_hashes (serialized without underscore prefix)
seen_hashes = data.get("seen_instance_hashes", [])
+ if not isinstance(seen_hashes, list) or not all(isinstance(h, str) for h in seen_hashes):
+ raise TypeError("seen_instance_hashes is not a list of strings")
pattern = cls(**filtered)
pattern._seen_instance_hashes = seen_hashes[:100] # Limit on load
@@ -438,6 +445,38 @@ class ToolPattern:
return pattern
+# What each stored ToolPattern field may hold, by the base of its annotation.
+# Merges store some counts as floats, so numeric fields accept either.
+_KIND_BY_ANNOTATION: Final[dict[str, type | tuple[type, ...]]] = {
+ "str": str,
+ "int": (int, float),
+ "float": (int, float),
+ "bool": bool,
+ "list": list,
+ "dict": dict,
+}
+_PATTERN_FIELD_KINDS: Final[dict[str, type | tuple[type, ...]]] = {
+ f.name: _KIND_BY_ANNOTATION.get(str(f.type).split("[")[0], object) for f in fields(ToolPattern)
+}
+_PATTERN_CONTAINER_FIELDS: Final = tuple(
+ f.name for f in fields(ToolPattern) if f.default_factory in (list, dict, set)
+)
+
+
+def _detached_copy(pattern: ToolPattern) -> ToolPattern:
+ """Copy ``pattern`` so that merging into the copy leaves the original intact.
+
+ ``_merge_patterns`` reassigns scalars and adds to the pattern's lists, dicts
+ and sets, so those containers are the parts that need their own copies.
+ """
+ import copy
+
+ clone = copy.copy(pattern)
+ for name in _PATTERN_CONTAINER_FIELDS:
+ setattr(clone, name, getattr(pattern, name).copy())
+ return clone
+
+
@dataclass
class TOINConfig:
"""Configuration for the Tool Output Intelligence Network."""
@@ -1397,40 +1436,65 @@ class ToolIntelligenceNetwork:
patterns_data = data.get("patterns", {})
source_instance = data.get("instance_id", "unknown")
+ skipped = 0
+ first_error: Exception | None = None
with self._lock:
for serialized_key, pattern_dict in patterns_data.items():
- key = _deserialize_pattern_key(serialized_key)
- imported = ToolPattern.from_dict(pattern_dict)
- self._sanitize_loaded_pattern(imported)
- # Make sure dataclass fields agree with the dict key — pre-F3
- # dumps don't carry tenant_key on the pattern, and pre-B5
- # dumps don't carry auth_mode/model_family either; promote
- # from the (possibly default) key.
- imported.tenant_key = key[0]
- imported.auth_mode = key[1]
- imported.model_family = key[2]
-
- if key in self._patterns:
- # Merge with existing
- self._merge_patterns(self._patterns[key], imported)
- else:
- # Add new pattern - need to track source instance
- self._patterns[key] = imported
-
- # For NEW patterns from another instance, track the source in
- # _seen_instance_hashes so user_count reflects cross-user data
- if source_instance != self._instance_id:
- pattern = self._patterns[key]
- if source_instance not in pattern._seen_instance_hashes:
- # Limit storage to 100 unique instances to bound memory
- if len(pattern._seen_instance_hashes) < 100:
- pattern._seen_instance_hashes.append(source_instance)
- # CRITICAL: Always increment user_count (even after cap)
- pattern.user_count += 1
+ # Each entry is parsed, tracked and merged into a pattern that is
+ # only stored once all of that succeeds. One unreadable entry must
+ # not abort the rest (the store that did load would be saved over
+ # the whole file) or leave a half-merged pattern behind.
+ try:
+ key = _deserialize_pattern_key(serialized_key)
+ imported = ToolPattern.from_dict(pattern_dict)
+ self._sanitize_loaded_pattern(imported)
+ # Make sure dataclass fields agree with the dict key — pre-F3
+ # dumps don't carry tenant_key on the pattern, and pre-B5
+ # dumps don't carry auth_mode/model_family either; promote
+ # from the (possibly default) key.
+ imported.tenant_key = key[0]
+ imported.auth_mode = key[1]
+ imported.model_family = key[2]
+
+ existing = self._patterns.get(key)
+ if existing is not None:
+ # Merge with existing
+ pattern = _detached_copy(existing)
+ self._merge_patterns(pattern, imported)
+ else:
+ # Add new pattern - need to track source instance
+ pattern = imported
+
+ # For NEW patterns from another instance, track the source in
+ # _seen_instance_hashes so user_count reflects cross-user data
+ if source_instance != self._instance_id:
+ if source_instance not in pattern._seen_instance_hashes:
+ # Limit storage to 100 unique instances to bound memory
+ if len(pattern._seen_instance_hashes) < 100:
+ pattern._seen_instance_hashes.append(source_instance)
+ # CRITICAL: Always increment user_count (even after cap)
+ pattern.user_count += 1
+ except (AttributeError, TypeError, ValueError) as e:
+ skipped += 1
+ first_error = first_error or e
+ continue
+ self._patterns[key] = pattern
self._prune_patterns_locked()
self._dirty = True
+ if first_error is not None:
+ logger.warning(
+ "TOIN skipped malformed patterns on import",
+ extra={
+ "event": "toin_import_skipped",
+ "skipped": skipped,
+ "imported": len(patterns_data) - skipped,
+ "error_type": type(first_error).__name__,
+ "error": str(first_error),
+ },
+ )
+
def _merge_patterns(self, existing: ToolPattern, imported: ToolPattern) -> None:
"""Merge imported pattern into existing."""
total = existing.sample_size + imported.sample_size
diff --git a/tests/test_toin_retention.py b/tests/test_toin_retention.py
index c43f95c05..75f54a324 100644
--- a/tests/test_toin_retention.py
+++ b/tests/test_toin_retention.py
@@ -3,6 +3,9 @@
from __future__ import annotations
import json
+import logging
+
+import pytest
from headroom.telemetry.backends.filesystem import FileSystemTOINBackend
from headroom.telemetry.models import ToolSignature
@@ -83,6 +86,150 @@ def test_legacy_raw_query_keys_are_removed_on_load(tmp_path) -> None:
assert pattern.common_query_patterns == ["status:* user:*"]
+def _record(toin: ToolIntelligenceNetwork, index: int) -> None:
+ toin.record_compression(
+ tool_signature=_signature(index),
+ original_count=10,
+ compressed_count=5,
+ original_tokens=100,
+ compressed_tokens=50,
+ strategy="test",
+ )
+
+
+def _saved_store(path, count: int) -> dict:
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=0))
+ for index in range(count):
+ _record(toin, index)
+ toin.save()
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _skip_warnings(caplog) -> list[logging.LogRecord]:
+ return [r for r in caplog.records if getattr(r, "event", None) == "toin_import_skipped"]
+
+
+ "corrupt",
+ [
+ lambda entry: {k: v for k, v in entry.items() if k != "tool_signature_hash"},
+ lambda entry: {**entry, "field_semantics": {"field_1": "not a dict"}},
+ lambda entry: {**entry, "query_pattern_frequency": "not a dict"},
+ lambda entry: {**entry, "query_pattern_frequency": {"status:*": "many"}},
+ lambda entry: {**entry, "seen_instance_hashes": "bad"},
+ lambda entry: {**entry, "commonly_retrieved_fields": "abc"},
+ lambda entry: {**entry, "sample_size": "x"},
+ lambda entry: "not a pattern",
+ ],
+ ids=[
+ "missing_signature_hash",
+ "bad_field_semantics",
+ "bad_query_frequencies",
+ "bad_query_count",
+ "tracking_list_is_a_string",
+ "list_field_is_a_string",
+ "count_is_a_string",
+ "not_a_dict",
+ ],
+)
+def test_malformed_pattern_does_not_drop_the_rest_of_the_store(tmp_path, caplog, corrupt) -> None:
+ path = tmp_path / "toin.json"
+ data = _saved_store(path, 5)
+ keys = list(data["patterns"])
+ data["patterns"][keys[1]] = corrupt(data["patterns"][keys[1]])
+ path.write_text(json.dumps(data), encoding="utf-8")
+
+ with caplog.at_level(logging.WARNING, logger="headroom.telemetry.toin"):
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=0))
+
+ assert len(toin._patterns) == 4
+ [warning] = _skip_warnings(caplog)
+ assert warning.skipped == 1
+ assert warning.imported == 4
+
+ # The next save used to write only the patterns read before the bad one.
+ _record(toin, 99)
+ toin.save()
+ saved = json.loads(path.read_text(encoding="utf-8"))["patterns"]
+ assert set(keys) - {keys[1]} <= set(saved)
+ assert len(saved) == 5
+
+
+def test_foreign_store_keeps_the_healthy_entries_after_a_malformed_one(tmp_path, caplog) -> None:
+ path = tmp_path / "toin.json"
+ data = _saved_store(path, 3)
+ keys = list(data["patterns"])
+ # A string tracking list used to pass from_dict and then fail on .append()
+ # while tracking the foreign source, outside the per-entry guard.
+ data["patterns"][keys[0]]["seen_instance_hashes"] = "bad"
+ data["instance_id"] = "foreign-instance"
+ path.write_text(json.dumps(data), encoding="utf-8")
+
+ with caplog.at_level(logging.WARNING, logger="headroom.telemetry.toin"):
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=0))
+
+ assert len(toin._patterns) == 2
+ [warning] = _skip_warnings(caplog)
+ assert warning.skipped == 1
+ assert all("foreign-instance" in p._seen_instance_hashes for p in toin._patterns.values())
+
+ toin.save()
+ saved = json.loads(path.read_text(encoding="utf-8"))["patterns"]
+ assert set(saved) == set(keys[1:])
+
+
+def test_failed_merge_leaves_the_existing_pattern_unchanged(caplog) -> None:
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=""))
+ for index in range(2):
+ _record(toin, index)
+ exported = toin.export_patterns()
+ keys = list(exported["patterns"])
+ # to_dict() shares the pattern's containers, so snapshot through JSON.
+ before = {key: json.loads(json.dumps(p.to_dict())) for key, p in toin._patterns.items()}
+
+ bad = dict(exported["patterns"][keys[0]])
+ # Passes from_dict, then fails part-way through _merge_patterns: the counts
+ # and the "field_new" key are already added when the "x" value raises.
+ bad["field_retrieval_frequency"] = {"field_new": 1, "field_0": "x"}
+ healthy = dict(exported["patterns"][keys[1]])
+ with caplog.at_level(logging.WARNING, logger="headroom.telemetry.toin"):
+ toin.import_patterns(
+ {"instance_id": "foreign-instance", "patterns": {keys[0]: bad, keys[1]: healthy}}
+ )
+
+ [warning] = _skip_warnings(caplog)
+ assert warning.skipped == 1
+ first, second = (toin._patterns[key] for key in before)
+ assert json.loads(json.dumps(first.to_dict())) == before[next(iter(before))]
+ assert second.total_compressions == 2
+
+
+def test_float_counts_written_by_merges_still_load(tmp_path, caplog) -> None:
+ # _merge_patterns stores optimal_max_items as a weighted float.
+ path = tmp_path / "toin.json"
+ data = _saved_store(path, 2)
+ for entry in data["patterns"].values():
+ entry["optimal_max_items"] = 37.5
+ path.write_text(json.dumps(data), encoding="utf-8")
+
+ with caplog.at_level(logging.WARNING, logger="headroom.telemetry.toin"):
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=0))
+
+ assert len(toin._patterns) == 2
+ assert _skip_warnings(caplog) == []
+
+
+def test_valid_store_loads_without_a_skip_warning(tmp_path, caplog) -> None:
+ path = tmp_path / "toin.json"
+ _saved_store(path, 5)
+
+ with caplog.at_level(logging.WARNING, logger="headroom.telemetry.toin"):
+ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(path), auto_save_interval=0))
+
+ assert len(toin._patterns) == 5
+ assert _skip_warnings(caplog) == []
+
+
def test_filesystem_backend_writes_compact_json(tmp_path) -> None:
path = tmp_path / "toin.json"
FileSystemTOINBackend(str(path)).save({"patterns": {"a": {"value": 1}}})