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 error `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 binary data.
272 Data []byte `json:"data"`
273 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
274}
275
276// GetType returns the type of the file content.
277func (f FileContent) GetType() ContentType {
278 return ContentTypeFile
279}
280
281// SourceType represents the type of source.
282type SourceType string
283
284const (
285 // SourceTypeURL represents a URL source.
286 SourceTypeURL SourceType = "url"
287 // SourceTypeDocument represents a document source.
288 SourceTypeDocument SourceType = "document"
289)
290
291// SourceContent represents a source that has been used as input to generate the response.
292type SourceContent struct {
293 SourceType SourceType `json:"source_type"` // "url" or "document"
294 ID string `json:"id"`
295 URL string `json:"url"` // for URL sources
296 Title string `json:"title"`
297 MediaType string `json:"media_type"` // for document sources (IANA media type)
298 Filename string `json:"filename"` // for document sources
299 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
300}
301
302// GetType returns the type of the source content.
303func (s SourceContent) GetType() ContentType {
304 return ContentTypeSource
305}
306
307// ToolCallContent represents tool calls that the model has generated.
308type ToolCallContent struct {
309 ToolCallID string `json:"tool_call_id"`
310 ToolName string `json:"tool_name"`
311 // Stringified JSON object with the tool call arguments.
312 // Must match the parameters schema of the tool.
313 Input string `json:"input"`
314 // Whether the tool call will be executed by the provider.
315 // If this flag is not set or is false, the tool call will be executed by the client.
316 ProviderExecuted bool `json:"provider_executed"`
317 // Additional provider-specific metadata for the tool call.
318 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
319}
320
321// GetType returns the type of the tool call content.
322func (t ToolCallContent) GetType() ContentType {
323 return ContentTypeToolCall
324}
325
326// ToolResultContent represents result of a tool call that has been executed by the provider.
327type ToolResultContent struct {
328 // The ID of the tool call that this result is associated with.
329 ToolCallID string `json:"tool_call_id"`
330 // Name of the tool that generated this result.
331 ToolName string `json:"tool_name"`
332 // Result of the tool call. This is a JSON-serializable object.
333 Result ToolResultOutputContent `json:"result"`
334 // Whether the tool result was generated by the provider.
335 // If this flag is set to true, the tool result was generated by the provider.
336 // If this flag is not set or is false, the tool result was generated by the client.
337 ProviderExecuted bool `json:"provider_executed"`
338 // Additional provider-specific metadata for the tool result.
339 ProviderMetadata ProviderMetadata `json:"provider_metadata"`
340}
341
342// GetType returns the type of the tool result content.
343func (t ToolResultContent) GetType() ContentType {
344 return ContentTypeToolResult
345}
346
347// ToolType represents the type of tool.
348type ToolType string
349
350const (
351 // ToolTypeFunction represents a function tool.
352 ToolTypeFunction ToolType = "function"
353 // ToolTypeProviderDefined represents a provider-defined tool.
354 ToolTypeProviderDefined ToolType = "provider-defined"
355)
356
357// Tool represents a tool that can be used by the model.
358//
359// Note: this is **not** the user-facing tool definition. The AI SDK methods will
360// map the user-facing tool definitions to this format.
361type Tool interface {
362 GetType() ToolType
363 GetName() string
364}
365
366// FunctionTool represents a function tool.
367//
368// A tool has a name, a description, and a set of parameters.
369type FunctionTool struct {
370 // Name of the tool. Unique within this model call.
371 Name string `json:"name"`
372 // Description of the tool. The language model uses this to understand the
373 // tool's purpose and to provide better completion suggestions.
374 Description string `json:"description"`
375 // InputSchema - the parameters that the tool expects. The language model uses this to
376 // understand the tool's input requirements and to provide matching suggestions.
377 InputSchema map[string]any `json:"input_schema"` // JSON Schema
378 // ProviderOptions are provider-specific options for the tool.
379 ProviderOptions ProviderOptions `json:"provider_options"`
380}
381
382// GetType returns the type of the function tool.
383func (f FunctionTool) GetType() ToolType {
384 return ToolTypeFunction
385}
386
387// GetName returns the name of the function tool.
388func (f FunctionTool) GetName() string {
389 return f.Name
390}
391
392// ProviderDefinedTool represents the configuration of a tool that is defined by the provider.
393type ProviderDefinedTool struct {
394 // ID of the tool. Should follow the format `<provider-name>.<unique-tool-name>`.
395 ID string `json:"id"`
396 // Name of the tool that the user must use in the tool set.
397 Name string `json:"name"`
398 // Args for configuring the tool. Must match the expected arguments defined by the provider for this tool.
399 Args map[string]any `json:"args"`
400}
401
402// GetType returns the type of the provider-defined tool.
403func (p ProviderDefinedTool) GetType() ToolType {
404 return ToolTypeProviderDefined
405}
406
407// GetName returns the name of the provider-defined tool.
408func (p ProviderDefinedTool) GetName() string {
409 return p.Name
410}
411
412// Helpers
413func NewUserMessage(prompt string, files ...FilePart) Message {
414 content := []MessagePart{
415 TextPart{
416 Text: prompt,
417 },
418 }
419
420 for _, f := range files {
421 content = append(content, f)
422 }
423
424 return Message{
425 Role: MessageRoleUser,
426 Content: content,
427 }
428}
429
430func NewSystemMessage(prompt ...string) Message {
431 var content []MessagePart
432 for _, p := range prompt {
433 content = append(content, TextPart{Text: p})
434 }
435
436 return Message{
437 Role: MessageRoleSystem,
438 Content: content,
439 }
440}