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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
refactor(utils): deprecate the marker, JSON and hash helpers nothing calls (#4107)
Tejas Chopraebc59356ecbc
diff --git a/headroom/utils.py b/headroom/utils.pyindex 05c31edf5..cbd085895 100644--- a/headroom/utils.py+++ b/headroom/utils.py@@ -7,6 +7,7 @@ import hashlibimport jsonimport reimport uuid+import warningsfrom datetime import datetime, timezonefrom typing import Any@@ -43,7 +44,18 @@ def fast_hash(data: str | bytes, length: int = 16) -> str:Uses MD5 (2-3x faster than SHA256). Not used for security — only forcontent-addressable lookups in compression caches, prefix tracking, etc.++ .. deprecated::+ Use ``hashlib.md5(data).hexdigest()[:length]``, encoding ``str``+ input as UTF-8 first. For ``str`` input and the default length,+ :func:`headroom.parser.compute_hash` returns the same value."""+ warnings.warn(+ "fast_hash is deprecated and will be removed in a future release; "+ "use hashlib.md5(data).hexdigest()[:length], encoding str input as UTF-8 first.",+ DeprecationWarning,+ stacklevel=2,+ )if isinstance(data, str):data = data.encode("utf-8")return hashlib.md5(data).hexdigest()[:length] # nosec B324@@ -165,14 +177,34 @@ def create_tool_digest_marker(original_hash: str) -> str:def create_dropped_context_marker(reason: str, count: int | None = None) -> str:- """Create marker for dropped context."""+ """Create marker for dropped context.++ .. deprecated::+ Use :func:`create_marker` with ``"dropped_context"``.+ """+ warnings.warn(+ "create_dropped_context_marker is deprecated and will be removed in a future release; "+ "use create_marker('dropped_context', ...) instead.",+ DeprecationWarning,+ stacklevel=2,+ )if count is not None:return create_marker("dropped_context", reason=reason, count=str(count))return create_marker("dropped_context", reason=reason)def create_truncated_marker(original_length: int, truncated_to: int) -> str:- """Create marker for truncated content."""+ """Create marker for truncated content.++ .. deprecated::+ Use :func:`create_marker` with ``"truncated"``.+ """+ warnings.warn(+ "create_truncated_marker is deprecated and will be removed in a future release; "+ "use create_marker('truncated', ...) instead.",+ DeprecationWarning,+ stacklevel=2,+ )return create_marker("truncated",original=str(original_length),@@ -186,7 +218,16 @@ def extract_markers(text: str) -> list[dict[str, Any]]:Returns:List of dicts with marker_type and attributes.++ .. deprecated::+ It has no replacement."""+ warnings.warn(+ "extract_markers is deprecated and will be removed in a future release; "+ "it has no replacement.",+ DeprecationWarning,+ stacklevel=2,+ )pattern = re.compile(r"<headroom:(\w+)([^>]*)>")markers = []@@ -215,7 +256,16 @@ def safe_json_loads(text: str) -> tuple[Any | None, bool]:Returns:Tuple of (parsed_result or None, success_bool).++ .. deprecated::+ Call :func:`json.loads` and catch :class:`ValueError`."""+ warnings.warn(+ "safe_json_loads is deprecated and will be removed in a future release; "+ "call json.loads and catch ValueError instead.",+ DeprecationWarning,+ stacklevel=2,+ )try:return json.loads(text), Trueexcept (json.JSONDecodeError, ValueError):@@ -232,7 +282,17 @@ def safe_json_dumps(obj: Any, **kwargs: Any) -> str:Returns:JSON string.++ .. deprecated::+ Call :func:`json.dumps` with ``ensure_ascii=False`` and+ ``separators=(",", ":")``."""+ warnings.warn(+ "safe_json_dumps is deprecated and will be removed in a future release; "+ "call json.dumps(obj, ensure_ascii=False, separators=(',', ':')) instead.",+ DeprecationWarning,+ stacklevel=2,+ )kwargs.setdefault("ensure_ascii", False)kwargs.setdefault("separators", (",", ":")) # Compact by defaultreturn json.dumps(obj, **kwargs)diff --git a/tests/test_utils.py b/tests/test_utils.pyindex be4a5a9b3..fafae8ead 100644--- a/tests/test_utils.py+++ b/tests/test_utils.py@@ -2,6 +2,8 @@ from __future__ import annotationsfrom datetime import datetime, timedelta, timezone+import pytest+from headroom import utils@@ -30,7 +32,6 @@ def test_hash_helpers_and_request_id() -> None:"hi\ud800".encode("utf-8", "surrogatepass"))assert utils.compute_short_hash("hello", length=8) == "2cf24dba"- assert utils.fast_hash("hello", length=8) == "5d41402a"def test_extract_user_query_and_message_hashes() -> None:@@ -124,27 +125,47 @@ def test_format_timestamp_normalizes_aware_datetimes() -> None:marker = utils.create_marker("tool_digest", sha256="abc", count="2")assert marker == '<headroom:tool_digest sha256="abc" count="2">'assert utils.create_tool_digest_marker("abc") == '<headroom:tool_digest sha256="abc">'- assert utils.create_dropped_context_marker("budget") == (- '<headroom:dropped_context reason="budget">'- )- assert utils.create_dropped_context_marker("budget", count=4) == (- '<headroom:dropped_context reason="budget" count="4">'- )- assert utils.create_truncated_marker(100, 25) == (- '<headroom:truncated original="100" truncated_to="25">'- )- extracted = utils.extract_markers(- 'x <headroom:tool_digest sha256="abc"> y <headroom:dropped_context reason="budget" count="2">'- )- assert extracted == [- {"type": "tool_digest", "attributes": {"sha256": "abc"}},- {"type": "dropped_context", "attributes": {"reason": "budget", "count": "2"}},- ]- assert utils.safe_json_loads('{"ok": true}') == ({"ok": True}, True)- assert utils.safe_json_loads("{bad") == (None, False)- assert utils.safe_json_dumps({"emoji": "café"}) == '{"emoji":"café"}'+ ("name", "args", "expected"),+ [+ ("fast_hash", ("hello", 8), "5d41402a"),+ ("fast_hash", (b"hello",), "5d41402abc4b2a76"),+ (+ "create_dropped_context_marker",+ ("budget",),+ '<headroom:dropped_context reason="budget">',+ ),+ (+ "create_dropped_context_marker",+ ("budget", 4),+ '<headroom:dropped_context reason="budget" count="4">',+ ),+ (+ "create_truncated_marker",+ (100, 25),+ '<headroom:truncated original="100" truncated_to="25">',+ ),+ (+ "extract_markers",+ (+ 'x <headroom:tool_digest sha256="abc"> y '+ '<headroom:dropped_context reason="budget" count="2">',+ ),+ [+ {"type": "tool_digest", "attributes": {"sha256": "abc"}},+ {"type": "dropped_context", "attributes": {"reason": "budget", "count": "2"}},+ ],+ ),+ ("safe_json_loads", ('{"ok": true}',), ({"ok": True}, True)),+ ("safe_json_loads", ("{bad",), (None, False)),+ ("safe_json_dumps", ({"emoji": "café"},), '{"emoji":"café"}'),+ ],+)+def test_deprecated_helpers_warn_and_still_work(name: str, args: tuple, expected: object) -> None:+ with pytest.warns(DeprecationWarning, match=f"{name} is deprecated"):+ assert getattr(utils, name)(*args) == expecteddef test_cost_formatting_and_deep_copy() -> None: