### Install OpenAI Scala Stream Client Dependency (sbt)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-client-stream/README.md

Add this line to your `build.sbt` file to include the `openai-scala-client-stream` library, enabling streaming capabilities for the OpenAI client in Scala projects.

```Scala
"io.cequence" %% "openai-scala-client-stream" % "1.0.0"
```

--------------------------------

### Responses API: Image Input (Partial)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Initiates an example for using the Responses API with image input. The provided snippet is incomplete but shows the necessary imports for `Inputs`, `Input`, `InputMessageContent`, and `ChatRole`.

```Scala
  import io.cequence.openaiscala.domain.responsesapi.{Inputs, Input}
  import io.cequence.openaiscala.domain.responsesapi.InputMessageContent
  import io.cequence.openaiscala.domain.ChatRole

  service
```

--------------------------------

### Install OpenAI Scala Client with Streaming Support

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

For projects requiring streaming capabilities, use this specific dependency in your `build.sbt`. This provides an alternative to the standard client, enabling real-time data processing and interactions with OpenAI services.

```Scala (SBT)
"io.cequence" %% "openai-scala-client-stream" % "1.2.0"
```

--------------------------------

### Install OpenAI Scala Stream Client Dependency (Maven)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-client-stream/README.md

Add this XML snippet to your `pom.xml` file to include the `openai-scala-client-stream` library, providing streaming support for the OpenAI client in Maven-based projects.

```XML
<dependency>
    <groupId>io.cequence</groupId>
    <artifactId>openai-scala-client-stream_2.12</artifactId>
    <version>1.0.0</version>
</dependency>
```

--------------------------------

### Install OpenAI Scala Client Library

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This section provides instructions for adding the core OpenAI Scala client library to your project. It includes dependency configurations for both SBT and Maven build systems, supporting Scala versions 2.12, 2.13, and 3.

```Scala (SBT)
"io.cequence" %% "openai-scala-client" % "1.2.0"
```

```XML (Maven)
<dependency>
    <groupId>io.cequence</groupId>
    <artifactId>openai-scala-client_2.12</artifactId>
    <version>1.2.0</version>
</dependency>
```

--------------------------------

### Create Model Response with Web Search Tool (Scala)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates using `createModelResponse` with a `WebSearchTool` to allow the model to perform web searches. The example asks for a positive news story, configures the `WebSearchTool`, and then extracts and prints any URL citations from the model's output.

```scala
  service
    .createModelResponse(
      Inputs.Text("What was a positive news story from today?"),
      settings = CreateModelResponseSettings(
        model = ModelId.gpt_4o_2024_08_06,
        tools = Seq(WebSearchTool())
      )
    )
    .map { response =>
      println(response.outputText.getOrElse("N/A"))

      // citations
      val citations: Seq[Annotation.UrlCitation] = response.outputMessageContents.collect {
        case e: OutputText =>
          e.annotations.collect { case citation: Annotation.UrlCitation => citation }
      }.flatten

      println("Citations:")
      citations.foreach { citation =>
        println(s"${citation.title} - ${citation.url}")
      }
    }
```

--------------------------------

### List Available OpenAI Models

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Example of calling the `listModels` method on the `OpenAIService` instance to retrieve a list of available OpenAI models. The result is a `Future` which is then mapped to print each model's details to the console.

```scala
service.listModels.map(models =>
    models.foreach(println)
  )
```

--------------------------------

### Create Model Response with File Search Tool (Scala)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Illustrates how to integrate a `FileSearchTool` with `createModelResponse` to enable the model to search specified vector stores. The example queries for dragon attributes, configures the tool with a `vectorStoreId`, and extracts file citations from the model's response.

```scala
  service
    .createModelResponse(
      Inputs.Text("What are the attributes of an ancient brown dragon?"),
      settings = CreateModelResponseSettings(
        model = ModelId.gpt_4o_2024_08_06,
        tools = Seq(
          FileSearchTool(
            vectorStoreIds = Seq("vs_1234567890"),
            maxNumResults = Some(20),
            filters = None,
            rankingOptions = None
          )
        )
      )
    )
    .map { response =>
      println(response.outputText.getOrElse("N/A"))

      // citations
      val citations: Seq[Annotation.FileCitation] = response.outputMessageContents.collect {
        case e: OutputText =>
          e.annotations.collect { case citation: Annotation.FileCitation => citation }
      }.flatten

      println("Citations:")
      citations.foreach { citation =>
        println(s"${citation.fileId} - ${citation.filename}")
      }
    }
```

--------------------------------

### Install OpenAI Scala Client Dependency

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-client/README.md

Instructions for adding the OpenAI Scala Client library as a dependency to your Scala project. This library provides the WS client implementation for interacting with OpenAI services. It supports Scala versions 2.12, 2.13, and 3.

```sbt
"io.cequence" %% "openai-scala-client" % "1.0.0"
```

```Maven XML
<dependency>
    <groupId>io.cequence</groupId>
    <artifactId>openai-scala-client_2.12</artifactId>
    <version>1.0.0</version>
</dependency>
```

--------------------------------

### Create Model Response with Image Input (Scala)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates how to use the `createModelResponse` method to send an image as part of the input message content to an OpenAI model. The example constructs an `InputMessageContent.Image` with a URL and prints the model's text output.

```scala
.createModelResponse(
      Inputs.Items(
        Input.ofInputMessage(
          Seq(
            InputMessageContent.Text("what is in this image?"),
            InputMessageContent.Image(
              imageUrl = Some(
                "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
              )
            )
          ),
          role = ChatRole.User
        )
      )
    )
    .map { response =>
      println(response.outputText.getOrElse("N/A"))
    }
```

--------------------------------

### Create Model Response with Function Call Tool (Scala)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Illustrates how to define and use a `FunctionTool` with `createModelResponse` to enable the model to call external functions. The example defines a `get_current_weather` function, sets `toolChoice` to auto, and then parses and prints the details of the function call made by the model.

```scala
  service
    .createModelResponse(
      Inputs.Text("What is the weather like in Boston today?"),
      settings = CreateModelResponseSettings(
        model = ModelId.gpt_4o_2024_08_06,
        tools = Seq(
          FunctionTool(
            name = "get_current_weather",
            parameters = JsonSchema.Object(
              properties = Map(
                "location" -> JsonSchema.String(
                  description = Some("The city and state, e.g. San Francisco, CA")
                ),
                "unit" -> JsonSchema.String(
                  `enum` = Seq("celsius", "fahrenheit")
                )
              ),
              required = Seq("location", "unit")
            ),
            description = Some("Get the current weather in a given location"),
            strict = true
          )
        ),
        toolChoice = Some(ToolChoice.Mode.Auto)
      )
    )
    .map { response =>
      val functionCall = response.outputFunctionCalls.headOption
        .getOrElse(throw new RuntimeException("No function call output found"))

      println(
        s"""Function Call Details:\n           |Name: ${functionCall.name}\n           |Arguments: ${functionCall.arguments}\n           |Call ID: ${functionCall.callId}\n           |ID: ${functionCall.id}\n           |Status: ${functionCall.status}""".stripMargin
      )

      val toolsUsed = response.tools.map(_.typeString)

      println(s"${toolsUsed.size} tools used: ${toolsUsed.mkString(", ")}")
    }
```

--------------------------------

### Implement Round Robin Load Distribution for OpenAI Services in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This example shows how to configure a round-robin load distribution adapter for OpenAI services. It initializes two separate `OpenAIService` instances and then uses `OpenAIServiceAdapters.forFullService.roundRobin` to distribute requests evenly between them, enhancing scalability and reliability.

```Scala
  val adapters = OpenAIServiceAdapters.forFullService

  val service1 = OpenAIServiceFactory("your-api-key1")
  val service2 = OpenAIServiceFactory("your-api-key2")

  val service = adapters.roundRobin(service1, service2)
```

--------------------------------

### Initialize OpenAI Chat Completion Service with Custom URL

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates how to initialize an `OpenAIChatCompletionServiceFactory` instance, specifying a custom `coreUrl` for the service endpoint. This setup is for a non-streaming chat completion service, often used for local LLM instances like Ollama.

```scala
val service = OpenAIChatCompletionServiceFactory.withStreaming(
    coreUrl = "http://localhost:11434/v1/"
  )
```

--------------------------------

### Add Logging to OpenAI Service Calls in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This example demonstrates how to integrate logging into OpenAI service calls using an adapter. It wraps a raw `OpenAIService` with `OpenAIServiceAdapters.forFullService.log`, allowing for custom logging of service interactions, which is useful for monitoring and debugging.

```Scala
  val adapters = OpenAIServiceAdapters.forFullService

  val rawService = OpenAIServiceFactory()
  
  val service = adapters.log(
    rawService,
    "openAIService",
    logger.log
  )
```

--------------------------------

### Count OpenAI Chat Completion Message Tokens in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-count-tokens/README.md

This Scala example demonstrates how to use the OpenAICountTokensHelper to estimate the token count for a sequence of OpenAI chat messages. It initializes a model and a list of various message types (System, User, Assistant), then calls the countMessageTokens method to get the estimated token usage.

```Scala
import io.cequence.openaiscala.domain.{AssistantMessage, BaseMessage, FunctionSpec, ModelId, SystemMessage, UserMessage}

class MyCompletionService extends OpenAICountTokensHelper {
  def exec = {
    val model = ModelId.gpt_4_turbo_2024_04_09

    // messages to be sent to OpenAI
    val messages: Seq[BaseMessage] = Seq(
      SystemMessage("You are a helpful assistant."),
      UserMessage("Who won the world series in 2020?"),
      AssistantMessage("The Los Angeles Dodgers won the World Series in 2020."),
      UserMessage("Where was it played?"),
    )

    val tokenCount = countMessageTokens(model, messages)
  }
}
```

--------------------------------

### Create Chat Completion with JSON/Structured Output

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates how to instruct the chat model to return responses in a specific JSON format. It involves defining a `JsonSchema` for the desired output structure and providing system and user messages to guide the model's generation.

```scala
val messages = Seq(
    SystemMessage("Give me the most populous capital cities in JSON format."),
    UserMessage("List only african countries")
  )

  val capitalsSchema = JsonSchema.Object(
    properties = Map(
      "countries" -> JsonSchema.Array(
        items = JsonSchema.Object(
          properties = Map(
            "country" -> JsonSchema.String(
              description = Some("The name of the country")
            ),
            "capital" -> JsonSchema.String(
```

--------------------------------

### Count Message Tokens for OpenAI Chat Completions (Scala)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Provides an example of how to count the expected number of tokens for a sequence of chat messages before making an OpenAI API call. This helps in model selection and cost management. Requires the `openai-scala-count-tokens` library.

```scala
import io.cequence.openaiscala.service.OpenAICountTokensHelper
import io.cequence.openaiscala.domain.{AssistantMessage, BaseMessage, FunctionSpec, ModelId, SystemMessage, UserMessage}

class MyCompletionService extends OpenAICountTokensHelper {
  def exec = {
    val model = ModelId.gpt_4_turbo_2024_04_09

    // messages to be sent to OpenAI
    val messages: Seq[BaseMessage] = Seq(
      SystemMessage("You are a helpful assistant."),
      UserMessage("Who won the world series in 2020?"),
      AssistantMessage("The Los Angeles Dodgers won the World Series in 2020."),
      UserMessage("Where was it played?"),
    )

    val tokenCount = countMessageTokens(model, messages)
  }
}
```

--------------------------------

### Adapt Chat Completion to Core Completion Service in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This example demonstrates how to use a `chatToCompletion` adapter to convert chat completion requests into a format compatible with a core completion service. This is useful when interacting with APIs that primarily support chat completions but need to be adapted for a core completion interface, such as Fireworks AI.

```Scala
    val adapters = OpenAIServiceAdapters.forCoreService

    val service = adapters.chatToCompletion(
      OpenAICoreServiceFactory(
        coreUrl = "https://api.fireworks.ai/inference/v1/",
        authHeaders = Seq(("Authorization", s"Bearer ${sys.env("FIREWORKS_API_KEY")}"))
      )
    )
```

--------------------------------

### Chat Completion with Failover and JSON Schema Response

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Combines model failover with structured JSON output. This example uses `createChatCompletionWithJSON` along with failover models, `maxRetries`, and `retryOnAnyError` to ensure a robust JSON response even if the primary model encounters issues.

```Scala
  import io.cequence.openaiscala.service.OpenAIChatCompletionExtra._

  val capitalsSchema = JsonSchema.Object(
    properties = Map(
      "countries" -> JsonSchema.Array(
        items = JsonSchema.Object(
          properties = Map(
            "country" -> JsonSchema.String(
              description = Some("The name of the country")
            ),
            "capital" -> JsonSchema.String(
              description = Some("The capital city of the country")
            )
          ),
          required = Seq("country", "capital")
        )
      )
    ),
    required = Seq("countries")
  )

  val jsonSchemaDef = JsonSchemaDef(
    name = "capitals_response",
    strict = true,
    structure = capitalsSchema
  )

  // Define the chat messages
  val messages = Seq(
    SystemMessage("Give me the most populous capital cities in JSON format."),
    UserMessage("List only african countries")
  )

  // Call the service with failover support
  service
    .createChatCompletionWithJSON[JsObject](
      messages = messages,
      settings = CreateChatCompletionSettings(
        model = ModelId.o3_mini, // Primary model
        max_tokens = Some(1000),
        response_format_type = Some(ChatCompletionResponseFormatType.json_schema),
        jsonSchema = Some(jsonSchemaDef)
      ),
      failoverModels = Seq(
        ModelId.gpt_4_5_preview,  // First fallback model
        ModelId.gpt_4o            // Second fallback model
      ),
      maxRetries = Some(3),       // Maximum number of retries per model
      retryOnAnyError = true,     // Retry on any error, not just retryable ones
      taskNameForLogging = Some("capitals-query") // For better logging
    )
    .map { json =>
      println(Json.prettyPrint(json))
    }
```

--------------------------------

### Count Tokens for OpenAI Chat Completion with Functions in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This snippet demonstrates how to calculate the token count for a list of messages and a function specification using the `OpenAICountTokensHelper`. It defines a `SystemMessage`, a `UserMessage`, and a `FunctionSpec` for `getWeather` with `location` and `unit` parameters, then uses `countFunMessageTokens` to get the total token count.

```Scala
import io.cequence.openaiscala.domain.{BaseMessage, FunctionSpec, ModelId, SystemMessage, UserMessage}

class MyCompletionService extends OpenAICountTokensHelper {
  def exec = {
    val model = ModelId.gpt_4_turbo_2024_04_09
    
    // messages to be sent to OpenAI
    val messages: Seq[BaseMessage] = 
     Seq(
       SystemMessage("You are a helpful assistant."),
       UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?")
     )
     
    // function to be called
    val function: FunctionSpec = FunctionSpec(
      name = "getWeather",
      parameters = Map(
        "type" -> "object",
        "properties" -> Map(
          "location" -> Map(
            "type" -> "string",
            "description" -> "The city to get the weather for"
          ),
          "unit" -> Map("type" -> "string", "enum" -> List("celsius", "fahrenheit"))
        )
      )
    )

    val tokenCount = countFunMessageTokens(model, messages, Seq(function), Some(function.name))
  }
}
```

--------------------------------

### Implement Retries for Specific OpenAI Service Functions in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This example demonstrates how to apply a retry mechanism directly to a specific function call within an OpenAI service using `RetryHelpers`. It defines a `MyCompletionService` that extends `RetryHelpers`, configures `RetrySettings`, and then uses `.retryOnFailure` on the `createChatCompletion` call to automatically retry on failures.

```Scala
class MyCompletionService @Inject() (
  val actorSystem: ActorSystem,
  implicit val ec: ExecutionContext,
  implicit val scheduler: Scheduler
)(val apiKey: String)
  extends RetryHelpers {
  val service: OpenAIService = OpenAIServiceFactory(apiKey)
  implicit val retrySettings: RetrySettings =
    RetrySettings(interval = 10.seconds)

  def ask(prompt: String): Future[String] =
    for {
      completion <- service
        .createChatCompletion(
          List(MessageSpec(ChatRole.User, prompt))
        )
        .retryOnFailure
    } yield completion.choices.head.message.content
}
```

--------------------------------

### Initialize OpenAI Service with Streaming Support

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Shows how to create an `OpenAIService` instance with streaming capabilities. This requires importing `OpenAIStreamedService` and its implicits, and uses the `withStreaming()` factory method for general OpenAI API interactions.

```scala
import io.cequence.openaiscala.service.StreamedServiceTypes.OpenAIStreamedService
  import io.cequence.openaiscala.service.OpenAIStreamedServiceImplicits._

  val service: OpenAIStreamedService = OpenAIServiceFactory.withStreaming()
```

--------------------------------

### Obtain OpenAIService with Custom Configuration in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIService` by loading a custom configuration file. This approach allows for flexible management of API keys and other settings from a specified path.

```Scala
  val config = ConfigFactory.load("path_to_my_custom_config")
  val service = OpenAIServiceFactory(config)
```

--------------------------------

### Obtain OpenAIService with Default Configuration in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIService` using default configuration settings. This method relies on environment variables being set as defined in the library's `Config` section.

```Scala
  val service = OpenAIServiceFactory()
```

--------------------------------

### Initialize OpenAI Chat Completion Service with Streaming and Custom Authentication

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Illustrates initializing a streaming chat completion service, configuring a custom `coreUrl` and providing authentication headers, such as an API key from environment variables, for third-party services like Fireworks.ai.

```scala
import io.cequence.openaiscala.service.OpenAIStreamedServiceImplicits._

  val service = OpenAIChatCompletionServiceFactory.withStreaming(
    coreUrl = "https://api.fireworks.ai/inference/v1/",
    authHeaders = Seq(("Authorization", s"Bearer ${sys.env("FIREWORKS_API_KEY")}"))
  )
```

--------------------------------

### Run Tests for OpenAI Scala Client with sbt

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-count-tokens/README.md

To execute the test suite for the OpenAI Scala client, use this sbt command in your terminal. This runs all defined tests within the project, helping to validate functionality and debug token count mismatches.

```Bash
sbt test
```

--------------------------------

### Obtain OpenAIChatCompletionService for Groq AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Groq AI. This requires the `GROQ_API_KEY` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.groq)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.groq)
```

--------------------------------

### Create OpenAI Chat Completion

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Illustrates how to create a chat completion using the `createChatCompletion` method. It involves defining `CreateChatCompletionSettings` (e.g., model) and a sequence of `ChatMessage` objects (System, User, Assistant). The response's content head is then printed.

```scala
val createChatCompletionSettings = CreateChatCompletionSettings(
    model = ModelId.gpt_4o
  )

  val messages = Seq(
    SystemMessage("You are a helpful assistant."),
    UserMessage("Who won the world series in 2020?"),
    AssistantMessage("The Los Angeles Dodgers won the World Series in 2020."),
    UserMessage("Where was it played?"),
  )

  service.createChatCompletion(
    messages = messages,
    settings = createChatCompletionSettings
  ).map { chatCompletion =>
    println(chatCompletion.contentHead)
  }
```

--------------------------------

### Obtain OpenAIChatCompletionService for Google Gemini in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Google Gemini. This requires the `openai-scala-google-gemini-client` library and the `GOOGLE_API_KEY` environment variable.

```Scala
  val service = GeminiServiceFactory.asOpenAI()
```

--------------------------------

### Obtain OpenAIChatCompletionService for Google Vertex AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Google Vertex AI. This requires the `openai-scala-google-vertexai-client` library and environment variables for `VERTEXAI_LOCATION` and `VERTEXAI_PROJECT_ID`.

```Scala
  val service = VertexAIServiceFactory.asOpenAI()
```

--------------------------------

### Obtain OpenAIChatCompletionService for Novita AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Novita AI. This requires the `NOVITA_API_KEY` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.novita)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.novita)
```

--------------------------------

### Initialize Dedicated Streaming Chat Completion Service

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates direct initialization of `OpenAIChatCompletionStreamedServiceExtra` for scenarios where only streaming is required. It allows specifying a custom `coreUrl` and authentication headers, providing fine-grained control over the streaming client.

```scala
val service: OpenAIChatCompletionStreamedServiceExtra =
    OpenAIChatCompletionStreamedServiceFactory(
      coreUrl = "https://api.fireworks.ai/inference/v1/",
      authHeaders = Seq(("Authorization", s"Bearer ${sys.env("FIREWORKS_API_KEY")}"))
   )
```

--------------------------------

### Responses API: Basic Textual Input

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates the basic usage of the `createModelResponse` method from the Responses API with a simple textual input. It sends a single text query and prints the `outputText` from the response.

```Scala
  import io.cequence.openaiscala.domain.responsesapi.Inputs

  service
    .createModelResponse(
      Inputs.Text("What is the capital of France?")
    )
    .map { response =>
      println(response.outputText.getOrElse("N/A"))
    }
```

--------------------------------

### Obtain OpenAIChatCompletionService for TogetherAI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for TogetherAI. This requires the `TOGETHERAI_API_KEY` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.togetherAI)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.togetherAI)
```

--------------------------------

### Obtain OpenAIChatCompletionService for Grok AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Grok AI. This requires the `GROK_API_KEY` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.grok)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.grok)
```

--------------------------------

### Obtain OpenAIChatCompletionService for Perplexity Sonar in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Perplexity Sonar models. This requires the `openai-scala-perplexity-client` library and the `SONAR_API_KEY` environment variable.

```Scala
  val service = SonarServiceFactory.asOpenAI()
```

--------------------------------

### Configure OpenAI Scala Client via Environment Variables or File

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

The OpenAI Scala client supports flexible configuration methods. You can set API keys and organization IDs using environment variables, or rely on a default configuration file for more complex settings. Environment variables take precedence over file configurations.

```APIDOC (Environment Variables)
OPENAI_SCALA_CLIENT_API_KEY: Your OpenAI API key
OPENAI_SCALA_CLIENT_ORG_ID: (Optional) Your OpenAI organization ID
```

```APIDOC (File Configuration)
Default configuration file: openai-scala-client.conf (located at ./openai-client/src/main/resources/openai-scala-client.conf)
```

--------------------------------

### Responses API: Multiple Textual Inputs with Roles

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Shows how to use the Responses API `createModelResponse` with multiple textual inputs, specifying different roles (System and User messages). This allows for more complex conversational prompts.

```Scala
  import io.cequence.openaiscala.domain.responsesapi.Input

  service
    .createModelResponse(
      Inputs.Items(
        Input.ofInputSystemTextMessage(
          "You are a helpful assistant. Be verbose and detailed and don't be afraid to use emojis."
        ),
        Input.ofInputUserTextMessage("What is the capital of France?")
      )
    )
    .map { response =>
      println(response.outputText.getOrElse("N/A"))
    }
```

--------------------------------

### Create Chat Completion with Function/Tool Calling

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Shows how to use the `createChatToolCompletion` method to enable the model to call external functions. It defines `FunctionSpec` with parameters and demonstrates how to process the `tool_calls` from the model's response, extracting tool IDs, names, and arguments for subsequent execution.

```scala
val messages = Seq(
    SystemMessage("You are a helpful assistant."),
    UserMessage("What's the weather like in San Francisco, Tokyo, and Paris?")
  )

  // as a param type we can use "number", "string", "boolean", "object", "array", and "null"
  val tools = Seq(
    FunctionSpec(
      name = "get_current_weather",
      description = Some("Get the current weather in a given location"),
      parameters = Map(
        "type" -> "object",
        "properties" -> Map(
          "location" -> Map(
            "type" -> "string",
            "description" -> "The city and state, e.g. San Francisco, CA"
          ),
          "unit" -> Map(
            "type" -> "string",
            "enum" -> Seq("celsius", "fahrenheit")
          )
        ),
        "required" -> Seq("location")
      )
    )
  )

  // if we want to force the model to use the above function as a response
  // we can do so by passing: responseToolChoice = Some("get_current_weather")`
  service.createChatToolCompletion(
    messages = messages,
    tools = tools,
    responseToolChoice = None, // means "auto"
    settings = CreateChatCompletionSettings(ModelId.gpt_4o)
  ).map { response =>
    val chatFunCompletionMessage = response.choices.head.message
    val toolCalls = chatFunCompletionMessage.tool_calls.collect {
      case (id, x: FunctionCallSpec) => (id, x)
    }

    println(
      "tool call ids                : " + toolCalls.map(_._1).mkString(", ")
    )
    println(
      "function/tool call names     : " + toolCalls.map(_._2.name).mkString(", ")
    )
    println(
      "function/tool call arguments : " + toolCalls.map(_._2.arguments).mkString(", ")
    )
  }
```

--------------------------------

### Obtain OpenAIChatCompletionService for Mistral AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Mistral AI. This requires the `MISTRAL_API_KEY` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.mistral)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.mistral)
```

--------------------------------

### Inject OpenAI Service using Guice

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Shows how to inject an `OpenAIService` instance into a class using Guice for dependency injection. This approach requires the `openai-scala-guice` library and the `@Inject()` annotation for automatic service provision.

```scala
class MyClass @Inject() (openAIService: OpenAIService) {...}
```

--------------------------------

### Obtain Minimal OpenAICoreService for FastChat in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate a minimal `OpenAICoreService` that supports core functionalities like `listModels`, `createCompletion`, `createChatCompletion`, and `createEmbeddings`. This is ideal for connecting to compatible services like FastChat running on a local endpoint.

```Scala
  val service = OpenAICoreServiceFactory("http://localhost:8000/v1/")
```

--------------------------------

### Obtain OpenAIChatCompletionService for Ollama in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Ollama, connecting to a local Ollama instance. This allows interaction with locally hosted models.

```Scala
  val service = OpenAIChatCompletionServiceFactory(
    coreUrl = "http://localhost:11434/v1/"
  )
```

--------------------------------

### Obtain OpenAIChatCompletionService for Anthropic in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Anthropic models. This requires the `openai-scala-anthropic-client` library and the `ANTHROPIC_API_KEY` environment variable for authentication.

```Scala
  val service = AnthropicServiceFactory.asOpenAI() // or AnthropicServiceFactory.bedrockAsOpenAI
```

--------------------------------

### Obtain OpenAIChatCompletionService for Fireworks AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Fireworks AI. This requires the `FIREWORKS_API_KEY` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.fireworks)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.fireworks)
```

--------------------------------

### Obtain OpenAIService for Azure with API Key in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIService` specifically for Azure OpenAI deployments. This requires specifying the Azure resource name, deployment ID (typically the model name), API version, and your Azure API key.

```Scala
  val service = OpenAIServiceFactory.forAzureWithApiKey(
    resourceName = "your-resource-name",
    deploymentId = "your-deployment-id", // usually model name such as "gpt-35-turbo"
    apiVersion = "2023-05-15",           // newest version
    apiKey = "your_api_key"
  )
```

--------------------------------

### Add OpenAI Scala Guice dependency to Maven pom.xml

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-guice/README.md

This snippet demonstrates how to include the `openai-scala-guice` library as a dependency in a Maven `pom.xml` file. This module facilitates Guice-based dependency injection for the OpenAI Scala client in Maven projects.

```Maven
<dependency>
    <groupId>io.cequence</groupId>
    <artifactId>openai-scala-guice_2.12</artifactId>
    <version>1.0.0</version>
</dependency>
```

--------------------------------

### Obtain OpenAIChatCompletionService for Octo AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Octo AI. This requires the `OCTOAI_TOKEN` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.octoML)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.octoML)
```

--------------------------------

### Obtain OpenAIChatCompletionService for Azure AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Azure AI, supporting models like Cohere R+. This requires environment variables for the endpoint, region, and access token.

```Scala
  val service = OpenAIChatCompletionServiceFactory.forAzureAI(
    endpoint = sys.env("AZURE_AI_COHERE_R_PLUS_ENDPOINT"),
    region = sys.env("AZURE_AI_COHERE_R_PLUS_REGION"),
    accessToken = sys.env("AZURE_AI_COHERE_R_PLUS_ACCESS_KEY")
  )
```

--------------------------------

### Add OpenAI Scala Guice dependency to sbt

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-guice/README.md

This snippet shows how to add the `openai-scala-guice` library as a dependency in a Scala sbt build file. This module provides Guice-based dependency injection for the OpenAI Scala client.

```Scala
"io.cequence" %% "openai-scala-guice" % "1.0.0"
```

--------------------------------

### LLM Provider Compatibility Matrix

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Provides a compatibility overview for various Large Language Model (LLM) providers supported by the library, detailing their capabilities regarding JSON/Structured Output and Tools support. This library implements adapters for providers not natively compatible with the chat completion API.

```APIDOC
Provider       | JSON/Structured Output | Tools Support          | Description
---------------|------------------------|------------------------|------------------------
OpenAI         | Full                   | Standard + Responses API | Full API support
Azure OpenAI   | Full                   | Standard + Responses API | OpenAI on Azure
Anthropic      | Implied                |                        | Claude models
Azure AI       | Varies                 |                        | Open-source models
Cerebras       | Only JSON object mode  |                        | Fast inference
Deepseek       | Only JSON object mode  |                        | Chinese provider
FastChat       | Varies                 |                        | Local LLMs
```

--------------------------------

### Obtain OpenAIChatCompletionService for Cerebras AI in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIChatCompletionService` for Cerebras AI. This requires the `CEREBRAS_API_KEY` environment variable. Both standard and streaming service instances can be obtained.

```Scala
  val service = OpenAIChatCompletionServiceFactory(ChatProviderSettings.cerebras)
  // or with streaming
  val service = OpenAIChatCompletionServiceFactory.withStreaming(ChatProviderSettings.cerebras)
```

--------------------------------

### Implement Random Order Load Distribution for OpenAI Services in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This snippet illustrates how to set up a random order load distribution adapter for OpenAI services. Similar to round-robin, it uses `OpenAIServiceAdapters.forFullService.randomOrder` to distribute requests randomly among multiple service instances, providing another strategy for load balancing.

```Scala
  val adapters = OpenAIServiceAdapters.forFullService

  val service1 = OpenAIServiceFactory("your-api-key1")
  val service2 = OpenAIServiceFactory("your-api-key2")

  val service = adapters.randomOrder(service1, service2)
```

--------------------------------

### Supported AI Providers and Feature Compatibility

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This section details the compatibility and specific features offered by various AI providers when integrated with the OpenAI Scala client. It outlines support for JSON object mode, streaming capabilities, and provides additional notes for each listed provider.

```APIDOC (Provider Matrix)
Fireworks AI: Only JSON object mode, Cloud provider
Google Gemini: Full support, Yes (streaming), Google's models
Google Vertex AI: Full support, Yes (streaming), Gemini models
Grok: Full support, x.AI models
Groq: Only JSON object mode, Fast inference
Mistral: Only JSON object mode, Open-source leader
Novita: Only JSON object mode, Cloud provider
Octo AI: Only JSON object mode, Cloud provider (obsolete)
Ollama: Varies, Local LLMs
Perplexity Sonar: Only implied, Search-based AI
TogetherAI: Only JSON object mode, Cloud provider
```

--------------------------------

### OpenAI Scala Client Supported API Endpoints

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This section outlines the various OpenAI API endpoints supported by the Scala client, categorized by their functionality. It covers models, completions, chat completions, image generation, embeddings, audio processing, file management, fine-tuning, moderations, and the newer Assistants and Threads APIs.

```APIDOC
OpenAIService API Endpoints:

Models:
  - listModels
  - retrieveModel

Completions:
  - createCompletion

Chat Completions:
  - createChatCompletion
  - createChatFunCompletion (deprecated)
  - createChatToolCompletion

Edits:
  - createEdit (deprecated)

Images:
  - createImage
  - createImageEdit
  - createImageVariation

Embeddings:
  - createEmbeddings

Batches:
  - createBatch
  - retrieveBatch
  - cancelBatch
  - listBatches

Audio:
  - createAudioTranscription
  - createAudioTranslation
  - createAudioSpeech

Files:
  - listFiles
  - uploadFile
  - deleteFile
  - retrieveFile
  - retrieveFileContent

Fine-tunes:
  - createFineTune
  - listFineTunes
  - retrieveFineTune
  - cancelFineTune
  - listFineTuneEvents
  - listFineTuneCheckpoints
  - deleteFineTuneModel

Moderations:
  - createModeration

Assistants:
  - createAssistant
  - listAssistants
  - retrieveAssistant
  - modifyAssistant
  - deleteAssistant

Threads:
  - createThread
  - retrieveThread
  - modifyThread
  - deleteThread
```

--------------------------------

### Configure Akka Execution Context and Materializer in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Before initializing an OpenAI service, an implicit `ExecutionContext` and Akka `Materializer` are required. This snippet demonstrates how to define these prerequisites globally for use with the service factories.

```Scala
  implicit val ec = ExecutionContext.global
  implicit val materializer = Materializer(ActorSystem())
```

--------------------------------

### Add OpenAI Scala Count Tokens Dependency to sbt

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-count-tokens/README.md

To integrate the OpenAI Scala client library into your project using sbt, add this dependency line to your build.sbt file. This makes the token counting functionality available for use in your Scala application.

```Scala
"io.cequence" %% "openai-scala-count-tokens" % "1.2.0"
```

--------------------------------

### Chat Completion with Model Failover

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Shows how to implement model failover using `createChatCompletionWithFailover`. If the primary model (`o3_mini`) fails, the client attempts to use fallback models (`gpt_4_5_preview`, `gpt_4o`). The `retryOnAnyError` flag ensures retries for all error types.

```Scala
  import io.cequence.openaiscala.service.OpenAIChatCompletionExtra._

  val messages = Seq(
    SystemMessage("You are a helpful weather assistant."),
    UserMessage("What is the weather like in Norway?")
  )

  service
    .createChatCompletionWithFailover(
      messages = messages,
      settings = CreateChatCompletionSettings(
        model = ModelId.o3_mini
      ),
      failoverModels = Seq(ModelId.gpt_4_5_preview, ModelId.gpt_4o),
      retryOnAnyError = true,
      failureMessage = "Weather assistant failed to provide a response."
    )
    .map { response =>
      print(response.contentHead)
    }
```

--------------------------------

### Add OpenAI Scala Count Tokens Dependency to Maven

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-count-tokens/README.md

For Maven-managed projects, include this dependency block within your pom.xml file to pull the OpenAI Scala client library. This ensures the token counting module is available for your Java or Scala project.

```XML
<dependency>
    <groupId>io.cequence</groupId>
    <artifactId>openai-scala-count-tokens_2.12</artifactId>
    <version>1.2.0</version>
</dependency>
```

--------------------------------

### Obtain OpenAIService with Direct API Key and Org ID in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Instantiate `OpenAIService` by directly providing the API key and an optional organization ID. This method is suitable for direct credential injection without external configuration files.

```Scala
  val service = OpenAIServiceFactory(
     apiKey = "your_api_key",
     orgId = Some("your_org_id") // if you have one
  )
```

--------------------------------

### Create Chat Completion with JSON Schema Response (Manual Parsing)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates how to configure a chat completion request to return a JSON object conforming to a specified `JsonSchemaDef`. The response content is then manually parsed as JSON using `Json.parse` and pretty-printed.

```Scala
              description = Some("The capital city of the country")
            )
          ),
          required = Seq("country", "capital")
        )
      )
    ),
    required = Seq("countries")
  )

  val jsonSchemaDef = JsonSchemaDef(
    name = "capitals_response",
    strict = true,
    structure = capitalsSchema
  )

  service
    .createChatCompletion(
      messages = messages,
      settings = CreateChatCompletionSettings(
        model = ModelId.o3_mini,
        max_tokens = Some(1000),
        response_format_type = Some(ChatCompletionResponseFormatType.json_schema),
        jsonSchema = Some(jsonSchemaDef)
      )
    )
    .map { response =>
      val json = Json.parse(response.contentHead)
      println(Json.prettyPrint(json))
    }
```

--------------------------------

### Add OpenAI Scala Core Dependency to SBT

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-core/README.md

This snippet shows how to add the `openai-scala-core` library as a dependency to your Scala project using `build.sbt`. It specifies the group ID, artifact ID, and version required for the library.

```Scala
"io.cequence" %% "openai-scala-core" % "1.1.1"
```

--------------------------------

### Add OpenAI Scala Core Dependency to Maven POM

Source: https://github.com/cequence-io/openai-scala-client/blob/master/openai-core/README.md

This snippet demonstrates how to include the `openai-scala-core` library as a dependency in a Maven project's `pom.xml` file. It defines the `groupId`, `artifactId`, and `version` for the dependency, targeting Scala 2.12.

```XML
<dependency>
    <groupId>io.cequence</groupId>
    <artifactId>openai-scala-core_2.12</artifactId>
    <version>1.1.1</version>
</dependency>
```

--------------------------------

### Configure Timeout Settings for OpenAI Scala Client

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This configuration snippet demonstrates how to adjust various timeout settings for the OpenAI Scala Client. It includes request, read, connect, and pooled connection idle timeouts, which can be set either programmatically via `OpenAIServiceFactory` or by adding this block to a configuration file.

```HOCON
openai-scala-client {
    timeouts {
        requestTimeoutSec = 200
        readTimeoutSec = 200
        connectTimeoutSec = 5
        pooledConnectionIdleTimeoutSec = 60
    }
}
```

--------------------------------

### OpenAI API Endpoint Reference

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Lists various categories of OpenAI API endpoints supported by the Scala client, including Thread Messages, Runs, Vector Stores, and Responses, with their respective operations. The service function names in the library are designed to match OpenAI API endpoint titles/descriptions in camelCase for consistency.

```APIDOC
Thread Messages:
  - createThreadMessage
  - retrieveThreadMessage
  - modifyThreadMessage
  - listThreadMessages
  - retrieveThreadMessageFile
  - listThreadMessageFiles
Runs:
  - createRun
  - createThreadAndRun
  - listRuns
  - retrieveRun
  - modifyRun
  - submitToolOutputs
  - cancelRun
Run Steps:
  - listRunSteps
  - retrieveRunStep
Vector Stores:
  - createVectorStore
  - listVectorStores
  - retrieveVectorStore
  - modifyVectorStore
  - deleteVectorStore
Vector Store Files:
  - createVectorStoreFile
  - listVectorStoreFiles
  - retrieveVectorStoreFile
  - deleteVectorStoreFile
Vector Store File Batches:
  - createVectorStoreFileBatch
  - retrieveVectorStoreFileBatch
  - cancelVectorStoreFileBatch
  - listVectorStoreBatchFiles
Responses:
  - createModelResponse
  - getModelResponse
  - deleteModelResponse
  - listModelResponseInputItems
```

--------------------------------

### Create Chat Completion with JSON/Structured Output (Implicit Function)

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Illustrates using the `createChatCompletionWithJSON[T]` implicit function from `OpenAIChatCompletionExtra` to simplify JSON response handling. This function automatically extracts, potentially repairs, and deserializes the JSON response into a specified Scala object type (here, `JsObject`).

```Scala
  import io.cequence.openaiscala.service.OpenAIChatCompletionExtra._

  ...

  service
    .createChatCompletionWithJSON[JsObject](
      messages = messages,
      settings = CreateChatCompletionSettings(
        model = ModelId.o3_mini,
        max_tokens = Some(1000),
        response_format_type = Some(ChatCompletionResponseFormatType.json_schema),
        jsonSchema = Some(jsonSchemaDef)
      )
    )
    .map { json =>
      println(Json.prettyPrint(json))
    }
```

--------------------------------

### Route OpenAI Chat Completion Calls by Model to Different Services in Scala

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

This snippet illustrates how to route chat completion requests to different OpenAI-compatible services (e.g., OctoAI, Anthropic, OpenAI) based on the requested model ID. It configures `OpenAIChatCompletionServiceFactory` instances for various providers and uses `OpenAIServiceAdapters.forFullService.chatCompletionRouter` to direct calls to the appropriate backend service.

```Scala
  val adapters = OpenAIServiceAdapters.forFullService

  // OctoAI
  val octoMLService = OpenAIChatCompletionServiceFactory(
    coreUrl = "https://text.octoai.run/v1/",
    authHeaders = Seq(("Authorization", s"Bearer ${sys.env("OCTOAI_TOKEN")}"))
  )

  // Anthropic
  val anthropicService = AnthropicServiceFactory.asOpenAI()

  // OpenAI
  val openAIService = OpenAIServiceFactory()

  val service: OpenAIService =
    adapters.chatCompletionRouter(
      // OpenAI service is default so no need to specify its models here
      serviceModels = Map(
        octoMLService -> Seq(NonOpenAIModelId.mixtral_8x22b_instruct),
        anthropicService -> Seq(
          NonOpenAIModelId.claude_2_1,
          NonOpenAIModelId.claude_3_opus_20240229,
          NonOpenAIModelId.claude_3_haiku_20240307
        )
      ),
      openAIService
    )
```

--------------------------------

### Retrieve Specific OpenAI Model Details

Source: https://github.com/cequence-io/openai-scala-client/blob/master/README.md

Demonstrates how to retrieve details for a specific OpenAI model using its `ModelId`. The `retrieveModel` method returns a `Future[Option[Model]]`, which is then processed to print the model details or 'N/A' if the model is not found.

```scala
service.retrieveModel(ModelId.text_davinci_003).map(model =>
    println(model.getOrElse("N/A"))
  )
```