Skip to content

Commit e4158fc

Browse files
matannahmanimatannahmani
authoredMar 1, 2025··
(feat): anthropic cache control (#34)
* anthropic cache control with readme * update testing
·
v0.4.5v0.4.2
1 parent 6ba3e7c commit e4158fc

8 files changed

+499
-14
lines changed
 

‎CHANGELOG.md

+6
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Changelog
22

3+
## [0.4.2]
4+
5+
### Added
6+
7+
- Anthropic cache control
8+
39
## [Unreleased]
410

511
### Fixed

‎README.md

+36
Original file line numberDiff line numberDiff line change
@@ -107,3 +107,39 @@ There are 3 ways to pass extra body to OpenRouter:
107107
messages: [{ role: 'user', content: 'Hello' }],
108108
});
109109
```
110+
111+
## Anthropic Prompt Caching
112+
113+
You can include Anthropic-specific options directly in your messages when using functions like `streamText`. The OpenRouter provider will automatically convert these messages to the correct format internally.
114+
115+
### Basic Usage
116+
117+
```typescript
118+
import { createOpenRouter } from '@openrouter/ai-sdk-provider';
119+
import { streamText } from 'ai';
120+
121+
const openrouter = createOpenRouter({ apiKey: 'your-api-key' });
122+
const model = openrouter('anthropic/<supported-caching-model>');
123+
124+
await streamText({
125+
model,
126+
messages: [
127+
{
128+
role: 'system',
129+
content: 'You are a helpful assistant.',
130+
// Add provider options at the message level
131+
providerMetadata: {
132+
openrouter: {
133+
// cache_control also works
134+
// cache_control: { type: 'ephemeral' }
135+
cacheControl: { type: 'ephemeral' },
136+
},
137+
},
138+
},
139+
{
140+
role: 'user',
141+
content: 'Hello, how are you?',
142+
},
143+
],
144+
});
145+
```

‎package.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "@openrouter/ai-sdk-provider",
3-
"version": "0.4.1",
3+
"version": "0.4.2",
44
"license": "Apache-2.0",
55
"sideEffects": false,
66
"main": "./dist/index.js",

‎src/convert-to-openrouter-chat-messages.test.ts

+388
Original file line numberDiff line numberDiff line change
@@ -41,3 +41,391 @@ describe('user messages', () => {
4141
expect(result).toEqual([{ role: 'user', content: 'Hello' }]);
4242
});
4343
});
44+
45+
describe('cache control', () => {
46+
it('should pass cache control from system message provider metadata', () => {
47+
const result = convertToOpenRouterChatMessages([
48+
{
49+
role: 'system',
50+
content: 'System prompt',
51+
providerMetadata: {
52+
anthropic: {
53+
cacheControl: { type: 'ephemeral' },
54+
},
55+
},
56+
},
57+
]);
58+
59+
expect(result).toEqual([
60+
{
61+
role: 'system',
62+
content: 'System prompt',
63+
cache_control: { type: 'ephemeral' },
64+
},
65+
]);
66+
});
67+
68+
it('should pass cache control from user message provider metadata (single text part)', () => {
69+
const result = convertToOpenRouterChatMessages([
70+
{
71+
role: 'user',
72+
content: [{ type: 'text', text: 'Hello' }],
73+
providerMetadata: {
74+
anthropic: {
75+
cacheControl: { type: 'ephemeral' },
76+
},
77+
},
78+
},
79+
]);
80+
81+
expect(result).toEqual([
82+
{
83+
role: 'user',
84+
content: 'Hello',
85+
cache_control: { type: 'ephemeral' },
86+
},
87+
]);
88+
});
89+
90+
it('should pass cache control from user message provider metadata (multiple parts)', () => {
91+
const result = convertToOpenRouterChatMessages([
92+
{
93+
role: 'user',
94+
content: [
95+
{ type: 'text', text: 'Hello' },
96+
{
97+
type: 'image',
98+
image: new Uint8Array([0, 1, 2, 3]),
99+
mimeType: 'image/png',
100+
},
101+
],
102+
providerMetadata: {
103+
anthropic: {
104+
cacheControl: { type: 'ephemeral' },
105+
},
106+
},
107+
},
108+
]);
109+
110+
expect(result).toEqual([
111+
{
112+
role: 'user',
113+
content: [
114+
{
115+
type: 'text',
116+
text: 'Hello',
117+
cache_control: undefined,
118+
},
119+
{
120+
type: 'image_url',
121+
image_url: { url: 'data:image/png;base64,AAECAw==' },
122+
cache_control: { type: 'ephemeral' },
123+
},
124+
],
125+
},
126+
]);
127+
});
128+
129+
it('should pass cache control to multiple image parts from user message provider metadata', () => {
130+
const result = convertToOpenRouterChatMessages([
131+
{
132+
role: 'user',
133+
content: [
134+
{ type: 'text', text: 'Hello' },
135+
{
136+
type: 'image',
137+
image: new Uint8Array([0, 1, 2, 3]),
138+
mimeType: 'image/png',
139+
},
140+
{
141+
type: 'image',
142+
image: new Uint8Array([4, 5, 6, 7]),
143+
mimeType: 'image/jpeg',
144+
},
145+
],
146+
providerMetadata: {
147+
anthropic: {
148+
cacheControl: { type: 'ephemeral' },
149+
},
150+
},
151+
},
152+
]);
153+
154+
expect(result).toEqual([
155+
{
156+
role: 'user',
157+
content: [
158+
{
159+
type: 'text',
160+
text: 'Hello',
161+
cache_control: undefined,
162+
},
163+
{
164+
type: 'image_url',
165+
image_url: { url: 'data:image/png;base64,AAECAw==' },
166+
cache_control: { type: 'ephemeral' },
167+
},
168+
{
169+
type: 'image_url',
170+
image_url: { url: 'data:image/jpeg;base64,BAUGBw==' },
171+
cache_control: { type: 'ephemeral' },
172+
},
173+
],
174+
},
175+
]);
176+
});
177+
178+
it('should pass cache control to file parts from user message provider metadata', () => {
179+
const result = convertToOpenRouterChatMessages([
180+
{
181+
role: 'user',
182+
content: [
183+
{ type: 'text', text: 'Hello' },
184+
{
185+
type: 'file',
186+
data: 'file content',
187+
mimeType: 'text/plain',
188+
},
189+
],
190+
providerMetadata: {
191+
anthropic: {
192+
cacheControl: { type: 'ephemeral' },
193+
},
194+
},
195+
},
196+
]);
197+
198+
expect(result).toEqual([
199+
{
200+
role: 'user',
201+
content: [
202+
{
203+
type: 'text',
204+
text: 'Hello',
205+
cache_control: undefined,
206+
},
207+
{
208+
type: 'text',
209+
text: 'file content',
210+
cache_control: { type: 'ephemeral' },
211+
},
212+
],
213+
},
214+
]);
215+
});
216+
217+
it('should handle mixed part-specific and message-level cache control for multiple parts', () => {
218+
const result = convertToOpenRouterChatMessages([
219+
{
220+
role: 'user',
221+
content: [
222+
{
223+
type: 'text',
224+
text: 'Hello',
225+
// No part-specific provider metadata
226+
},
227+
{
228+
type: 'image',
229+
image: new Uint8Array([0, 1, 2, 3]),
230+
mimeType: 'image/png',
231+
providerMetadata: {
232+
anthropic: {
233+
cacheControl: { type: 'ephemeral' },
234+
},
235+
},
236+
},
237+
{
238+
type: 'file',
239+
data: 'file content',
240+
mimeType: 'text/plain',
241+
// No part-specific provider metadata
242+
},
243+
],
244+
providerMetadata: {
245+
anthropic: {
246+
cacheControl: { type: 'ephemeral' },
247+
},
248+
},
249+
},
250+
]);
251+
252+
expect(result).toEqual([
253+
{
254+
role: 'user',
255+
content: [
256+
{
257+
type: 'text',
258+
text: 'Hello',
259+
cache_control: undefined,
260+
},
261+
{
262+
type: 'image_url',
263+
image_url: { url: 'data:image/png;base64,AAECAw==' },
264+
cache_control: { type: 'ephemeral' },
265+
},
266+
{
267+
type: 'text',
268+
text: 'file content',
269+
cache_control: { type: 'ephemeral' },
270+
},
271+
],
272+
},
273+
]);
274+
});
275+
276+
it('should pass cache control from individual content part provider metadata', () => {
277+
const result = convertToOpenRouterChatMessages([
278+
{
279+
role: 'user',
280+
content: [
281+
{
282+
type: 'text',
283+
text: 'Hello',
284+
providerMetadata: {
285+
anthropic: {
286+
cacheControl: { type: 'ephemeral' },
287+
},
288+
},
289+
},
290+
{
291+
type: 'image',
292+
image: new Uint8Array([0, 1, 2, 3]),
293+
mimeType: 'image/png',
294+
},
295+
],
296+
},
297+
]);
298+
299+
expect(result).toEqual([
300+
{
301+
role: 'user',
302+
content: [
303+
{
304+
type: 'text',
305+
text: 'Hello',
306+
cache_control: { type: 'ephemeral' },
307+
},
308+
{
309+
type: 'image_url',
310+
image_url: { url: 'data:image/png;base64,AAECAw==' },
311+
},
312+
],
313+
},
314+
]);
315+
});
316+
317+
it('should pass cache control from assistant message provider metadata', () => {
318+
const result = convertToOpenRouterChatMessages([
319+
{
320+
role: 'assistant',
321+
content: [{ type: 'text', text: 'Assistant response' }],
322+
providerMetadata: {
323+
anthropic: {
324+
cacheControl: { type: 'ephemeral' },
325+
},
326+
},
327+
},
328+
]);
329+
330+
expect(result).toEqual([
331+
{
332+
role: 'assistant',
333+
content: 'Assistant response',
334+
cache_control: { type: 'ephemeral' },
335+
},
336+
]);
337+
});
338+
339+
it('should pass cache control from tool message provider metadata', () => {
340+
const result = convertToOpenRouterChatMessages([
341+
{
342+
role: 'tool',
343+
content: [
344+
{
345+
type: 'tool-result',
346+
toolCallId: 'call-123',
347+
toolName: 'calculator',
348+
result: { answer: 42 },
349+
isError: false,
350+
},
351+
],
352+
providerMetadata: {
353+
anthropic: {
354+
cacheControl: { type: 'ephemeral' },
355+
},
356+
},
357+
},
358+
]);
359+
360+
expect(result).toEqual([
361+
{
362+
role: 'tool',
363+
tool_call_id: 'call-123',
364+
content: JSON.stringify({ answer: 42 }),
365+
cache_control: { type: 'ephemeral' },
366+
},
367+
]);
368+
});
369+
370+
it('should support the alias cache_control field', () => {
371+
const result = convertToOpenRouterChatMessages([
372+
{
373+
role: 'system',
374+
content: 'System prompt',
375+
providerMetadata: {
376+
anthropic: {
377+
cache_control: { type: 'ephemeral' },
378+
},
379+
},
380+
},
381+
]);
382+
383+
expect(result).toEqual([
384+
{
385+
role: 'system',
386+
content: 'System prompt',
387+
cache_control: { type: 'ephemeral' },
388+
},
389+
]);
390+
});
391+
392+
it('should support cache control on last message in content array', () => {
393+
const result = convertToOpenRouterChatMessages([
394+
{
395+
role: 'system',
396+
content: 'System prompt',
397+
},
398+
{
399+
role: 'user',
400+
content: [
401+
{ type: 'text', text: 'User prompt' },
402+
{
403+
type: 'text',
404+
text: 'User prompt 2',
405+
providerMetadata: {
406+
anthropic: { cacheControl: { type: 'ephemeral' } },
407+
},
408+
},
409+
],
410+
},
411+
]);
412+
413+
expect(result).toEqual([
414+
{
415+
role: 'system',
416+
content: 'System prompt',
417+
},
418+
{
419+
role: 'user',
420+
content: [
421+
{ type: 'text', text: 'User prompt' },
422+
{
423+
type: 'text',
424+
text: 'User prompt 2',
425+
cache_control: { type: 'ephemeral' },
426+
},
427+
],
428+
},
429+
]);
430+
});
431+
});

‎src/convert-to-openrouter-chat-messages.ts

+53-7
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,70 @@
1-
import type { LanguageModelV1Prompt } from '@ai-sdk/provider';
1+
import type {
2+
LanguageModelV1Prompt,
3+
LanguageModelV1ProviderMetadata,
4+
} from '@ai-sdk/provider';
25
import type {
36
ChatCompletionContentPart,
47
OpenRouterChatPrompt,
58
} from './openrouter-chat-prompt';
69

710
import { convertUint8ArrayToBase64 } from '@ai-sdk/provider-utils';
811

12+
// Type for OpenRouter Cache Control following Anthropic's pattern
13+
export type OpenRouterCacheControl = { type: 'ephemeral' };
14+
915
export function convertToOpenRouterChatMessages(
1016
prompt: LanguageModelV1Prompt,
1117
): OpenRouterChatPrompt {
1218
const messages: OpenRouterChatPrompt = [];
1319

14-
for (const { role, content } of prompt) {
20+
function getCacheControl(
21+
providerMetadata: LanguageModelV1ProviderMetadata | undefined,
22+
): OpenRouterCacheControl | undefined {
23+
const anthropic = providerMetadata?.anthropic;
24+
25+
// Allow both cacheControl and cache_control:
26+
const cacheControlValue =
27+
anthropic?.cacheControl ?? anthropic?.cache_control;
28+
29+
// Return the cache control object if it exists
30+
return cacheControlValue as OpenRouterCacheControl | undefined;
31+
}
32+
33+
for (const { role, content, providerMetadata } of prompt) {
1534
switch (role) {
1635
case 'system': {
17-
messages.push({ role: 'system', content });
36+
messages.push({
37+
role: 'system',
38+
content,
39+
cache_control: getCacheControl(providerMetadata),
40+
});
1841
break;
1942
}
2043

2144
case 'user': {
2245
if (content.length === 1 && content[0]?.type === 'text') {
23-
messages.push({ role: 'user', content: content[0].text });
46+
messages.push({
47+
role: 'user',
48+
content: content[0].text,
49+
cache_control:
50+
getCacheControl(providerMetadata) ??
51+
getCacheControl(content[0].providerMetadata),
52+
});
2453
break;
2554
}
2655

56+
// Get message level cache control
57+
const messageCacheControl = getCacheControl(providerMetadata);
58+
2759
const contentParts: ChatCompletionContentPart[] = content.map(
2860
(part) => {
2961
switch (part.type) {
3062
case 'text':
3163
return {
3264
type: 'text' as const,
3365
text: part.text,
66+
// For text parts, only use part-specific cache control
67+
cache_control: getCacheControl(part.providerMetadata),
3468
};
3569
case 'image':
3670
return {
@@ -39,16 +73,23 @@ export function convertToOpenRouterChatMessages(
3973
url:
4074
part.image instanceof URL
4175
? part.image.toString()
42-
: `data:${
43-
part.mimeType ?? 'image/jpeg'
44-
};base64,${convertUint8ArrayToBase64(part.image)}`,
76+
: `data:${part.mimeType ?? 'image/jpeg'};base64,${convertUint8ArrayToBase64(
77+
part.image,
78+
)}`,
4579
},
80+
// For image parts, use part-specific or message-level cache control
81+
cache_control:
82+
getCacheControl(part.providerMetadata) ??
83+
messageCacheControl,
4684
};
4785
case 'file':
4886
return {
4987
type: 'text' as const,
5088
text:
5189
part.data instanceof URL ? part.data.toString() : part.data,
90+
cache_control:
91+
getCacheControl(part.providerMetadata) ??
92+
messageCacheControl,
5293
};
5394
default: {
5495
const _exhaustiveCheck: never = part;
@@ -60,6 +101,7 @@ export function convertToOpenRouterChatMessages(
60101
},
61102
);
62103

104+
// For multi-part messages, don't add cache_control at the root level
63105
messages.push({
64106
role: 'user',
65107
content: contentParts,
@@ -108,6 +150,7 @@ export function convertToOpenRouterChatMessages(
108150
role: 'assistant',
109151
content: text,
110152
tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
153+
cache_control: getCacheControl(providerMetadata),
111154
});
112155

113156
break;
@@ -119,6 +162,9 @@ export function convertToOpenRouterChatMessages(
119162
role: 'tool',
120163
tool_call_id: toolResponse.toolCallId,
121164
content: JSON.stringify(toolResponse.result),
165+
cache_control:
166+
getCacheControl(providerMetadata) ??
167+
getCacheControl(toolResponse.providerMetadata),
122168
});
123169
}
124170
break;

‎src/openrouter-chat-prompt.ts

+9
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
// Type for OpenRouter Cache Control following Anthropic's pattern
2+
export type OpenRouterCacheControl = { type: 'ephemeral' };
3+
14
export type OpenRouterChatPrompt = Array<ChatCompletionMessageParam>;
25

36
export type ChatCompletionMessageParam =
@@ -9,11 +12,13 @@ export type ChatCompletionMessageParam =
912
export interface ChatCompletionSystemMessageParam {
1013
role: 'system';
1114
content: string;
15+
cache_control?: OpenRouterCacheControl;
1216
}
1317

1418
export interface ChatCompletionUserMessageParam {
1519
role: 'user';
1620
content: string | Array<ChatCompletionContentPart>;
21+
cache_control?: OpenRouterCacheControl;
1722
}
1823

1924
export type ChatCompletionContentPart =
@@ -25,17 +30,20 @@ export interface ChatCompletionContentPartImage {
2530
image_url: {
2631
url: string;
2732
};
33+
cache_control?: OpenRouterCacheControl;
2834
}
2935

3036
export interface ChatCompletionContentPartText {
3137
type: 'text';
3238
text: string;
39+
cache_control?: OpenRouterCacheControl;
3340
}
3441

3542
export interface ChatCompletionAssistantMessageParam {
3643
role: 'assistant';
3744
content?: string | null;
3845
tool_calls?: Array<ChatCompletionMessageToolCall>;
46+
cache_control?: OpenRouterCacheControl;
3947
}
4048

4149
export interface ChatCompletionMessageToolCall {
@@ -51,4 +59,5 @@ export interface ChatCompletionToolMessageParam {
5159
role: 'tool';
5260
content: string;
5361
tool_call_id: string;
62+
cache_control?: OpenRouterCacheControl;
5463
}

‎vitest.edge.config.ts

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
import { defineConfig } from "vitest/config";
1+
import { defineConfig } from 'vitest/config';
22

33
// https://vitejs.dev/config/
44
export default defineConfig({
55
test: {
6-
environment: "edge-runtime",
6+
environment: 'edge-runtime',
77
globals: true,
8-
include: ["**/*.test.ts", "**/*.test.tsx"],
8+
include: ['**/*.test.ts', '**/*.test.tsx'],
99
},
1010
});

‎vitest.node.config.ts

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
1-
import { defineConfig } from "vitest/config";
1+
import { defineConfig } from 'vitest/config';
22

33
// https://vitejs.dev/config/
44
export default defineConfig({
55
test: {
6-
environment: "node",
6+
environment: 'node',
77
globals: true,
8-
include: ["**/*.test.ts", "**/*.test.tsx"],
8+
include: ['**/*.test.ts', '**/*.test.tsx'],
99
},
1010
});

0 commit comments

Comments
 (0)
Please sign in to comment.