From 3c31f9c51b773deec3da5d687d6f4a745762c1d6 Mon Sep 17 00:00:00 2001
From: Andrey Tabakov <ave.tabakov@gmail.com>
Date: Sun, 27 Apr 2025 13:20:28 +0300
Subject: [PATCH] feat(chat): support annotations field in ChatMessage.kt

---
 .../com.aallam.openai.api/chat/Annotations.kt | 41 +++++++++++++++++++
 .../com.aallam.openai.api/chat/ChatMessage.kt |  5 +++
 2 files changed, 46 insertions(+)
 create mode 100644 openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/Annotations.kt

diff --git a/openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/Annotations.kt b/openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/Annotations.kt
new file mode 100644
index 00000000..cfee2843
--- /dev/null
+++ b/openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/Annotations.kt
@@ -0,0 +1,41 @@
+package com.aallam.openai.api.chat
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+public data class Annotations(
+    /**
+     * Type of annotation. e.g. `url_citation`
+     */
+    val type: String,
+
+    /**
+     * An annotation object will contain the URL and title of the cited source,
+     * as well as the start and end index characters in the model's response where those sources were used.
+     */
+    @SerialName("url_citation")
+    val urlCitation: UrlCitation? = null
+)
+
+@Serializable
+public data class UrlCitation(
+    /**
+     * Start index of characters in the model's response
+     */
+    @SerialName("start_index")
+    val startIndex: Int,
+    /**
+     * End index of characters in the model's response
+     */
+    @SerialName("end_index")
+    val endIndex: Int,
+    /**
+     * URL of the cited source
+     */
+    val url: String,
+    /**
+     * Page title of the cited source
+     */
+    val title: String? = null,
+)
\ No newline at end of file
diff --git a/openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/ChatMessage.kt b/openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/ChatMessage.kt
index 1a76e031..fe5a7c24 100644
--- a/openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/ChatMessage.kt
+++ b/openai-core/src/commonMain/kotlin/com.aallam.openai.api/chat/ChatMessage.kt
@@ -55,6 +55,11 @@ public data class ChatMessage(
      * Azure Content Filter Offsets
      */
     @SerialName("content_filter_offsets") public val contentFilterOffsets: List<ContentFilterOffsets>? = null,
+
+    /**
+     * Response metadata. May be used for web search `url_citation`, for example
+     */
+    @SerialName("annotations") public val annotations: List<Annotations>? = null
 ) {
 
     public constructor(