langfuse-rb 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60270020fc35460c5e29381351bbca35f1cdfe8b7dfe05eca43a0fb20dc06b7b
-  data.tar.gz: 4951c9b1546de4c9d00bb3b3be4c5325c8edf4d5bf6f5ecab7d9520ab052451b
+  metadata.gz: e356e95702ea99ed80bfc258a3a1dbfa6c71985bb8a31110f26c09e6ac8c8b8d
+  data.tar.gz: 742033eb63885f9a1b33377258c423a25c0fe6af8554965de8fd76b1807d3a93
 SHA512:
-  metadata.gz: 84fa1fc6ea91bda9ddcaa32dd43cb457439e0e4cdee06e3f3df88aae9c54c5b10abd16cb120f234da28733ba6497c466d0ece7888410d7b2711815e13f3956ef
-  data.tar.gz: 785bd5801a8c6b0ecd7c94f43083bdd6f12463bb918fa5f4a6faee32924a87a5058cf9700b20984fa9e8964cb3070975235771ddfddabca115cb33538020b065
+  metadata.gz: d26c930cf723cbdbd5fdd738fcbae8b2181aca3f340eb0929c3ab2d76720aa3b1f217fe8f71804607f0cac32a3b115b7a625e02cf982d30ceceb1c0c45c0d603
+  data.tar.gz: a4667dc7d5abe11b7facd78c26e406a394696f9d0ca6663a200ad0232adcd7bd45d7d4bf495b2f98c7a7ed23b5f7b62ab7c2ba7b76a606b546859072b98cedec

data/CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-02-08
+
+### Added
+- Dataset and dataset item management support (#40)
+- Experiment runner for evaluating datasets (#41)
+- Project-scoped URL generation for traces, observations, datasets, and experiments (#43)
+
+### Changed
+- Extracted duplicated Faraday rescue pattern in API client (#44)
+
+### Documentation
+- YARD documentation for all public methods (#42)
+- Dataset and experiment usage guides (#45)
+
 ## [0.3.0] - 2026-01-23
 
 ### Added
@@ -40,7 +54,8 @@ 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.3.0...HEAD
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/simplepractice/langfuse-rb/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/simplepractice/langfuse-rb/releases/tag/v0.1.0

data/lib/langfuse/api_client.rb

@@ -22,7 +22,23 @@ module Langfuse
   #   )
   #
   class ApiClient # rubocop:disable Metrics/ClassLength
-    attr_reader :public_key, :secret_key, :base_url, :timeout, :logger, :cache
+    # @return [String] Langfuse public API key
+    attr_reader :public_key
+
+    # @return [String] Langfuse secret API key
+    attr_reader :secret_key
+
+    # @return [String] Base URL for Langfuse API
+    attr_reader :base_url
+
+    # @return [Integer] HTTP request timeout in seconds
+    attr_reader :timeout
+
+    # @return [Logger] Logger instance for debugging
+    attr_reader :logger
+
+    # @return [PromptCache, RailsCacheAdapter, nil] Optional cache for prompt responses
+    attr_reader :cache
 
     # Initialize a new API client
     #
@@ -31,7 +47,8 @@ module Langfuse
     # @param base_url [String] Base URL for Langfuse API
     # @param timeout [Integer] HTTP request timeout in seconds
     # @param logger [Logger] Logger instance for debugging
-    # @param cache [PromptCache, nil] Optional cache for prompt responses
+    # @param cache [PromptCache, RailsCacheAdapter, nil] Optional cache for prompt responses
+    # @return [ApiClient]
     def initialize(public_key:, secret_key:, base_url:, timeout: 5, logger: nil, cache: nil)
       @public_key = public_key
       @secret_key = secret_key
@@ -72,22 +89,15 @@ module Langfuse
     #     puts "#{prompt['name']} (v#{prompt['version']})"
     #   end
     def list_prompts(page: nil, limit: nil)
-      params = {}
-      params[:page] = page if page
-      params[:limit] = limit if limit
+      with_faraday_error_handling do
+        params = { page: page, limit: limit }.compact
 
-      path = "/api/public/v2/prompts"
-      response = connection.get(path, params)
-      result = handle_response(response)
+        response = connection.get("/api/public/v2/prompts", params)
+        result = handle_response(response)
 
-      # API returns { data: [...], meta: {...} }
-      result["data"] || []
-    rescue Faraday::RetriableResponse => e
-      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
-      handle_response(e.response)
-    rescue Faraday::Error => e
-      logger.error("Faraday error: #{e.message}")
-      raise ApiError, "HTTP request failed: #{e.message}"
+        # API returns { data: [...], meta: {...} }
+        result["data"] || []
+      end
     end
 
     # Fetch a prompt from the Langfuse API
@@ -135,25 +145,21 @@ module Langfuse
     #
     # rubocop:disable Metrics/ParameterLists
     def create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil)
-      path = "/api/public/v2/prompts"
-      payload = {
-        name: name,
-        prompt: prompt,
-        type: type,
-        config: config,
-        labels: labels,
-        tags: tags
-      }
-      payload[:commitMessage] = commit_message if commit_message
-
-      response = connection.post(path, payload)
-      handle_response(response)
-    rescue Faraday::RetriableResponse => e
-      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
-      handle_response(e.response)
-    rescue Faraday::Error => e
-      logger.error("Faraday error: #{e.message}")
-      raise ApiError, "HTTP request failed: #{e.message}"
+      with_faraday_error_handling do
+        path = "/api/public/v2/prompts"
+        payload = {
+          name: name,
+          prompt: prompt,
+          type: type,
+          config: config,
+          labels: labels,
+          tags: tags
+        }
+        payload[:commitMessage] = commit_message if commit_message
+
+        response = connection.post(path, payload)
+        handle_response(response)
+      end
     end
     # rubocop:enable Metrics/ParameterLists
 
@@ -177,17 +183,13 @@ module Langfuse
     def update_prompt(name:, version:, labels:)
       raise ArgumentError, "labels must be an array" unless labels.is_a?(Array)
 
-      path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}/versions/#{version}"
-      payload = { newLabels: labels }
+      with_faraday_error_handling do
+        path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}/versions/#{version}"
+        payload = { newLabels: labels }
 
-      response = connection.patch(path, payload)
-      handle_response(response)
-    rescue Faraday::RetriableResponse => e
-      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
-      handle_response(e.response)
-    rescue Faraday::Error => e
-      logger.error("Faraday error: #{e.message}")
-      raise ApiError, "HTTP request failed: #{e.message}"
+        response = connection.patch(path, payload)
+        handle_response(response)
+      end
     end
 
     # Send a batch of events to the Langfuse ingestion API
@@ -198,6 +200,7 @@ module Langfuse
     #
     # @param events [Array<Hash>] Array of event hashes to send
     # @return [void]
+    # @raise [ArgumentError] if events is not an Array or is empty
     # @raise [UnauthorizedError] if authentication fails
     # @raise [ApiError] for other API errors after retries exhausted
     #
@@ -229,10 +232,233 @@ module Langfuse
       raise ApiError, "Batch send failed: #{e.message}"
     end
 
+    # Create a dataset run item (link a trace to a dataset item within a run)
+    #
+    # @param dataset_item_id [String] Dataset item ID (required)
+    # @param run_name [String] Run name (required)
+    # @param trace_id [String, nil] Trace ID to link
+    # @param observation_id [String, nil] Observation ID to link
+    # @param metadata [Hash, nil] Optional metadata
+    # @param run_description [String, nil] Optional run description
+    # @return [Hash] The created dataset run item data
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   api_client.create_dataset_run_item(dataset_item_id: "item-123", run_name: "eval-v1", trace_id: "trace-abc")
+    def create_dataset_run_item(dataset_item_id:, run_name:, trace_id: nil,
+                                observation_id: nil, metadata: nil, run_description: nil)
+      with_faraday_error_handling do
+        payload = { datasetItemId: dataset_item_id, runName: run_name }
+        payload[:traceId] = trace_id if trace_id
+        payload[:observationId] = observation_id if observation_id
+        payload[:metadata] = metadata if metadata
+        payload[:runDescription] = run_description if run_description
+
+        response = connection.post("/api/public/dataset-run-items", payload)
+        handle_response(response)
+      end
+    end
+
+    # Fetch projects accessible with the current API keys
+    #
+    # @return [Hash] The parsed response body containing project data
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   data = api_client.get_projects
+    #   project_id = data["data"][0]["id"]
+    def get_projects # rubocop:disable Naming/AccessorMethodName
+      with_faraday_error_handling do
+        response = connection.get("/api/public/projects")
+        handle_response(response)
+      end
+    end
+
+    # Shut down the API client and release resources
+    #
+    # Shuts down the cache if it supports shutdown (e.g., SWR thread pool).
+    #
+    # @return [void]
     def shutdown
       cache.shutdown if cache.respond_to?(:shutdown)
     end
 
+    # List all datasets in the project
+    #
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @return [Array<Hash>] Array of dataset metadata hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   datasets = api_client.list_datasets(page: 1, limit: 10)
+    def list_datasets(page: nil, limit: nil)
+      with_faraday_error_handling do
+        params = { page: page, limit: limit }.compact
+
+        response = connection.get("/api/public/v2/datasets", params)
+        result = handle_response(response)
+        result["data"] || []
+      end
+    end
+
+    # Fetch a dataset by name
+    #
+    # @param name [String] Dataset name (supports folder paths like "evaluation/qa-dataset")
+    # @return [Hash] The dataset data
+    # @raise [NotFoundError] if the dataset is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   data = api_client.get_dataset("my-dataset")
+    def get_dataset(name)
+      with_faraday_error_handling do
+        encoded_name = URI.encode_uri_component(name)
+        response = connection.get("/api/public/v2/datasets/#{encoded_name}")
+        handle_response(response)
+      end
+    end
+
+    # Create a new dataset
+    #
+    # @param name [String] Dataset name (required)
+    # @param description [String, nil] Optional description
+    # @param metadata [Hash, nil] Optional metadata hash
+    # @return [Hash] The created dataset data
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   data = api_client.create_dataset(name: "my-dataset", description: "QA evaluation set")
+    def create_dataset(name:, description: nil, metadata: nil)
+      with_faraday_error_handling do
+        payload = { name: name, description: description, metadata: metadata }.compact
+
+        response = connection.post("/api/public/v2/datasets", payload)
+        handle_response(response)
+      end
+    end
+
+    # Create a new dataset item (or upsert if id is provided)
+    #
+    # @param dataset_name [String] Name of the dataset (required)
+    # @param input [Object, nil] Input data for the item
+    # @param expected_output [Object, nil] Expected output for evaluation
+    # @param metadata [Hash, nil] Optional metadata
+    # @param id [String, nil] Optional ID for upsert behavior
+    # @param source_trace_id [String, nil] Link to source trace
+    # @param source_observation_id [String, nil] Link to source observation
+    # @param status [Symbol, nil] Item status (:active or :archived)
+    # @return [Hash] The created dataset item data
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   data = api_client.create_dataset_item(
+    #     dataset_name: "my-dataset",
+    #     input: { query: "What is Ruby?" },
+    #     expected_output: { answer: "A programming language" }
+    #   )
+    # rubocop:disable Metrics/ParameterLists
+    def create_dataset_item(dataset_name:, input: nil, expected_output: nil,
+                            metadata: nil, id: nil, source_trace_id: nil,
+                            source_observation_id: nil, status: nil)
+      with_faraday_error_handling do
+        payload = build_dataset_item_payload(
+          dataset_name: dataset_name, input: input, expected_output: expected_output,
+          metadata: metadata, id: id, source_trace_id: source_trace_id,
+          source_observation_id: source_observation_id, status: status
+        )
+
+        response = connection.post("/api/public/dataset-items", payload)
+        handle_response(response)
+      end
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Fetch a dataset item by ID
+    #
+    # @param id [String] Dataset item ID
+    # @return [Hash] The dataset item data
+    # @raise [NotFoundError] if the item is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   data = api_client.get_dataset_item("item-uuid-123")
+    def get_dataset_item(id)
+      with_faraday_error_handling do
+        encoded_id = URI.encode_uri_component(id)
+        response = connection.get("/api/public/dataset-items/#{encoded_id}")
+        handle_response(response)
+      end
+    end
+
+    # List items in a dataset with optional filters
+    #
+    # @param dataset_name [String] Name of the dataset (required)
+    # @param page [Integer, nil] Optional page number for pagination
+    # @param limit [Integer, nil] Optional limit per page
+    # @param source_trace_id [String, nil] Filter by source trace ID
+    # @param source_observation_id [String, nil] Filter by source observation ID
+    # @return [Array<Hash>] Array of dataset item hashes
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example
+    #   items = api_client.list_dataset_items(dataset_name: "my-dataset", limit: 50)
+    def list_dataset_items(dataset_name:, page: nil, limit: nil,
+                           source_trace_id: nil, source_observation_id: nil)
+      result = list_dataset_items_paginated(
+        dataset_name: dataset_name, page: page, limit: limit,
+        source_trace_id: source_trace_id, source_observation_id: source_observation_id
+      )
+      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_items_paginated(dataset_name:, page: nil, limit: nil,
+                                     source_trace_id: nil, source_observation_id: nil)
+      with_faraday_error_handling do
+        params = build_dataset_items_params(
+          dataset_name: dataset_name, page: page, limit: limit,
+          source_trace_id: source_trace_id, source_observation_id: source_observation_id
+        )
+
+        response = connection.get("/api/public/dataset-items", params)
+        handle_response(response)
+      end
+    end
+
+    # Delete a dataset item by ID
+    #
+    # @param id [String] Dataset item ID
+    # @return [Hash] The response body
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    # @note 404 responses are treated as success to keep DELETE idempotent across retries
+    #
+    # @example
+    #   api_client.delete_dataset_item("item-uuid-123")
+    def delete_dataset_item(id)
+      encoded_id = URI.encode_uri_component(id)
+      response = connection.delete("/api/public/dataset-items/#{encoded_id}")
+      handle_delete_dataset_item_response(response, id)
+    rescue Faraday::RetriableResponse => e
+      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
+      handle_delete_dataset_item_response(e.response, id)
+    rescue Faraday::Error => e
+      logger.error("Faraday error: #{e.message}")
+      raise ApiError, "HTTP request failed: #{e.message}"
+    end
+
     private
 
     # Fetch prompt using the most appropriate caching strategy available
@@ -262,6 +488,43 @@ module Langfuse
       cache.respond_to?(:fetch_with_lock)
     end
 
+    # Build payload for create_dataset_item
+    # rubocop:disable Metrics/ParameterLists
+    def build_dataset_item_payload(dataset_name:, input:, expected_output:,
+                                   metadata:, id:, source_trace_id:,
+                                   source_observation_id:, status:)
+      { datasetName: dataset_name }.tap do |payload|
+        add_optional_dataset_item_fields(payload, input, expected_output, metadata, id)
+        add_optional_source_fields(payload, source_trace_id, source_observation_id, status)
+      end
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def add_optional_dataset_item_fields(payload, input, expected_output, metadata, id)
+      payload[:id] = id if id
+      payload[:input] = input if input
+      payload[:expectedOutput] = expected_output if expected_output
+      payload[:metadata] = metadata if metadata
+    end
+
+    def add_optional_source_fields(payload, source_trace_id, source_observation_id, status)
+      payload[:sourceTraceId] = source_trace_id if source_trace_id
+      payload[:sourceObservationId] = source_observation_id if source_observation_id
+      payload[:status] = status.to_s.upcase if status
+    end
+
+    # Build params for list_dataset_items
+    def build_dataset_items_params(dataset_name:, page:, limit:,
+                                   source_trace_id:, source_observation_id:)
+      {
+        datasetName: dataset_name,
+        page: page,
+        limit: limit,
+        sourceTraceId: source_trace_id,
+        sourceObservationId: source_observation_id
+      }.compact
+    end
+
     # Fetch with SWR cache
     def fetch_with_swr_cache(cache_key, name, version, label)
       cache.fetch_with_stale_while_revalidate(cache_key) do
@@ -296,18 +559,13 @@ module Langfuse
     # @raise [UnauthorizedError] if authentication fails
     # @raise [ApiError] for other API errors
     def fetch_prompt_from_api(name, version: nil, label: nil)
-      params = build_prompt_params(version: version, label: label)
-      path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}"
+      with_faraday_error_handling do
+        params = build_prompt_params(version: version, label: label)
+        path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}"
 
-      response = connection.get(path, params)
-      handle_response(response)
-    rescue Faraday::RetriableResponse => e
-      # Retry middleware exhausted all retries - handle the final response
-      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
-      handle_response(e.response)
-    rescue Faraday::Error => e
-      logger.error("Faraday error: #{e.message}")
-      raise ApiError, "HTTP request failed: #{e.message}"
+        response = connection.get(path, params)
+        handle_response(response)
+      end
     end
 
     # Build a new Faraday connection
@@ -332,7 +590,7 @@ module Langfuse
     # Retries transient errors with exponential backoff:
     # - Max 2 retries (3 total attempts)
     # - Exponential backoff (0.05s * 2^retry_count)
-    # - Retries GET and PATCH requests (idempotent operations)
+    # - Retries GET, PATCH, and DELETE requests (idempotent operations)
     # - Retries POST requests to batch endpoint (idempotent due to event UUIDs)
     # - Note: POST to create_prompt is NOT idempotent; retries may create duplicate versions
     # - Retries on: 429 (rate limit), 503 (service unavailable), 504 (gateway timeout)
@@ -344,7 +602,7 @@ module Langfuse
         max: 2,
         interval: 0.05,
         backoff_factor: 2,
-        methods: %i[get post patch],
+        methods: %i[get post patch delete],
         retry_statuses: [429, 503, 504],
         exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
       }
@@ -382,10 +640,25 @@ module Langfuse
     # @param label [String, nil] Optional label
     # @return [Hash] Query parameters
     def build_prompt_params(version: nil, label: nil)
-      params = {}
-      params[:version] = version if version
-      params[:label] = label if label
-      params
+      { version: version, label: label }.compact
+    end
+
+    # Wrap a block with standard Faraday error handling.
+    #
+    # Catches RetriableResponse (retries exhausted) and generic Faraday errors,
+    # translating them into ApiError with consistent logging.
+    #
+    # @yield The block containing the Faraday request and response handling
+    # @return [Object] The return value of the block
+    # @raise [ApiError] when a Faraday error occurs
+    def with_faraday_error_handling
+      yield
+    rescue Faraday::RetriableResponse => e
+      logger.error("Faraday error: Retries exhausted - #{e.response.status}")
+      handle_response(e.response)
+    rescue Faraday::Error => e
+      logger.error("Faraday error: #{e.message}")
+      raise ApiError, "HTTP request failed: #{e.message}"
     end
 
     # Handle HTTP response and raise appropriate errors
@@ -402,13 +675,20 @@ module Langfuse
       when 401
         raise UnauthorizedError, "Authentication failed. Check your API keys."
       when 404
-        raise NotFoundError, "Prompt not found"
+        raise NotFoundError, extract_error_message(response)
       else
         error_message = extract_error_message(response)
         raise ApiError, "API request failed (#{response.status}): #{error_message}"
       end
     end
 
+    def handle_delete_dataset_item_response(response, id)
+      return { "id" => id } if response&.status == 404
+      return response.body if [200, 201].include?(response&.status)
+
+      handle_response(response)
+    end
+
     # Handle HTTP response for batch requests
     #
     # @param response [Faraday::Response] The HTTP response

data/lib/langfuse/cache_warmer.rb

@@ -20,6 +20,7 @@ module Langfuse
   #   end
   #
   class CacheWarmer
+    # @return [Client] Langfuse client used for fetching prompts
     attr_reader :client
 
     # Initialize a new cache warmer
@@ -35,8 +36,8 @@ module Langfuse
     # safe to call multiple times.
     #
     # @param prompt_names [Array<String>] List of prompt names to cache
-    # @param versions [Hash<String, Integer>, nil] Optional version numbers per prompt
-    # @param labels [Hash<String, String>, nil] Optional labels per prompt
+    # @param versions [Hash<String, Integer>] Optional version numbers per prompt
+    # @param labels [Hash<String, String>] Optional labels per prompt
     # @return [Hash] Results with :success and :failed arrays
     #
     # @example Basic warming
@@ -73,8 +74,8 @@ module Langfuse
     # are cached without manually specifying them.
     #
     # @param default_label [String, nil] Label to use for all prompts (default: "production")
-    # @param versions [Hash<String, Integer>, nil] Optional version numbers per prompt
-    # @param labels [Hash<String, String>, nil] Optional labels per specific prompts (overrides default_label)
+    # @param versions [Hash<String, Integer>] Optional version numbers per prompt
+    # @param labels [Hash<String, String>] Optional labels per specific prompts (overrides default_label)
     # @return [Hash] Results with :success and :failed arrays
     #
     # @example Auto-discover and warm all prompts with "production" label
@@ -119,8 +120,8 @@ module Langfuse
     # Useful when you want to abort deployment if cache warming fails.
     #
     # @param prompt_names [Array<String>] List of prompt names to cache
-    # @param versions [Hash<String, Integer>, nil] Optional version numbers per prompt
-    # @param labels [Hash<String, String>, nil] Optional labels per prompt
+    # @param versions [Hash<String, Integer>] Optional version numbers per prompt
+    # @param labels [Hash<String, String>] Optional labels per prompt
     # @return [Hash] Results with :success array
     # @raise [CacheWarmingError] if any prompts fail to cache
     #

data/lib/langfuse/chat_prompt_client.rb

@@ -20,7 +20,23 @@ module Langfuse
   #   chat_prompt.labels    # => ["production"]
   #
   class ChatPromptClient
-    attr_reader :name, :version, :labels, :tags, :config, :prompt
+    # @return [String] Prompt name
+    attr_reader :name
+
+    # @return [Integer] Prompt version number
+    attr_reader :version
+
+    # @return [Array<String>] Labels assigned to this prompt
+    attr_reader :labels
+
+    # @return [Array<String>] Tags assigned to this prompt
+    attr_reader :tags
+
+    # @return [Hash] Prompt configuration
+    attr_reader :config
+
+    # @return [Array<Hash>] Array of message hashes with role and content
+    attr_reader :prompt
 
     # Initialize a new chat prompt client
     #