> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ruby AI SDK reference

> This topic documents how to get started with the Ruby AI SDK, and links to reference information on all of the supported features.

> For the complete documentation index, see [llms.txt](/llms.txt). For the full documentation snapshot, see [llms-full.txt](/llms-full.txt).

## Overview

This topic documents how to get started with the Ruby AI SDK, and links to reference information on all of the supported features.

The Ruby AI SDK is designed for use with LaunchDarkly's AI Configs. It is in a pre-1.0 release and the API may change based on feedback. Active feature development is ongoing in the [Python](/sdk/ai/python) and [Node.js](/sdk/ai/node-js) AI SDKs, so this SDK receives new features at a slower pace. You can follow development or contribute on [GitHub](https://github.com/launchdarkly/ruby-server-sdk-ai).

<Note title="SDK quick links">
  LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:
</Note>

| Resource | Location |
| - | - |
| SDK API documentation | [SDK API docs](https://launchdarkly.github.io/ruby-server-sdk-ai/) |
| GitHub repository | [ruby-server-sdk-ai](https://github.com/launchdarkly/ruby-server-sdk-ai) |
| Sample application | [Using Bedrock](https://github.com/launchdarkly/ruby-server-sdk-ai/tree/main/examples/chatbot/aws-bedrock) , [Using OpenAI](https://github.com/launchdarkly/ruby-server-sdk-ai/tree/main/examples/chatbot/openai) |
| Published module | [RubyGems](https://rubygems.org/gems/launchdarkly-server-sdk-ai) |

## Get started

LaunchDarkly AI SDKs interact with [AI Configs](/home/getting-started/vocabulary#ai-config). AI Configs are the LaunchDarkly resources that manage model configurations and messages for your generative AI applications.

<Tip title="Try the Quickstart">
  This reference guide describes working specifically with the Ruby AI SDK. For a complete introduction to LaunchDarkly AI SDKs and how they interact with AI Configs, read [Quickstart for AI Configs](/home/ai-configs/quickstart).
</Tip>

You can use the Ruby AI SDK to customize your AI Config based on the [context](/home/getting-started/vocabulary#context) that you provide. This means both the messages and the model evaluation in your generative AI application are specific to each end user, at runtime. You can also use the AI SDKs to record metrics from your AI model generation, including duration and tokens.

Follow these instructions to start using the Ruby AI SDK in your application.

### Understand version compatibility

The LaunchDarkly Ruby AI SDK is compatible with Ruby 3.0 and higher.

### Install the SDK

First, install the AI SDK as a dependency in your application using your application's dependency manager. If you want to depend on a specific version, refer to the [SDK releases page](https://github.com/launchdarkly/ruby-server-sdk-ai/releases) to identify the latest version.

Here's how:

<CodeGroup>
  ```bash title="Shell" theme={null}
      gem install launchdarkly-server-sdk
      gem install launchdarkly-server-sdk-ai
  ```
</CodeGroup>

Next, import the LaunchDarkly `LaunchDarkly::Server::AI::Client` into your application code:

<CodeGroup>
  ```ruby title="Ruby" theme={null}
      require 'launchdarkly-server-sdk'
      require 'launchdarkly-server-sdk-ai'
  ```
</CodeGroup>

### Initialize the client

After you install and import the AI SDK, create a single, shared instance of `LaunchDarkly::Server::AI::Client`. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

<Note title="The Ruby AI SDK uses an SDK key">
  The Ruby AI SDK uses an SDK key. Keys are specific to each project and environment. They are available from **Project settings**, on the **Environments** list. To learn more about key types, read [Keys](/sdk/concepts/client-side-server-side#keys).
</Note>

Here's how:

<CodeGroup>
  ```ruby title="Ruby" theme={null}
      ld_client = LaunchDarkly::LDClient.new("YOUR_SDK_KEY")
      ai_client = LaunchDarkly::AI::LDAIClient.new(ld_client)
  ```
</CodeGroup>

### Configure the context

Next, configure the context that will use the AI Config, that is, the context that will encounter generated AI content in your application. The context attributes determine which variation of the AI Config LaunchDarkly serves to the end user, based on the targeting rules in your AI Config. If you are using template variables in the messages in your AI Config's variations, the context attributes also fill in values for the template variables.

Here's how:

<CodeGroup>
  ```ruby title="Ruby AI SDK" theme={null}
      context = LaunchDarkly::LDContext.create({
          key: "example-user-key",
          kind: "user",
          firstName: "Sandy",
          lastName: "Smith",
          email: "sandy@example.com",
          groups: ["Acme", "Global Health Services"]
      })
  ```
</CodeGroup>

### Customize an AI Config

Then, use `Config` to customize the AI Config. Customization means that any variables you include in the messages when you define the AI Config variation have their values set to the context attributes and variables you pass to `Config`. You need to call `Config` each time you generate content from your AI model.

The customization process within the AI SDK is similar to [evaluating flags](/sdk/features/) in one of LaunchDarkly's client-side, server-side, or edge SDKs, in that the SDK completes the customization without a separate network call. The `Config` function takes an AI Config key, a context, and a fallback value. It performs the evaluation, then returns the customized messages and model along with a tracker instance for recording metrics. If it cannot perform the evaluation or LaunchDarkly is unreachable, it returns the fallback value. For example, you might use an empty, disabled `AIConfig` as a fallback value, or a fully configured default. Either way, you should make sure to check for this case and handle it appropriately in your application.

After you call `config`, you can pass the customized messages directly to your AI.

Here's how:

<CodeGroup>
  ```ruby title="Ruby AI SDK" theme={null}
      fallback_value = LaunchDarkly::AI::AIConfig.new(enabled: false)

      ai_config = ai_client.config('example-ai-config-key', context, fallback_value, { 'example_custom_variable' => 'example_custom_value' })
  ```
</CodeGroup>

To learn more, read [Customizing AI Configs](/sdk/features/ai-config#ruby-ai).

### Call provider, record metrics from AI model generation

Finally, use one of the `track_[model]_metrics` functions to make a request to your generative AI provider and record metrics from your AI model generation. The Ruby AI SDK provides specific `track_[model]_metrics` functions using completions from common AI model families. Make sure to check whether the returned `config` is enabled, and handle the disabled case appropriately in your application.

Here's how:

<CodeGroup>
  ```ruby title="Using OpenAI model" theme={null}
      if ai_config.enabled
        # Pass in the result of the OpenAI operation.
        # When calling the OpenAI operation, use details from ai_config.
        # For instance, you can pass ai_config.model.name
        # and ai_config.messages to your specific OpenAI operation.
        #
        # CAUTION: If the call inside of track_openai_metrics throws an exception,
        # the SDK will re-throw that exception

        completion = ai_config.tracker.track_openai_metrics(
            openai_client.chat.completions.create(
                model: ai_config.model.name,
                messages: ai_config.messages.map(&:to_h)
            )
        )
      else
        # Application path to take when the ai_config is disabled
      end
  ```

  ```ruby title="Using Bedrock model" theme={null}
      if ai_config.enabled
        # Pass in the result of the Bedrock Converse command.
        # When calling the Bedrock Converse command, use details from ai_config.
        # For instance, you can pass ai_config.model.name
        # and ai_config.messages to your specific Bedrock Converse command.

        completion = ai_config.tracker.track_bedrock_converse_metrics(
            bedrock_client.converse(
                map_converse_arguments(
                  ai_config.model.name,
                  ai_config.messages
                )
            )
        )
      else
        # Application path to take when the ai_config is disabled
      end
  ```

  ```ruby title="Bedrock helper function" theme={null}
      # The map_converse_arguments helper function transforms the messages
      # to fit the Bedrock SDK

        def map_converse_arguments(model_id, messages)
          args = {
            model_id: model_id,
          }

          mapped_messages = []
          user_messages = messages.select { |msg| msg.role == 'user' }
          mapped_messages << { role: 'user', content: user_messages.map { |msg| { text: msg.content } } } unless user_messages.empty?

          assistant_messages = messages.select { |msg| msg.role == 'assistant' }
          mapped_messages << { role: 'assistant', content: assistant_messages.map { |msg| { text: msg.content } } } unless assistant_messages.empty?
          args[:messages] = mapped_messages unless mapped_messages.empty?

          system_messages = messages.select { |msg| msg.role == 'system' }
          args[:system] = system_messages.map { |msg| { text: msg.content } } unless system_messages.empty?

          args
        end
  ```
</CodeGroup>

Alternatively, you can use the SDK's other `track*` functions to record these metrics manually. You may need to do this if you are using a model for which the SDK does not provide a convenience `track_[model]_metrics` function. The `track_[model]_metrics` functions are expecting a response, so you may also need to do this if your application requires streaming.

Make sure to call `config` each time you generate content from your AI model:

<CodeGroup>
  ```ruby title="Using OpenAI model, next request to provider" theme={null}
      ai_config = ai_client.config('example-ai-config-key', context, fallback_value, { 'example_custom_variable' => 'example_custom_value' })

      completion = ai_config.tracker.track_openai_metrics(...)
  ```

  ```ruby title="Using Bedrock model, next request to provider" theme={null}
      ai_config = ai_client.config('example-ai-config-key', context, fallback_value, { 'example_custom_variable' => 'example_custom_value' })

      completion = ai_config.tracker.track_bedrock_converse_metrics(...)
  ```
</CodeGroup>

To learn more, read [Tracking AI metrics](/sdk/features/ai-metrics#python-ai).

## Supported features

This SDK supports the following features:

* [Anonymous contexts](/sdk/features/anonymous#ruby-ai)
* [Context configuration](/sdk/features/context-config/ai#ruby-ai)
* [Customizing AI Configs](/sdk/features/ai-config#ruby-ai)
* [Private attributes](/sdk/features/private-attributes/ai#ruby-ai)
* [Tracking AI metrics](/sdk/features/ai-metrics#ruby-ai)