notebooks/spring-ai/tutorials/5. Structured Outputs.ipynb

{
 "cells": [
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "# Structured Outputs\n",
    "\n",
    "Structured outputs are a capability that allows language models to format responses in specific, well-defined structures rather than just generating free-form text.\n",
    "This enables LLMs to deliver answers in formats like **JSON**, **XML**, and others.\n",
    "\n",
    "**How It Works**:\n",
    "1. Define a schema that describes the exact format you want\n",
    "2. The LLM generates content that strictly adheres to this predefined structure\n",
    "3. You get consistently formatted responses that are easier to parse and use in applications\n",
    "\n",
    "There are two ways to ask an LLM to format a response in a specific schema:\n",
    "1. Describe the desired result in your prompt\n",
    "2. Use structured output capabilities and pass a response schema\n",
    "\n",
    "Let's start by adding our dependencies, apiKey, and `ChatClient`"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-28T18:55:40.916658Z",
     "start_time": "2025-03-28T18:55:40.786875Z"
    }
   },
   "cell_type": "code",
   "source": [
    "@file:DependsOn(\"org.springframework.ai:spring-ai-openai-spring-boot-starter:1.0.0-M6\")\n",
    "@file:DependsOn(\"com.fasterxml.jackson.module:jackson-module-kotlin:2.18.2\")"
   ],
   "outputs": [],
   "execution_count": 19
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-28T18:55:44.524547Z",
     "start_time": "2025-03-28T18:55:44.466745Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import org.springframework.ai.chat.client.ChatClient\n",
    "import org.springframework.ai.openai.OpenAiChatModel\n",
    "import org.springframework.ai.openai.OpenAiChatOptions\n",
    "import org.springframework.ai.openai.api.OpenAiApi\n",
    "\n",
    "val apiKey = System.getenv(\"OPENAI_API_KEY\") ?: \"YOUR_OPENAI_API_KEY\"\n",
    "\n",
    "val openAiApi = OpenAiApi.builder().apiKey(apiKey).build()\n",
    "val openAiOptions = OpenAiChatOptions.builder()\n",
    "    .model(OpenAiApi.ChatModel.GPT_4_O_MINI)\n",
    "    .temperature(0.7)\n",
    "    .build()\n",
    "\n",
    "val chatClient = ChatClient.create(\n",
    "    OpenAiChatModel.builder()\n",
    "        .openAiApi(openAiApi)\n",
    "        .defaultOptions(openAiOptions)\n",
    "        .build()\n",
    ")"
   ],
   "outputs": [],
   "execution_count": 20
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "First, let's try describing our desired response format in the prompt and see what happens:"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-28T18:55:57.892089Z",
     "start_time": "2025-03-28T18:55:56.816014Z"
    }
   },
   "cell_type": "code",
   "source": [
    "val response = chatClient\n",
    "    .prompt()\n",
    "    .system(\"The response must be a valid JSON object.\")\n",
    "    .user(\n",
    "        \"\"\"\n",
    "        What is the firstName and lastName of the person in this sentence?\n",
    "\n",
    "        \"Aurora Skyfield announced her candidacy for the local city council yesterday.\"\n",
    "        \"\"\"\n",
    "    )\n",
    "    .call()\n",
    "    .content()\n",
    "\n",
    "response"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{\n",
       "  \"firstName\": \"Aurora\",\n",
       "  \"lastName\": \"Skyfield\"\n",
       "}"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 21
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "As we can see, the result is JSON, so we can convert it to a Kotlin class:"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-28T18:56:08.915010Z",
     "start_time": "2025-03-28T18:56:08.833758Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import kotlinx.serialization.Serializable\n",
    "import kotlinx.serialization.json.Json\n",
    "\n",
    "@Serializable\n",
    "data class Person(val firstName: String, val lastName: String)\n",
    "\n",
    "Json.decodeFromString<Person>(response)"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Person(firstName=Aurora, lastName=Skyfield)"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 22
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "However, this approach for getting data isn't reliable,\n",
    "as the prompt doesn't guarantee that the result will be returned exactly in this format.\n",
    "\n",
    "So let's use a method that will definitely return a structured response —\n",
    "and directly as a Kotlin class.\n",
    "\n",
    "First, let's define the class we need:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-28T18:56:32.292028Z",
     "start_time": "2025-03-28T18:56:32.243091Z"
    }
   },
   "cell_type": "code",
   "source": [
    "data class MobileDevice(\n",
    "    val name: String,\n",
    "    val price: Double,\n",
    "    val category: String,\n",
    "    val features: List<String> = emptyList()\n",
    ")"
   ],
   "outputs": [],
   "execution_count": 23
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "Now we can simply pass it as the expected result:"
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-03-28T18:56:47.244367Z",
     "start_time": "2025-03-28T18:56:45.536558Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import org.springframework.ai.chat.client.entity\n",
    "\n",
    "chatClient\n",
    "    .prompt(\"Tell me about the latest smartphone\")\n",
    "    .call()\n",
    "    .entity<MobileDevice>()"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "MobileDevice(name=SuperPhone X1, price=999.99, category=smartphone, features=[5G connectivity, Triple camera system, AMOLED display, Fast charging, Water resistant, In-display fingerprint sensor])"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 24
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Kotlin",
   "language": "kotlin",
   "name": "kotlin"
  },
  "language_info": {
   "name": "kotlin",
   "version": "1.9.23",
   "mimetype": "text/x-kotlin",
   "file_extension": ".kt",
   "pygments_lexer": "kotlin",
   "codemirror_mode": "text/x-kotlin",
   "nbconvert_exporter": ""
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}