Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

provider-options-example.ts

335 lines9.4 KB

1/**
2 * Provider-Specific Options Example
3 *
4 * This example demonstrates how to use type-safe provider-specific options
5 * with different AI adapters. The providerOptions field is typed based on
6 * the selected adapter, giving you autocomplete and type checking.
7 */
8
9import { AI, tool } from "@tanstack/ai";
10import { OpenAIAdapter } from "@tanstack/ai-openai";
11import { AnthropicAdapter } from "@tanstack/ai-anthropic";
13// Initialize AI with multiple adapters
14const ai = new AI({
15 adapters: {
16 openai: new OpenAIAdapter({
17 apiKey: process.env.OPENAI_API_KEY!,
18 }),
19 anthropic: new AnthropicAdapter({
20 apiKey: process.env.ANTHROPIC_API_KEY!,
21 }),
22 },
23 tools: {
24 calculator: tool({
25 type: "function",
26 function: {
27 name: "calculator",
28 description: "Perform a calculation",
29 parameters: {
30 type: "object",
31 properties: {
32 operation: { type: "string" },
33 a: { type: "number" },
34 b: { type: "number" },
35 },
36 required: ["operation", "a", "b"],
37 },
38 },
39 execute: async (args) => {
40 const { operation, a, b } = args;
41 switch (operation) {
42 case "add": return String(a + b);
43 case "subtract": return String(a - b);
44 case "multiply": return String(a * b);
45 case "divide": return String(a / b);
46 default: return "Unknown operation";
47 }
48 },
49 }),
50 },
51});
53// ============================================================================
54// OpenAI-Specific Options
55// ============================================================================
57async function exampleOpenAIReasoningModel() {
58 const response = await ai.chat({
59 adapter: "openai",
60 model: "gpt-4o", // Reasoning-capable model
61 messages: [
62 {
63 role: "user",
64 content: "Explain the reasoning behind choosing TypeScript over JavaScript for a large project",
65 },
66 ],
67 // ✅ TypeScript knows this is OpenAI and provides autocomplete
68 providerOptions: {
69 openai: {
70 // Get detailed reasoning summaries from reasoning models
71 reasoningSummary: "detailed", // 'auto' | 'detailed'
73 // Control response verbosity
74 textVerbosity: "high", // 'low' | 'medium' | 'high'
76 // Store generation for distillation
77 store: true,
78 metadata: {
79 session: "example-123",
80 user: "demo-user",
81 },
82 },
83 },
84 });
86 console.log("Response:", response.content);
87}
89async function exampleOpenAIToolCalling() {
90 const response = await ai.chat({
91 adapter: "openai",
92 model: "gpt-4o",
93 messages: [
94 {
95 role: "user",
96 content: "What is 25 multiplied by 4, then divide that by 2?",
97 },
98 ],
99 tools: ["calculator"],
100 providerOptions: {
101 openai: {
102 // Control parallel tool calls
103 parallelToolCalls: false, // Execute tools one at a time
105 // Limit total tool calls
106 maxToolCalls: 5,
108 // User identifier for monitoring
109 user: "demo-user-123",
110 },
111 },
112 });
114 console.log("Response:", response.content);
115}
117async function exampleOpenAIPromptCaching() {
118 const response = await ai.chat({
119 adapter: "openai",
120 model: "gpt-4o",
121 messages: [
122 {
123 role: "system",
124 content: "You are an expert TypeScript developer. " + "A".repeat(2000), // Long prompt
125 },
126 {
127 role: "user",
128 content: "How do I create a generic type?",
129 },
130 ],
131 providerOptions: {
132 openai: {
133 // Manual prompt caching control
134 promptCacheKey: "typescript-expert-v1",
136 // Service tier for cost/latency tradeoff
137 serviceTier: "flex", // 'auto' | 'flex' | 'priority' | 'default'
138 },
139 },
140 });
142 console.log("Response:", response.content);
143}
145async function exampleOpenAILogprobs() {
146 const response = await ai.chat({
147 adapter: "openai",
148 model: "gpt-4o",
149 messages: [
150 {
151 role: "user",
152 content: "Is TypeScript better than JavaScript? Answer with yes or no.",
153 },
154 ],
155 providerOptions: {
156 openai: {
157 // Get log probabilities for tokens
158 logprobs: 5, // Get top 5 token probabilities (or use true for all)
160 // Bias specific tokens
161 logitBias: {
162 // Token IDs for "yes" and "no" - adjust likelihood
163 9820: 10, // Increase likelihood of "yes"
164 2201: -10, // Decrease likelihood of "no"
165 },
166 },
167 },
168 });
170 console.log("Response:", response.content);
171}
173// ============================================================================
174// Anthropic-Specific Options
175// ============================================================================
177async function exampleAnthropicReasoning() {
178 const response = await ai.chat({
179 adapter: "anthropic",
180 model: "claude-opus-4-20250514", // Reasoning-capable model
181 messages: [
182 {
183 role: "user",
184 content: "How many people will live in the world in 2040?",
185 },
186 ],
187 // ✅ TypeScript knows this is Anthropic and provides different options
188 providerOptions: {
189 anthropic: {
190 // Enable reasoning with token budget
191 thinking: {
192 type: "enabled",
193 budgetTokens: 12000, // Allocate tokens for reasoning
194 },
196 // Include reasoning content in requests
197 sendReasoning: true,
198 },
199 },
200 });
202 console.log("Response:", response.content);
203}
205async function exampleAnthropicPromptCaching() {
206 // Note: Cache control is applied at the message level via providerOptions in content
207 const longDocument = "A".repeat(5000); // Document longer than 2048 tokens
209 const response = await ai.chat({
210 adapter: "anthropic",
211 model: "claude-3-5-sonnet-20241022",
212 messages: [
213 {
214 role: "user",
215 content: `Analyze this document: ${longDocument}`,
216 },
217 ],
218 providerOptions: {
219 anthropic: {
220 // Enable prompt caching with longer TTL
221 cacheControl: {
222 type: "ephemeral",
223 ttl: "1h", // '5m' (default) | '1h'
224 },
225 },
226 },
227 });
229 console.log("Response:", response.content);
230}
232// ============================================================================
233// Image Generation with Provider Options
234// ============================================================================
236async function exampleOpenAIImageGeneration() {
237 const result = await ai.image({
238 adapter: "openai",
239 model: "dall-e-3",
240 prompt: "A futuristic guitar made of crystal with glowing strings",
241 size: "1024x1024",
242 providerOptions: {
243 openai: {
244 // DALL-E 3 specific options
245 quality: "hd", // 'standard' | 'hd'
246 style: "vivid", // 'natural' | 'vivid'
248 // Reproducibility
249 seed: 42,
250 },
251 },
252 });
254 console.log("Generated image:", result.image?.base64.substring(0, 50) + "...");
255}
257// ============================================================================
258// Type Safety Demonstration
259// ============================================================================
261async function demonstrateTypeSafety() {
262 // ❌ This would be a TypeScript error:
263 // await ai.chat({
264 // adapter: "openai",
265 // model: "gpt-4",
266 // messages: [],
267 // providerOptions: {
268 // openai: {
269 // thinking: { type: "enabled", budgetTokens: 1000 } // ERROR: thinking doesn't exist on OpenAI
270 // }
271 // }
272 // });
274 // ❌ This would also be a TypeScript error:
275 // await ai.chat({
276 // adapter: "anthropic",
277 // model: "claude-3-opus-20240229",
278 // messages: [],
279 // providerOptions: {
280 // anthropic: {
281 // reasoningSummary: "detailed" // ERROR: reasoningSummary doesn't exist on Anthropic
282 // }
283 // }
284 // });
286 // ✅ Only valid options are allowed
287 await ai.chat({
288 adapter: "openai",
289 model: "gpt-4o",
290 messages: [{ role: "user", content: "Hello" }],
291 providerOptions: {
292 openai: {
293 reasoningSummary: "detailed", // Valid OpenAI option
294 textVerbosity: "high", // Valid OpenAI option
295 },
296 },
297 });
299 await ai.chat({
300 adapter: "anthropic",
301 model: "claude-3-opus-20240229",
302 messages: [{ role: "user", content: "Hello" }],
303 providerOptions: {
304 anthropic: {
305 thinking: { type: "enabled", budgetTokens: 5000 }, // Valid Anthropic option
306 sendReasoning: true, // Valid Anthropic option
307 },
308 },
309 });
310}
312// ============================================================================
313// Run Examples
314// ============================================================================
316async function main() {
317 console.log("\n=== OpenAI Examples ===");
318 await exampleOpenAIReasoningModel();
319 await exampleOpenAIToolCalling();
320 await exampleOpenAIPromptCaching();
321 await exampleOpenAILogprobs();
322 await exampleOpenAIImageGeneration();
324 console.log("\n=== Anthropic Examples ===");
325 await exampleAnthropicReasoning();
326 await exampleAnthropicPromptCaching();
328 console.log("\n=== Type Safety Demo ===");
329 await demonstrateTypeSafety();
330}
332// Run if called directly
333if (require.main === module) {
334 main().catch(console.error);
335}