Add create and update methods to client API (#36)

Author: kxzk

docs/PROMPTS.md

@@ -9,11 +9,22 @@ Langfuse centralizes prompt management, allowing you to:
 - A/B test prompt variations
 - Roll back to previous versions
 - Manage prompts across environments (dev/staging/prod)
+- **Create and update prompts programmatically** from your Ruby code
 
 The SDK supports two prompt types:
 - **Text Prompts:** Single string templates (e.g., instructions, system messages)
 - **Chat Prompts:** Structured message arrays (e.g., conversation templates)
 
+### Quick Reference
+
+| Method | Description |
+|--------|-------------|
+| `get_prompt(name)` | Fetch a prompt by name |
+| `compile_prompt(name, variables:)` | Fetch and compile in one call |
+| `create_prompt(name:, prompt:, type:)` | Create a new prompt or version |
+| `update_prompt(name:, version:, labels:)` | Update labels on a version |
+| `list_prompts` | List all prompts in your project |
+
 ## Text Prompts
 
 ### Fetching Text Prompts
@@ -281,6 +292,126 @@ prompt.compile(
 # Context: Customer browsing electronics
 ```
 
+## Creating Prompts
+
+You can create prompts programmatically without using the Langfuse UI.
+
+### `create_prompt` - Create New Prompts
+
+Create a new prompt or add a new version to an existing prompt:
+
+```ruby
+# Create a text prompt
+prompt = client.create_prompt(
+  name: "welcome-email",
+  prompt: "Welcome {{name}}! Thank you for joining {{company}}.",
+  type: :text,
+  config: { model: "gpt-4o", temperature: 0.7 },
+  labels: ["staging"],
+  tags: ["email", "onboarding"]
+)
+
+puts prompt.name       # => "welcome-email"
+puts prompt.version    # => 1
+```
+
+If a prompt with the same name already exists, a new version is created:
+
+```ruby
+# Create version 2 of "welcome-email"
+prompt_v2 = client.create_prompt(
+  name: "welcome-email",
+  prompt: "Hello {{name}}! Welcome to {{company}}. We're glad you're here!",
+  type: :text,
+  labels: ["staging"]
+)
+
+puts prompt_v2.version  # => 2
+```
+
+### Creating Chat Prompts
+
+Chat prompts use an array of message hashes:
+
+```ruby
+prompt = client.create_prompt(
+  name: "support-bot",
+  prompt: [
+    { role: "system", content: "You are a {{role}} support assistant for {{company}}." },
+    { role: "user", content: "{{question}}" }
+  ],
+  type: :chat,
+  config: { model: "gpt-4o", max_tokens: 500 },
+  labels: ["production"]
+)
+```
+
+**Note:** Message roles can use either strings (`"system"`) or symbols (`:system`).
+
+### Commit Messages
+
+Track changes with optional commit messages:
+
+```ruby
+prompt = client.create_prompt(
+  name: "greeting",
+  prompt: "Hi {{name}}, how can I help you today?",
+  type: :text,
+  commit_message: "Added friendlier tone per UX feedback"
+)
+```
+
+Commit messages are visible in the Langfuse UI version history.
+
+## Updating Prompts
+
+### `update_prompt` - Update Labels
+
+Update the labels on an existing prompt version. This is useful for promoting prompts through environments:
+
+```ruby
+# Promote version 3 to production
+prompt = client.update_prompt(
+  name: "greeting",
+  version: 3,
+  labels: ["production"]
+)
+
+puts prompt.labels  # => ["production"]
+```
+
+**Note:** Only labels can be updated. Prompt content is immutable after creation—create a new version instead.
+
+### Promotion Workflow Example
+
+A typical promotion workflow:
+
+```ruby
+# 1. Create new version in staging
+new_prompt = client.create_prompt(
+  name: "checkout-flow",
+  prompt: "Complete your purchase of {{product}}...",
+  type: :text,
+  labels: ["staging"]
+)
+
+# 2. Test in staging environment...
+
+# 3. Promote to production
+client.update_prompt(
+  name: "checkout-flow",
+  version: new_prompt.version,
+  labels: ["production"]
+)
+
+# 4. Remove old production label if needed
+client.update_prompt(
+  name: "checkout-flow",
+  version: old_version,
+  labels: []  # Empty array removes all labels
+)
+```
+
 ## Convenience Methods
 
 ### `compile_prompt` - Fetch and Compile
@@ -437,4 +568,4 @@ See [TRACING.md](TRACING.md) for more tracing patterns.
 - [TRACING.md](TRACING.md) - Tracking prompt usage in traces
 - [CACHING.md](CACHING.md) - Optimizing prompt fetch performance
 - [ERROR_HANDLING.md](ERROR_HANDLING.md) - Handling prompt errors
-- [API_REFERENCE.md](API_REFERENCE.md) - Complete method signatures
+- [API_REFERENCE.md](API_REFERENCE.md) - Complete method signatures for all prompt methods

lib/langfuse/api_client.rb

@@ -4,6 +4,7 @@
 require "faraday/retry"
 require "base64"
 require "json"
+require "uri"
 
 module Langfuse
   # HTTP client for Langfuse API
@@ -128,6 +129,84 @@ def get_prompt(name, version: nil, label: nil)
       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 @@ def send_batch(events)
     # @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 @@ def build_connection(timeout: nil)
     # 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 @@ def retry_options
         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 @@ def build_prompt_params(version: nil, label: nil)
     # @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."