Context Engineering

# count_tokens.py - what the same document costs on two models

import anthropic

from handbook import HANDBOOK

client = anthropic.Anthropic()

question = "Can I return a final sale item?"

for model in ["claude-haiku-4-5", "claude-sonnet-5"]:
    count = client.messages.count_tokens(
        model=model,
        system=HANDBOOK,
        messages=[{"role": "user", "content": question}],
    )
    ratio = len(HANDBOOK) / count.input_tokens
    print(f"{model:17} input_tokens = {count.input_tokens:5}   chars/token = {ratio:.2f}")

print("handbook characters:", len(HANDBOOK))

# caching.py - the same handbook, marked as a cacheable prefix

import anthropic

from handbook import HANDBOOK

client = anthropic.Anthropic()

# Mark the stable prefix as cacheable. Everything up to and including this
# block (tools, then system) is what gets cached.
stable_system = [{
    "type": "text",
    "text": HANDBOOK,
    "cache_control": {"type": "ephemeral"},
}]


def ask(question):
    r = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=100,
        system=stable_system,
        messages=[{"role": "user", "content": question}],
    )
    return r.usage


u1 = ask("Can I return a final sale item?")
print("request 1 (cold)")
print("   cache_creation_input_tokens :", u1.cache_creation_input_tokens)
print("   cache_read_input_tokens     :", u1.cache_read_input_tokens)
print("   input_tokens (uncached)     :", u1.input_tokens)

u2 = ask("What about EU cooling-off periods?")
print("request 2 (warm, different question)")
print("   cache_creation_input_tokens :", u2.cache_creation_input_tokens)
print("   cache_read_input_tokens     :", u2.cache_read_input_tokens)
print("   input_tokens (uncached)     :", u2.input_tokens)

# invalidator.py - one line at the front of the prefix, and the cache is gone

import anthropic
from datetime import datetime

from handbook import HANDBOOK

client = anthropic.Anthropic()


def ask_with(system, question):
    r = client.messages.create(
        model="claude-haiku-4-5",
        max_tokens=100,
        system=system,
        messages=[{"role": "user", "content": question}],
    )
    return r.usage


def volatile_system():
    # A timestamp at the FRONT of the prefix. Looks harmless. Is not.
    header = f"Current time: {datetime.now().isoformat()}\n\n"
    return [{
        "type": "text",
        "text": header + HANDBOOK,
        "cache_control": {"type": "ephemeral"},
    }]


v1 = ask_with(volatile_system(), "Can I return a final sale item?")
v2 = ask_with(volatile_system(), "What about EU cooling-off periods?")

print("request 1: created =", v1.cache_creation_input_tokens,
      "| read =", v1.cache_read_input_tokens)
print("request 2: created =", v2.cache_creation_input_tokens,
      "| read =", v2.cache_read_input_tokens)

# compaction.py - summarizing a 56,000-token conversation server-side

import anthropic

from handbook import HANDBOOK

client = anthropic.Anthropic()

# Nine handbook revisions: enough to cross the trigger on the next request.
messages = []
for i in range(1, 10):
    messages.append({"role": "user", "content": f"Revision {i}:\n\n{HANDBOOK}"})
    messages.append({"role": "assistant", "content": f"Recorded revision {i}."})
messages.append({"role": "user", "content": "What is the final sale rule?"})

before = client.messages.count_tokens(model="claude-sonnet-5", messages=messages)
print("conversation before :", before.input_tokens, "tokens")

response = client.beta.messages.create(
    betas=["compact-2026-01-12"],
    model="claude-sonnet-5",
    max_tokens=4000,
    messages=messages,
    context_management={"edits": [{
        "type": "compact_20260112",
        "trigger": {"type": "input_tokens", "value": 50_000},  # 50,000 is the minimum
    }]},
)

print("content blocks      :", [b.type for b in response.content])
for step in response.usage.iterations:
    print(f"   {step.type:10} input_tokens = {step.input_tokens}")

# CRITICAL: append the whole content list, not just the text. The compaction
# block carries encrypted state, so it cannot be rebuilt from the summary text.
messages.append({"role": "assistant", "content": response.content})

# context_editing.py - dropping tool results once the loop gets long

import anthropic

from handbook import HANDBOOK

client = anthropic.Anthropic()

TOOLS = [{
    "name": "read_policy",
    "description": "Return the full policy text for one region. The output is large.",
    "input_schema": {
        "type": "object",
        "properties": {"region": {"type": "string"}},
        "required": ["region"],
    },
}]

messages = [{"role": "user", "content":
             "Read the policy for the EU, then the UK, then the US, one at a time. "
             "Then give me the final sale rule in one sentence."}]

for turn in range(1, 6):
    response = client.beta.messages.create(
        betas=["context-management-2025-06-27"],
        model="claude-sonnet-5",
        max_tokens=2000,
        tools=TOOLS,
        messages=messages,
        context_management={"edits": [
            # clear_thinking_20251015 must come FIRST when both are used.
            {"type": "clear_thinking_20251015"},
            {"type": "clear_tool_uses_20250919",
             "trigger": {"type": "input_tokens", "value": 5000},
             "keep": {"type": "tool_uses", "value": 1}},
        ]},
    )

    print(f"turn {turn}: input_tokens = {response.usage.input_tokens:5}")
    for edit in response.context_management.applied_edits:
        cleared = getattr(edit, "cleared_input_tokens", 0)
        print(f"         applied {edit.type} ({cleared} tokens cleared)")

    messages.append({"role": "assistant", "content": response.content})
    calls = [b for b in response.content if b.type == "tool_use"]
    if not calls:
        break

    # A real tool would read a file; this returns a large slice of the handbook.
    messages.append({"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": c.id, "content": HANDBOOK[:6000]}
        for c in calls
    ]})