chore (ai/core): move providerMetadata to stable (#4814)

.changeset/nine-clouds-film.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+chore (ai/core): move providerMetadata to stable

content/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx

@@ -676,7 +676,7 @@ To see `generateText` in action, check out [these examples](#examples).
                 'True when there will be a continuation step with a continuation text.',
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               isOptional: true,
               description:
@@ -857,7 +857,7 @@ To see `generateText` in action, check out [these examples](#examples).
         'Warnings from the model provider (e.g. unsupported settings).',
     },
     {
-      name: 'experimental_providerMetadata',
+      name: 'providerMetadata',
       type: 'Record<string,Record<string,JSONValue>> | undefined',
       description:
         'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
@@ -1055,7 +1055,7 @@ To see `generateText` in action, check out [these examples](#examples).
                 'True when there will be a continuation step with a continuation text.',
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               isOptional: true,
               description:

content/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx

@@ -968,7 +968,7 @@ To see `streamText` in action, check out [these examples](#examples).
                 'True when there will be a continuation step with a continuation text.',
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               isOptional: true,
               description:
@@ -1022,7 +1022,7 @@ To see `streamText` in action, check out [these examples](#examples).
               ],
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               description:
                 'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
@@ -1191,7 +1191,7 @@ To see `streamText` in action, check out [these examples](#examples).
       ],
     },
     {
-      name: 'experimental_providerMetadata',
+      name: 'providerMetadata',
       type: 'Promise<Record<string,Record<string,JSONValue>> | undefined>',
       description:
         'Optional metadata from the provider. Resolved whe the response is finished. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
@@ -1515,7 +1515,7 @@ To see `streamText` in action, check out [these examples](#examples).
                 'True when there will be a continuation step with a continuation text.',
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               isOptional: true,
               description:
@@ -1851,7 +1851,7 @@ To see `streamText` in action, check out [these examples](#examples).
               description: 'The reason the model finished generating the text.',
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               isOptional: true,
               description:
@@ -1907,7 +1907,7 @@ To see `streamText` in action, check out [these examples](#examples).
               ],
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               isOptional: true,
               description:

content/docs/07-reference/01-ai-sdk-core/03-generate-object.mdx

@@ -601,7 +601,7 @@ To see `generateObject` in action, check out the [additional examples](#more-exa
         'Warnings from the model provider (e.g. unsupported settings).',
     },
     {
-      name: 'experimental_providerMetadata',
+      name: 'providerMetadata',
       type: 'Record<string,Record<string,JSONValue>> | undefined',
       description:
         'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',

content/docs/07-reference/01-ai-sdk-core/04-stream-object.mdx

@@ -538,7 +538,7 @@ To see `streamObject` in action, check out the [additional examples](#more-examp
               ],
             },
             {
-              name: 'experimental_providerMetadata',
+              name: 'providerMetadata',
               type: 'Record<string,Record<string,JSONValue>> | undefined',
               description:
                 'Optional metadata from the provider. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',
@@ -638,7 +638,7 @@ To see `streamObject` in action, check out the [additional examples](#more-examp
       ],
     },
     {
-      name: 'experimental_providerMetadata',
+      name: 'providerMetadata',
       type: 'Promise<Record<string,Record<string,JSONValue>> | undefined>',
       description:
         'Optional metadata from the provider. Resolved whe the response is finished. The outer key is the provider name. The inner values are the metadata. Details depend on the provider.',

content/providers/01-ai-sdk-providers/01-openai.mdx

@@ -294,10 +294,10 @@ const result = streamText({
 ```
 
 OpenAI provides usage information for predicted outputs (`acceptedPredictionTokens` and `rejectedPredictionTokens`).
-You can access it in the `experimental_providerMetadata` object.
+You can access it in the `providerMetadata` object.
 
 ```ts highlight="11"
-const openaiMetadata = (await result.experimental_providerMetadata)?.openai;
+const openaiMetadata = (await result.providerMetadata)?.openai;
 
 const acceptedPredictionTokens = openaiMetadata?.acceptedPredictionTokens;
 const rejectedPredictionTokens = openaiMetadata?.rejectedPredictionTokens;
@@ -383,13 +383,13 @@ Reasoning models support additional settings and response metadata:
 
   - the `reasoningEffort` option (or alternatively the `reasoningEffort` model setting), which determines the amount of reasoning the model performs.
 
-- You can use response `experimental_providerMetadata` to access the number of reasoning tokens that the model generated.
+- You can use response `providerMetadata` to access the number of reasoning tokens that the model generated.
 
 ```ts highlight="4,7-11,17"
 import { openai } from '@ai-sdk/openai';
 import { generateText } from 'ai';
 
-const { text, usage, experimental_providerMetadata } = await generateText({
+const { text, usage, providerMetadata } = await generateText({
   model: openai('o3-mini'),
   prompt: 'Invent a new holiday and describe its traditions.',
   providerOptions: {
@@ -402,7 +402,7 @@ const { text, usage, experimental_providerMetadata } = await generateText({
 console.log(text);
 console.log('Usage:', {
   ...usage,
-  reasoningTokens: experimental_providerMetadata?.openai?.reasoningTokens,
+  reasoningTokens: providerMetadata?.openai?.reasoningTokens,
 });
 ```
 
@@ -437,7 +437,7 @@ including `gpt-4o`, `gpt-4o-mini`, `o1-preview`, and `o1-mini`.
 
 - Prompt caching is automatically enabled for these models, when the prompt is 1024 tokens or longer. It does
   not need to be explicitly enabled.
-- You can use response `experimental_providerMetadata` to access the number of prompt tokens that were a cache hit.
+- You can use response `providerMetadata` to access the number of prompt tokens that were a cache hit.
 - Note that caching behavior is dependent on load on OpenAI's infrastructure. Prompt prefixes generally remain in the
   cache following 5-10 minutes of inactivity before they are evicted, but during off-peak periods they may persist for up
   to an hour.
@@ -446,14 +446,14 @@ including `gpt-4o`, `gpt-4o-mini`, `o1-preview`, and `o1-mini`.
 import { openai } from '@ai-sdk/openai';
 import { generateText } from 'ai';
 
-const { text, usage, experimental_providerMetadata } = await generateText({
+const { text, usage, providerMetadata } = await generateText({
   model: openai('gpt-4o-mini'),
   prompt: `A 1024-token or longer prompt...`,
 });
 
 console.log(`usage:`, {
   ...usage,
-  cachedPromptTokens: experimental_providerMetadata?.openai?.cachedPromptTokens,
+  cachedPromptTokens: providerMetadata?.openai?.cachedPromptTokens,
 });
 ```
 

content/providers/01-ai-sdk-providers/05-anthropic.mdx

@@ -107,7 +107,7 @@ Anthropic language models can also be used in the `streamText`, `generateObject`
 In the messages and message parts, you can use the `providerOptions` property to set cache control breakpoints.
 You need to set the `anthropic` property in the `providerOptions` object to `{ cacheControl: { type: 'ephemeral' } }` to set a cache control breakpoint.
 
-The cache creation input tokens are then returned in the `experimental_providerMetadata` object
+The cache creation input tokens are then returned in the `providerMetadata` object
 for `generateText` and `generateObject`, again under the `anthropic` property.
 When you use `streamText` or `streamObject`, the response contains a promise
 that resolves to the metadata. Alternatively you can receive it in the
@@ -140,7 +140,7 @@ const result = await generateText({
 });
 
 console.log(result.text);
-console.log(result.experimental_providerMetadata?.anthropic);
+console.log(result.providerMetadata?.anthropic);
 // e.g. { cacheCreationInputTokens: 2118, cacheReadInputTokens: 0 }
 ```
 

content/providers/01-ai-sdk-providers/08-amazon-bedrock.mdx

@@ -236,7 +236,7 @@ const result = await generateText({
 Tracing information will be returned in the provider metadata if you have tracing enabled.
 
 ```ts
-if (result.experimental_providerMetadata?.bedrock.trace) {
+if (result.providerMetadata?.bedrock.trace) {
   // ...
 }
 ```

content/providers/01-ai-sdk-providers/10-google-generative-ai.mdx

@@ -237,7 +237,7 @@ import { google } from '@ai-sdk/google';
 import { GoogleGenerativeAIProviderMetadata } from '@ai-sdk/google';
 import { generateText } from 'ai';
 
-const { text, experimental_providerMetadata } = await generateText({
+const { text, providerMetadata } = await generateText({
   model: google('gemini-1.5-pro', {
     useSearchGrounding: true,
   }),
@@ -248,7 +248,7 @@ const { text, experimental_providerMetadata } = await generateText({
 
 // access the grounding metadata. Casting to the provider metadata type
 // is optional but provides autocomplete and type safety.
-const metadata = experimental_providerMetadata?.google as
+const metadata = providerMetadata?.google as
   | GoogleGenerativeAIProviderMetadata
   | undefined;
 const groundingMetadata = metadata?.groundingMetadata;

content/providers/01-ai-sdk-providers/11-google-vertex.mdx

@@ -364,7 +364,7 @@ import { vertex } from '@ai-sdk/google-vertex';
 import { GoogleGenerativeAIProviderMetadata } from '@ai-sdk/google';
 import { generateText } from 'ai';
 
-const { text, experimental_providerMetadata } = await generateText({
+const { text, providerMetadata } = await generateText({
   model: vertex('gemini-1.5-pro', {
     useSearchGrounding: true,
   }),
@@ -375,7 +375,7 @@ const { text, experimental_providerMetadata } = await generateText({
 
 // access the grounding metadata. Casting to the provider metadata type
 // is optional but provides autocomplete and type safety.
-const metadata = experimental_providerMetadata?.google as
+const metadata = providerMetadata?.google as
   | GoogleGenerativeAIProviderMetadata
   | undefined;
 const groundingMetadata = metadata?.groundingMetadata;
@@ -809,7 +809,7 @@ Anthropic language models can also be used in the `streamText`, `generateObject`
 In the messages and message parts, you can use the `providerOptions` property to set cache control breakpoints.
 You need to set the `anthropic` property in the `providerOptions` object to `{ cacheControl: { type: 'ephemeral' } }` to set a cache control breakpoint.
 
-The cache creation input tokens are then returned in the `experimental_providerMetadata` object
+The cache creation input tokens are then returned in the `providerMetadata` object
 for `generateText` and `generateObject`, again under the `anthropic` property.
 When you use `streamText` or `streamObject`, the response contains a promise
 that resolves to the metadata. Alternatively you can receive it in the
@@ -842,7 +842,7 @@ const result = await generateText({
 });
 
 console.log(result.text);
-console.log(result.experimental_providerMetadata?.anthropic);
+console.log(result.providerMetadata?.anthropic);
 // e.g. { cacheCreationInputTokens: 2118, cacheReadInputTokens: 0 }
 ```
 

content/providers/01-ai-sdk-providers/30-deepseek.mdx

@@ -81,7 +81,7 @@ DeepSeek language models can be used in the `streamText` and `streamUI` function
 
 ### Cache Token Usage
 
-DeepSeek provides context caching on disk technology that can significantly reduce token costs for repeated content. You can access the cache hit/miss metrics through the `experimental_providerMetadata` property in the response:
+DeepSeek provides context caching on disk technology that can significantly reduce token costs for repeated content. You can access the cache hit/miss metrics through the `providerMetadata` property in the response:
 
 ```ts
 import { deepseek } from '@ai-sdk/deepseek';
@@ -92,7 +92,7 @@ const result = await generateText({
   prompt: 'Your prompt here',
 });
 
-console.log(result.experimental_providerMetadata);
+console.log(result.providerMetadata);
 // Example output: { deepseek: { promptCacheHitTokens: 1856, promptCacheMissTokens: 5 } }
 ```
 

content/providers/01-ai-sdk-providers/70-perplexity.mdx

@@ -82,7 +82,7 @@ Perplexity models can be used in the `streamText` and `streamUI` functions (see
 
 ### Provider Metadata
 
-The Perplexity provider includes additional experimental metadata in the response through `experimental_providerMetadata`:
+The Perplexity provider includes additional experimental metadata in the response through `providerMetadata`:
 
 ```ts
 const result = await generateText({
@@ -95,7 +95,7 @@ const result = await generateText({
   },
 });
 
-console.log(result.experimental_providerMetadata);
+console.log(result.providerMetadata);
 // Example output:
 // {
 //   perplexity: {

examples/ai-core/src/e2e/feature-test-suite.ts

@@ -926,8 +926,9 @@ export function createFeatureTestSuite({
                 expect(result.text.toLowerCase()).toContain('tokyo');
                 expect(result.usage?.totalTokens).toBeGreaterThan(0);
 
-                const metadata = result.experimental_providerMetadata
-                  ?.google as GoogleGenerativeAIProviderMetadata | undefined;
+                const metadata = result.providerMetadata?.google as
+                  | GoogleGenerativeAIProviderMetadata
+                  | undefined;
                 verifyGroundingMetadata(metadata?.groundingMetadata);
               });
 
@@ -942,8 +943,9 @@ export function createFeatureTestSuite({
                   chunks.push(chunk);
                 }
 
-                const metadata = (await result.experimental_providerMetadata)
-                  ?.google as GoogleGenerativeAIProviderMetadata | undefined;
+                const metadata = (await result.providerMetadata)?.google as
+                  | GoogleGenerativeAIProviderMetadata
+                  | undefined;
 
                 const completeText = chunks.join('');
                 expect(completeText).toBeTruthy();
@@ -959,8 +961,9 @@ export function createFeatureTestSuite({
                   prompt: 'What is the current population of Tokyo?',
                 });
 
-                const metadata = result.experimental_providerMetadata
-                  ?.google as GoogleGenerativeAIProviderMetadata | undefined;
+                const metadata = result.providerMetadata?.google as
+                  | GoogleGenerativeAIProviderMetadata
+                  | undefined;
                 verifySafetyRatings(metadata?.safetyRatings ?? []);
               });
 
@@ -974,8 +977,9 @@ export function createFeatureTestSuite({
                   // consume the stream
                 }
 
-                const metadata = (await result.experimental_providerMetadata)
-                  ?.google as GoogleGenerativeAIProviderMetadata | undefined;
+                const metadata = (await result.providerMetadata)?.google as
+                  | GoogleGenerativeAIProviderMetadata
+                  | undefined;
 
                 verifySafetyRatings(metadata?.safetyRatings ?? []);
               });

examples/ai-core/src/generate-text/amazon-bedrock-guardrails.ts

@@ -23,13 +23,7 @@ async function main() {
 
   console.log(result.text);
   console.log();
-  console.log(
-    JSON.stringify(
-      result.experimental_providerMetadata?.bedrock.trace,
-      null,
-      2,
-    ),
-  );
+  console.log(JSON.stringify(result.providerMetadata?.bedrock.trace, null, 2));
 }
 
 main().catch(console.error);

examples/ai-core/src/generate-text/anthropic-cache-control.ts

@@ -37,7 +37,7 @@ async function main() {
   });
 
   console.log(result.text);
-  console.log(result.experimental_providerMetadata?.anthropic);
+  console.log(result.providerMetadata?.anthropic);
   // e.g. { cacheCreationInputTokens: 2118, cacheReadInputTokens: 0 }
 }
 

examples/ai-core/src/generate-text/anthropic-computer-use-editor-cache-control.ts

@@ -51,7 +51,7 @@ This is a test file.
   });
 
   console.log('TEXT', result.text);
-  console.log('CACHE', result.experimental_providerMetadata?.anthropic);
+  console.log('CACHE', result.providerMetadata?.anthropic);
   console.log();
   console.log('EDITOR CONTENT', editorContent);
 }

examples/ai-core/src/generate-text/deepseek-cache-token.ts

@@ -31,7 +31,7 @@ async function main() {
 
   console.log(result.text);
   console.log(result.usage);
-  console.log(result.experimental_providerMetadata);
+  console.log(result.providerMetadata);
   // "prompt_cache_hit_tokens":1856,"prompt_cache_miss_tokens":5}
 }
 

examples/ai-core/src/generate-text/google-grounding.ts

@@ -14,7 +14,7 @@ async function main() {
   console.log(result.sources);
   console.log();
   console.log('PROVIDER METADATA');
-  console.log(result.experimental_providerMetadata?.google);
+  console.log(result.providerMetadata?.google);
 }
 
 main().catch(console.error);