1package ai
2
3// ProviderMetadata represents additional provider-specific metadata.
4// They are passed through from the provider to the AI SDK and enable
5// provider-specific results that can be fully encapsulated in the provider.
6//
7// The outer map is keyed by the provider name, and the inner
8// map is keyed by the provider-specific metadata key.
9//
10// Example:
11//
12// {
13// "anthropic": {
14// "cacheControl": { "type": "ephemeral" }
15// }
16// }
17type ProviderMetadata map[string]map[string]any
18
19// ProviderOptions represents additional provider-specific options.
20// Options are additional input to the provider. They are passed through
21// to the provider from the AI SDK and enable provider-specific functionality
22// that can be fully encapsulated in the provider.
23//
24// This enables us to quickly ship provider-specific functionality
25// without affecting the core AI SDK.
26//
27// The outer map is keyed by the provider name, and the inner
28// map is keyed by the provider-specific option key.
29//
30// Example:
31//
32// {
33// "anthropic": {
34// "cacheControl": { "type": "ephemeral" }
35// }
36// }
37type ProviderOptions map[string]map[string]any
38
39// FinishReason represents why a language model finished generating a response.
40//
41// Can be one of the following:
42// - `stop`: model generated stop sequence
43// - `length`: model generated maximum number of tokens
44// - `content-filter`: content filter violation stopped the model
45// - `tool-calls`: model triggered tool calls
46// - `error`: model stopped because of an error
47// - `other`: model stopped for other reasons
48// - `unknown`: the model has not transmitted a finish reason
49type FinishReason string
50
51const (
52 FinishReasonStop FinishReason = "stop" // model generated stop sequence
53 FinishReasonLength FinishReason = "length" // model generated maximum number of tokens
54 FinishReasonContentFilter FinishReason = "content-filter" // content filter violation stopped the model
55 FinishReasonToolCalls FinishReason = "tool-calls" // model triggered tool calls
56 FinishReasonError FinishReason = "error" // model stopped because of an error
57 FinishReasonOther FinishReason = "other" // model stopped for other reasons
58 FinishReasonUnknown FinishReason = "unknown" // the model has not transmitted a finish reason
59)
60
61// Prompt represents a list of messages for the language model.
62type Prompt []Message
63
64// MessageRole represents the role of a message.
65type MessageRole string
66
67const (
68 MessageRoleSystem MessageRole = "system"
69 MessageRoleUser MessageRole = "user"
70 MessageRoleAssistant MessageRole = "assistant"
71 MessageRoleTool MessageRole = "tool"
72)
73
74// Message represents a message in a prompt.
75type Message struct {
76 Role MessageRole `json:"role"`
77 Content []MessagePart `json:"content"`
78 ProviderOptions ProviderOptions `json:"provider_options"`
79}
80
81func AsContentType[T MessagePart](content MessagePart) (T, bool) {
82 var zero T
83 if content == nil {
84 return zero, false
85 }
86 switch v := any(content).(type) {
87 case T:
88 return v, true
89 case *T:
90 return *v, true
91 default:
92 return zero, false
93 }
94}
95
96// MessagePart represents a part of a message content.
97type MessagePart interface {
98 GetType() ContentType
99}
100
101// TextPart represents text content in a message.
102type TextPart struct {
103 Text string `json:"text"`
104 ProviderOptions ProviderOptions `json:"provider_options"`
105}
106
107// GetType returns the type of the text part.
108func (t TextPart) GetType() ContentType {
109 return ContentTypeText
110}
111
112// ReasoningPart represents reasoning content in a message.
113type ReasoningPart struct {
114 Text string `json:"text"`
115 ProviderOptions ProviderOptions `json:"provider_options"`
116}
117
118// GetType returns the type of the reasoning part.
119func (r ReasoningPart) GetType() ContentType {
120 return ContentTypeReasoning
121}
122
123// FilePart represents file content in a message.
124type FilePart struct {
125 Filename string `json:"filename"`
126 Data []byte `json:"data"`
127 MediaType string `json:"media_type"`
128 ProviderOptions ProviderOptions `json:"provider_options"`
129}
130
131// GetType returns the type of the file part.
132func (f FilePart) GetType() ContentType {
133 return ContentTypeFile
134}
135
136// ToolCallPart represents a tool call in a message.
137type ToolCallPart struct {
138 ToolCallID string `json:"tool_call_id"`
139 ToolName string `json:"tool_name"`
140 Input string `json:"input"` // the json string
141 ProviderExecuted bool `json:"provider_executed"`
142 ProviderOptions ProviderOptions `json:"provider_options"`
143}
144
145// GetType returns the type of the tool call part.
146func (t ToolCallPart) GetType() ContentType {
147 return ContentTypeToolCall
148}
149
150// ToolResultPart represents a tool result in a message.
151type ToolResultPart struct {
152 ToolCallID string `json:"tool_call_id"`
153 Output ToolResultOutputContent `json:"output"`
154 ProviderOptions ProviderOptions `json:"provider_options"`
155}
156
157// GetType returns the type of the tool result part.
158func (t ToolResultPart) GetType() ContentType {
159 return ContentTypeToolResult
160}
161
162// ToolResultContentType represents the type of tool result output.
163type ToolResultContentType string
164
165const (
166 // ToolResultContentTypeText represents text output.
167 ToolResultContentTypeText ToolResultContentType = "text"
168 // ToolResultContentTypeError represents error text output.
169 ToolResultContentTypeError ToolResultContentType = "error"
170 // ToolResultContentTypeMedia represents content output.
171 ToolResultContentTypeMedia ToolResultContentType = "media"
172)
173
174type ToolResultOutputContent interface {
175 GetType() ToolResultContentType
176}
177
178type ToolResultOutputContentText struct {
179 Text string `json:"text"`
180}
181
182func (t ToolResultOutputContentText) GetType() ToolResultContentType {
183 return ToolResultContentTypeText
184}
185
186type ToolResultOutputContentError struct {
187 Error string `json:"error"`
188}
189
190func (t ToolResultOutputContentError) GetType() ToolResultContentType {
191 return ToolResultContentTypeError
192}
193
194type ToolResultOutputContentMedia struct {
195 Data string `json:"data"` // for media type (base64)
196 MediaType string `json:"media_type"` // for media type
197}
198
199func (t ToolResultOutputContentMedia) GetType() ToolResultContentType {
200 return ToolResultContentTypeMedia
201}
202
203func AsToolResultOutputType[T ToolResultOutputContent](content ToolResultOutputContent) (T, bool) {
204 var zero T
205 if content == nil {
206 return zero, false
207 }
208 switch v := any(content).(type) {
209 case T:
210 return v, true
211 case *T:
212 return *v, true
213 default:
214 return zero, false
215 }
216}
217
218// ContentType represents the type of content.
219type ContentType string
220
221const (
222 // ContentTypeText represents text content.
223 ContentTypeText ContentType = "text"
224 // ContentTypeReasoning represents reasoning content.
225 ContentTypeReasoning ContentType = "reasoning"
226 // ContentTypeFile represents file content.
227 ContentTypeFile ContentType = "file"
228 // ContentTypeSource represents source content.
229 ContentTypeSource ContentType = "source"
230 // ContentTypeToolCall represents a tool call.
231 ContentTypeToolCall ContentType = "tool-call"
232 // ContentTypeToolResult represents a tool result.
233 ContentTypeToolResult ContentType = "tool-result"
234)
235
236// Content represents generated content from the model.
237type Content interface {
238 GetType() ContentType
239}
240
241// TextContent represents text that the model has generated.
242type TextContent struct {
243 // The text content.
244 Text string `json:"text"`
245 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
246}
247
248// GetType returns the type of the text content.
249func (t TextContent) GetType() ContentType {
250 return ContentTypeText
251}
252
253// ReasoningContent represents reasoning that the model has generated.
254type ReasoningContent struct {
255 Text string `json:"text"`
256 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
257}
258
259// GetType returns the type of the reasoning content.
260func (r ReasoningContent) GetType() ContentType {
261 return ContentTypeReasoning
262}
263
264// FileContent represents a file that has been generated by the model.
265// Generated files as base64 encoded strings or binary data.
266// The files should be returned without any unnecessary conversion.
267type FileContent struct {
268 // The IANA media type of the file, e.g. `image/png` or `audio/mp3`.
269 // @see https://www.iana.org/assignments/media-types/media-types.xhtml
270 MediaType string `json:"media_type"`
271 // Generated file data as base64 encoded strings or binary data.
272 // If the API returns base64 encoded strings, the file data should be returned
273 // as base64 encoded strings. If the API returns binary data, the file data should
274 // be returned as binary data.
275 Data any `json:"data"` // string (base64) or []byte
276}
277
278// GetType returns the type of the file content.
279func (f FileContent) GetType() ContentType {
280 return ContentTypeFile
281}
282
283// SourceType represents the type of source.
284type SourceType string
285
286const (
287 // SourceTypeURL represents a URL source.
288 SourceTypeURL SourceType = "url"
289 // SourceTypeDocument represents a document source.
290 SourceTypeDocument SourceType = "document"
291)
292
293// SourceContent represents a source that has been used as input to generate the response.
294type SourceContent struct {
295 SourceType SourceType `json:"source_type"` // "url" or "document"
296 ID string `json:"id"`
297 URL string `json:"url"` // for URL sources
298 Title string `json:"title"`
299 MediaType string `json:"media_type"` // for document sources (IANA media type)
300 Filename string `json:"filename"` // for document sources
301 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
302}
303
304// GetType returns the type of the source content.
305func (s SourceContent) GetType() ContentType {
306 return ContentTypeSource
307}
308
309// ToolCallContent represents tool calls that the model has generated.
310type ToolCallContent struct {
311 ToolCallID string `json:"tool_call_id"`
312 ToolName string `json:"tool_name"`
313 // Stringified JSON object with the tool call arguments.
314 // Must match the parameters schema of the tool.
315 Input string `json:"input"`
316 // Whether the tool call will be executed by the provider.
317 // If this flag is not set or is false, the tool call will be executed by the client.
318 ProviderExecuted bool `json:"provider_executed"`
319 // Additional provider-specific metadata for the tool call.
320 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
321}
322
323// GetType returns the type of the tool call content.
324func (t ToolCallContent) GetType() ContentType {
325 return ContentTypeToolCall
326}
327
328// ToolResultContent represents result of a tool call that has been executed by the provider.
329type ToolResultContent struct {
330 // The ID of the tool call that this result is associated with.
331 ToolCallID string `json:"tool_call_id"`
332 // Name of the tool that generated this result.
333 ToolName string `json:"tool_name"`
334 // Result of the tool call. This is a JSON-serializable object.
335 Result any `json:"result"`
336 // Optional flag if the result is an error or an error message.
337 IsError bool `json:"is_error"`
338 // Whether the tool result was generated by the provider.
339 // If this flag is set to true, the tool result was generated by the provider.
340 // If this flag is not set or is false, the tool result was generated by the client.
341 ProviderExecuted bool `json:"provider_executed"`
342 // Additional provider-specific metadata for the tool result.
343 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
344}
345
346// GetType returns the type of the tool result content.
347func (t ToolResultContent) GetType() ContentType {
348 return ContentTypeToolResult
349}
350
351// ToolType represents the type of tool.
352type ToolType string
353
354const (
355 // ToolTypeFunction represents a function tool.
356 ToolTypeFunction ToolType = "function"
357 // ToolTypeProviderDefined represents a provider-defined tool.
358 ToolTypeProviderDefined ToolType = "provider-defined"
359)
360
361// Tool represents a tool that can be used by the model.
362//
363// Note: this is **not** the user-facing tool definition. The AI SDK methods will
364// map the user-facing tool definitions to this format.
365type Tool interface {
366 GetType() ToolType
367 GetName() string
368}
369
370// FunctionTool represents a function tool.
371//
372// A tool has a name, a description, and a set of parameters.
373type FunctionTool struct {
374 // Name of the tool. Unique within this model call.
375 Name string `json:"name"`
376 // Description of the tool. The language model uses this to understand the
377 // tool's purpose and to provide better completion suggestions.
378 Description string `json:"description"`
379 // InputSchema - the parameters that the tool expects. The language model uses this to
380 // understand the tool's input requirements and to provide matching suggestions.
381 InputSchema map[string]any `json:"input_schema"` // JSON Schema
382 // ProviderOptions are provider-specific options for the tool.
383 ProviderOptions ProviderOptions `json:"provider_options"`
384}
385
386// GetType returns the type of the function tool.
387func (f FunctionTool) GetType() ToolType {
388 return ToolTypeFunction
389}
390
391// GetName returns the name of the function tool.
392func (f FunctionTool) GetName() string {
393 return f.Name
394}
395
396// ProviderDefinedTool represents the configuration of a tool that is defined by the provider.
397type ProviderDefinedTool struct {
398 // ID of the tool. Should follow the format `<provider-name>.<unique-tool-name>`.
399 ID string `json:"id"`
400 // Name of the tool that the user must use in the tool set.
401 Name string `json:"name"`
402 // Args for configuring the tool. Must match the expected arguments defined by the provider for this tool.
403 Args map[string]any `json:"args"`
404}
405
406// GetType returns the type of the provider-defined tool.
407func (p ProviderDefinedTool) GetType() ToolType {
408 return ToolTypeProviderDefined
409}
410
411// GetName returns the name of the provider-defined tool.
412func (p ProviderDefinedTool) GetName() string {
413 return p.Name
414}
415
416// Helpers
417func NewUserMessage(prompt string, files ...FilePart) Message {
418 content := []MessagePart{
419 TextPart{
420 Text: prompt,
421 },
422 }
423
424 for _, f := range files {
425 content = append(content, f)
426 }
427
428 return Message{
429 Role: MessageRoleUser,
430 Content: content,
431 }
432}