@fondation-io/ai 7.0.0-beta.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (536) hide show
  1. package/CHANGELOG.md +7687 -0
  2. package/README.md +238 -0
  3. package/dist/index.d.mts +7056 -0
  4. package/dist/index.d.ts +7056 -0
  5. package/dist/index.js +14607 -0
  6. package/dist/index.js.map +1 -0
  7. package/dist/index.mjs +14578 -0
  8. package/dist/index.mjs.map +1 -0
  9. package/dist/internal/index.d.mts +303 -0
  10. package/dist/internal/index.d.ts +303 -0
  11. package/dist/internal/index.js +1352 -0
  12. package/dist/internal/index.js.map +1 -0
  13. package/dist/internal/index.mjs +1336 -0
  14. package/dist/internal/index.mjs.map +1 -0
  15. package/dist/test/index.d.mts +265 -0
  16. package/dist/test/index.d.ts +265 -0
  17. package/dist/test/index.js +509 -0
  18. package/dist/test/index.js.map +1 -0
  19. package/dist/test/index.mjs +472 -0
  20. package/dist/test/index.mjs.map +1 -0
  21. package/docs/00-introduction/index.mdx +76 -0
  22. package/docs/02-foundations/01-overview.mdx +43 -0
  23. package/docs/02-foundations/02-providers-and-models.mdx +160 -0
  24. package/docs/02-foundations/03-prompts.mdx +616 -0
  25. package/docs/02-foundations/04-tools.mdx +251 -0
  26. package/docs/02-foundations/05-streaming.mdx +62 -0
  27. package/docs/02-foundations/06-provider-options.mdx +345 -0
  28. package/docs/02-foundations/index.mdx +49 -0
  29. package/docs/02-getting-started/00-choosing-a-provider.mdx +110 -0
  30. package/docs/02-getting-started/01-navigating-the-library.mdx +85 -0
  31. package/docs/02-getting-started/02-nextjs-app-router.mdx +559 -0
  32. package/docs/02-getting-started/03-nextjs-pages-router.mdx +542 -0
  33. package/docs/02-getting-started/04-svelte.mdx +627 -0
  34. package/docs/02-getting-started/05-nuxt.mdx +566 -0
  35. package/docs/02-getting-started/06-nodejs.mdx +512 -0
  36. package/docs/02-getting-started/07-expo.mdx +766 -0
  37. package/docs/02-getting-started/08-tanstack-start.mdx +583 -0
  38. package/docs/02-getting-started/09-coding-agents.mdx +179 -0
  39. package/docs/02-getting-started/index.mdx +44 -0
  40. package/docs/03-agents/01-overview.mdx +96 -0
  41. package/docs/03-agents/02-building-agents.mdx +449 -0
  42. package/docs/03-agents/03-workflows.mdx +386 -0
  43. package/docs/03-agents/04-loop-control.mdx +394 -0
  44. package/docs/03-agents/05-configuring-call-options.mdx +286 -0
  45. package/docs/03-agents/06-memory.mdx +222 -0
  46. package/docs/03-agents/06-subagents.mdx +362 -0
  47. package/docs/03-agents/index.mdx +46 -0
  48. package/docs/03-ai-sdk-core/01-overview.mdx +31 -0
  49. package/docs/03-ai-sdk-core/05-generating-text.mdx +707 -0
  50. package/docs/03-ai-sdk-core/10-generating-structured-data.mdx +498 -0
  51. package/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx +1148 -0
  52. package/docs/03-ai-sdk-core/16-mcp-tools.mdx +383 -0
  53. package/docs/03-ai-sdk-core/20-prompt-engineering.mdx +146 -0
  54. package/docs/03-ai-sdk-core/25-settings.mdx +216 -0
  55. package/docs/03-ai-sdk-core/26-reasoning.mdx +190 -0
  56. package/docs/03-ai-sdk-core/30-embeddings.mdx +236 -0
  57. package/docs/03-ai-sdk-core/31-reranking.mdx +218 -0
  58. package/docs/03-ai-sdk-core/35-image-generation.mdx +341 -0
  59. package/docs/03-ai-sdk-core/36-transcription.mdx +227 -0
  60. package/docs/03-ai-sdk-core/37-speech.mdx +169 -0
  61. package/docs/03-ai-sdk-core/38-video-generation.mdx +366 -0
  62. package/docs/03-ai-sdk-core/40-middleware.mdx +485 -0
  63. package/docs/03-ai-sdk-core/45-provider-management.mdx +349 -0
  64. package/docs/03-ai-sdk-core/50-error-handling.mdx +149 -0
  65. package/docs/03-ai-sdk-core/55-testing.mdx +219 -0
  66. package/docs/03-ai-sdk-core/60-telemetry.mdx +391 -0
  67. package/docs/03-ai-sdk-core/65-devtools.mdx +107 -0
  68. package/docs/03-ai-sdk-core/65-event-listeners.mdx +1303 -0
  69. package/docs/03-ai-sdk-core/index.mdx +99 -0
  70. package/docs/04-ai-sdk-ui/01-overview.mdx +44 -0
  71. package/docs/04-ai-sdk-ui/02-chatbot.mdx +1320 -0
  72. package/docs/04-ai-sdk-ui/03-chatbot-message-persistence.mdx +534 -0
  73. package/docs/04-ai-sdk-ui/03-chatbot-resume-streams.mdx +263 -0
  74. package/docs/04-ai-sdk-ui/03-chatbot-tool-usage.mdx +682 -0
  75. package/docs/04-ai-sdk-ui/04-generative-user-interfaces.mdx +389 -0
  76. package/docs/04-ai-sdk-ui/05-completion.mdx +181 -0
  77. package/docs/04-ai-sdk-ui/08-object-generation.mdx +344 -0
  78. package/docs/04-ai-sdk-ui/20-streaming-data.mdx +397 -0
  79. package/docs/04-ai-sdk-ui/21-error-handling.mdx +190 -0
  80. package/docs/04-ai-sdk-ui/21-transport.mdx +174 -0
  81. package/docs/04-ai-sdk-ui/24-reading-ui-message-streams.mdx +104 -0
  82. package/docs/04-ai-sdk-ui/25-message-metadata.mdx +152 -0
  83. package/docs/04-ai-sdk-ui/50-stream-protocol.mdx +503 -0
  84. package/docs/04-ai-sdk-ui/index.mdx +64 -0
  85. package/docs/05-ai-sdk-rsc/01-overview.mdx +45 -0
  86. package/docs/05-ai-sdk-rsc/02-streaming-react-components.mdx +209 -0
  87. package/docs/05-ai-sdk-rsc/03-generative-ui-state.mdx +279 -0
  88. package/docs/05-ai-sdk-rsc/03-saving-and-restoring-states.mdx +105 -0
  89. package/docs/05-ai-sdk-rsc/04-multistep-interfaces.mdx +282 -0
  90. package/docs/05-ai-sdk-rsc/05-streaming-values.mdx +157 -0
  91. package/docs/05-ai-sdk-rsc/06-loading-state.mdx +273 -0
  92. package/docs/05-ai-sdk-rsc/08-error-handling.mdx +94 -0
  93. package/docs/05-ai-sdk-rsc/09-authentication.mdx +42 -0
  94. package/docs/05-ai-sdk-rsc/10-migrating-to-ui.mdx +722 -0
  95. package/docs/05-ai-sdk-rsc/index.mdx +63 -0
  96. package/docs/06-advanced/01-prompt-engineering.mdx +96 -0
  97. package/docs/06-advanced/02-stopping-streams.mdx +184 -0
  98. package/docs/06-advanced/03-backpressure.mdx +173 -0
  99. package/docs/06-advanced/04-caching.mdx +169 -0
  100. package/docs/06-advanced/05-multiple-streamables.mdx +68 -0
  101. package/docs/06-advanced/06-rate-limiting.mdx +60 -0
  102. package/docs/06-advanced/07-rendering-ui-with-language-models.mdx +225 -0
  103. package/docs/06-advanced/08-model-as-router.mdx +120 -0
  104. package/docs/06-advanced/09-multistep-interfaces.mdx +115 -0
  105. package/docs/06-advanced/09-sequential-generations.mdx +55 -0
  106. package/docs/06-advanced/10-vercel-deployment-guide.mdx +117 -0
  107. package/docs/06-advanced/index.mdx +11 -0
  108. package/docs/07-reference/01-ai-sdk-core/01-generate-text.mdx +2785 -0
  109. package/docs/07-reference/01-ai-sdk-core/02-stream-text.mdx +3752 -0
  110. package/docs/07-reference/01-ai-sdk-core/05-embed.mdx +332 -0
  111. package/docs/07-reference/01-ai-sdk-core/06-embed-many.mdx +330 -0
  112. package/docs/07-reference/01-ai-sdk-core/06-rerank.mdx +323 -0
  113. package/docs/07-reference/01-ai-sdk-core/10-generate-image.mdx +251 -0
  114. package/docs/07-reference/01-ai-sdk-core/11-transcribe.mdx +152 -0
  115. package/docs/07-reference/01-ai-sdk-core/12-generate-speech.mdx +221 -0
  116. package/docs/07-reference/01-ai-sdk-core/13-generate-video.mdx +264 -0
  117. package/docs/07-reference/01-ai-sdk-core/15-agent.mdx +235 -0
  118. package/docs/07-reference/01-ai-sdk-core/16-tool-loop-agent.mdx +973 -0
  119. package/docs/07-reference/01-ai-sdk-core/17-create-agent-ui-stream.mdx +154 -0
  120. package/docs/07-reference/01-ai-sdk-core/18-create-agent-ui-stream-response.mdx +173 -0
  121. package/docs/07-reference/01-ai-sdk-core/18-pipe-agent-ui-stream-to-response.mdx +150 -0
  122. package/docs/07-reference/01-ai-sdk-core/20-tool.mdx +209 -0
  123. package/docs/07-reference/01-ai-sdk-core/22-dynamic-tool.mdx +223 -0
  124. package/docs/07-reference/01-ai-sdk-core/23-create-mcp-client.mdx +423 -0
  125. package/docs/07-reference/01-ai-sdk-core/24-mcp-stdio-transport.mdx +68 -0
  126. package/docs/07-reference/01-ai-sdk-core/25-json-schema.mdx +94 -0
  127. package/docs/07-reference/01-ai-sdk-core/26-zod-schema.mdx +109 -0
  128. package/docs/07-reference/01-ai-sdk-core/27-valibot-schema.mdx +58 -0
  129. package/docs/07-reference/01-ai-sdk-core/28-output.mdx +342 -0
  130. package/docs/07-reference/01-ai-sdk-core/30-model-message.mdx +435 -0
  131. package/docs/07-reference/01-ai-sdk-core/31-ui-message.mdx +264 -0
  132. package/docs/07-reference/01-ai-sdk-core/32-validate-ui-messages.mdx +101 -0
  133. package/docs/07-reference/01-ai-sdk-core/33-safe-validate-ui-messages.mdx +113 -0
  134. package/docs/07-reference/01-ai-sdk-core/40-provider-registry.mdx +198 -0
  135. package/docs/07-reference/01-ai-sdk-core/42-custom-provider.mdx +157 -0
  136. package/docs/07-reference/01-ai-sdk-core/50-cosine-similarity.mdx +52 -0
  137. package/docs/07-reference/01-ai-sdk-core/60-wrap-language-model.mdx +59 -0
  138. package/docs/07-reference/01-ai-sdk-core/61-wrap-image-model.mdx +64 -0
  139. package/docs/07-reference/01-ai-sdk-core/65-language-model-v2-middleware.mdx +74 -0
  140. package/docs/07-reference/01-ai-sdk-core/66-extract-reasoning-middleware.mdx +68 -0
  141. package/docs/07-reference/01-ai-sdk-core/67-simulate-streaming-middleware.mdx +71 -0
  142. package/docs/07-reference/01-ai-sdk-core/68-default-settings-middleware.mdx +80 -0
  143. package/docs/07-reference/01-ai-sdk-core/69-add-tool-input-examples-middleware.mdx +155 -0
  144. package/docs/07-reference/01-ai-sdk-core/70-extract-json-middleware.mdx +147 -0
  145. package/docs/07-reference/01-ai-sdk-core/70-step-count-is.mdx +84 -0
  146. package/docs/07-reference/01-ai-sdk-core/71-has-tool-call.mdx +120 -0
  147. package/docs/07-reference/01-ai-sdk-core/75-simulate-readable-stream.mdx +94 -0
  148. package/docs/07-reference/01-ai-sdk-core/80-smooth-stream.mdx +145 -0
  149. package/docs/07-reference/01-ai-sdk-core/90-generate-id.mdx +30 -0
  150. package/docs/07-reference/01-ai-sdk-core/91-create-id-generator.mdx +89 -0
  151. package/docs/07-reference/01-ai-sdk-core/92-default-generated-file.mdx +68 -0
  152. package/docs/07-reference/01-ai-sdk-core/index.mdx +160 -0
  153. package/docs/07-reference/02-ai-sdk-ui/01-use-chat.mdx +493 -0
  154. package/docs/07-reference/02-ai-sdk-ui/02-use-completion.mdx +185 -0
  155. package/docs/07-reference/02-ai-sdk-ui/03-use-object.mdx +196 -0
  156. package/docs/07-reference/02-ai-sdk-ui/31-convert-to-model-messages.mdx +231 -0
  157. package/docs/07-reference/02-ai-sdk-ui/32-prune-messages.mdx +108 -0
  158. package/docs/07-reference/02-ai-sdk-ui/40-create-ui-message-stream.mdx +162 -0
  159. package/docs/07-reference/02-ai-sdk-ui/41-create-ui-message-stream-response.mdx +119 -0
  160. package/docs/07-reference/02-ai-sdk-ui/42-pipe-ui-message-stream-to-response.mdx +77 -0
  161. package/docs/07-reference/02-ai-sdk-ui/43-read-ui-message-stream.mdx +57 -0
  162. package/docs/07-reference/02-ai-sdk-ui/46-infer-ui-tools.mdx +99 -0
  163. package/docs/07-reference/02-ai-sdk-ui/47-infer-ui-tool.mdx +75 -0
  164. package/docs/07-reference/02-ai-sdk-ui/50-direct-chat-transport.mdx +333 -0
  165. package/docs/07-reference/02-ai-sdk-ui/index.mdx +89 -0
  166. package/docs/07-reference/03-ai-sdk-rsc/01-stream-ui.mdx +767 -0
  167. package/docs/07-reference/03-ai-sdk-rsc/02-create-ai.mdx +90 -0
  168. package/docs/07-reference/03-ai-sdk-rsc/03-create-streamable-ui.mdx +91 -0
  169. package/docs/07-reference/03-ai-sdk-rsc/04-create-streamable-value.mdx +78 -0
  170. package/docs/07-reference/03-ai-sdk-rsc/05-read-streamable-value.mdx +79 -0
  171. package/docs/07-reference/03-ai-sdk-rsc/06-get-ai-state.mdx +50 -0
  172. package/docs/07-reference/03-ai-sdk-rsc/07-get-mutable-ai-state.mdx +70 -0
  173. package/docs/07-reference/03-ai-sdk-rsc/08-use-ai-state.mdx +26 -0
  174. package/docs/07-reference/03-ai-sdk-rsc/09-use-actions.mdx +42 -0
  175. package/docs/07-reference/03-ai-sdk-rsc/10-use-ui-state.mdx +35 -0
  176. package/docs/07-reference/03-ai-sdk-rsc/11-use-streamable-value.mdx +46 -0
  177. package/docs/07-reference/03-ai-sdk-rsc/20-render.mdx +266 -0
  178. package/docs/07-reference/03-ai-sdk-rsc/index.mdx +67 -0
  179. package/docs/07-reference/05-ai-sdk-errors/ai-api-call-error.mdx +31 -0
  180. package/docs/07-reference/05-ai-sdk-errors/ai-download-error.mdx +28 -0
  181. package/docs/07-reference/05-ai-sdk-errors/ai-empty-response-body-error.mdx +24 -0
  182. package/docs/07-reference/05-ai-sdk-errors/ai-invalid-argument-error.mdx +26 -0
  183. package/docs/07-reference/05-ai-sdk-errors/ai-invalid-data-content-error.mdx +26 -0
  184. package/docs/07-reference/05-ai-sdk-errors/ai-invalid-message-role-error.mdx +25 -0
  185. package/docs/07-reference/05-ai-sdk-errors/ai-invalid-prompt-error.mdx +47 -0
  186. package/docs/07-reference/05-ai-sdk-errors/ai-invalid-response-data-error.mdx +25 -0
  187. package/docs/07-reference/05-ai-sdk-errors/ai-invalid-tool-approval-error.mdx +24 -0
  188. package/docs/07-reference/05-ai-sdk-errors/ai-invalid-tool-input-error.mdx +27 -0
  189. package/docs/07-reference/05-ai-sdk-errors/ai-json-parse-error.mdx +25 -0
  190. package/docs/07-reference/05-ai-sdk-errors/ai-load-api-key-error.mdx +24 -0
  191. package/docs/07-reference/05-ai-sdk-errors/ai-load-setting-error.mdx +24 -0
  192. package/docs/07-reference/05-ai-sdk-errors/ai-message-conversion-error.mdx +25 -0
  193. package/docs/07-reference/05-ai-sdk-errors/ai-no-content-generated-error.mdx +24 -0
  194. package/docs/07-reference/05-ai-sdk-errors/ai-no-image-generated-error.mdx +36 -0
  195. package/docs/07-reference/05-ai-sdk-errors/ai-no-object-generated-error.mdx +43 -0
  196. package/docs/07-reference/05-ai-sdk-errors/ai-no-output-generated-error.mdx +25 -0
  197. package/docs/07-reference/05-ai-sdk-errors/ai-no-speech-generated-error.mdx +24 -0
  198. package/docs/07-reference/05-ai-sdk-errors/ai-no-such-model-error.mdx +26 -0
  199. package/docs/07-reference/05-ai-sdk-errors/ai-no-such-provider-error.mdx +28 -0
  200. package/docs/07-reference/05-ai-sdk-errors/ai-no-such-tool-error.mdx +26 -0
  201. package/docs/07-reference/05-ai-sdk-errors/ai-no-transcript-generated-error.mdx +24 -0
  202. package/docs/07-reference/05-ai-sdk-errors/ai-no-video-generated-error.mdx +39 -0
  203. package/docs/07-reference/05-ai-sdk-errors/ai-retry-error.mdx +27 -0
  204. package/docs/07-reference/05-ai-sdk-errors/ai-too-many-embedding-values-for-call-error.mdx +27 -0
  205. package/docs/07-reference/05-ai-sdk-errors/ai-tool-call-not-found-for-approval-error.mdx +25 -0
  206. package/docs/07-reference/05-ai-sdk-errors/ai-tool-call-repair-error.mdx +28 -0
  207. package/docs/07-reference/05-ai-sdk-errors/ai-type-validation-error.mdx +25 -0
  208. package/docs/07-reference/05-ai-sdk-errors/ai-ui-message-stream-error.mdx +67 -0
  209. package/docs/07-reference/05-ai-sdk-errors/ai-unsupported-functionality-error.mdx +25 -0
  210. package/docs/07-reference/05-ai-sdk-errors/index.mdx +39 -0
  211. package/docs/07-reference/index.mdx +28 -0
  212. package/docs/08-migration-guides/00-versioning.mdx +46 -0
  213. package/docs/08-migration-guides/23-migration-guide-7-0.mdx +95 -0
  214. package/docs/08-migration-guides/24-migration-guide-6-0.mdx +823 -0
  215. package/docs/08-migration-guides/25-migration-guide-5-0-data.mdx +882 -0
  216. package/docs/08-migration-guides/26-migration-guide-5-0.mdx +3427 -0
  217. package/docs/08-migration-guides/27-migration-guide-4-2.mdx +99 -0
  218. package/docs/08-migration-guides/28-migration-guide-4-1.mdx +14 -0
  219. package/docs/08-migration-guides/29-migration-guide-4-0.mdx +1157 -0
  220. package/docs/08-migration-guides/36-migration-guide-3-4.mdx +14 -0
  221. package/docs/08-migration-guides/37-migration-guide-3-3.mdx +64 -0
  222. package/docs/08-migration-guides/38-migration-guide-3-2.mdx +46 -0
  223. package/docs/08-migration-guides/39-migration-guide-3-1.mdx +168 -0
  224. package/docs/08-migration-guides/index.mdx +22 -0
  225. package/docs/09-troubleshooting/01-azure-stream-slow.mdx +33 -0
  226. package/docs/09-troubleshooting/03-server-actions-in-client-components.mdx +40 -0
  227. package/docs/09-troubleshooting/04-strange-stream-output.mdx +36 -0
  228. package/docs/09-troubleshooting/05-streamable-ui-errors.mdx +16 -0
  229. package/docs/09-troubleshooting/05-tool-invocation-missing-result.mdx +106 -0
  230. package/docs/09-troubleshooting/06-streaming-not-working-when-deployed.mdx +31 -0
  231. package/docs/09-troubleshooting/06-streaming-not-working-when-proxied.mdx +31 -0
  232. package/docs/09-troubleshooting/06-timeout-on-vercel.mdx +60 -0
  233. package/docs/09-troubleshooting/07-unclosed-streams.mdx +34 -0
  234. package/docs/09-troubleshooting/08-use-chat-failed-to-parse-stream.mdx +26 -0
  235. package/docs/09-troubleshooting/09-client-stream-error.mdx +25 -0
  236. package/docs/09-troubleshooting/10-use-chat-tools-no-response.mdx +32 -0
  237. package/docs/09-troubleshooting/11-use-chat-custom-request-options.mdx +149 -0
  238. package/docs/09-troubleshooting/12-typescript-performance-zod.mdx +46 -0
  239. package/docs/09-troubleshooting/12-use-chat-an-error-occurred.mdx +59 -0
  240. package/docs/09-troubleshooting/13-repeated-assistant-messages.mdx +73 -0
  241. package/docs/09-troubleshooting/14-stream-abort-handling.mdx +73 -0
  242. package/docs/09-troubleshooting/14-tool-calling-with-structured-outputs.mdx +48 -0
  243. package/docs/09-troubleshooting/15-abort-breaks-resumable-streams.mdx +55 -0
  244. package/docs/09-troubleshooting/15-stream-text-not-working.mdx +33 -0
  245. package/docs/09-troubleshooting/16-streaming-status-delay.mdx +63 -0
  246. package/docs/09-troubleshooting/17-use-chat-stale-body-data.mdx +141 -0
  247. package/docs/09-troubleshooting/18-ontoolcall-type-narrowing.mdx +66 -0
  248. package/docs/09-troubleshooting/19-unsupported-model-version.mdx +50 -0
  249. package/docs/09-troubleshooting/20-no-object-generated-content-filter.mdx +76 -0
  250. package/docs/09-troubleshooting/21-missing-tool-results-error.mdx +82 -0
  251. package/docs/09-troubleshooting/30-model-is-not-assignable-to-type.mdx +21 -0
  252. package/docs/09-troubleshooting/40-typescript-cannot-find-namespace-jsx.mdx +24 -0
  253. package/docs/09-troubleshooting/50-react-maximum-update-depth-exceeded.mdx +39 -0
  254. package/docs/09-troubleshooting/60-jest-cannot-find-module-ai-rsc.mdx +22 -0
  255. package/docs/09-troubleshooting/70-high-memory-usage-with-images.mdx +108 -0
  256. package/docs/09-troubleshooting/index.mdx +11 -0
  257. package/internal.d.ts +1 -0
  258. package/package.json +120 -0
  259. package/src/agent/agent.ts +156 -0
  260. package/src/agent/create-agent-ui-stream-response.ts +61 -0
  261. package/src/agent/create-agent-ui-stream.ts +84 -0
  262. package/src/agent/index.ts +37 -0
  263. package/src/agent/infer-agent-tools.ts +7 -0
  264. package/src/agent/infer-agent-ui-message.ts +11 -0
  265. package/src/agent/pipe-agent-ui-stream-to-response.ts +64 -0
  266. package/src/agent/tool-loop-agent-settings.ts +252 -0
  267. package/src/agent/tool-loop-agent.ts +205 -0
  268. package/src/embed/embed-events.ts +181 -0
  269. package/src/embed/embed-many-result.ts +53 -0
  270. package/src/embed/embed-many.ts +428 -0
  271. package/src/embed/embed-result.ts +50 -0
  272. package/src/embed/embed.ts +266 -0
  273. package/src/embed/index.ts +5 -0
  274. package/src/error/index.ts +37 -0
  275. package/src/error/invalid-argument-error.ts +34 -0
  276. package/src/error/invalid-stream-part-error.ts +28 -0
  277. package/src/error/invalid-tool-approval-error.ts +26 -0
  278. package/src/error/invalid-tool-input-error.ts +33 -0
  279. package/src/error/missing-tool-result-error.ts +28 -0
  280. package/src/error/no-image-generated-error.ts +39 -0
  281. package/src/error/no-object-generated-error.ts +70 -0
  282. package/src/error/no-output-generated-error.ts +26 -0
  283. package/src/error/no-speech-generated-error.ts +28 -0
  284. package/src/error/no-such-tool-error.ts +35 -0
  285. package/src/error/no-transcript-generated-error.ts +30 -0
  286. package/src/error/no-video-generated-error.ts +57 -0
  287. package/src/error/tool-call-not-found-for-approval-error.ts +32 -0
  288. package/src/error/tool-call-repair-error.ts +30 -0
  289. package/src/error/ui-message-stream-error.ts +48 -0
  290. package/src/error/unsupported-model-version-error.ts +23 -0
  291. package/src/error/verify-no-object-generated-error.ts +27 -0
  292. package/src/generate-image/generate-image-result.ts +42 -0
  293. package/src/generate-image/generate-image.ts +361 -0
  294. package/src/generate-image/index.ts +18 -0
  295. package/src/generate-object/generate-object-result.ts +67 -0
  296. package/src/generate-object/generate-object.ts +514 -0
  297. package/src/generate-object/index.ts +9 -0
  298. package/src/generate-object/inject-json-instruction.ts +30 -0
  299. package/src/generate-object/output-strategy.ts +415 -0
  300. package/src/generate-object/parse-and-validate-object-result.ts +111 -0
  301. package/src/generate-object/repair-text.ts +12 -0
  302. package/src/generate-object/stream-object-result.ts +120 -0
  303. package/src/generate-object/stream-object.ts +984 -0
  304. package/src/generate-object/validate-object-generation-input.ts +144 -0
  305. package/src/generate-speech/generate-speech-result.ts +30 -0
  306. package/src/generate-speech/generate-speech.ts +191 -0
  307. package/src/generate-speech/generated-audio-file.ts +65 -0
  308. package/src/generate-speech/index.ts +3 -0
  309. package/src/generate-text/collect-tool-approvals.ts +116 -0
  310. package/src/generate-text/content-part.ts +31 -0
  311. package/src/generate-text/core-events.ts +390 -0
  312. package/src/generate-text/create-execute-tools-transformation.ts +144 -0
  313. package/src/generate-text/execute-tool-call.ts +190 -0
  314. package/src/generate-text/extract-reasoning-content.ts +17 -0
  315. package/src/generate-text/extract-text-content.ts +15 -0
  316. package/src/generate-text/generate-text-result.ts +168 -0
  317. package/src/generate-text/generate-text.ts +1445 -0
  318. package/src/generate-text/generated-file.ts +70 -0
  319. package/src/generate-text/index.ts +78 -0
  320. package/src/generate-text/invoke-tool-callbacks-from-stream.ts +81 -0
  321. package/src/generate-text/is-approval-needed.ts +29 -0
  322. package/src/generate-text/output-utils.ts +23 -0
  323. package/src/generate-text/output.ts +590 -0
  324. package/src/generate-text/parse-tool-call.ts +188 -0
  325. package/src/generate-text/prepare-step.ts +103 -0
  326. package/src/generate-text/prune-messages.ts +167 -0
  327. package/src/generate-text/reasoning-output.ts +99 -0
  328. package/src/generate-text/reasoning.ts +10 -0
  329. package/src/generate-text/response-message.ts +10 -0
  330. package/src/generate-text/smooth-stream.ts +162 -0
  331. package/src/generate-text/step-result.ts +310 -0
  332. package/src/generate-text/stop-condition.ts +29 -0
  333. package/src/generate-text/stream-model-call.ts +418 -0
  334. package/src/generate-text/stream-text-result.ts +536 -0
  335. package/src/generate-text/stream-text.ts +2696 -0
  336. package/src/generate-text/to-response-messages.ts +195 -0
  337. package/src/generate-text/tool-approval-request-output.ts +21 -0
  338. package/src/generate-text/tool-call-repair-function.ts +27 -0
  339. package/src/generate-text/tool-call.ts +47 -0
  340. package/src/generate-text/tool-error.ts +34 -0
  341. package/src/generate-text/tool-output-denied.ts +21 -0
  342. package/src/generate-text/tool-output.ts +7 -0
  343. package/src/generate-text/tool-result.ts +36 -0
  344. package/src/generate-text/tool-set.ts +14 -0
  345. package/src/generate-video/generate-video-result.ts +36 -0
  346. package/src/generate-video/generate-video.ts +402 -0
  347. package/src/generate-video/index.ts +3 -0
  348. package/src/global.ts +36 -0
  349. package/src/index.ts +49 -0
  350. package/src/logger/index.ts +6 -0
  351. package/src/logger/log-warnings.ts +140 -0
  352. package/src/middleware/add-tool-input-examples-middleware.ts +90 -0
  353. package/src/middleware/default-embedding-settings-middleware.ts +22 -0
  354. package/src/middleware/default-settings-middleware.ts +33 -0
  355. package/src/middleware/extract-json-middleware.ts +197 -0
  356. package/src/middleware/extract-reasoning-middleware.ts +249 -0
  357. package/src/middleware/index.ts +10 -0
  358. package/src/middleware/simulate-streaming-middleware.ts +79 -0
  359. package/src/middleware/wrap-embedding-model.ts +89 -0
  360. package/src/middleware/wrap-image-model.ts +92 -0
  361. package/src/middleware/wrap-language-model.ts +108 -0
  362. package/src/middleware/wrap-provider.ts +51 -0
  363. package/src/model/as-embedding-model-v3.ts +24 -0
  364. package/src/model/as-embedding-model-v4.ts +25 -0
  365. package/src/model/as-image-model-v3.ts +24 -0
  366. package/src/model/as-image-model-v4.ts +21 -0
  367. package/src/model/as-language-model-v3.ts +103 -0
  368. package/src/model/as-language-model-v4.ts +25 -0
  369. package/src/model/as-provider-v3.ts +36 -0
  370. package/src/model/as-provider-v4.ts +47 -0
  371. package/src/model/as-reranking-model-v4.ts +16 -0
  372. package/src/model/as-speech-model-v3.ts +24 -0
  373. package/src/model/as-speech-model-v4.ts +21 -0
  374. package/src/model/as-transcription-model-v3.ts +24 -0
  375. package/src/model/as-transcription-model-v4.ts +25 -0
  376. package/src/model/as-video-model-v4.ts +19 -0
  377. package/src/model/resolve-model.ts +172 -0
  378. package/src/prompt/call-settings.ts +169 -0
  379. package/src/prompt/content-part.ts +236 -0
  380. package/src/prompt/convert-to-language-model-prompt.ts +548 -0
  381. package/src/prompt/create-tool-model-output.ts +34 -0
  382. package/src/prompt/data-content.ts +134 -0
  383. package/src/prompt/index.ts +27 -0
  384. package/src/prompt/invalid-data-content-error.ts +29 -0
  385. package/src/prompt/invalid-message-role-error.ts +27 -0
  386. package/src/prompt/message-conversion-error.ts +28 -0
  387. package/src/prompt/message.ts +72 -0
  388. package/src/prompt/prepare-call-settings.ts +110 -0
  389. package/src/prompt/prepare-tools-and-tool-choice.ts +86 -0
  390. package/src/prompt/prompt.ts +43 -0
  391. package/src/prompt/split-data-url.ts +17 -0
  392. package/src/prompt/standardize-prompt.ts +99 -0
  393. package/src/prompt/wrap-gateway-error.ts +29 -0
  394. package/src/registry/custom-provider.ts +210 -0
  395. package/src/registry/index.ts +7 -0
  396. package/src/registry/no-such-provider-error.ts +41 -0
  397. package/src/registry/provider-registry.ts +331 -0
  398. package/src/rerank/index.ts +8 -0
  399. package/src/rerank/rerank-events.ts +189 -0
  400. package/src/rerank/rerank-result.ts +70 -0
  401. package/src/rerank/rerank.ts +348 -0
  402. package/src/telemetry/assemble-operation-name.ts +21 -0
  403. package/src/telemetry/get-base-telemetry-attributes.ts +45 -0
  404. package/src/telemetry/get-global-telemetry-integration.ts +126 -0
  405. package/src/telemetry/get-tracer.ts +20 -0
  406. package/src/telemetry/index.ts +4 -0
  407. package/src/telemetry/noop-tracer.ts +69 -0
  408. package/src/telemetry/open-telemetry-integration.ts +875 -0
  409. package/src/telemetry/record-span.ts +75 -0
  410. package/src/telemetry/select-telemetry-attributes.ts +78 -0
  411. package/src/telemetry/stringify-for-telemetry.ts +33 -0
  412. package/src/telemetry/telemetry-integration-registry.ts +22 -0
  413. package/src/telemetry/telemetry-integration.ts +139 -0
  414. package/src/telemetry/telemetry-settings.ts +55 -0
  415. package/src/test/mock-embedding-model-v2.ts +35 -0
  416. package/src/test/mock-embedding-model-v3.ts +48 -0
  417. package/src/test/mock-embedding-model-v4.ts +48 -0
  418. package/src/test/mock-image-model-v2.ts +28 -0
  419. package/src/test/mock-image-model-v3.ts +28 -0
  420. package/src/test/mock-image-model-v4.ts +28 -0
  421. package/src/test/mock-language-model-v2.ts +72 -0
  422. package/src/test/mock-language-model-v3.ts +77 -0
  423. package/src/test/mock-language-model-v4.ts +77 -0
  424. package/src/test/mock-provider-v2.ts +68 -0
  425. package/src/test/mock-provider-v3.ts +80 -0
  426. package/src/test/mock-provider-v4.ts +80 -0
  427. package/src/test/mock-reranking-model-v3.ts +25 -0
  428. package/src/test/mock-reranking-model-v4.ts +25 -0
  429. package/src/test/mock-server-response.ts +69 -0
  430. package/src/test/mock-speech-model-v2.ts +24 -0
  431. package/src/test/mock-speech-model-v3.ts +24 -0
  432. package/src/test/mock-speech-model-v4.ts +24 -0
  433. package/src/test/mock-tracer.ts +156 -0
  434. package/src/test/mock-transcription-model-v2.ts +24 -0
  435. package/src/test/mock-transcription-model-v3.ts +24 -0
  436. package/src/test/mock-transcription-model-v4.ts +24 -0
  437. package/src/test/mock-values.ts +4 -0
  438. package/src/test/mock-video-model-v3.ts +28 -0
  439. package/src/test/mock-video-model-v4.ts +28 -0
  440. package/src/test/not-implemented.ts +3 -0
  441. package/src/text-stream/create-text-stream-response.ts +30 -0
  442. package/src/text-stream/index.ts +2 -0
  443. package/src/text-stream/pipe-text-stream-to-response.ts +38 -0
  444. package/src/transcribe/index.ts +2 -0
  445. package/src/transcribe/transcribe-result.ts +60 -0
  446. package/src/transcribe/transcribe.ts +187 -0
  447. package/src/types/embedding-model-middleware.ts +15 -0
  448. package/src/types/embedding-model.ts +20 -0
  449. package/src/types/image-model-middleware.ts +15 -0
  450. package/src/types/image-model-response-metadata.ts +16 -0
  451. package/src/types/image-model.ts +19 -0
  452. package/src/types/index.ts +29 -0
  453. package/src/types/json-value.ts +15 -0
  454. package/src/types/language-model-middleware.ts +15 -0
  455. package/src/types/language-model-request-metadata.ts +6 -0
  456. package/src/types/language-model-response-metadata.ts +21 -0
  457. package/src/types/language-model.ts +106 -0
  458. package/src/types/provider-metadata.ts +16 -0
  459. package/src/types/provider.ts +55 -0
  460. package/src/types/reranking-model.ts +6 -0
  461. package/src/types/speech-model-response-metadata.ts +21 -0
  462. package/src/types/speech-model.ts +10 -0
  463. package/src/types/transcription-model-response-metadata.ts +16 -0
  464. package/src/types/transcription-model.ts +14 -0
  465. package/src/types/usage.ts +200 -0
  466. package/src/types/video-model-response-metadata.ts +28 -0
  467. package/src/types/video-model.ts +15 -0
  468. package/src/types/warning.ts +7 -0
  469. package/src/ui/call-completion-api.ts +157 -0
  470. package/src/ui/chat-transport.ts +83 -0
  471. package/src/ui/chat.ts +786 -0
  472. package/src/ui/convert-file-list-to-file-ui-parts.ts +36 -0
  473. package/src/ui/convert-to-model-messages.ts +403 -0
  474. package/src/ui/default-chat-transport.ts +36 -0
  475. package/src/ui/direct-chat-transport.ts +117 -0
  476. package/src/ui/http-chat-transport.ts +273 -0
  477. package/src/ui/index.ts +76 -0
  478. package/src/ui/last-assistant-message-is-complete-with-approval-responses.ts +44 -0
  479. package/src/ui/last-assistant-message-is-complete-with-tool-calls.ts +39 -0
  480. package/src/ui/process-text-stream.ts +16 -0
  481. package/src/ui/process-ui-message-stream.ts +858 -0
  482. package/src/ui/text-stream-chat-transport.ts +23 -0
  483. package/src/ui/transform-text-to-ui-message-stream.ts +27 -0
  484. package/src/ui/ui-messages.ts +602 -0
  485. package/src/ui/use-completion.ts +84 -0
  486. package/src/ui/validate-ui-messages.ts +521 -0
  487. package/src/ui-message-stream/create-ui-message-stream-response.ts +44 -0
  488. package/src/ui-message-stream/create-ui-message-stream.ts +145 -0
  489. package/src/ui-message-stream/get-response-ui-message-id.ts +35 -0
  490. package/src/ui-message-stream/handle-ui-message-stream-finish.ts +170 -0
  491. package/src/ui-message-stream/index.ts +14 -0
  492. package/src/ui-message-stream/json-to-sse-transform-stream.ts +17 -0
  493. package/src/ui-message-stream/pipe-ui-message-stream-to-response.ts +51 -0
  494. package/src/ui-message-stream/read-ui-message-stream.ts +87 -0
  495. package/src/ui-message-stream/ui-message-chunks.ts +372 -0
  496. package/src/ui-message-stream/ui-message-stream-headers.ts +7 -0
  497. package/src/ui-message-stream/ui-message-stream-on-finish-callback.ts +32 -0
  498. package/src/ui-message-stream/ui-message-stream-on-step-finish-callback.ts +25 -0
  499. package/src/ui-message-stream/ui-message-stream-response-init.ts +14 -0
  500. package/src/ui-message-stream/ui-message-stream-writer.ts +24 -0
  501. package/src/util/as-array.ts +3 -0
  502. package/src/util/async-iterable-stream.ts +94 -0
  503. package/src/util/consume-stream.ts +31 -0
  504. package/src/util/cosine-similarity.ts +46 -0
  505. package/src/util/create-resolvable-promise.ts +30 -0
  506. package/src/util/create-stitchable-stream.ts +112 -0
  507. package/src/util/data-url.ts +17 -0
  508. package/src/util/deep-partial.ts +84 -0
  509. package/src/util/detect-media-type.ts +226 -0
  510. package/src/util/download/create-download.ts +13 -0
  511. package/src/util/download/download-function.ts +45 -0
  512. package/src/util/download/download.ts +74 -0
  513. package/src/util/error-handler.ts +1 -0
  514. package/src/util/fix-json.ts +401 -0
  515. package/src/util/get-potential-start-index.ts +39 -0
  516. package/src/util/index.ts +12 -0
  517. package/src/util/is-deep-equal-data.ts +48 -0
  518. package/src/util/is-non-empty-object.ts +5 -0
  519. package/src/util/job.ts +1 -0
  520. package/src/util/log-v2-compatibility-warning.ts +21 -0
  521. package/src/util/merge-abort-signals.ts +43 -0
  522. package/src/util/merge-objects.ts +79 -0
  523. package/src/util/notify.ts +22 -0
  524. package/src/util/now.ts +4 -0
  525. package/src/util/parse-partial-json.ts +30 -0
  526. package/src/util/prepare-headers.ts +14 -0
  527. package/src/util/prepare-retries.ts +47 -0
  528. package/src/util/retry-error.ts +41 -0
  529. package/src/util/retry-with-exponential-backoff.ts +154 -0
  530. package/src/util/serial-job-executor.ts +36 -0
  531. package/src/util/simulate-readable-stream.ts +39 -0
  532. package/src/util/split-array.ts +20 -0
  533. package/src/util/value-of.ts +65 -0
  534. package/src/util/write-to-server-response.ts +49 -0
  535. package/src/version.ts +5 -0
  536. package/test.d.ts +1 -0
@@ -0,0 +1,218 @@
1
+ ---
2
+ title: Reranking
3
+ description: Learn how to rerank documents with the AI SDK.
4
+ ---
5
+
6
+ # Reranking
7
+
8
+ Reranking is a technique used to improve search relevance by reordering a set of documents based on their relevance to a query.
9
+ Unlike embedding-based similarity search, reranking models are specifically trained to understand the relationship between queries and documents,
10
+ often producing more accurate relevance scores.
11
+
12
+ ## Reranking Documents
13
+
14
+ The AI SDK provides the [`rerank`](/docs/reference/ai-sdk-core/rerank) function to rerank documents based on their relevance to a query.
15
+ You can use it with reranking models, e.g. `cohere.reranking('rerank-v3.5')` or `bedrock.reranking('cohere.rerank-v3-5:0')`.
16
+
17
+ ```tsx
18
+ import { rerank } from 'ai';
19
+ import { cohere } from '@ai-sdk/cohere';
20
+
21
+ const documents = [
22
+ 'sunny day at the beach',
23
+ 'rainy afternoon in the city',
24
+ 'snowy night in the mountains',
25
+ ];
26
+
27
+ const { ranking } = await rerank({
28
+ model: cohere.reranking('rerank-v3.5'),
29
+ documents,
30
+ query: 'talk about rain',
31
+ topN: 2, // Return top 2 most relevant documents
32
+ });
33
+
34
+ console.log(ranking);
35
+ // [
36
+ // { originalIndex: 1, score: 0.9, document: 'rainy afternoon in the city' },
37
+ // { originalIndex: 0, score: 0.3, document: 'sunny day at the beach' }
38
+ // ]
39
+ ```
40
+
41
+ ## Working with Object Documents
42
+
43
+ Reranking also supports structured documents (JSON objects), making it ideal for searching through databases, emails, or other structured content:
44
+
45
+ ```tsx
46
+ import { rerank } from 'ai';
47
+ import { cohere } from '@ai-sdk/cohere';
48
+
49
+ const documents = [
50
+ {
51
+ from: 'Paul Doe',
52
+ subject: 'Follow-up',
53
+ text: 'We are happy to give you a discount of 20% on your next order.',
54
+ },
55
+ {
56
+ from: 'John McGill',
57
+ subject: 'Missing Info',
58
+ text: 'Sorry, but here is the pricing information from Oracle: $5000/month',
59
+ },
60
+ ];
61
+
62
+ const { ranking, rerankedDocuments } = await rerank({
63
+ model: cohere.reranking('rerank-v3.5'),
64
+ documents,
65
+ query: 'Which pricing did we get from Oracle?',
66
+ topN: 1,
67
+ });
68
+
69
+ console.log(rerankedDocuments[0]);
70
+ // { from: 'John McGill', subject: 'Missing Info', text: '...' }
71
+ ```
72
+
73
+ ## Understanding the Results
74
+
75
+ The `rerank` function returns a comprehensive result object:
76
+
77
+ ```ts
78
+ import { cohere } from '@ai-sdk/cohere';
79
+ import { rerank } from 'ai';
80
+
81
+ const { ranking, rerankedDocuments, originalDocuments } = await rerank({
82
+ model: cohere.reranking('rerank-v3.5'),
83
+ documents: ['sunny day at the beach', 'rainy afternoon in the city'],
84
+ query: 'talk about rain',
85
+ });
86
+
87
+ // ranking: sorted array of { originalIndex, score, document }
88
+ // rerankedDocuments: documents sorted by relevance (convenience property)
89
+ // originalDocuments: original documents array
90
+ ```
91
+
92
+ Each item in the `ranking` array contains:
93
+
94
+ - `originalIndex`: Position in the original documents array
95
+ - `score`: Relevance score (typically 0-1, where higher is more relevant)
96
+ - `document`: The original document
97
+
98
+ ## Settings
99
+
100
+ ### Top-N Results
101
+
102
+ Use `topN` to limit the number of results returned. This is useful for retrieving only the most relevant documents:
103
+
104
+ ```ts highlight={"7"}
105
+ import { cohere } from '@ai-sdk/cohere';
106
+ import { rerank } from 'ai';
107
+
108
+ const { ranking } = await rerank({
109
+ model: cohere.reranking('rerank-v3.5'),
110
+ documents: ['doc1', 'doc2', 'doc3', 'doc4', 'doc5'],
111
+ query: 'relevant information',
112
+ topN: 3, // Return only top 3 most relevant documents
113
+ });
114
+ ```
115
+
116
+ ### Provider Options
117
+
118
+ Reranking model settings can be configured using `providerOptions` for provider-specific parameters:
119
+
120
+ ```ts highlight={"8-12"}
121
+ import { cohere } from '@ai-sdk/cohere';
122
+ import { rerank } from 'ai';
123
+
124
+ const { ranking } = await rerank({
125
+ model: cohere.reranking('rerank-v3.5'),
126
+ documents: ['sunny day at the beach', 'rainy afternoon in the city'],
127
+ query: 'talk about rain',
128
+ providerOptions: {
129
+ cohere: {
130
+ maxTokensPerDoc: 1000, // Limit tokens per document
131
+ },
132
+ },
133
+ });
134
+ ```
135
+
136
+ ### Retries
137
+
138
+ The `rerank` function accepts an optional `maxRetries` parameter of type `number`
139
+ that you can use to set the maximum number of retries for the reranking process.
140
+ It defaults to `2` retries (3 attempts in total). You can set it to `0` to disable retries.
141
+
142
+ ```ts highlight={"7"}
143
+ import { cohere } from '@ai-sdk/cohere';
144
+ import { rerank } from 'ai';
145
+
146
+ const { ranking } = await rerank({
147
+ model: cohere.reranking('rerank-v3.5'),
148
+ documents: ['sunny day at the beach', 'rainy afternoon in the city'],
149
+ query: 'talk about rain',
150
+ maxRetries: 0, // Disable retries
151
+ });
152
+ ```
153
+
154
+ ### Abort Signals and Timeouts
155
+
156
+ The `rerank` function accepts an optional `abortSignal` parameter of
157
+ type [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
158
+ that you can use to abort the reranking process or set a timeout.
159
+
160
+ ```ts highlight={"7"}
161
+ import { cohere } from '@ai-sdk/cohere';
162
+ import { rerank } from 'ai';
163
+
164
+ const { ranking } = await rerank({
165
+ model: cohere.reranking('rerank-v3.5'),
166
+ documents: ['sunny day at the beach', 'rainy afternoon in the city'],
167
+ query: 'talk about rain',
168
+ abortSignal: AbortSignal.timeout(5000), // Abort after 5 seconds
169
+ });
170
+ ```
171
+
172
+ ### Custom Headers
173
+
174
+ The `rerank` function accepts an optional `headers` parameter of type `Record<string, string>`
175
+ that you can use to add custom headers to the reranking request.
176
+
177
+ ```ts highlight={"7"}
178
+ import { cohere } from '@ai-sdk/cohere';
179
+ import { rerank } from 'ai';
180
+
181
+ const { ranking } = await rerank({
182
+ model: cohere.reranking('rerank-v3.5'),
183
+ documents: ['sunny day at the beach', 'rainy afternoon in the city'],
184
+ query: 'talk about rain',
185
+ headers: { 'X-Custom-Header': 'custom-value' },
186
+ });
187
+ ```
188
+
189
+ ## Response Information
190
+
191
+ The `rerank` function returns response information that includes the raw provider response:
192
+
193
+ ```ts highlight={"4,10"}
194
+ import { cohere } from '@ai-sdk/cohere';
195
+ import { rerank } from 'ai';
196
+
197
+ const { ranking, response } = await rerank({
198
+ model: cohere.reranking('rerank-v3.5'),
199
+ documents: ['sunny day at the beach', 'rainy afternoon in the city'],
200
+ query: 'talk about rain',
201
+ });
202
+
203
+ console.log(response); // { id, timestamp, modelId, headers, body }
204
+ ```
205
+
206
+ ## Reranking Providers & Models
207
+
208
+ Several providers offer reranking models:
209
+
210
+ | Provider | Model |
211
+ | ----------------------------------------------------------------------------- | ------------------------------------- |
212
+ | [Cohere](/providers/ai-sdk-providers/cohere#reranking-models) | `rerank-v3.5` |
213
+ | [Cohere](/providers/ai-sdk-providers/cohere#reranking-models) | `rerank-english-v3.0` |
214
+ | [Cohere](/providers/ai-sdk-providers/cohere#reranking-models) | `rerank-multilingual-v3.0` |
215
+ | [Amazon Bedrock](/providers/ai-sdk-providers/amazon-bedrock#reranking-models) | `amazon.rerank-v1:0` |
216
+ | [Amazon Bedrock](/providers/ai-sdk-providers/amazon-bedrock#reranking-models) | `cohere.rerank-v3-5:0` |
217
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#reranking-models) | `Salesforce/Llama-Rank-v1` |
218
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#reranking-models) | `mixedbread-ai/Mxbai-Rerank-Large-V2` |
@@ -0,0 +1,341 @@
1
+ ---
2
+ title: Image Generation
3
+ description: Learn how to generate images with the AI SDK.
4
+ ---
5
+
6
+ # Image Generation
7
+
8
+ The AI SDK provides the [`generateImage`](/docs/reference/ai-sdk-core/generate-image)
9
+ function to generate images based on a given prompt using an image model.
10
+
11
+ ```tsx
12
+ import { generateImage } from 'ai';
13
+ import { openai } from '@ai-sdk/openai';
14
+
15
+ const { image } = await generateImage({
16
+ model: openai.image('dall-e-3'),
17
+ prompt: 'Santa Claus driving a Cadillac',
18
+ });
19
+ ```
20
+
21
+ You can access the image data using the `base64` or `uint8Array` properties:
22
+
23
+ ```tsx
24
+ const base64 = image.base64; // base64 image data
25
+ const uint8Array = image.uint8Array; // Uint8Array image data
26
+ ```
27
+
28
+ ## Settings
29
+
30
+ ### Size and Aspect Ratio
31
+
32
+ Depending on the model, you can either specify the size or the aspect ratio.
33
+
34
+ ##### Size
35
+
36
+ The size is specified as a string in the format `{width}x{height}`.
37
+ Models only support a few sizes, and the supported sizes are different for each model and provider.
38
+
39
+ ```tsx highlight={"7"}
40
+ import { generateImage } from 'ai';
41
+ import { openai } from '@ai-sdk/openai';
42
+
43
+ const { image } = await generateImage({
44
+ model: openai.image('dall-e-3'),
45
+ prompt: 'Santa Claus driving a Cadillac',
46
+ size: '1024x1024',
47
+ });
48
+ ```
49
+
50
+ ##### Aspect Ratio
51
+
52
+ The aspect ratio is specified as a string in the format `{width}:{height}`.
53
+ Models only support a few aspect ratios, and the supported aspect ratios are different for each model and provider.
54
+
55
+ ```tsx highlight={"7"}
56
+ import { generateImage } from 'ai';
57
+ import { vertex } from '@ai-sdk/google-vertex';
58
+
59
+ const { image } = await generateImage({
60
+ model: vertex.image('imagen-4.0-generate-001'),
61
+ prompt: 'Santa Claus driving a Cadillac',
62
+ aspectRatio: '16:9',
63
+ });
64
+ ```
65
+
66
+ ### Generating Multiple Images
67
+
68
+ `generateImage` also supports generating multiple images at once:
69
+
70
+ ```tsx highlight={"7"}
71
+ import { generateImage } from 'ai';
72
+ import { openai } from '@ai-sdk/openai';
73
+
74
+ const { images } = await generateImage({
75
+ model: openai.image('dall-e-2'),
76
+ prompt: 'Santa Claus driving a Cadillac',
77
+ n: 4, // number of images to generate
78
+ });
79
+ ```
80
+
81
+ <Note>
82
+ `generateImage` will automatically call the model as often as needed (in
83
+ parallel) to generate the requested number of images.
84
+ </Note>
85
+
86
+ Each image model has an internal limit on how many images it can generate in a single API call. The AI SDK manages this automatically by batching requests appropriately when you request multiple images using the `n` parameter. By default, the SDK uses provider-documented limits (for example, DALL-E 3 can only generate 1 image per call, while DALL-E 2 supports up to 10).
87
+
88
+ If needed, you can override this behavior using the `maxImagesPerCall` setting when generating your image. This is particularly useful when working with new or custom models where the default batch size might not be optimal:
89
+
90
+ ```tsx
91
+ const { images } = await generateImage({
92
+ model: openai.image('dall-e-2'),
93
+ prompt: 'Santa Claus driving a Cadillac',
94
+ maxImagesPerCall: 5, // Override the default batch size
95
+ n: 10, // Will make 2 calls of 5 images each
96
+ });
97
+ ```
98
+
99
+ ### Providing a Seed
100
+
101
+ You can provide a seed to the `generateImage` function to control the output of the image generation process.
102
+ If supported by the model, the same seed will always produce the same image.
103
+
104
+ ```tsx highlight={"7"}
105
+ import { generateImage } from 'ai';
106
+ import { openai } from '@ai-sdk/openai';
107
+
108
+ const { image } = await generateImage({
109
+ model: openai.image('dall-e-3'),
110
+ prompt: 'Santa Claus driving a Cadillac',
111
+ seed: 1234567890,
112
+ });
113
+ ```
114
+
115
+ ### Provider-specific Settings
116
+
117
+ Image models often have provider- or even model-specific settings.
118
+ You can pass such settings to the `generateImage` function
119
+ using the `providerOptions` parameter. The options for the provider
120
+ (`openai` in the example below) become request body properties.
121
+
122
+ ```tsx highlight={"9"}
123
+ import { generateImage } from 'ai';
124
+ import { openai } from '@ai-sdk/openai';
125
+
126
+ const { image } = await generateImage({
127
+ model: openai.image('dall-e-3'),
128
+ prompt: 'Santa Claus driving a Cadillac',
129
+ size: '1024x1024',
130
+ providerOptions: {
131
+ openai: { style: 'vivid', quality: 'hd' },
132
+ },
133
+ });
134
+ ```
135
+
136
+ ### Abort Signals and Timeouts
137
+
138
+ `generateImage` accepts an optional `abortSignal` parameter of
139
+ type [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)
140
+ that you can use to abort the image generation process or set a timeout.
141
+
142
+ ```ts highlight={"7"}
143
+ import { openai } from '@ai-sdk/openai';
144
+ import { generateImage } from 'ai';
145
+
146
+ const { image } = await generateImage({
147
+ model: openai.image('dall-e-3'),
148
+ prompt: 'Santa Claus driving a Cadillac',
149
+ abortSignal: AbortSignal.timeout(1000), // Abort after 1 second
150
+ });
151
+ ```
152
+
153
+ ### Custom Headers
154
+
155
+ `generateImage` accepts an optional `headers` parameter of type `Record<string, string>`
156
+ that you can use to add custom headers to the image generation request.
157
+
158
+ ```ts highlight={"7"}
159
+ import { openai } from '@ai-sdk/openai';
160
+ import { generateImage } from 'ai';
161
+
162
+ const { image } = await generateImage({
163
+ model: openai.image('dall-e-3'),
164
+ prompt: 'Santa Claus driving a Cadillac',
165
+ headers: { 'X-Custom-Header': 'custom-value' },
166
+ });
167
+ ```
168
+
169
+ ### Warnings
170
+
171
+ If the model returns warnings, e.g. for unsupported parameters, they will be available in the `warnings` property of the response.
172
+
173
+ ```tsx
174
+ const { image, warnings } = await generateImage({
175
+ model: openai.image('dall-e-3'),
176
+ prompt: 'Santa Claus driving a Cadillac',
177
+ });
178
+ ```
179
+
180
+ ### Additional provider-specific meta data
181
+
182
+ Some providers expose additional meta data for the result overall or per image.
183
+
184
+ ```tsx
185
+ const prompt = 'Santa Claus driving a Cadillac';
186
+
187
+ const { image, providerMetadata } = await generateImage({
188
+ model: openai.image('dall-e-3'),
189
+ prompt,
190
+ });
191
+
192
+ const revisedPrompt = providerMetadata.openai.images[0]?.revisedPrompt;
193
+
194
+ console.log({
195
+ prompt,
196
+ revisedPrompt,
197
+ });
198
+ ```
199
+
200
+ The outer key of the returned `providerMetadata` is the provider name. The inner values are the metadata. An `images` key is always present in the metadata and is an array with the same length as the top level `images` key.
201
+
202
+ ### Error Handling
203
+
204
+ When `generateImage` cannot generate a valid image, it throws a [`AI_NoImageGeneratedError`](/docs/reference/ai-sdk-errors/ai-no-image-generated-error).
205
+
206
+ This error occurs when the AI provider fails to generate an image. It can arise due to the following reasons:
207
+
208
+ - The model failed to generate a response
209
+ - The model generated a response that could not be parsed
210
+
211
+ The error preserves the following information to help you log the issue:
212
+
213
+ - `responses`: Metadata about the image model responses, including timestamp, model, and headers.
214
+ - `cause`: The cause of the error. You can use this for more detailed error handling
215
+
216
+ ```ts
217
+ import { generateImage, NoImageGeneratedError } from 'ai';
218
+
219
+ try {
220
+ await generateImage({ model, prompt });
221
+ } catch (error) {
222
+ if (NoImageGeneratedError.isInstance(error)) {
223
+ console.log('NoImageGeneratedError');
224
+ console.log('Cause:', error.cause);
225
+ console.log('Responses:', error.responses);
226
+ }
227
+ }
228
+ ```
229
+
230
+ ## Image Middleware
231
+
232
+ You can enhance image models, e.g. to set default values or implement logging, using
233
+ `wrapImageModel` and `ImageModelV4Middleware`.
234
+
235
+ Here is an example that sets a default size when none is provided:
236
+
237
+ ```ts
238
+ import { generateImage, wrapImageModel } from 'ai';
239
+ import { openai } from '@ai-sdk/openai';
240
+
241
+ const model = wrapImageModel({
242
+ model: openai.image('gpt-image-1'),
243
+ middleware: {
244
+ specificationVersion: 'v3',
245
+ transformParams: async ({ params }) => ({
246
+ ...params,
247
+ size: params.size ?? '1024x1024',
248
+ }),
249
+ },
250
+ });
251
+
252
+ const { image } = await generateImage({
253
+ model,
254
+ prompt: 'Santa Claus driving a Cadillac',
255
+ });
256
+ ```
257
+
258
+ ## Generating Images with Language Models
259
+
260
+ Some language models such as Google `gemini-2.5-flash-image` support multi-modal outputs including images.
261
+ With such models, you can access the generated images using the `files` property of the response.
262
+
263
+ ```ts
264
+ import { google } from '@ai-sdk/google';
265
+ import { generateText } from 'ai';
266
+
267
+ const result = await generateText({
268
+ model: google('gemini-2.5-flash-image'),
269
+ prompt: 'Generate an image of a comic cat',
270
+ });
271
+
272
+ for (const file of result.files) {
273
+ if (file.mediaType.startsWith('image/')) {
274
+ // The file object provides multiple data formats:
275
+ // Access images as base64 string, Uint8Array binary data, or check type
276
+ // - file.base64: string (data URL format)
277
+ // - file.uint8Array: Uint8Array (binary data)
278
+ // - file.mediaType: string (e.g. "image/png")
279
+ }
280
+ }
281
+ ```
282
+
283
+ ## Image Models
284
+
285
+ | Provider | Model | Support sizes (`width x height`) or aspect ratios (`width : height`) |
286
+ | ------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
287
+ | [xAI Grok](/providers/ai-sdk-providers/xai#image-models) | `grok-imagine-image` | `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `2:1`, `1:2`, `19.5:9`, `9:19.5`, `20:9`, `9:20`, `auto` |
288
+ | [OpenAI](/providers/ai-sdk-providers/openai#image-models) | `gpt-image-1` | 1024x1024, 1536x1024, 1024x1536 |
289
+ | [OpenAI](/providers/ai-sdk-providers/openai#image-models) | `dall-e-3` | 1024x1024, 1792x1024, 1024x1792 |
290
+ | [OpenAI](/providers/ai-sdk-providers/openai#image-models) | `dall-e-2` | 256x256, 512x512, 1024x1024 |
291
+ | [Amazon Bedrock](/providers/ai-sdk-providers/amazon-bedrock#image-models) | `amazon.nova-canvas-v1:0` | 320-4096 (multiples of 16), 1:4 to 4:1, max 4.2M pixels |
292
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/flux/dev` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
293
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/flux-lora` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
294
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/fast-sdxl` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
295
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/flux-pro/v1.1-ultra` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
296
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/ideogram/v2` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
297
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/recraft-v3` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
298
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/stable-diffusion-3.5-large` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
299
+ | [Fal](/providers/ai-sdk-providers/fal#image-models) | `fal-ai/hyper-sdxl` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
300
+ | [DeepInfra](/providers/ai-sdk-providers/deepinfra#image-models) | `stabilityai/sd3.5` | 1:1, 16:9, 1:9, 3:2, 2:3, 4:5, 5:4, 9:16, 9:21 |
301
+ | [DeepInfra](/providers/ai-sdk-providers/deepinfra#image-models) | `black-forest-labs/FLUX-1.1-pro` | 256-1440 (multiples of 32) |
302
+ | [DeepInfra](/providers/ai-sdk-providers/deepinfra#image-models) | `black-forest-labs/FLUX-1-schnell` | 256-1440 (multiples of 32) |
303
+ | [DeepInfra](/providers/ai-sdk-providers/deepinfra#image-models) | `black-forest-labs/FLUX-1-dev` | 256-1440 (multiples of 32) |
304
+ | [DeepInfra](/providers/ai-sdk-providers/deepinfra#image-models) | `black-forest-labs/FLUX-pro` | 256-1440 (multiples of 32) |
305
+ | [DeepInfra](/providers/ai-sdk-providers/deepinfra#image-models) | `stabilityai/sd3.5-medium` | 1:1, 16:9, 1:9, 3:2, 2:3, 4:5, 5:4, 9:16, 9:21 |
306
+ | [DeepInfra](/providers/ai-sdk-providers/deepinfra#image-models) | `stabilityai/sdxl-turbo` | 1:1, 16:9, 1:9, 3:2, 2:3, 4:5, 5:4, 9:16, 9:21 |
307
+ | [Replicate](/providers/ai-sdk-providers/replicate) | `black-forest-labs/flux-schnell` | 1:1, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9 |
308
+ | [Replicate](/providers/ai-sdk-providers/replicate) | `recraft-ai/recraft-v3` | 1024x1024, 1365x1024, 1024x1365, 1536x1024, 1024x1536, 1820x1024, 1024x1820, 1024x2048, 2048x1024, 1434x1024, 1024x1434, 1024x1280, 1280x1024, 1024x1707, 1707x1024 |
309
+ | [Google](/providers/ai-sdk-providers/google-generative-ai#image-models) | `imagen-4.0-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 |
310
+ | [Google](/providers/ai-sdk-providers/google-generative-ai#image-models) | `imagen-4.0-fast-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 |
311
+ | [Google](/providers/ai-sdk-providers/google-generative-ai#image-models) | `imagen-4.0-ultra-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 |
312
+ | [Google Vertex](/providers/ai-sdk-providers/google-vertex#image-models) | `imagen-4.0-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 |
313
+ | [Google Vertex](/providers/ai-sdk-providers/google-vertex#image-models) | `imagen-4.0-fast-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 |
314
+ | [Google Vertex](/providers/ai-sdk-providers/google-vertex#image-models) | `imagen-4.0-ultra-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 |
315
+ | [Google Vertex](/providers/ai-sdk-providers/google-vertex#image-models) | `imagen-3.0-fast-generate-001` | 1:1, 3:4, 4:3, 9:16, 16:9 |
316
+ | [Fireworks](/providers/ai-sdk-providers/fireworks#image-models) | `accounts/fireworks/models/flux-1-dev-fp8` | 1:1, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9 |
317
+ | [Fireworks](/providers/ai-sdk-providers/fireworks#image-models) | `accounts/fireworks/models/flux-1-schnell-fp8` | 1:1, 2:3, 3:2, 4:5, 5:4, 16:9, 9:16, 9:21, 21:9 |
318
+ | [Fireworks](/providers/ai-sdk-providers/fireworks#image-models) | `accounts/fireworks/models/playground-v2-5-1024px-aesthetic` | 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640 |
319
+ | [Fireworks](/providers/ai-sdk-providers/fireworks#image-models) | `accounts/fireworks/models/japanese-stable-diffusion-xl` | 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640 |
320
+ | [Fireworks](/providers/ai-sdk-providers/fireworks#image-models) | `accounts/fireworks/models/playground-v2-1024px-aesthetic` | 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640 |
321
+ | [Fireworks](/providers/ai-sdk-providers/fireworks#image-models) | `accounts/fireworks/models/SSD-1B` | 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640 |
322
+ | [Fireworks](/providers/ai-sdk-providers/fireworks#image-models) | `accounts/fireworks/models/stable-diffusion-xl-1024-v1-0` | 640x1536, 768x1344, 832x1216, 896x1152, 1024x1024, 1152x896, 1216x832, 1344x768, 1536x640 |
323
+ | [Luma](/providers/ai-sdk-providers/luma#image-models) | `photon-1` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
324
+ | [Luma](/providers/ai-sdk-providers/luma#image-models) | `photon-flash-1` | 1:1, 3:4, 4:3, 9:16, 16:9, 9:21, 21:9 |
325
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `stabilityai/stable-diffusion-xl-base-1.0` | 512x512, 768x768, 1024x1024 |
326
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-dev` | 512x512, 768x768, 1024x1024 |
327
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-dev-lora` | 512x512, 768x768, 1024x1024 |
328
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-schnell` | 512x512, 768x768, 1024x1024 |
329
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-canny` | 512x512, 768x768, 1024x1024 |
330
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-depth` | 512x512, 768x768, 1024x1024 |
331
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-redux` | 512x512, 768x768, 1024x1024 |
332
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1.1-pro` | 512x512, 768x768, 1024x1024 |
333
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-pro` | 512x512, 768x768, 1024x1024 |
334
+ | [Together.ai](/providers/ai-sdk-providers/togetherai#image-models) | `black-forest-labs/FLUX.1-schnell-Free` | 512x512, 768x768, 1024x1024 |
335
+ | [Black Forest Labs](/providers/ai-sdk-providers/black-forest-labs#image-models) | `flux-kontext-pro` | From 3:7 (portrait) to 7:3 (landscape) |
336
+ | [Black Forest Labs](/providers/ai-sdk-providers/black-forest-labs#image-models) | `flux-kontext-max` | From 3:7 (portrait) to 7:3 (landscape) |
337
+ | [Black Forest Labs](/providers/ai-sdk-providers/black-forest-labs#image-models) | `flux-pro-1.1-ultra` | From 3:7 (portrait) to 7:3 (landscape) |
338
+ | [Black Forest Labs](/providers/ai-sdk-providers/black-forest-labs#image-models) | `flux-pro-1.1` | From 3:7 (portrait) to 7:3 (landscape) |
339
+ | [Black Forest Labs](/providers/ai-sdk-providers/black-forest-labs#image-models) | `flux-pro-1.0-fill` | From 3:7 (portrait) to 7:3 (landscape) |
340
+
341
+ Above are a small subset of the image models supported by the AI SDK providers. For more, see the respective provider documentation.