Rewrite README with verified before/after examples

- Replace marketing claims with actual API test results - Add needle-in-haystack test: critical error at position 67/100 - Show real JSON compression: 100 entries → 6 entries (93.9% reduction) - Verified with Claude Sonnet: 87.6% fewer tokens, 4/4 correct answers - Add example scripts for reproducing the tests
2026-08-27 14:17:10 -04:00 · 2026-01-19 08:19:37 -08:00 · 2026-01-19 08:19:37 -08:00 · 8766d83f68
commit 8766d83f68
parent 57b2de525c
5 changed files with 763 additions and 25 deletions
--- a/README.md
+++ b/README.md
@ -4,7 +4,7 @@
    <strong>The Context Optimization Layer for LLM Applications</strong>
  </p>
  <p align="center">
-    Cut your LLM costs by 50-90% without losing accuracy
+    Tool outputs are 70-95% redundant boilerplate. Headroom compresses that away.
  </p>
 </p>

@ -26,28 +26,78 @@

 ---

-## Why Headroom?
+## Does It Actually Work? A Real Test

- **Zero code changes** - works as a transparent proxy
- **50-90% cost savings** - verified on real workloads
- **Reversible compression** - LLM retrieves original data via CCR
- **Content-aware** - code, logs, JSON each handled optimally
- **Provider caching** - automatic prefix optimization for cache hits
- **Persistent memory** - remember across conversations with zero-latency extraction
- **Framework native** - LangChain, Agno, MCP, agents supported
+**The setup:** 100 production log entries. One critical error buried at position 67.
+
+<details>
+<summary><b>BEFORE:</b> 100 log entries (18,952 chars) - click to expand</summary>
+
+```json
+[
+  {"timestamp": "2024-12-15T00:00:00Z", "level": "INFO", "service": "api-gateway", "message": "Request processed successfully - latency=50ms", "request_id": "req-000000", "status_code": 200},
+  {"timestamp": "2024-12-15T01:01:00Z", "level": "INFO", "service": "user-service", "message": "Request processed successfully - latency=51ms", "request_id": "req-000001", "status_code": 200},
+  {"timestamp": "2024-12-15T02:02:00Z", "level": "INFO", "service": "inventory", "message": "Request processed successfully - latency=52ms", "request_id": "req-000002", "status_code": 200},
+  // ... 64 more INFO entries ...
+  {"timestamp": "2024-12-15T03:47:23Z", "level": "FATAL", "service": "payment-gateway", "message": "Connection pool exhausted", "error_code": "PG-5523", "resolution": "Increase max_connections to 500 in config/database.yml", "affected_transactions": 1847},
+  // ... 32 more INFO entries ...
+]
+```
+</details>
+
+**AFTER:** Headroom compresses to 6 entries (1,155 chars):
+
+```json
+[
+  {"timestamp": "2024-12-15T00:00:00Z", "level": "INFO", "service": "api-gateway", ...},
+  {"timestamp": "2024-12-15T01:01:00Z", "level": "INFO", "service": "user-service", ...},
+  {"timestamp": "2024-12-15T02:02:00Z", "level": "INFO", "service": "inventory", ...},
+  {"timestamp": "2024-12-15T03:47:23Z", "level": "FATAL", "service": "payment-gateway", "error_code": "PG-5523", "resolution": "Increase max_connections to 500 in config/database.yml", "affected_transactions": 1847},
+  {"timestamp": "2024-12-15T02:38:00Z", "level": "INFO", "service": "inventory", ...},
+  {"timestamp": "2024-12-15T03:39:00Z", "level": "INFO", "service": "auth", ...}
+]
+```
+
+**What happened:** First 3 items + the FATAL error + last 2 items. The critical error at position 67 was automatically preserved.

 ---

-## Headroom vs Alternatives
+**The question we asked Claude:** "What caused the outage? What's the error code? What's the fix?"

-| Approach | Token Reduction | Accuracy | Reversible | Latency |
-|----------|-----------------|----------|------------|---------|
-| **Headroom** | 50-90% | No loss | Yes (CCR) | ~1-5ms |
-| Truncation | Variable | Data loss | No | ~0ms |
-| Summarization | 60-80% | Lossy | No | ~500ms+ |
-| No optimization | 0% | Full | N/A | 0ms |
+|  | Baseline | Headroom |
+|--|----------|----------|
+| Input tokens | 10,144 | 1,260 |
+| Correct answers | **4/4** | **4/4** |

-**Headroom wins** because it intelligently selects relevant content while keeping a retrieval path to the original data.
+Both responses: *"payment-gateway service, error PG-5523, fix: Increase max_connections to 500, 1,847 transactions affected"*
+
+**87.6% fewer tokens. Same answer.**
+
+Run it yourself: `python examples/needle_in_haystack_test.py`
+
+---
+
+## How It Works
+
+Headroom doesn't summarize or truncate blindly. It uses **statistical analysis**:
+
+1. **Detects redundancy** - Repeated fields like `"language": "typescript"` across 100 items
+2. **Keeps what matters** - First items, last items, query-relevant matches, anomalies
+3. **Preserves errors** - Never drops items containing "error", "exception", "failed"
+4. **Maintains schema** - Output JSON structure stays identical
+
+The compression is **reversible** via CCR (Compress-Cache-Retrieve). If the LLM needs more data, it can request the original.
+
+---
+
+## Why Headroom?
+
+- **Zero code changes** - works as a transparent proxy
+- **47-92% savings** - depends on your workload (tool-heavy = more savings)
+- **Reversible compression** - LLM retrieves original data via CCR
+- **Content-aware** - code, logs, JSON each handled optimally
+- **Provider caching** - automatic prefix optimization for cache hits
+- **Framework native** - LangChain, Agno, MCP, agents supported

 ---

@ -144,16 +194,21 @@ See the full [Agno Integration Guide](docs/agno.md) for hooks, multi-provider su

 ---

-## Performance
+## Verified Performance

-| Scenario | Before | After | Savings |
-|----------|--------|-------|---------|
-| Search results (1000 items) | 45,000 tokens | 4,500 tokens | 90% |
-| Log analysis (500 entries) | 22,000 tokens | 3,300 tokens | 85% |
-| Long conversation (50 turns) | 80,000 tokens | 32,000 tokens | 60% |
-| Agent with tools (10 calls) | 100,000 tokens | 15,000 tokens | 85% |
+These numbers are from actual API calls, not estimates:

-**Overhead**: ~1-5ms per request
+| Scenario | Before | After | Savings | Verified |
+|----------|--------|-------|---------|----------|
+| Code search (100 results) | 17,765 tokens | 1,408 tokens | 92% | Claude Sonnet |
+| SRE incident debugging | 65,694 tokens | 5,118 tokens | 92% | GPT-4o |
+| Codebase exploration | 78,502 tokens | 41,254 tokens | 47% | GPT-4o |
+| GitHub issue triage | 54,174 tokens | 14,761 tokens | 73% | GPT-4o |
+
+**Overhead**: ~1-5ms compression latency
+
+**When savings are highest**: Tool-heavy workloads (search, logs, database queries)
+**When savings are lowest**: Conversation-heavy workloads with minimal tool use

 ---

--- a/examples/capture_before_after_json.py
+++ b/examples/capture_before_after_json.py
@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Capture the actual before/after JSON for the README."""
+
+import json
+
+from headroom.config import SmartCrusherConfig
+from headroom.transforms.smart_crusher import SmartCrusher
+
+# The critical error (needle)
+CRITICAL_ERROR = {
+    "timestamp": "2024-12-15T03:47:23Z",
+    "level": "FATAL",
+    "service": "payment-gateway",
+    "message": "Connection pool exhausted - max_connections=100 exceeded",
+    "error_code": "PG-5523",
+    "resolution": "Increase max_connections to 500 in config/database.yml",
+    "affected_transactions": 1847,
+}
+
+
+def create_log_entries(n: int = 100, needle_position: int = 67) -> list:
+    """Create n log entries with the critical error at needle_position."""
+    logs = []
+    for i in range(n):
+        if i == needle_position:
+            logs.append(CRITICAL_ERROR)
+        else:
+            logs.append(
+                {
+                    "timestamp": f"2024-12-15T{(i % 24):02d}:{(i % 60):02d}:00Z",
+                    "level": "INFO",
+                    "service": ["api-gateway", "user-service", "inventory", "auth"][i % 4],
+                    "message": f"Request processed successfully - latency={50 + (i % 100)}ms",
+                    "request_id": f"req-{i:06d}",
+                    "status_code": 200,
+                }
+            )
+    return logs
+
+
+def main():
+    logs = create_log_entries(100, needle_position=67)
+    original_json = json.dumps(logs)
+
+    # Compress with SmartCrusher
+    config = SmartCrusherConfig()
+    crusher = SmartCrusher(config)
+    result = crusher.crush(original_json, query="error outage fatal")
+
+    compressed_data = json.loads(result.compressed)
+
+    print("=" * 70)
+    print("BEFORE: First 3 of 100 log entries")
+    print("=" * 70)
+    print(json.dumps(logs[:3], indent=2))
+    print(f"\n... plus 97 more entries (100 total, {len(original_json):,} chars)")
+
+    print("\n" + "=" * 70)
+    print(f"AFTER: Headroom keeps {len(compressed_data)} entries")
+    print("=" * 70)
+    print(json.dumps(compressed_data, indent=2))
+
+    # Check if the needle was preserved
+    print("\n" + "=" * 70)
+    print("NEEDLE PRESERVED?")
+    print("=" * 70)
+    needle_found = any(item.get("error_code") == "PG-5523" for item in compressed_data)
+    print(f"Critical error (PG-5523) in compressed output: {needle_found}")
+
+    # Stats
+    print("\n" + "=" * 70)
+    print("STATS")
+    print("=" * 70)
+    print(f"Items: {len(logs)} → {len(compressed_data)}")
+    print(f"Chars: {len(original_json):,} → {len(result.compressed):,}")
+    print(f"Reduction: {(1 - len(result.compressed) / len(original_json)) * 100:.1f}%")
+
+
+if __name__ == "__main__":
+    main()
--- a/examples/needle_in_haystack_test.py
+++ b/examples/needle_in_haystack_test.py
@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""
+Needle-in-Haystack Test: Proving Headroom Preserves Critical Information
+
+This test embeds a SPECIFIC answer deep in a large JSON response,
+then verifies both baseline and Headroom-optimized calls can find it.
+
+The scenario: Production incident logs with ONE critical error buried in the middle.
+The question: "What caused the outage and what's the fix?"
+"""
+
+import json
+import os
+
+import httpx
+
+ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY")
+if not ANTHROPIC_API_KEY:
+    raise ValueError("ANTHROPIC_API_KEY environment variable required")
+
+# =============================================================================
+# THE NEEDLE: A critical error buried at position 67 out of 100
+# =============================================================================
+CRITICAL_ERROR = {
+    "timestamp": "2024-12-15T03:47:23Z",
+    "level": "FATAL",
+    "service": "payment-gateway",
+    "message": "Connection pool exhausted - max_connections=100 exceeded",
+    "error_code": "PG-5523",
+    "stack_trace": "ConnectionPoolError at PaymentService.processTransaction()",
+    "resolution": "Increase max_connections to 500 in config/database.yml",
+    "affected_transactions": 1847,
+    "incident_id": "INC-2024-1215-001",
+}
+
+
+# =============================================================================
+# THE HAYSTACK: 99 normal log entries
+# =============================================================================
+def create_log_entries(n: int = 100, needle_position: int = 67) -> list:
+    """Create n log entries with the critical error at needle_position."""
+    logs = []
+    for i in range(n):
+        if i == needle_position:
+            # Insert the needle
+            logs.append(CRITICAL_ERROR)
+        else:
+            # Normal log entry
+            logs.append(
+                {
+                    "timestamp": f"2024-12-15T{(i % 24):02d}:{(i % 60):02d}:00Z",
+                    "level": "INFO",
+                    "service": ["api-gateway", "user-service", "inventory", "auth"][i % 4],
+                    "message": f"Request processed successfully - latency={50 + (i % 100)}ms",
+                    "request_id": f"req-{i:06d}",
+                    "status_code": 200,
+                    "endpoint": ["/api/users", "/api/products", "/api/orders", "/health"][i % 4],
+                    "metadata": {
+                        "region": ["us-east-1", "us-west-2", "eu-west-1"][i % 3],
+                        "version": "2.4.1",
+                    },
+                }
+            )
+    return logs
+
+
+# =============================================================================
+# THE QUESTION
+# =============================================================================
+QUESTION = """Based on these production logs, answer these specific questions:
+
+1. What service caused the outage?
+2. What was the exact error code?
+3. What is the specific fix mentioned in the logs?
+4. How many transactions were affected?
+
+Be precise - cite the exact values from the logs."""
+
+
+def create_messages(tool_content: str) -> list:
+    """Create the conversation with tool output."""
+    return [
+        {
+            "role": "user",
+            "content": "Search the production logs for the root cause of last night's outage",
+        },
+        {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "I'll search the production logs for errors."},
+                {
+                    "type": "tool_use",
+                    "id": "logs_1",
+                    "name": "search_logs",
+                    "input": {"query": "error OR fatal", "limit": 100},
+                },
+            ],
+        },
+        {
+            "role": "user",
+            "content": [
+                {
+                    "type": "tool_result",
+                    "tool_use_id": "logs_1",
+                    "content": tool_content,
+                }
+            ],
+        },
+        {
+            "role": "user",
+            "content": QUESTION,
+        },
+    ]
+
+
+def make_api_call(base_url: str, messages: list, label: str) -> dict:
+    """Make API call and return response + usage."""
+    headers = {
+        "x-api-key": ANTHROPIC_API_KEY,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+    }
+
+    payload = {
+        "model": "claude-sonnet-4-20250514",
+        "max_tokens": 1000,
+        "messages": messages,
+        "tools": [
+            {
+                "name": "search_logs",
+                "description": "Search production logs",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {
+                        "query": {"type": "string"},
+                        "limit": {"type": "integer"},
+                    },
+                    "required": ["query"],
+                },
+            }
+        ],
+    }
+
+    print(f"\n{'=' * 70}")
+    print(f"{label}")
+    print(f"{'=' * 70}")
+
+    try:
+        with httpx.Client(timeout=120.0) as client:
+            response = client.post(
+                f"{base_url}/v1/messages",
+                headers=headers,
+                json=payload,
+            )
+
+            if response.status_code != 200:
+                print(f"Error: {response.status_code}")
+                print(response.text[:500])
+                return {"error": response.text}
+
+            data = response.json()
+            usage = data.get("usage", {})
+
+            # Extract text response
+            response_text = ""
+            for block in data.get("content", []):
+                if block.get("type") == "text":
+                    response_text += block.get("text", "")
+
+            return {
+                "input_tokens": usage.get("input_tokens", 0),
+                "output_tokens": usage.get("output_tokens", 0),
+                "response": response_text,
+            }
+
+    except Exception as e:
+        print(f"Exception: {e}")
+        return {"error": str(e)}
+
+
+def verify_answer(response: str) -> dict:
+    """Check if the response contains the correct answers."""
+    checks = {
+        "service": "payment-gateway" in response.lower(),
+        "error_code": "PG-5523" in response or "pg-5523" in response.lower(),
+        "fix": "max_connections" in response.lower() or "500" in response,
+        "transactions": "1847" in response or "1,847" in response,
+    }
+    return checks
+
+
+def main():
+    print("\n" + "=" * 70)
+    print("NEEDLE-IN-HAYSTACK TEST")
+    print("Proving Headroom preserves critical information")
+    print("=" * 70)
+
+    # Create the test data
+    logs = create_log_entries(100, needle_position=67)
+    log_json = json.dumps(logs)
+
+    print("\nTest setup:")
+    print(f"  - Total log entries: {len(logs)}")
+    print("  - Critical error at position: 67")
+    print(f"  - JSON size: {len(log_json):,} characters")
+
+    print("\nThe needle (what we're looking for):")
+    print(f"  - Service: {CRITICAL_ERROR['service']}")
+    print(f"  - Error code: {CRITICAL_ERROR['error_code']}")
+    print(f"  - Fix: {CRITICAL_ERROR['resolution']}")
+    print(f"  - Affected: {CRITICAL_ERROR['affected_transactions']} transactions")
+
+    messages = create_messages(log_json)
+
+    # Test 1: Baseline (direct to Anthropic)
+    print("\n" + "-" * 70)
+    baseline = make_api_call(
+        "https://api.anthropic.com",
+        messages,
+        "BASELINE: Direct to Anthropic API",
+    )
+
+    if "error" not in baseline:
+        print(f"\nInput tokens: {baseline['input_tokens']:,}")
+        print(f"\nResponse:\n{baseline['response'][:1000]}...")
+        baseline_checks = verify_answer(baseline["response"])
+        print(f"\nAnswer verification: {baseline_checks}")
+
+    # Test 2: Headroom optimized
+    print("\n" + "-" * 70)
+    optimized = make_api_call(
+        "http://localhost:8787",
+        messages,
+        "HEADROOM: Through optimization proxy",
+    )
+
+    if "error" not in optimized:
+        print(f"\nInput tokens: {optimized['input_tokens']:,}")
+        print(f"\nResponse:\n{optimized['response'][:1000]}...")
+        optimized_checks = verify_answer(optimized["response"])
+        print(f"\nAnswer verification: {optimized_checks}")
+
+    # Final comparison
+    print("\n" + "=" * 70)
+    print("FINAL RESULTS")
+    print("=" * 70)
+
+    if "error" not in baseline and "error" not in optimized:
+        baseline_input = baseline["input_tokens"]
+        optimized_input = optimized["input_tokens"]
+        saved = baseline_input - optimized_input
+        percent = (saved / baseline_input * 100) if baseline_input > 0 else 0
+
+        baseline_score = sum(baseline_checks.values())
+        optimized_score = sum(optimized_checks.values())
+
+        print(f"""
+TOKEN COMPARISON:
+  Baseline:  {baseline_input:,} tokens
+  Headroom:  {optimized_input:,} tokens
+  Saved:     {saved:,} tokens ({percent:.1f}% reduction)
+
+ANSWER ACCURACY (4 questions):
+  Baseline:  {baseline_score}/4 correct
+  Headroom:  {optimized_score}/4 correct
+
+VERIFICATION DETAILS:
+  Baseline: {baseline_checks}
+  Headroom: {optimized_checks}
+
+CONCLUSION:
+  {"PASS - Headroom found the needle!" if optimized_score >= 3 else "NEEDS REVIEW"}
+  {"Answer quality maintained with " + f"{percent:.0f}% fewer tokens" if optimized_score >= baseline_score else ""}
+""")
+
+        return {
+            "baseline_tokens": baseline_input,
+            "optimized_tokens": optimized_input,
+            "tokens_saved": saved,
+            "percent_saved": percent,
+            "baseline_accuracy": baseline_score,
+            "optimized_accuracy": optimized_score,
+            "baseline_checks": baseline_checks,
+            "optimized_checks": optimized_checks,
+            "baseline_response": baseline["response"],
+            "optimized_response": optimized["response"],
+        }
+
+    return None
+
+
+if __name__ == "__main__":
+    result = main()
+    if result:
+        print("\n" + "=" * 70)
+        print("JSON SUMMARY:")
+        print("=" * 70)
+        summary = {k: v for k, v in result.items() if not k.endswith("_response")}
+        print(json.dumps(summary, indent=2))
--- a/examples/real_before_after_test.py
+++ b/examples/real_before_after_test.py
@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""
+Real before/after test - NO MARKETING, JUST FACTS.
+
+This script makes actual API calls to demonstrate Headroom compression.
+"""
+
+import json
+import os
+
+import httpx
+
+# API Key from environment
+ANTHROPIC_API_KEY = os.environ.get("ANTHROPIC_API_KEY")
+if not ANTHROPIC_API_KEY:
+    raise ValueError("ANTHROPIC_API_KEY environment variable required")
+
+# Realistic tool output: 100 search results from a code search
+MOCK_TOOL_OUTPUT = json.dumps(
+    [
+        {
+            "file": f"src/components/{['Button', 'Modal', 'Form', 'Table', 'Card'][i % 5]}.tsx",
+            "line": 10 + (i * 3),
+            "content": f"export function {['Button', 'Modal', 'Form', 'Table', 'Card'][i % 5]}Component{i}(props: Props) {{",
+            "language": "typescript",
+            "repository": "frontend-app",
+            "branch": "main",
+            "last_modified": "2024-12-15T10:00:00Z",
+            "author": f"dev{i % 10}@company.com",
+            "match_score": 0.95 - (i * 0.005),
+            "context": {
+                "before": ["import React from 'react';", "import { useCallback } from 'react';"],
+                "after": ["  return <div>...</div>;", "}"],
+            },
+            "metadata": {
+                "size_bytes": 1500 + (i * 10),
+                "encoding": "utf-8",
+                "mime_type": "text/typescript",
+            },
+        }
+        for i in range(100)
+    ]
+)
+
+
+# The conversation we'll send
+def create_messages(tool_content: str) -> list:
+    return [
+        {"role": "user", "content": "Find all React components that use forms"},
+        {
+            "role": "assistant",
+            "content": [
+                {"type": "text", "text": "I'll search for React form components."},
+                {
+                    "type": "tool_use",
+                    "id": "search_1",
+                    "name": "code_search",
+                    "input": {"query": "React form component", "limit": 100},
+                },
+            ],
+        },
+        {
+            "role": "user",
+            "content": [
+                {"type": "tool_result", "tool_use_id": "search_1", "content": tool_content}
+            ],
+        },
+    ]
+
+
+def count_tokens_anthropic(text: str) -> int:
+    """Rough token estimate (actual would use anthropic tokenizer)"""
+    # Claude's tokenizer is roughly 4 chars per token for JSON
+    return len(text) // 4
+
+
+def make_api_call(base_url: str, messages: list, label: str) -> dict:
+    """Make actual API call and return usage stats."""
+
+    headers = {
+        "x-api-key": ANTHROPIC_API_KEY,
+        "anthropic-version": "2023-06-01",
+        "content-type": "application/json",
+    }
+
+    payload = {
+        "model": "claude-sonnet-4-20250514",
+        "max_tokens": 500,
+        "messages": messages,
+        "tools": [
+            {
+                "name": "code_search",
+                "description": "Search for code in the repository",
+                "input_schema": {
+                    "type": "object",
+                    "properties": {"query": {"type": "string"}, "limit": {"type": "integer"}},
+                    "required": ["query"],
+                },
+            }
+        ],
+    }
+
+    print(f"\n{'=' * 60}")
+    print(f"{label}")
+    print(f"{'=' * 60}")
+    print(f"Endpoint: {base_url}")
+
+    try:
+        with httpx.Client(timeout=60.0) as client:
+            response = client.post(f"{base_url}/v1/messages", headers=headers, json=payload)
+
+            if response.status_code != 200:
+                print(f"Error: {response.status_code}")
+                print(response.text[:500])
+                return {"error": response.text}
+
+            data = response.json()
+            usage = data.get("usage", {})
+
+            result = {
+                "input_tokens": usage.get("input_tokens", 0),
+                "output_tokens": usage.get("output_tokens", 0),
+                "response_preview": str(data.get("content", [{}])[0].get("text", ""))[:200],
+            }
+
+            print(f"Input tokens:  {result['input_tokens']:,}")
+            print(f"Output tokens: {result['output_tokens']:,}")
+            print(f"Response: {result['response_preview']}...")
+
+            return result
+
+    except Exception as e:
+        print(f"Exception: {e}")
+        return {"error": str(e)}
+
+
+def main():
+    print("\n" + "=" * 70)
+    print("HEADROOM REAL BEFORE/AFTER TEST")
+    print("NO MARKETING - JUST ACTUAL API RESULTS")
+    print("=" * 70)
+
+    # Show what we're testing
+    print(f"\nTest data: {len(json.loads(MOCK_TOOL_OUTPUT))} code search results")
+    print(f"Raw JSON size: {len(MOCK_TOOL_OUTPUT):,} characters")
+    print(f"Estimated tokens: ~{count_tokens_anthropic(MOCK_TOOL_OUTPUT):,}")
+
+    messages = create_messages(MOCK_TOOL_OUTPUT)
+
+    # Test 1: Direct to Anthropic API (baseline)
+    baseline = make_api_call(
+        "https://api.anthropic.com", messages, "BASELINE: Direct to Anthropic API"
+    )
+
+    # Test 2: Through Headroom proxy
+    optimized = make_api_call(
+        "http://localhost:8787", messages, "OPTIMIZED: Through Headroom Proxy"
+    )
+
+    # Results
+    print("\n" + "=" * 70)
+    print("RESULTS")
+    print("=" * 70)
+
+    if "error" not in baseline and "error" not in optimized:
+        baseline_input = baseline["input_tokens"]
+        optimized_input = optimized["input_tokens"]
+        saved = baseline_input - optimized_input
+        percent = (saved / baseline_input * 100) if baseline_input > 0 else 0
+
+        # Cost calculation (Claude Sonnet: $3/1M input, $15/1M output)
+        cost_baseline = (baseline_input * 3 + baseline["output_tokens"] * 15) / 1_000_000
+        cost_optimized = (optimized_input * 3 + optimized["output_tokens"] * 15) / 1_000_000
+        cost_saved = cost_baseline - cost_optimized
+
+        print(f"""
+Input Tokens:
+  Baseline:  {baseline_input:,}
+  Optimized: {optimized_input:,}
+  Saved:     {saved:,} ({percent:.1f}%)
+
+Cost per request (Claude Sonnet pricing):
+  Baseline:  ${cost_baseline:.6f}
+  Optimized: ${cost_optimized:.6f}
+  Saved:     ${cost_saved:.6f}
+
+At 10,000 requests/day:
+  Daily savings:   ${cost_saved * 10000:.2f}
+  Monthly savings: ${cost_saved * 10000 * 30:.2f}
+""")
+
+        # Return data for README
+        return {
+            "baseline_tokens": baseline_input,
+            "optimized_tokens": optimized_input,
+            "tokens_saved": saved,
+            "percent_saved": percent,
+            "tool_output_size": len(MOCK_TOOL_OUTPUT),
+            "num_items": len(json.loads(MOCK_TOOL_OUTPUT)),
+        }
+    else:
+        print("Test failed - check errors above")
+        return None
+
+
+if __name__ == "__main__":
+    result = main()
+    if result:
+        print("\n" + "=" * 70)
+        print("JSON FOR README:")
+        print("=" * 70)
+        print(json.dumps(result, indent=2))
--- a/examples/show_actual_compression.py
+++ b/examples/show_actual_compression.py
@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""
+Show the actual before/after JSON - what gets sent to the LLM.
+"""
+
+import json
+
+from headroom.config import SmartCrusherConfig
+from headroom.transforms.smart_crusher import SmartCrusher
+
+
+# Same realistic data as the API test
+def create_search_results(n: int = 100) -> list:
+    return [
+        {
+            "file": f"src/components/{['Button', 'Modal', 'Form', 'Table', 'Card'][i % 5]}.tsx",
+            "line": 10 + (i * 3),
+            "content": f"export function {['Button', 'Modal', 'Form', 'Table', 'Card'][i % 5]}Component{i}(props: Props) {{",
+            "language": "typescript",
+            "repository": "frontend-app",
+            "branch": "main",
+            "last_modified": "2024-12-15T10:00:00Z",
+            "author": f"dev{i % 10}@company.com",
+            "match_score": 0.95 - (i * 0.005),
+            "context": {
+                "before": ["import React from 'react';", "import { useCallback } from 'react';"],
+                "after": ["  return <div>...</div>;", "}"],
+            },
+            "metadata": {
+                "size_bytes": 1500 + (i * 10),
+                "encoding": "utf-8",
+                "mime_type": "text/typescript",
+            },
+        }
+        for i in range(n)
+    ]
+
+
+def main():
+    # Create the crusher
+    config = SmartCrusherConfig()
+    crusher = SmartCrusher(config)
+
+    # Original data
+    original_data = create_search_results(100)
+    original_json = json.dumps(original_data, indent=2)
+
+    print("=" * 70)
+    print("BEFORE: Original Tool Output (first 2 items shown)")
+    print("=" * 70)
+    print(json.dumps(original_data[:2], indent=2))
+    print(f"\n... plus {len(original_data) - 2} more items (100 total)")
+    print(f"\nTotal characters: {len(original_json):,}")
+
+    # Compress it using the crush method
+    result = crusher.crush(
+        content=json.dumps(original_data), query="Find all React form components"
+    )
+
+    compressed_content = result.compressed
+    compressed_data = json.loads(compressed_content)
+
+    print("\n" + "=" * 70)
+    print("AFTER: Compressed Tool Output (all items shown)")
+    print("=" * 70)
+    print(json.dumps(compressed_data, indent=2))
+
+    print("\n" + "=" * 70)
+    print("COMPRESSION STATS")
+    print("=" * 70)
+    print(f"Items before: {len(original_data)}")
+    print(f"Items after:  {len(compressed_data)}")
+    print(f"Characters before: {len(original_json):,}")
+    print(f"Characters after:  {len(compressed_content):,}")
+    print(f"Reduction: {(1 - len(compressed_content) / len(original_json)) * 100:.1f}%")
+
+    # Show what was kept and why
+    print("\n" + "=" * 70)
+    print("WHAT WAS KEPT AND WHY")
+    print("=" * 70)
+
+    for i, item in enumerate(compressed_data):
+        file_name = item.get("file", "unknown")
+        score = item.get("match_score", 0)
+        reason = (
+            "first" if i < 3 else ("last" if i >= len(compressed_data) - 2 else "high relevance")
+        )
+        print(f"  {i + 1}. {file_name} (score: {score:.2f}) - {reason}")
+
+
+if __name__ == "__main__":
+    main()