langfuse-rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5905472e2a3dc7fc674f1fbdc86b76105f8513a3079c00c8f9c5c346c19c2f16
-  data.tar.gz: 683d86aca0810243d76fd4a0e5418e635ccaf50fd0cbe966290541eff91ccf4e
+  metadata.gz: ae64454a24bf090bcaedf13432b8c2c7ecc0c1d986bc5ffdec8ad3f5ada1b2d5
+  data.tar.gz: 05dcbaaa1aa3aa90fcb75d42086a526c60914b3f88ce2fa0049b77d7cafc33cb
 SHA512:
-  metadata.gz: a5a5b0352f26ce66c2997b6a9bdebde37f1629550bca0c7ef221ad1954f763f1d5a1343915c54d6354ccaafb02b9e7183ac66ef2bf18a9142a69a13852e41762
-  data.tar.gz: a2c05dd96df86951eccefd43719805b07595139f6dc56bc4fe1c35a54fe9ee3936ac4f06b4b1ac78fa419cdf717fd988f4555e349ab3b9a67738405e4ee34220
+  metadata.gz: 1b8b91ba6180d4450fef21f59bcca7c06b21c2a5d336e70bf233ca3d2b4d325387f78950ac3ee2c41c4655a0199a4fbd03fdf07164cf224dba7bc2734af1f95c
+  data.tar.gz: 00d0a265e3f41cf6690f740b63c7d61853733b9701e1d1ea0630fe19a6d8b8022d8a1cd26b9eceb62133fe169fde093544d738ba3f258f765cd9ced0e2aecea9

data/CHANGELOG.md

@@ -7,54 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [1.0.0] - 2025-10-16 🚀
-
-### Initial Release
-
-Complete Ruby SDK for Langfuse with prompt management, distributed caching, LLM tracing, and Rails integration.
-
-#### Prompt Management
-- Fetch and compile text and chat prompts with Mustache templating
-- Support for prompt versioning and label-based fetching (production, staging, etc.)
-- Automatic variable substitution with nested objects and arrays
-- Global configuration pattern with `Langfuse.configure` block
-- Fallback prompt support for graceful error recovery
-
-#### Caching
-- Dual backend support: in-memory (default) and Rails.cache (distributed)
-- Thread-safe in-memory cache with TTL and LRU eviction
-- Distributed caching with Redis/Memcached via Rails.cache
-- Automatic stampede protection with distributed locks (Rails.cache only)
-- Cache warming utilities for deployment automation
-- Auto-discovery of all prompts with configurable labels
-
-#### LLM Tracing & Observability
-- Built on OpenTelemetry for industry-standard distributed tracing
-- Block-based Ruby API for traces, spans, and generations
-- Automatic prompt-to-trace linking
-- Token usage and cost tracking
-- W3C Trace Context support for distributed tracing across services
-- Integration with APM tools (Datadog, New Relic, Honeycomb, etc.)
-- Async processing with batch span export
-
-#### Rails Integration
-- Rails-friendly configuration with initializer support
-- Background job integration (Sidekiq, GoodJob, Delayed Job, etc.)
-- Rake tasks for cache management
-- Environment-specific configuration patterns
-- Credentials support for secure key management
-
-#### Developer Experience
-- Comprehensive error handling with specific error classes
-- HTTP client with automatic retry logic and exponential backoff
-- Circuit breaker pattern for resilience (via Stoplight)
-- 99.7% test coverage with 339 comprehensive test cases
-- Extensive documentation with guides for Rails, tracing, and migration
-
-#### Dependencies
-- Ruby >= 3.2.0
-- No Rails dependency (works with any Ruby project)
-- Minimal runtime dependencies (Faraday, Mustache, OpenTelemetry)
-
-[Unreleased]: https://github.com/langfuse/langfuse-ruby/compare/v1.0.0...HEAD
-[1.0.0]: https://github.com/langfuse/langfuse-ruby/releases/tag/v1.0.0
+### Added
+- Create and update methods for prompts (#36)
+
+
+## [0.2.0] - 2025-12-19
+
+### Added
+- Prompt creation and update methods (`create_prompt`, `update_prompt`)
+- Extended prompt management documentation with create/update examples
+
+## [0.1.0] - 2025-12-01
+
+### Added
+- Observe API with context propagation and scoring (#31)
+- W3C TraceContext propagator for distributed tracing (#1)
+- Ruby 3.4 support (#3)
+- OpenTelemetry-based tracing with OTLP export
+- Distributed caching with Rails.cache backend and stampede protection
+- Prompt management (text and chat) with Mustache templating
+- In-memory caching with TTL and LRU eviction
+- Fallback prompt support
+- Global configuration pattern with `Langfuse.configure`
+
+### Changed
+- Migrated from legacy ingestion API to OTLP endpoint
+- Removed `tracing_enabled` configuration flag (#2)
+
+[Unreleased]: https://github.com/simplepractice/langfuse-rb/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/simplepractice/langfuse-rb/releases/tag/v0.1.0

data/README.md

@@ -2,13 +2,15 @@
 
 # Langfuse Ruby SDK
 
-[![Gem Version](https://badge.fury.io/rb/langfuse.svg)](https://badge.fury.io/rb/langfuse)
+[![Gem Version](https://badge.fury.io/rb/langfuse-rb.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/langfuse-rb)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.2.0-ruby.svg)](https://www.ruby-lang.org/en/)
 [![Test Coverage](https://img.shields.io/badge/coverage-99.6%25-brightgreen.svg)](coverage)
 
 > Ruby SDK for [Langfuse](https://langfuse.com) - Open-source LLM observability and prompt management.
 
-## Features
+<br>
+
+### Features
 
 - 🎯 **Prompt Management** - Centralized prompt versioning with Mustache templating
 - 📊 **LLM Tracing** - Zero-boilerplate observability built on OpenTelemetry
@@ -18,24 +20,24 @@
 - 🛡️ **Fallback Support** - Graceful degradation when API unavailable
 - 🚀 **Rails-Friendly** - Global configuration pattern, works with any Ruby project
 
-## Installation
+<br>
+
+### Installation
 
 ```ruby
-# Gemfile
+# Add to Gemfile & bundle install
 gem 'langfuse-rb'
 ```
 
-```bash
-bundle install
-```
+<br>
 
-## Quick Start
+### Quick Start
 
-**Configure once at startup:**
+> Configure once at startup
 
 ```ruby
 # config/initializers/langfuse.rb (Rails)
-# or at the top of your script
+# 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']
@@ -44,7 +46,7 @@ Langfuse.configure do |config|
 end
 ```
 
-**Fetch and use a prompt:**
+> Fetch and use a prompt
 
 ```ruby
 prompt = Langfuse.client.get_prompt("greeting")
@@ -52,7 +54,7 @@ message = prompt.compile(name: "Alice")
 # => "Hello Alice!"
 ```
 
-**Trace an LLM call:**
+> Trace an LLM call
 
 ```ruby
 Langfuse.observe("chat-completion", as_type: :generation) do |gen|
@@ -74,33 +76,37 @@ Langfuse.observe("chat-completion", as_type: :generation) do |gen|
 end
 ```
 
-> [!IMPORTANT]  
+> [!IMPORTANT]
 > For complete reference see [docs](./docs/) section.
 
-## Requirements
+<br>
+
+### Requirements
 
 - Ruby >= 3.2.0
 - No Rails dependency (works with any Ruby project)
 
-## Contributing
+<br>
+
+### Contributing
 
 We welcome contributions! Please:
 
-1. Check existing [issues](https://github.com/simplepractice/langfuse-rb/issues) and roadmap
+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
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+> [!TIP]
+> See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+<br>
 
-## Support
+### Support
 
 - **[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
 
-## License
-
-[MIT](LICENSE)

data/lib/langfuse/api_client.rb

@@ -4,6 +4,7 @@ require "faraday"
 require "faraday/retry"
 require "base64"
 require "json"
+require "uri"
 
 module Langfuse
   # HTTP client for Langfuse API
@@ -128,6 +129,84 @@ module Langfuse
       end
     end
 
+    # Create a new prompt (or new version if prompt with same name exists)
+    #
+    # @param name [String] The prompt name
+    # @param prompt [String, Array<Hash>] The prompt content
+    # @param type [String] Prompt type ("text" or "chat")
+    # @param config [Hash] Optional configuration (model params, etc.)
+    # @param labels [Array<String>] Optional labels (e.g., ["production"])
+    # @param tags [Array<String>] Optional tags
+    # @param commit_message [String, nil] Optional commit message
+    # @return [Hash] The created prompt data
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Create a text prompt
+    #   api_client.create_prompt(
+    #     name: "greeting",
+    #     prompt: "Hello {{name}}!",
+    #     type: "text",
+    #     labels: ["production"]
+    #   )
+    #
+    # 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}"
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Update labels for an existing prompt version
+    #
+    # @param name [String] The prompt name
+    # @param version [Integer] The version number to update
+    # @param labels [Array<String>] New labels (replaces existing). Required.
+    # @return [Hash] The updated prompt data
+    # @raise [ArgumentError] if labels is not an array
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Promote a prompt to production
+    #   api_client.update_prompt(
+    #     name: "greeting",
+    #     version: 2,
+    #     labels: ["production"]
+    #   )
+    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 }
+
+      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}"
+    end
+
     # Send a batch of events to the Langfuse ingestion API
     #
     # Sends events (scores, traces, observations) to the ingestion endpoint.
@@ -180,7 +259,7 @@ module Langfuse
     # @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/#{name}"
+      path = "/api/public/v2/prompts/#{URI.encode_uri_component(name)}"
 
       response = connection.get(path, params)
       handle_response(response)
@@ -215,7 +294,9 @@ module Langfuse
     # Retries transient errors with exponential backoff:
     # - Max 2 retries (3 total attempts)
     # - Exponential backoff (0.05s * 2^retry_count)
-    # - Retries GET requests and POST requests to batch endpoint (idempotent operations)
+    # - Retries GET and PATCH 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)
     # - Does NOT retry on: 4xx errors (except 429), 5xx errors (except 503, 504)
     #
@@ -225,7 +306,7 @@ module Langfuse
         max: 2,
         interval: 0.05,
         backoff_factor: 2,
-        methods: %i[get post],
+        methods: %i[get post patch],
         retry_statuses: [429, 503, 504],
         exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
       }
@@ -278,7 +359,7 @@ module Langfuse
     # @raise [ApiError] for other error statuses
     def handle_response(response)
       case response.status
-      when 200
+      when 200, 201
         response.body
       when 401
         raise UnauthorizedError, "Authentication failed. Check your API keys."

data/lib/langfuse/client.rb

@@ -17,6 +17,7 @@ module Langfuse
   #   prompt = client.get_prompt("greeting")
   #   compiled = prompt.compile(name: "Alice")
   #
+  # rubocop:disable Metrics/ClassLength
   class Client
     attr_reader :config, :api_client
 
@@ -139,6 +140,93 @@ module Langfuse
       prompt.compile(**variables)
     end
 
+    # Create a new prompt (or new version if name already exists)
+    #
+    # Creates a new prompt in Langfuse. If a prompt with the same name already
+    # exists, this creates a new version of that prompt.
+    #
+    # @param name [String] The prompt name (required)
+    # @param prompt [String, Array<Hash>] The prompt content (required)
+    #   - For text prompts: a string with {{variable}} placeholders
+    #   - For chat prompts: array of message hashes with role and content
+    # @param type [Symbol] Prompt type (:text or :chat) (required)
+    # @param config [Hash] Optional configuration (model parameters, tools, etc.)
+    # @param labels [Array<String>] Optional labels (e.g., ["production"])
+    # @param tags [Array<String>] Optional tags for categorization
+    # @param commit_message [String, nil] Optional commit message
+    # @return [TextPromptClient, ChatPromptClient] The created prompt client
+    # @raise [ArgumentError] if required parameters are missing or invalid
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Create a text prompt
+    #   prompt = client.create_prompt(
+    #     name: "greeting",
+    #     prompt: "Hello {{name}}!",
+    #     type: :text,
+    #     labels: ["production"],
+    #     config: { model: "gpt-4o", temperature: 0.7 }
+    #   )
+    #
+    # @example Create a chat prompt
+    #   prompt = client.create_prompt(
+    #     name: "support-bot",
+    #     prompt: [
+    #       { role: "system", content: "You are a {{role}} assistant" },
+    #       { role: "user", content: "{{question}}" }
+    #     ],
+    #     type: :chat,
+    #     labels: ["staging"]
+    #   )
+    # rubocop:disable Metrics/ParameterLists
+    def create_prompt(name:, prompt:, type:, config: {}, labels: [], tags: [], commit_message: nil)
+      validate_prompt_type!(type)
+      validate_prompt_content!(prompt, type)
+
+      prompt_data = api_client.create_prompt(
+        name: name,
+        prompt: normalize_prompt_content(prompt, type),
+        type: type.to_s,
+        config: config,
+        labels: labels,
+        tags: tags,
+        commit_message: commit_message
+      )
+
+      build_prompt_client(prompt_data)
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    # Update an existing prompt version's metadata
+    #
+    # Updates the labels of an existing prompt version.
+    # Note: The prompt content itself cannot be changed after creation.
+    #
+    # @param name [String] The prompt name (required)
+    # @param version [Integer] The version number to update (required)
+    # @param labels [Array<String>] New labels (replaces existing). Required.
+    # @return [TextPromptClient, ChatPromptClient] The updated prompt client
+    # @raise [ArgumentError] if labels is not an array
+    # @raise [NotFoundError] if the prompt is not found
+    # @raise [UnauthorizedError] if authentication fails
+    # @raise [ApiError] for other API errors
+    #
+    # @example Update labels to promote to production
+    #   prompt = client.update_prompt(
+    #     name: "greeting",
+    #     version: 2,
+    #     labels: ["production"]
+    #   )
+    def update_prompt(name:, version:, labels:)
+      prompt_data = api_client.update_prompt(
+        name: name,
+        version: version,
+        labels: labels
+      )
+
+      build_prompt_client(prompt_data)
+    end
+
     # Generate URL for viewing a trace in Langfuse UI
     #
     # @param trace_id [String] The trace ID (hex-encoded, 32 characters)
@@ -314,6 +402,8 @@ module Langfuse
     # @return [TextPromptClient, ChatPromptClient]
     # @raise [ArgumentError] if type is invalid
     def build_fallback_prompt_client(name, fallback, type)
+      validate_prompt_type!(type)
+
       # Create minimal prompt data structure
       prompt_data = {
         "name" => name,
@@ -330,9 +420,58 @@ module Langfuse
         TextPromptClient.new(prompt_data)
       when :chat
         ChatPromptClient.new(prompt_data)
-      else
-        raise ArgumentError, "Invalid type: #{type}. Must be :text or :chat"
+      end
+    end
+
+    # Validate prompt type parameter
+    #
+    # @param type [Symbol] The type to validate
+    # @raise [ArgumentError] if type is invalid
+    def validate_prompt_type!(type)
+      valid_types = %i[text chat]
+      return if valid_types.include?(type)
+
+      raise ArgumentError, "Invalid type: #{type}. Must be :text or :chat"
+    end
+
+    # Validate prompt content matches the declared type
+    #
+    # @param prompt [String, Array] The prompt content
+    # @param type [Symbol] The declared type
+    # @raise [ArgumentError] if content doesn't match type
+    def validate_prompt_content!(prompt, type)
+      case type
+      when :text
+        raise ArgumentError, "Text prompt must be a String" unless prompt.is_a?(String)
+      when :chat
+        raise ArgumentError, "Chat prompt must be an Array" unless prompt.is_a?(Array)
+      end
+    end
+
+    # Normalize prompt content for API request
+    #
+    # Converts Ruby symbol keys to string keys for chat messages
+    #
+    # @param prompt [String, Array] The prompt content
+    # @param type [Symbol] The prompt type
+    # @return [String, Array] Normalized content
+    def normalize_prompt_content(prompt, type)
+      return prompt if type == :text
+
+      # 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]
+        }
       end
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/langfuse/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Langfuse
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: langfuse-rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - SimplePractice
@@ -171,7 +171,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.2
 specification_version: 4
 summary: Ruby SDK for Langfuse - LLM observability and prompt management
 test_files: []