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.

refactor(utils): deprecate the marker, JSON and hash helpers nothing calls (#4107)

Tejas Chopraebc59356ecbc
diff --git a/headroom/utils.py b/headroom/utils.py
index 05c31edf5..cbd085895 100644
--- a/headroom/utils.py
+++ b/headroom/utils.py
@@ -7,6 +7,7 @@ import hashlib
import json
import re
import uuid
+import warnings
from datetime import datetime, timezone
from 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 for
content-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), True
except (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 default
return json.dumps(obj, **kwargs)
diff --git a/tests/test_utils.py b/tests/test_utils.py
index be4a5a9b3..fafae8ead 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -2,6 +2,8 @@ from __future__ import annotations
from 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) == expected
def test_cost_formatting_and_deep_copy() -> None: