perf: add prompt caching to intake and research agents (#22)

Wraps system prompts and tool lists with cache_control: ephemeral at all
five API call sites. Cached tokens are billed at 10% of normal input rate,
saving ~90% on repeated turns within a session.

Adds cached_system() and cached_tools() helpers to llm.py so the pattern
stays consistent and easy to update.

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

agents/intake.py

@@ -11,6 +11,7 @@ from rich.text import Text
 
 from beacon_logging import get_logger
 from config import INTAKE_MODEL
+from llm import cached_system, cached_tools
 from models import PatientProfile, geocode_zip
 from prompts import INTAKE_SYSTEM, lookup_disease_profile
 from tools import INTAKE_TOOLS
@@ -55,8 +56,8 @@ def run_intake_agent(client: anthropic.Anthropic) -> PatientProfile:
         response = client.messages.create(
             model=INTAKE_MODEL,
             max_tokens=1024,
-            system=f"Today's date is {today}.\n\n" + INTAKE_SYSTEM,
-            tools=INTAKE_TOOLS,
+            system=cached_system(f"Today's date is {today}.\n\n" + INTAKE_SYSTEM),
+            tools=cached_tools(INTAKE_TOOLS),
             messages=messages,
         )
 
@@ -132,8 +133,8 @@ def intake_greeting(client: anthropic.Anthropic, lang: str = "en") -> tuple[str,
     response = client.messages.create(
         model=INTAKE_MODEL,
         max_tokens=1024,
-        system=system,
-        tools=INTAKE_TOOLS,
+        system=cached_system(system),
+        tools=cached_tools(INTAKE_TOOLS),
         messages=messages,
     )
     text = next((b.text for b in response.content if b.type == "text"), "")
@@ -163,8 +164,8 @@ def stream_intake_turn(
         with client.messages.stream(
             model=INTAKE_MODEL,
             max_tokens=1024,
-            system=system,
-            tools=INTAKE_TOOLS,
+            system=cached_system(system),
+            tools=cached_tools(INTAKE_TOOLS),
             messages=new_msgs,
         ) as stream:
             for chunk in stream.text_stream:

agents/research.py

@@ -8,6 +8,7 @@ import anthropic
 from agents.eligibility import bulk_parse_and_strip
 from beacon_logging import get_logger
 from config import RESEARCH_MODEL
+from llm import cached_system, cached_tools
 from models import PatientProfile
 from prompts import RESEARCH_SYSTEM
 from tools import RESEARCH_TOOLS
@@ -33,8 +34,8 @@ def run_research_agent(client: anthropic.Anthropic, profile: PatientProfile) ->
         response = client.messages.create(
             model=RESEARCH_MODEL,
             max_tokens=8096,
-            system=RESEARCH_SYSTEM,
-            tools=RESEARCH_TOOLS,
+            system=cached_system(RESEARCH_SYSTEM),
+            tools=cached_tools(RESEARCH_TOOLS),
             messages=messages,
         )
 
@@ -113,8 +114,8 @@ def stream_research_agent(
         with client.messages.stream(
             model=RESEARCH_MODEL,
             max_tokens=8096,
-            system=LANGUAGE_DIRECTIVE[profile.lang] + RESEARCH_SYSTEM,
-            tools=RESEARCH_TOOLS,
+            system=cached_system(LANGUAGE_DIRECTIVE[profile.lang] + RESEARCH_SYSTEM),
+            tools=cached_tools(RESEARCH_TOOLS),
             messages=messages,
         ) as stream:
             for chunk in stream.text_stream:

llm.py

@@ -5,6 +5,18 @@ import anthropic
 import openai
 
 
+def cached_system(text: str) -> list[dict]:
+    """Wrap a system prompt string for Anthropic prompt caching."""
+    return [{"type": "text", "text": text, "cache_control": {"type": "ephemeral"}}]
+
+
+def cached_tools(tools: list[dict]) -> list[dict]:
+    """Mark the last tool with cache_control so the full tool list is cached."""
+    if not tools:
+        return tools
+    return [*tools[:-1], {**tools[-1], "cache_control": {"type": "ephemeral"}}]
+
+
 def _normalize_messages(messages: list) -> list[dict]:
     """Convert LangGraph/LangChain message objects or dicts to {role, content} dicts."""
     result = []