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
fix(toin): make diagnostic pattern identifiers addressable (#4021)
Mansurshakh Japarovdef6d41185d3
diff --git a/headroom/proxy/server.py b/headroom/proxy/server.pyindex 404ecbd81..ccedd24a2 100644--- a/headroom/proxy/server.py+++ b/headroom/proxy/server.py@@ -5935,7 +5935,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:limit: Maximum number of patterns to return (default 20)Response includes for each pattern:- - hash: Truncated tool signature hash (12 chars)+ - hash: Full aggregation key identifying one scoped tool pattern- compressions: Total compression events- retrievals: Total retrieval events- retrieval_rate: Percentage of compressions that triggered retrieval@@ -5959,7 +5959,7 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:patterns_list.append({- "hash": sig_hash[:12],+ "hash": sig_hash,"compressions": total_compressions,"retrievals": total_retrievals,"retrieval_rate": f"{retrieval_rate:.1%}",@@ -5979,36 +5979,41 @@ def create_app(config: ProxyConfig | None = None) -> FastAPI:return patterns_list[:limit]- @app.get("/v1/toin/pattern/{hash_prefix}", dependencies=[Depends(_require_loopback)])+ @app.get("/v1/toin/pattern/{hash_prefix:path}", dependencies=[Depends(_require_loopback)])async def toin_pattern_detail(hash_prefix: str):- """Get detailed TOIN pattern info by hash prefix.+ """Get detailed TOIN pattern info by the listed identifier or a unique prefix.- Searches for a pattern where the tool signature hash starts with- the provided prefix. Returns full pattern details if found.+ Pass the ``hash`` returned by ``/v1/toin/patterns`` for an exact+ lookup. A shorter aggregation-key prefix is accepted only when it+ identifies one pattern; ambiguous prefixes return 409.- Path params:- hash_prefix: Beginning of the tool signature hash (min 4 chars recommended)-- Response: Full pattern.to_dict() with all learned statistics and recommendations.+ Response: Learned statistics without query text or field semantics."""toin = get_toin()exported = toin.export_patterns()patterns_data = exported.get("patterns", {})- # Search for pattern with matching hash prefix- for sig_hash, pattern_dict in patterns_data.items():- if sig_hash.startswith(hash_prefix):- # Keep this response aligned with /v1/toin/patterns while- # excluding query text, field semantics, and other internal- # learning state from the detail endpoint.- return {- "compressions": pattern_dict.get("total_compressions", 0),- "retrievals": pattern_dict.get("total_retrievals", 0),- "retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),- "confidence": pattern_dict.get("confidence", 0.0),- "skip_recommended": pattern_dict.get("skip_compression_recommended", False),- "optimal_max_items": pattern_dict.get("optimal_max_items", 20),- }+ pattern_dict = patterns_data.get(hash_prefix)+ if pattern_dict is None:+ matches = (+ pattern for key, pattern in patterns_data.items() if key.startswith(hash_prefix)+ )+ pattern_dict = next(matches, None)+ if next(matches, None) is not None:+ raise HTTPException(+ status_code=409,+ detail="Ambiguous TOIN pattern prefix; use a full hash from /v1/toin/patterns",+ )+ if pattern_dict is not None:+ # Keep query text, field semantics, and internal learning state private.+ return {+ "compressions": pattern_dict.get("total_compressions", 0),+ "retrievals": pattern_dict.get("total_retrievals", 0),+ "retrieval_rate": pattern_dict.get("retrieval_rate", 0.0),+ "confidence": pattern_dict.get("confidence", 0.0),+ "skip_recommended": pattern_dict.get("skip_compression_recommended", False),+ "optimal_max_items": pattern_dict.get("optimal_max_items", 20),+ }raise HTTPException(status_code=404, detail=f"No TOIN pattern found with hash starting with: {hash_prefix}"diff --git a/sdk/typescript/README.md b/sdk/typescript/README.mdindex b4200bcaa..0d5eba03d 100644--- a/sdk/typescript/README.md+++ b/sdk/typescript/README.md@@ -279,8 +279,16 @@ const hints = await client.feedback.getHints('list_servers');// TOIN (Tool Output Intelligence Network)const toinStats = await client.toin.getStats();const patterns = await client.toin.getPatterns(20);+const pattern = patterns[0] && await client.toin.getPattern(patterns[0].hash);```+Each `hash` is the complete scoped aggregation key, including tenant, auth mode,+model family, and tool signature. Pass it back unchanged for an exact lookup;+the client URL-encodes it. Shorter aggregation-key prefixes are accepted only+when they identify one pattern; ambiguous prefixes return HTTP 409 rather than+an arbitrary pattern.++## Configuration TypesFull TypeScript interfaces for every Python config dataclass.diff --git a/tests/test_proxy_loopback_gating.py b/tests/test_proxy_loopback_gating.pyindex 1e76430e1..382baa449 100644--- a/tests/test_proxy_loopback_gating.py+++ b/tests/test_proxy_loopback_gating.py@@ -112,7 +112,9 @@ def test_toin_pattern_detail_whitelists_learned_payload(monkeypatch: pytest.Monk}monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: FakeTOIN())- response = _loopback_client().get("/v1/toin/pattern/unknown")+ client = _loopback_client()+ identifier = client.get("/v1/toin/patterns").json()[0]["hash"]+ response = client.get(f"/v1/toin/pattern/{identifier}")assert response.status_code == 200assert response.json() == {@@ -125,6 +127,63 @@ def test_toin_pattern_detail_whitelists_learned_payload(monkeypatch: pytest.Monk}+def scoped_toin(monkeypatch: pytest.MonkeyPatch, tmp_path):+ from headroom.telemetry.toin import TOINConfig, ToolIntelligenceNetwork++ toin = ToolIntelligenceNetwork(TOINConfig(storage_path=str(tmp_path / "toin.json")))+ patterns = {+ "global|unknown|unknown|abc123": 8,+ "global|unknown|unknown|abc456": 16,+ "global|payg|claude|abc123": 24,+ "other-tenant|unknown|unknown|abc123": 32,+ "tenant/alpha?scope=one#fragment|unknown|unknown|abc123": 40,+ }+ toin.import_patterns(+ {+ "instance_id": "scoped-pattern-regression",+ "patterns": {+ key: {+ "tool_signature_hash": key.rsplit("|", 1)[-1],+ "sample_size": count,+ "total_compressions": count,+ "total_retrievals": 0,+ }+ for key, count in patterns.items()+ },+ }+ )+ monkeypatch.setattr("headroom.proxy.server.get_toin", lambda: toin)+ return patterns+++def test_listed_toin_identifiers_address_their_own_scoped_pattern(scoped_toin) -> None:+ from urllib.parse import quote++ client = _loopback_client()+ listed = client.get("/v1/toin/patterns").json()+ assert {item["hash"] for item in listed} == set(scoped_toin)+ for item in listed:+ response = client.get(f"/v1/toin/pattern/{quote(item['hash'], safe='')}")+ assert response.status_code == 200+ assert response.json()["compressions"] == item["compressions"]+++ ("prefix", "status", "count"),+ [+ ("global|unknown|unknown|abc", 409, None),+ ("global|unknown|unknown|abc1", 200, 8),+ ("missing-pattern", 404, None),+ ],+)+def test_toin_prefix_lookup_is_unambiguous(scoped_toin, prefix, status, count) -> None:+ response = _loopback_client().get(f"/v1/toin/pattern/{prefix}")+ assert response.status_code == status+ if count is not None:+ assert response.json()["compressions"] == count++# Mutating routes reachable from loopback. `require_loopback` cannot stop a# remote page from POSTing to a known 127.0.0.1 URL: a "simple" cross-origin# request (Content-Type: text/plain carrying JSON) skips preflight, and the