notebooks/openai/OpenAI Java SDK Overview.ipynb

{
 "cells": [
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "# OpenAI Java SDK Overview\n",
    "\n",
    "## 1. Introduction and Installation\n",
    "\n",
    "### What is OpenAI Java SDK?\n",
    "\n",
    "[OpenAI Java SDK](https://github.com/openai/openai-java/tree/main) is an official Java library generated by\n",
    "[Stainless](https://www.stainless.com/) in pure Kotlin for interacting with the OpenAI API.\n",
    "It allows developers to easily integrate language model capabilities and other OpenAI AI services into their JVM applications.\n",
    "\n",
    "\n",
    "### Installation and Environment Setup\n",
    "\n",
    "Using OpenAI Java SDK is straightforward.\n",
    "\n",
    "For JVM projects:\n",
    "\n",
    "```kotlin\n",
    "implementation(\"com.openai:openai-java:$sdkVersion)\n",
    "```\n",
    "\n",
    "In Kotlin Notebook:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:00:42.487230Z",
     "start_time": "2025-04-01T23:00:42.187330Z"
    }
   },
   "cell_type": "code",
   "source": "@file:DependsOn(\"com.openai:openai-java:0.41.1\")",
   "outputs": [],
   "execution_count": 1
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "#### API Key\n",
    "\n",
    "To work with the API, you need an API key that can be obtained from your personal account on the OpenAI website.\n",
    "\n",
    "Add it to your environment variables.\n",
    "\n",
    "[MacOS/Linux]\n",
    "```bash\n",
    "export OPENAI_API_KEY=<INSERT KEY HERE>\n",
    "```\n",
    "\n",
    "[Windows]\n",
    "```shell\n",
    "set OPENAI_API_KEY=<INSERT KEY HERE>\n",
    "```"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:00:42.696974Z",
     "start_time": "2025-04-01T23:00:42.492834Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import com.openai.client.okhttp.OpenAIOkHttpClient\n",
    "\n",
    "// Create a client using your API key from environment variables\n",
    "// Configures using the `OPENAI_API_KEY`, `OPENAI_ORG_ID` and `OPENAI_PROJECT_ID` environment variables\n",
    "val client = OpenAIOkHttpClient.fromEnv()"
   ],
   "outputs": [],
   "execution_count": 2
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": "Let's create a simple request."
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:00:49.150957Z",
     "start_time": "2025-04-01T23:00:42.706680Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import com.openai.models.ChatModel\n",
    "import com.openai.models.chat.completions.ChatCompletionCreateParams\n",
    "\n",
    "val response = client.chat().completions().create(\n",
    "    ChatCompletionCreateParams.builder()\n",
    "        .model(ChatModel.GPT_4O_MINI)\n",
    "        .addSystemMessage(\"You are a helpful assistant.\")\n",
    "        .addUserMessage(\"Hello! Who are you?\")\n",
    "        .build()\n",
    ")\n",
    "\n",
    "response.choices().first().message().content().get()"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Hello! I’m an AI assistant designed to help you with information, answer questions, and assist with a variety of topics. How can I help you today?"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 3
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## 2. Basic\n",
    "\n",
    "#### Text Requests\n",
    "\n",
    "Basic example of interacting with the model"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:01:01.029018Z",
     "start_time": "2025-04-01T23:00:49.156287Z"
    }
   },
   "cell_type": "code",
   "source": [
    "val response = client.chat().completions().create(\n",
    "    ChatCompletionCreateParams.builder()\n",
    "        .model(ChatModel.GPT_4O_MINI)\n",
    "        .addSystemMessage(\"You are a Kotlin expert. You can answer questions about Kotlin.\")\n",
    "        .addUserMessage(\"Explain what coroutines are in Kotlin and provide an example.\")\n",
    "        .build()\n",
    ")\n",
    "\n",
    "response.choices().first().message().content().get()"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Coroutines in Kotlin are a powerful feature that simplifies asynchronous programming and concurrency. They allow you to write non-blocking code in a sequential style, making it easier to work with asynchronous tasks without the complexity of traditional callback methods or thread management.\n",
       "\n",
       "Coroutines are lightweight threads that can be suspended and resumed, enabling you to perform long-running tasks without blocking the main thread. They are particularly useful for tasks like network calls, file I/O, or any operation that might take time and would otherwise cause your application to become unresponsive if handled on the main thread.\n",
       "\n",
       "### Key Concepts of Coroutines\n",
       "- **Suspend Functions**: Functions marked with the `suspend` keyword can be paused and resumed later. They can call other suspend functions, but they need to be called from within a coroutine or another suspend function.\n",
       "- **Coroutine Builders**: Functions that help create coroutines, such as `launch`, `async`, and `runBlocking`.\n",
       "- **Scope**: A coroutine scope defines a context for running coroutines. It manages the lifecycle of coroutines and provides a structure for launching them.\n",
       "\n",
       "### Example:\n",
       "\n",
       "Here's a simple example demonstrating the use of coroutines in Kotlin. In this example, we'll simulate a network call that fetches data and update the UI accordingly.\n",
       "\n",
       "```kotlin\n",
       "import kotlinx.coroutines.*\n",
       "\n",
       "fun main() = runBlocking {\n",
       "    // Launching a coroutine\n",
       "    launch {\n",
       "        // Call a suspend function\n",
       "        val result = fetchDataFromNetwork()\n",
       "        println(\"Data fetched: $result\")\n",
       "    }\n",
       "\n",
       "    println(\"Coroutine launched, continuing with other work.\")\n",
       "}\n",
       "\n",
       "suspend fun fetchDataFromNetwork(): String {\n",
       "    // Simulating a long-running network call\n",
       "    delay(2000) // This is a suspend function\n",
       "    return \"Sample Data\"\n",
       "}\n",
       "```\n",
       "\n",
       "### Explanation of the Example:\n",
       "1. **`runBlocking { ... }`**: This is a coroutine builder that blocks the current thread until all the coroutines inside it complete. It's typically used in main functions or tests.\n",
       "   \n",
       "2. **`launch { ... }`**: This launches a new coroutine in the background. It doesn't block the current thread and returns immediately.\n",
       "\n",
       "3. **`suspend fun fetchDataFromNetwork()`**: This function simulates fetching data from the network. The `delay` function is used here to mimic the time taken for a network call without blocking the thread.\n",
       "\n",
       "4. **`delay(2000)`**: This is a suspending function that introduces a delay of 2 seconds. During this time, other coroutines or code can run without being blocked.\n",
       "\n",
       "When you run this program, it will print \"Coroutine launched, continuing with other work.\" almost immediately, followed by \"Data fetched: Sample Data\" after a 2-second delay, demonstrating the non-blocking behavior of coroutines."
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 4
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Configuring Parameters\n",
    "\n",
    "OpenAI SDK allows configuring various parameters that affect text generation:"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:01:06.366674Z",
     "start_time": "2025-04-01T23:01:01.046810Z"
    }
   },
   "cell_type": "code",
   "source": [
    "val response = client.chat().completions().create(\n",
    "    ChatCompletionCreateParams.builder()\n",
    "        .model(ChatModel.GPT_4O_MINI)\n",
    "        .addSystemMessage(\"You are a creative writer.\")\n",
    "        .addUserMessage(\"Come up with a short story about a space voyage.\")\n",
    "        .temperature(0.8)           // Controls randomness (0-2, default is 1)\n",
    "        .maxCompletionTokens(300)   // Maximum response length\n",
    "        .topP(0.95)                 // Nucleus sampling - alternative to temperature\n",
    "        .presencePenalty(0.2)       // Penalty for topic repetition (-2.0 to 2.0)\n",
    "        .frequencyPenalty(0.5)      // Penalty for phrase repetition (-2.0 to 2.0)\n",
    "        .build()\n",
    ")\n",
    "\n",
    "response.choices().first().message().content().get()"
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "**Title: The Last Signal**\n",
       "\n",
       "In the year 2267, humanity had expanded far beyond the cradle of Earth, establishing colonies on distant planets and moons. Among these ventures was the starship *Odyssey*, a sleek vessel tasked with exploring the uncharted reaches of the Andromeda sector. Captain Elara Voss stood on the bridge, her eyes fixed on the swirling cosmos outside.\n",
       "\n",
       "“Prepare for jump in thirty seconds,” she commanded, her voice steady despite the excitement that buzzed through her crew. They were about to embark on a voyage that would take them deeper into space than any human had ever ventured before.\n",
       "\n",
       "As they transitioned through hyperspace, time seemed to stretch and warp around them. For a brief moment, Elara found herself lost in thought about what lay ahead: new worlds, new lifeforms—perhaps even ancient civilizations hidden among the stars.\n",
       "\n",
       "The ship jolted violently as they exited hyperspace. Alarms blared, and lights flickered ominously. “Status report!” Elara shouted as she regained her footing.\n",
       "\n",
       "“Systems are stable,” replied Keira, the ship’s engineer, her fingers flying over her console. “We’ve emerged in an uncharted system… but there’s interference.” \n",
       "\n",
       "Elara squinted at the screen where swirling clouds of gas obscured their view of nearby planets. Yet one signal pulsed steadily amidst it all—a beacon unlike anything they’d ever encountered before.\n",
       "\n",
       "“Can you trace it?” she asked.\n",
       "\n",
       "“It’s faint but"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 5
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "### Prompt Examples\n",
    "\n",
    "The quality of the response heavily depends on the request structure"
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:01:12.710709Z",
     "start_time": "2025-04-01T23:01:06.374896Z"
    }
   },
   "cell_type": "code",
   "source": [
    "// Example 1: Basic prompt\n",
    "val basicPrompt = \"Explain machine learning.\"\n",
    "\n",
    "// Example 2: Improved prompt\n",
    "val goodPrompt =\n",
    "    \"\"\"\n",
    "    Explain the concept of machine learning to a beginner student.\n",
    "    Include the following:\n",
    "    1) a definition in simple words\n",
    "    2) the difference between supervised and unsupervised learning\n",
    "    3) three real-world application examples\n",
    "    Use analogies to explain complex concepts and keep the explanation within 200 words.\n",
    "    \"\"\".trimIndent()\n",
    "\n",
    "// Сравним результаты\n",
    "for (prompt in listOf(basicPrompt, goodPrompt)) {\n",
    "    val response = client.chat().completions().create(\n",
    "        ChatCompletionCreateParams.builder()\n",
    "            .model(ChatModel.GPT_4O_MINI)\n",
    "            .addSystemMessage(\"You are a scientific expert.\")\n",
    "            .addUserMessage(prompt)\n",
    "            .maxCompletionTokens(150)\n",
    "            .build()\n",
    "    )\n",
    "\n",
    "    println(\"Prompt: $prompt\")\n",
    "    println(\"Response:\\n${response.choices().first().message().content().get()}\")\n",
    "    println(\"-\".repeat(80))\n",
    "}"
   ],
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Prompt: Explain machine learning.\n",
      "Response:\n",
      "Machine learning (ML) is a subset of artificial intelligence (AI) that focuses on the development of algorithms and statistical models that enable computers to perform specific tasks without being explicitly programmed. It allows systems to learn from data, improve their performance over time, and make predictions or decisions based on patterns and insights derived from that data.\n",
      "\n",
      "### Key Concepts of Machine Learning:\n",
      "\n",
      "1. **Data**: The foundation of machine learning is data. This can be structured (like tables) or unstructured (like text, images, or audio). Quality and quantity of data significantly impact the performance of ML models.\n",
      "\n",
      "2. **Algorithms**: Machine learning uses a variety of algorithms to analyze data and identify patterns. Common types include:\n",
      "   - **Supervised Learning**\n",
      "--------------------------------------------------------------------------------\n",
      "Prompt: Explain the concept of machine learning to a beginner student.\n",
      "Include the following:\n",
      "1) a definition in simple words\n",
      "2) the difference between supervised and unsupervised learning\n",
      "3) three real-world application examples\n",
      "Use analogies to explain complex concepts and keep the explanation within 200 words.\n",
      "Response:\n",
      "**Definition:** Machine learning is like teaching a computer to learn from experience, just as we do. Instead of programming it with every rule, we give it lots of data, and it learns patterns from that data to make decisions or predictions.\n",
      "\n",
      "**Supervised vs. Unsupervised Learning:** \n",
      "Think of supervised learning like a teacher guiding a student. The student (computer) learns from labeled examples—like showing a child pictures of cats and dogs and telling them which is which. In contrast, unsupervised learning is like letting a student explore without guidance. The student gets a pile of pictures but must find out patterns on their own, like grouping similar images without knowing what they are.\n",
      "\n",
      "**Real-World Applications:**\n",
      "1. **Spam Filtering\n",
      "--------------------------------------------------------------------------------\n"
     ]
    }
   ],
   "execution_count": 6
  },
  {
   "metadata": {},
   "cell_type": "markdown",
   "source": [
    "## 3. Function Calling\n",
    "\n",
    "Function calling allows models to call specific functions,\n",
    "which is especially useful for extracting structured data from text or\n",
    "performing specific actions based on user input."
   ]
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:01:14.624335Z",
     "start_time": "2025-04-01T23:01:12.717333Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import com.openai.core.JsonValue\n",
    "import com.openai.models.FunctionDefinition\n",
    "import com.openai.models.FunctionParameters\n",
    "import com.openai.models.chat.completions.ChatCompletionTool\n",
    "\n",
    "fun getWeather(location: String): Map<String, Any> = when {\n",
    "    \"Berlin\" in location -> mapOf(\"temp\" to 13, \"conditions\" to \"Cloudy\")\n",
    "    \"Tokyo\" in location -> mapOf(\"temp\" to 21, \"conditions\" to \"Sunny\")\n",
    "    \"New York\" in location -> mapOf(\"temp\" to 15, \"conditions\" to \"Rainy\")\n",
    "    else -> mapOf(\"temp\" to 0, \"conditions\" to \"Unknown\")\n",
    "}\n",
    "\n",
    "val functionDef = FunctionDefinition.builder()\n",
    "    .name(\"get_weather\")\n",
    "    .description(\"Get the weather conditions in a given location\")\n",
    "    .parameters(\n",
    "        FunctionParameters.builder()\n",
    "            .putAdditionalProperty(\"type\", JsonValue.from(\"object\"))\n",
    "            .putAdditionalProperty(\n",
    "                \"properties\", JsonValue.from(\n",
    "                    mapOf(\n",
    "                        \"location\" to JsonValue.from(\n",
    "                            mapOf(\n",
    "                                \"type\" to \"string\",\n",
    "                                \"description\" to \"The city or location to get the weather for\"\n",
    "                            )\n",
    "                        )\n",
    "                    )\n",
    "                )\n",
    "            )\n",
    "            .putAdditionalProperty(\"required\", JsonValue.from(listOf(\"location\")))\n",
    "            .putAdditionalProperty(\"additionalProperties\", JsonValue.from(false))\n",
    "            .build()\n",
    "    )\n",
    "    .build()\n",
    "\n",
    "val userQuery = \"What is the weather in Berlin?\"\n",
    "\n",
    "val params = ChatCompletionCreateParams.builder()\n",
    "    .model(ChatModel.GPT_4O_MINI)\n",
    "    .addUserMessage(userQuery)\n",
    "    .addTool(ChatCompletionTool.builder().function(functionDef).build())\n",
    "\n",
    "\n",
    "val response = client.chat().completions().create(params.build())\n",
    "\n",
    "val aiMessage = response.choices().first().message()\n",
    "\n",
    "\"Response: $aiMessage\""
   ],
   "outputs": [
    {
     "data": {
      "text/plain": [
       "Response: ChatCompletionMessage{content=null, refusal=null, role=assistant, annotations=[], audio=, functionCall=, toolCalls=[ChatCompletionMessageToolCall{id=call_OjCBz1vP0J7BdY2ntTF8yILW, function=Function{arguments={\"location\":\"Berlin\"}, name=get_weather, additionalProperties={}}, type=function, additionalProperties={}}], additionalProperties={}}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "execution_count": 7
  },
  {
   "metadata": {
    "ExecuteTime": {
     "end_time": "2025-04-01T23:01:15.786948Z",
     "start_time": "2025-04-01T23:01:14.632713Z"
    }
   },
   "cell_type": "code",
   "source": [
    "import com.openai.core.jsonMapper\n",
    "import com.openai.models.chat.completions.ChatCompletionToolMessageParam\n",
    "import kotlin.jvm.optionals.getOrNull\n",
    "\n",
    "if (aiMessage.toolCalls().getOrNull()?.isNotEmpty() ?: false) {\n",
    "    val functionCall = aiMessage.toolCalls().get().first()\n",
    "    val functionName = functionCall.function().name()\n",
    "    val functionArgs = jsonMapper().readValue(functionCall.function().arguments(), Map::class.java)\n",
    "\n",
    "    println(\"The model wants to call a function: $functionName\")\n",
    "    println(\"With arguments: $functionArgs\")\n",
    "\n",
    "    if (functionName == \"get_weather\") {\n",
    "        val location = functionArgs[\"location\"] as? String ?: \"Unknown\"\n",
    "        val funResponse = getWeather(location)\n",
    "\n",
    "        val finalResponse = client.chat().completions().create(\n",
    "            params\n",
    "                .addMessage(aiMessage)\n",
    "                .addMessage(\n",
    "                    ChatCompletionToolMessageParam.builder()\n",
    "                        .toolCallId(functionCall.id())\n",
    "                        .content(funResponse.values.toString())\n",
    "                        .build()\n",
    "                )\n",
    "                .build()\n",
    "        )\n",
    "\n",
    "        println(\"Final answer:\")\n",
    "        println(finalResponse.choices().first().message().content().getOrNull())\n",
    "    }\n",
    "}"
   ],
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "The model wants to call a function: get_weather\n",
      "With arguments: {location=Berlin}\n",
      "Final answer:\n",
      "The weather in Berlin is currently 13°C and cloudy.\n"
     ]
    }
   ],
   "execution_count": 8
  }
 ],
 "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
}