langfuse-rb 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bf0fdf8f1b31f237397c90d8db3fc61c40bc8a69e20111a949aa0bdffc8dd3e
-  data.tar.gz: b6b83329218d23b3ebd53562a4eb5bb1cd01179f07fdbf5d90b2b1c97fc192ef
+  metadata.gz: 1eedf02269727792fdb13a343429d2108556cc4c7df52dea9e2c638a011409a0
+  data.tar.gz: 0130f17065fa3e4233090e858a2699105d9be48dce85d6765b0c3ee394c88bff
 SHA512:
-  metadata.gz: a0bda13a371bcc93d37d4ae17548f04c65f1cc8fdf4982756eebac468d280f5b3a44d51ecb5ed5406e2ffee204a958988b3423860916471d8eb1a9e728fcf51c
-  data.tar.gz: a2bebff2e84e94c5fa30b6774c89c35f63ed4d2af214a76348a370ddbd9326ff0c8346fac9b3601e9bf9427bdb56f73a3f309f7eb71d439bd31b70426461ae3d
+  metadata.gz: 036b34ce7908114bdad51bf895c5f50159f005bbf53f3256a347dc7a6c813d9c49d18c9f7491dc42c8771d66fb6b509ae1441af6812d575ff45b80fe4e73ce6e
+  data.tar.gz: c4cf129fd0260c35f91e75797903d29e16d74b0bf543a89d9f566201a69e08eaf6245fc9d117e5f2f0e3bad5673cfee5cd54e0802d46a53809ab9c5ea825f172

data/CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-04-28
+
+### Added
+- Expose `type`, `commit_message`, and `resolution_graph` metadata on text and chat prompt clients (#87)
+
+### Fixed
+- Preserve and compile chat prompt message placeholders in parity with Langfuse Python and JS SDKs (#86)
+- Preserve raw prompt compile variables instead of HTML-escaping JSON, XML, and HTML-like values (#85)
+- Suppress prompt name/version attribution on fallback prompt clients so fallback output is not reported as prompt version 0 (#84)
+
+### Documentation
+- Link to upstream Langfuse agent skills and refresh README header image (#81, #83)
+
+## [0.8.0] - 2026-04-24
+
+### Added
+- Probabilistic trace sampling with score parity (#60)
+- Dataset run lifecycle methods: `get_dataset_run`, `list_dataset_runs`, `delete_dataset_run` (#62)
+
+### Fixed
+- Tracing is now isolated-by-default with lazy setup and smart export filtering (#77)
+
+### Documentation
+- Align docs with implementation (#78)
+
 ## [0.7.0] - 2026-04-14
 
 ### Added
@@ -88,7 +113,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Migrated from legacy ingestion API to OTLP endpoint
 - Removed `tracing_enabled` configuration flag (#2)
 
-[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.7.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.7.0...v0.8.0
 [0.7.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.4.0...v0.5.0

data/README.md

@@ -1,4 +1,5 @@
-![header](https://camo.githubusercontent.com/26d19b945bc752101b4aca468e07b118a44af07340db79af29f7df95505f2cea/68747470733a2f2f6c616e67667573652e636f6d2f6c616e67667573655f6c6f676f5f77686974652e706e67)
+<img width="2255" height="527" alt="langfuse-wordart" src="https://github.com/user-attachments/assets/59422d0a-6ecb-4e5f-a21c-cae955b5ce75" />
+
 
 # Langfuse Ruby SDK
 
@@ -8,69 +9,49 @@
 
 > Ruby SDK for [Langfuse](https://langfuse.com) - Open-source LLM observability and prompt management.
 
-<br>
-
-### Features
-
-- 🎯 **Prompt Management** - Centralized prompt versioning with Mustache templating
-- 📊 **LLM Tracing** - Zero-boilerplate observability built on OpenTelemetry
-- ⚡ **Performance** - In-memory or Redis-backed caching with stampede protection, both supporting stale-while-revalidate cache strategy
-- 💬 **Chat & Text Prompts** - First-class support for both formats
-- 🔄 **Automatic Retries** - Built-in exponential backoff for resilient API calls
-- 🛡️ **Fallback Support** - Graceful degradation when API unavailable
-- 🚀 **Rails-Friendly** - Global configuration pattern, works with any Ruby project
-
-<br>
-
-### Installation
+## Installation
 
 ```ruby
-# Add to Gemfile & bundle install
-gem 'langfuse-rb'
+gem "langfuse-rb"
 ```
 
-<br>
-
-### Quick Start
-
-> Configure once at startup
+## Quick Start
 
 ```ruby
-# config/initializers/langfuse.rb (Rails)
-# Or at the top of your script
 Langfuse.configure do |config|
-  config.public_key = ENV['LANGFUSE_PUBLIC_KEY']
-  config.secret_key = ENV['LANGFUSE_SECRET_KEY']
-  # Optional: for self-hosted instances
-  config.base_url = ENV.fetch('LANGFUSE_BASE_URL', 'https://cloud.langfuse.com')
-
-  # Optional: Enable stale-while-revalidate for best performance
-  config.cache_backend = :rails  # or :memory
-  config.cache_stale_while_revalidate = true
+  config.public_key = ENV["LANGFUSE_PUBLIC_KEY"]
+  config.secret_key = ENV["LANGFUSE_SECRET_KEY"]
+  config.base_url = ENV.fetch("LANGFUSE_BASE_URL", "https://cloud.langfuse.com")
+
+  # Optional: sample traces and trace-linked scores deterministically
+  config.sample_rate = 1.0
 end
+
+message = Langfuse.client.compile_prompt(
+  "greeting",
+  variables: { name: "Alice" }
+)
 ```
 
-> Fetch and use a prompt
+Langfuse tracing is isolated by default. `Langfuse.configure` stores configuration only; it does not replace `OpenTelemetry.tracer_provider`.
 
-```ruby
-prompt = Langfuse.client.get_prompt("greeting")
-message = prompt.compile(name: "Alice")
-# => "Hello Alice!"
-```
+`sample_rate` is applied to traces and trace-linked scores. Rebuild the client with `Langfuse.reset!` before expecting runtime sampling changes to take effect.
 
-> Trace an LLM call
+## Trace an LLM Call
 
 ```ruby
 Langfuse.observe("chat-completion", as_type: :generation) do |gen|
+  gen.model = "gpt-4.1-mini"
+  gen.input = [{ role: "user", content: "Hello!" }]
+
   response = openai_client.chat(
     parameters: {
-      model: "gpt-4",
+      model: "gpt-4.1-mini",
       messages: [{ role: "user", content: "Hello!" }]
     }
   )
 
   gen.update(
-    model: "gpt-4",
     output: response.dig("choices", 0, "message", "content"),
     usage_details: {
       prompt_tokens: response.dig("usage", "prompt_tokens"),
@@ -80,39 +61,16 @@ Langfuse.observe("chat-completion", as_type: :generation) do |gen|
 end
 ```
 
-> [!IMPORTANT]
-> For complete reference see [docs](./docs/) section.
-
-<br>
-
-### Requirements
-
-- Ruby >= 3.2.0
-- No Rails dependency (works with any Ruby project)
-
-<br>
-
-### Contributing
-
-We welcome contributions! Please:
-
-1. Check existing [issues](https://github.com/simplepractice/langfuse-rb/issues)
-2. Open an issue to discuss your idea
-3. Fork the repo and create a feature branch
-4. Write tests (maintain >95% coverage)
-5. Ensure `bundle exec rspec` and `bundle exec rubocop` pass
-6. Submit a pull request
-
-> [!TIP]
-> See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
-
-<br>
-
-### Support
+## Start Here
 
-- **[GitHub Issues](https://github.com/simplepractice/langfuse-rb/issues)** - Bug reports and feature requests
-- **[Langfuse Documentation](https://langfuse.com/docs)** - Platform documentation
-- **[API Reference](https://api.reference.langfuse.com)** - REST API reference
+- [Documentation Hub](docs/README.md)
+- [Getting Started](docs/GETTING_STARTED.md)
+- [Prompts](docs/PROMPTS.md)
+- [Tracing](docs/TRACING.md)
+- [Scoring](docs/SCORING.md)
+- [Rails Patterns](docs/RAILS.md)
+- [Agent Skills](https://github.com/langfuse/skills)
+- [Agent Skill Docs](https://langfuse.com/docs/api-and-data-platform/features/agent-skill)
 
 ## License
 

data/lib/langfuse/api_client.rb

@@ -260,6 +260,61 @@ module Langfuse
       end
     end
 
+    # Fetch a dataset run by dataset and run name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [Hash] The dataset run data
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def get_dataset_run(dataset_name:, run_name:)
+      with_faraday_error_handling do
+        response = connection.get(dataset_run_path(dataset_name: dataset_name, run_name: run_name))
+        handle_response(response)
+      end
+    end
+
+    # List dataset runs in a dataset
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @return [Array<Hash>] Array of dataset run hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def list_dataset_runs(dataset_name:, page: nil, limit: nil)
+      result = list_dataset_runs_paginated(dataset_name: dataset_name, page: page, limit: limit)
+      result["data"] || []
+    end
+
+    # Full paginated response including "meta" for internal pagination use
+    #
+    # @api private
+    # @return [Hash] Full response hash with "data" array and "meta" pagination info
+    def list_dataset_runs_paginated(dataset_name:, page: nil, limit: nil)
+      with_faraday_error_handling do
+        response = connection.get(dataset_runs_path(dataset_name), build_dataset_runs_params(page: page, limit: limit))
+        handle_response(response)
+      end
+    end
+
+    # Delete a dataset run by name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [Hash, nil] Response body, or nil for 204 responses
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    # @note 404 responses raise NotFoundError to preserve strict delete semantics
+    def delete_dataset_run(dataset_name:, run_name:)
+      with_faraday_error_handling do
+        response = connection.delete(dataset_run_path(dataset_name: dataset_name, run_name: run_name))
+        response.status == 204 ? nil : handle_response(response)
+      end
+    end
+
     # Fetch projects accessible with the current API keys
     #
     # @return [Hash] The parsed response body containing project data
@@ -604,6 +659,23 @@ module Langfuse
       }.compact
     end
 
+    # Build params for list_dataset_runs
+    def build_dataset_runs_params(page:, limit:)
+      { page: page, limit: limit }.compact
+    end
+
+    # Build endpoint path for dataset runs
+    def dataset_runs_path(dataset_name)
+      encoded_name = URI.encode_uri_component(dataset_name)
+      "/api/public/datasets/#{encoded_name}/runs"
+    end
+
+    # Build endpoint path for a specific dataset run
+    def dataset_run_path(dataset_name:, run_name:)
+      encoded_run_name = URI.encode_uri_component(run_name)
+      "#{dataset_runs_path(dataset_name)}/#{encoded_run_name}"
+    end
+
     # Build query params for list_traces, mapping snake_case to camelCase
     # rubocop:disable Metrics/ParameterLists
     def build_traces_params(page:, limit:, user_id:, name:, session_id:,

data/lib/langfuse/chat_prompt_client.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-require "mustache"
+require_relative "prompt_renderer"
 
 module Langfuse
   # Chat prompt client for compiling chat prompts with variable substitution
@@ -20,6 +20,8 @@ module Langfuse
   #   chat_prompt.labels    # => ["production"]
   #
   class ChatPromptClient
+    PLACEHOLDER_TYPE = "placeholder"
+
     # @return [String] Prompt name
     attr_reader :name
 
@@ -35,14 +37,24 @@ module Langfuse
     # @return [Hash] Prompt configuration
     attr_reader :config
 
-    # @return [Array<Hash>] Array of message hashes with role and content
+    # @return [Array<Hash>] Array of message hashes and placeholder entries
     attr_reader :prompt
 
+    # @return [String, nil] Optional commit message for this prompt version
+    attr_reader :commit_message
+
+    # @return [Hash, nil] Optional dependency resolution graph for composed prompts
+    attr_reader :resolution_graph
+
+    # @return [Boolean] Whether this client uses caller-provided fallback content
+    attr_reader :is_fallback
+
     # Initialize a new chat prompt client
     #
     # @param prompt_data [Hash] The prompt data from the API
+    # @param is_fallback [Boolean] Whether this client wraps caller-provided fallback content
     # @raise [ArgumentError] if prompt data is invalid
-    def initialize(prompt_data)
+    def initialize(prompt_data, is_fallback: false)
       validate_prompt_data!(prompt_data)
 
       @name = prompt_data["name"]
@@ -51,16 +63,27 @@ module Langfuse
       @labels = prompt_data["labels"] || []
       @tags = prompt_data["tags"] || []
       @config = prompt_data["config"] || {}
+      @commit_message = prompt_data["commitMessage"]
+      @resolution_graph = prompt_data["resolutionGraph"]
+      @is_fallback = is_fallback
     end
 
-    # Compile the chat prompt with variable substitution
+    # @return [String] Prompt type ("chat")
+    def type
+      "chat"
+    end
+
+    # Compile the chat prompt with variable substitution and message placeholders
     #
     # Returns an array of message hashes with roles and compiled content.
-    # Each message in the prompt will have its content compiled with the
-    # provided variables using Mustache templating.
+    # Placeholder entries are resolved from keyword arguments: arrays are
+    # expanded, empty arrays are skipped, unresolved placeholders stay in the
+    # output, and malformed values raise before invalid messages are sent to
+    # an LLM provider.
     #
-    # @param kwargs [Hash] Variables to substitute in message templates (as keyword arguments)
-    # @return [Array<Hash>] Array of compiled messages with :role and :content keys
+    # @param kwargs [Hash] Variables and placeholder values to compile
+    # @return [Array<Hash>] Array of compiled messages and unresolved placeholders
+    # @raise [ArgumentError] if a placeholder value is malformed
     #
     # @example
     #   chat_prompt.compile(name: "Alice", topic: "Ruby")
@@ -69,9 +92,18 @@ module Langfuse
     #   #   { role: :user, content: "Hello Alice, let's discuss Ruby!" }
     #   # ]
     def compile(**kwargs)
-      prompt.map do |message|
-        compile_message(message, kwargs)
+      unresolved = []
+      compiled = []
+      prompt.each do |message|
+        normalized = symbolize_keys(message)
+        if normalized[:type].to_s == PLACEHOLDER_TYPE
+          append_placeholder(normalized, kwargs, compiled, unresolved)
+        else
+          compiled << compile_message(normalized, kwargs)
+        end
       end
+      warn_unresolved(unresolved)
+      compiled
     end
 
     private
@@ -88,19 +120,102 @@ module Langfuse
       raise ArgumentError, "prompt must be an Array" unless prompt_data["prompt"].is_a?(Array)
     end
 
-    # Compile a single message with variable substitution
+    # Compile a single role/content message with variable substitution
     #
-    # @param message [Hash] The message with role and content
+    # @param normalized [Hash] Symbolized message hash
     # @param variables [Hash] Variables to substitute
     # @return [Hash] Compiled message with :role and :content as symbols
-    def compile_message(message, variables)
-      content = message["content"] || ""
-      compiled_content = variables.empty? ? content : Mustache.render(content, variables)
-
-      {
-        role: normalize_role(message["role"]),
-        content: compiled_content
-      }
+    def compile_message(normalized, variables)
+      normalized.except(:type).merge(
+        role: normalize_role(normalized[:role]),
+        content: render(normalized[:content] || "", variables)
+      )
+    end
+
+    # @api private
+    def append_placeholder(message, variables, compiled, unresolved)
+      name = message[:name].to_s
+      found, value = lookup_placeholder(variables, name)
+      return append_unresolved(name, compiled, unresolved) unless found
+
+      expand_placeholder(name, value, variables, compiled)
+    end
+
+    # @api private
+    def append_unresolved(name, compiled, unresolved)
+      unresolved << name
+      compiled << { type: PLACEHOLDER_TYPE, name: name }
+    end
+
+    # @api private
+    def expand_placeholder(name, value, variables, compiled)
+      return if value.is_a?(Array) && value.empty?
+
+      unless value.is_a?(Array)
+        raise ArgumentError, "Placeholder '#{name}' must contain an array of chat message hashes, got #{value.class}."
+      end
+
+      value.each { |entry| compiled << placeholder_message(entry, variables, name) }
+    end
+
+    # @api private
+    def lookup_placeholder(variables, name)
+      return [true, variables[name.to_sym]] if variables.key?(name.to_sym)
+      return [true, variables[name]] if variables.key?(name)
+
+      [false, nil]
+    end
+
+    # @api private
+    def placeholder_message(message, variables, name)
+      unless message.is_a?(Hash)
+        raise ArgumentError,
+              "Placeholder '#{name}' must contain an array of chat message hashes with role and content fields."
+      end
+
+      normalized = symbolize_keys(message)
+      unless valid_placeholder_message?(normalized)
+        raise ArgumentError,
+              "Placeholder '#{name}' must contain an array of chat message hashes with role and content fields."
+      end
+
+      normalized.merge(
+        role: normalize_role(normalized[:role]),
+        content: render(normalized[:content] || "", variables)
+      )
+    end
+
+    # @api private
+    def render(content, variables)
+      variables.empty? ? content : PromptRenderer.render(content, variables)
+    end
+
+    # @api private
+    def valid_placeholder_message?(message)
+      message.is_a?(Hash) &&
+        message.key?(:role) &&
+        !message[:role].to_s.empty? &&
+        message.key?(:content)
+    end
+
+    # @api private
+    def warn_unresolved(names)
+      return if names.empty?
+
+      unresolved_names = names.uniq.sort
+      message = "Placeholders #{unresolved_names.inspect} have not been resolved. " \
+                "Pass them as keyword arguments to compile()."
+      warn_msg(message)
+    end
+
+    # @api private
+    def warn_msg(message)
+      Langfuse.configuration.logger.warn("Langfuse: #{message}")
+    end
+
+    # @api private
+    def symbolize_keys(hash)
+      hash.transform_keys(&:to_sym)
     end
 
     # Normalize role to symbol

data/lib/langfuse/client.rb

@@ -588,6 +588,51 @@ module Langfuse
       )
     end
 
+    # Fetch a dataset run by dataset and run name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [Hash] The dataset run data, including linked run items
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def get_dataset_run(dataset_name:, run_name:)
+      api_client.get_dataset_run(dataset_name: dataset_name, run_name: run_name)
+    end
+
+    # List dataset runs for a dataset
+    #
+    # When page is nil (default), auto-paginates to fetch all runs.
+    # When page is provided, returns only that single page.
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @return [Array<Hash>] Array of dataset run hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    def list_dataset_runs(dataset_name:, page: nil, limit: nil)
+      if page
+        fetch_dataset_runs_page(dataset_name: dataset_name, page: page, limit: limit)
+      else
+        fetch_all_dataset_runs(dataset_name: dataset_name, limit: limit)
+      end
+    end
+
+    # Delete a dataset run by name
+    #
+    # @param dataset_name [String] Dataset name (required)
+    # @param run_name [String] Run name (required)
+    # @return [nil]
+    # @raise [NotFoundError] if the dataset run is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    # @note 404 responses raise NotFoundError to preserve strict delete semantics
+    def delete_dataset_run(dataset_name:, run_name:)
+      api_client.delete_dataset_run(dataset_name: dataset_name, run_name: run_name)
+      nil
+    end
+
     # Run an experiment against local data or a named dataset
     #
     # @param name [String] Experiment/run name (required)
@@ -656,17 +701,35 @@ module Langfuse
     end
 
     def fetch_all_dataset_items(limit:, **filters)
-      per_page = limit || DATASET_ITEMS_PAGE_SIZE
-      first_result = api_client.list_dataset_items_paginated(page: 1, limit: per_page, **filters)
-      items = first_result["data"] || []
+      fetch_all_paginated_data(limit: limit) do |page:, per_page:|
+        api_client.list_dataset_items_paginated(page: page, limit: per_page, **filters)
+      end
+    end
+
+    def fetch_dataset_runs_page(dataset_name:, page:, limit:)
+      api_client.list_dataset_runs(dataset_name: dataset_name, page: page, limit: limit)
+    end
+
+    def fetch_all_dataset_runs(dataset_name:, limit:)
+      fetch_all_paginated_data(limit: limit) do |page:, per_page:|
+        api_client.list_dataset_runs_paginated(dataset_name: dataset_name, page: page, limit: per_page)
+      end
+    end
+
+    # Keep dataset collection pagination semantics in one place so edge cases
+    # like missing or zero totalPages stay consistent across APIs.
+    def fetch_all_paginated_data(limit:)
+      page_size = limit || DATASET_ITEMS_PAGE_SIZE
+      first_result = yield(page: 1, per_page: page_size)
+      records = first_result["data"] || []
       total_pages = first_result.dig("meta", "totalPages") || 1
 
-      (2..total_pages).each do |pg|
-        result = api_client.list_dataset_items_paginated(page: pg, limit: per_page, **filters)
-        items.concat(result["data"] || [])
+      (2..total_pages).each do |page|
+        result = yield(page: page, per_page: page_size)
+        records.concat(result["data"] || [])
       end
 
-      items
+      records
     end
 
     def resolve_experiment_items(data, dataset_name)
@@ -760,9 +823,9 @@ module Langfuse
 
       case type
       when :text
-        TextPromptClient.new(prompt_data)
+        TextPromptClient.new(prompt_data, is_fallback: true)
       when :chat
-        ChatPromptClient.new(prompt_data)
+        ChatPromptClient.new(prompt_data, is_fallback: true)
       end
     end
 
@@ -793,7 +856,8 @@ module Langfuse
 
     # Normalize prompt content for API request
     #
-    # Converts Ruby symbol keys to string keys for chat messages
+    # Converts Ruby symbol keys to string keys for chat messages and preserves
+    # Langfuse message placeholder entries.
     #
     # @param prompt [String, Array] The prompt content
     # @param type [Symbol] The prompt type
@@ -803,18 +867,28 @@ module Langfuse
 
       # Normalize chat messages to use string keys
       prompt.map do |message|
-        # Convert all keys to symbols first, then extract
-        normalized = message.transform_keys do |k|
-          k.to_sym
-        rescue StandardError
-          k
-        end
-        {
-          "role" => normalized[:role]&.to_s,
-          "content" => normalized[:content]
-        }
+        normalized = message.transform_keys(&:to_s)
+        next placeholder_prompt_content(normalized) if normalized["type"] == ChatPromptClient::PLACEHOLDER_TYPE
+
+        normalize_chat_message_content(normalized)
       end
     end
+
+    # @api private
+    def placeholder_prompt_content(message)
+      {
+        "type" => ChatPromptClient::PLACEHOLDER_TYPE,
+        "name" => message["name"].to_s
+      }
+    end
+
+    # @api private
+    def normalize_chat_message_content(message)
+      message.merge(
+        "role" => message["role"]&.to_s,
+        "content" => message["content"]
+      )
+    end
   end
   # rubocop:enable Metrics/ClassLength
 end