langfuse-ruby 0.1.0

data/examples/basic_tracing.rb

@@ -0,0 +1,196 @@
+#!/usr/bin/env ruby
+
+require 'langfuse'
+
+# Initialize the Langfuse client
+client = Langfuse.new(
+  public_key: ENV['LANGFUSE_PUBLIC_KEY'],
+  secret_key: ENV['LANGFUSE_SECRET_KEY'],
+  host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+)
+
+puts '🚀 Starting basic tracing example...'
+
+# Example 1: Simple trace with generation
+puts "\n📝 Example 1: Simple trace with generation"
+
+trace = client.trace(
+  name: 'simple-chat',
+  user_id: 'user-123',
+  session_id: 'session-456',
+  input: { message: 'Hello, how are you?' },
+  metadata: {
+    environment: 'development',
+    version: '1.0.0'
+  }
+)
+
+puts "Created trace: #{trace.id}"
+
+generation = trace.generation(
+  name: 'openai-chat',
+  model: 'gpt-3.5-turbo',
+  input: [
+    { role: 'user', content: 'Hello, how are you?' }
+  ],
+  output: { content: "I'm doing well, thank you! How can I help you today?" },
+  usage: {
+    prompt_tokens: 12,
+    completion_tokens: 18,
+    total_tokens: 30
+  },
+  model_parameters: {
+    temperature: 0.7,
+    max_tokens: 150
+  }
+)
+
+puts "Created generation: #{generation.id}"
+
+# Update trace with final output
+trace.update(
+  output: { response: "I'm doing well, thank you! How can I help you today?" }
+)
+
+puts "Trace URL: #{trace.get_url}"
+
+# Example 2: Nested spans for complex workflow
+puts "\n🔗 Example 2: Nested spans for complex workflow"
+
+workflow_trace = client.trace(
+  name: 'document-qa-workflow',
+  user_id: 'user-456',
+  input: { question: 'What is machine learning?' }
+)
+
+# Document retrieval span
+retrieval_span = workflow_trace.span(
+  name: 'document-retrieval',
+  input: { query: 'What is machine learning?' }
+)
+
+# Embedding generation within retrieval
+embedding_gen = retrieval_span.generation(
+  name: 'embedding-generation',
+  model: 'text-embedding-ada-002',
+  input: 'What is machine learning?',
+  output: [0.1, 0.2, 0.3, 0.4, 0.5], # Simplified embedding
+  usage: { prompt_tokens: 5, total_tokens: 5 }
+)
+
+# End retrieval span
+retrieval_span.end(
+  output: {
+    documents: [
+      'Machine learning is a subset of artificial intelligence...',
+      'ML algorithms learn patterns from data...'
+    ]
+  }
+)
+
+# Answer generation span
+answer_span = workflow_trace.span(
+  name: 'answer-generation',
+  input: {
+    question: 'What is machine learning?',
+    context: [
+      'Machine learning is a subset of artificial intelligence...',
+      'ML algorithms learn patterns from data...'
+    ]
+  }
+)
+
+# LLM generation for answer
+answer_gen = answer_span.generation(
+  name: 'openai-completion',
+  model: 'gpt-3.5-turbo',
+  input: [
+    {
+      role: 'system',
+      content: "Answer the user's question based on the provided context."
+    },
+    {
+      role: 'user',
+      content: 'What is machine learning? Context: Machine learning is a subset of artificial intelligence... ML algorithms learn patterns from data...'
+    }
+  ],
+  output: {
+    content: 'Machine learning is a subset of artificial intelligence that enables computers to learn and improve from experience without being explicitly programmed. ML algorithms identify patterns in data and use these patterns to make predictions or decisions.'
+  },
+  usage: {
+    prompt_tokens: 85,
+    completion_tokens: 45,
+    total_tokens: 130
+  }
+)
+
+answer_span.end(
+  output: {
+    answer: 'Machine learning is a subset of artificial intelligence that enables computers to learn and improve from experience without being explicitly programmed. ML algorithms identify patterns in data and use these patterns to make predictions or decisions.'
+  }
+)
+
+# Update workflow trace
+workflow_trace.update(
+  output: {
+    answer: 'Machine learning is a subset of artificial intelligence that enables computers to learn and improve from experience without being explicitly programmed. ML algorithms identify patterns in data and use these patterns to make predictions or decisions.'
+  }
+)
+
+puts "Workflow trace URL: #{workflow_trace.get_url}"
+
+# Example 3: Adding scores and evaluations
+puts "\n⭐ Example 3: Adding scores and evaluations"
+
+# Score the generation quality
+answer_gen.score(
+  name: 'accuracy',
+  value: 0.9,
+  comment: 'Highly accurate answer based on context'
+)
+
+answer_gen.score(
+  name: 'helpfulness',
+  value: 0.85,
+  comment: 'Very helpful and informative response'
+)
+
+# Score the entire workflow
+workflow_trace.score(
+  name: 'user-satisfaction',
+  value: 0.95,
+  comment: 'User was very satisfied with the answer'
+)
+
+puts 'Added scores to generation and trace'
+
+# Example 4: Error handling
+puts "\n🚨 Example 4: Error handling"
+
+begin
+  error_trace = client.trace(name: 'error-example')
+
+  error_gen = error_trace.generation(
+    name: 'failed-generation',
+    model: 'gpt-3.5-turbo',
+    input: [{ role: 'user', content: 'This will fail' }],
+    level: 'ERROR',
+    status_message: 'Rate limit exceeded'
+  )
+
+  puts "Created error trace: #{error_trace.id}"
+rescue Langfuse::RateLimitError => e
+  puts "Rate limit error: #{e.message}"
+rescue Langfuse::APIError => e
+  puts "API error: #{e.message}"
+end
+
+# Flush all events
+puts "\n🔄 Flushing events..."
+client.flush
+
+puts "\n✅ Basic tracing example completed!"
+puts 'Check your Langfuse dashboard to see the traces.'
+
+# Shutdown client
+client.shutdown

data/examples/prompt_management.rb

@@ -0,0 +1,283 @@
+#!/usr/bin/env ruby
+
+require 'langfuse'
+
+# Initialize the Langfuse client
+client = Langfuse.new(
+  public_key: ENV['LANGFUSE_PUBLIC_KEY'],
+  secret_key: ENV['LANGFUSE_SECRET_KEY'],
+  host: ENV['LANGFUSE_HOST'] || 'https://cloud.langfuse.com'
+)
+
+puts "🚀 Starting prompt management example..."
+
+# Example 1: Create and use text prompts
+puts "\n📝 Example 1: Create and use text prompts"
+
+begin
+  # Create a text prompt
+  text_prompt = client.create_prompt(
+    name: "greeting-prompt",
+    prompt: "Hello {{user_name}}! Welcome to {{service_name}}. How can I help you with {{topic}} today?",
+    labels: ["greeting", "customer-service"],
+    config: {
+      temperature: 0.7,
+      max_tokens: 100
+    }
+  )
+
+  puts "Created text prompt: #{text_prompt.name} (Version: #{text_prompt.version})"
+
+rescue Langfuse::APIError => e
+  puts "Note: Prompt might already exist - #{e.message}"
+end
+
+# Get and use the prompt
+begin
+  prompt = client.get_prompt("greeting-prompt")
+
+  # Compile prompt with variables
+  compiled_text = prompt.compile(
+    user_name: "Alice",
+    service_name: "AI Assistant",
+    topic: "machine learning"
+  )
+
+  puts "Compiled prompt: #{compiled_text}"
+
+rescue Langfuse::APIError => e
+  puts "Could not retrieve prompt: #{e.message}"
+end
+
+# Example 2: Create and use chat prompts
+puts "\n💬 Example 2: Create and use chat prompts"
+
+begin
+  # Create a chat prompt
+  chat_prompt = client.create_prompt(
+    name: "ai-assistant-chat",
+    prompt: [
+      {
+        role: "system",
+        content: "You are a helpful AI assistant specialized in {{domain}}. Always be {{tone}} and provide {{detail_level}} answers."
+      },
+      {
+        role: "user",
+        content: "{{user_message}}"
+      }
+    ],
+    labels: ["chat", "assistant", "ai"],
+    config: {
+      temperature: 0.8,
+      max_tokens: 200
+    }
+  )
+
+  puts "Created chat prompt: #{chat_prompt.name}"
+
+rescue Langfuse::APIError => e
+  puts "Note: Chat prompt might already exist - #{e.message}"
+end
+
+# Get and use the chat prompt
+begin
+  chat_prompt = client.get_prompt("ai-assistant-chat")
+
+  # Compile chat prompt with variables
+  compiled_messages = chat_prompt.compile(
+    domain: "software development",
+    tone: "friendly and professional",
+    detail_level: "detailed",
+    user_message: "How do I implement a REST API in Ruby?"
+  )
+
+  puts "Compiled chat messages:"
+  compiled_messages.each_with_index do |message, index|
+    puts "  #{index + 1}. #{message[:role]}: #{message[:content]}"
+  end
+
+rescue Langfuse::APIError => e
+  puts "Could not retrieve chat prompt: #{e.message}"
+end
+
+# Example 3: Using prompt templates
+puts "\n🎨 Example 3: Using prompt templates"
+
+# Create a reusable text template
+translation_template = Langfuse::PromptTemplate.from_template(
+  "Translate the following {{source_language}} text to {{target_language}}:\n\n{{text}}\n\nTranslation:"
+)
+
+puts "Template variables: #{translation_template.input_variables}"
+
+# Use the template
+translated_prompt = translation_template.format(
+  source_language: "English",
+  target_language: "Spanish",
+  text: "Hello, how are you today?"
+)
+
+puts "Translation prompt: #{translated_prompt}"
+
+# Create a reusable chat template
+coding_template = Langfuse::ChatPromptTemplate.from_messages([
+  {
+    role: "system",
+    content: "You are an expert {{language}} developer. Provide clean, well-commented code examples."
+  },
+  {
+    role: "user",
+    content: "{{request}}"
+  }
+])
+
+puts "Chat template variables: #{coding_template.input_variables}"
+
+# Use the chat template
+coding_messages = coding_template.format(
+  language: "Ruby",
+  request: "Show me how to create a simple HTTP server"
+)
+
+puts "Coding chat messages:"
+coding_messages.each_with_index do |message, index|
+  puts "  #{index + 1}. #{message[:role]}: #{message[:content]}"
+end
+
+# Example 4: Prompt versioning and caching
+puts "\n🔄 Example 4: Prompt versioning and caching"
+
+# Get specific version of a prompt
+begin
+  versioned_prompt = client.get_prompt("greeting-prompt", version: 1)
+  puts "Retrieved prompt version: #{versioned_prompt.version}"
+
+  # Get latest version (cached)
+  latest_prompt = client.get_prompt("greeting-prompt")
+  puts "Latest prompt version: #{latest_prompt.version}"
+
+  # Get with label
+  labeled_prompt = client.get_prompt("greeting-prompt", label: "production")
+  puts "Labeled prompt: #{labeled_prompt.labels}"
+
+rescue Langfuse::APIError => e
+  puts "Could not retrieve versioned prompt: #{e.message}"
+end
+
+# Example 5: Using prompts in tracing
+puts "\n🔗 Example 5: Using prompts in tracing"
+
+begin
+  # Get a prompt for use in generation
+  system_prompt = client.get_prompt("ai-assistant-chat")
+
+  # Create a trace
+  trace = client.trace(
+    name: "prompt-based-chat",
+    user_id: "user-789",
+    input: { message: "Explain Ruby blocks" }
+  )
+
+  # Compile the prompt
+  messages = system_prompt.compile(
+    domain: "Ruby programming",
+    tone: "educational and clear",
+    detail_level: "beginner-friendly",
+    user_message: "Explain Ruby blocks"
+  )
+
+  # Create generation with prompt
+  generation = trace.generation(
+    name: "openai-chat-with-prompt",
+    model: "gpt-3.5-turbo",
+    input: messages,
+    output: {
+      content: "Ruby blocks are pieces of code that can be passed to methods. They're defined using either do...end or curly braces {}. Blocks are commonly used with iterators like .each, .map, and .select."
+    },
+    usage: {
+      prompt_tokens: 45,
+      completion_tokens: 35,
+      total_tokens: 80
+    },
+    metadata: {
+      prompt_name: system_prompt.name,
+      prompt_version: system_prompt.version
+    }
+  )
+
+  puts "Created generation with prompt: #{generation.id}"
+  puts "Trace URL: #{trace.get_url}"
+
+rescue Langfuse::APIError => e
+  puts "Could not use prompt in tracing: #{e.message}"
+end
+
+# Example 6: Advanced prompt features
+puts "\n🎯 Example 6: Advanced prompt features"
+
+# Create a prompt with complex templating
+begin
+  complex_prompt = client.create_prompt(
+    name: "code-review-prompt",
+    prompt: {
+      system: "You are a senior {{language}} developer reviewing code. Focus on {{review_aspects}}.",
+      user: "Please review this {{language}} code:\n\n```{{language}}\n{{code}}\n```\n\nProvide feedback on: {{specific_feedback}}"
+    },
+    labels: ["code-review", "development"],
+    config: {
+      temperature: 0.3,
+      max_tokens: 500
+    }
+  )
+
+  puts "Created complex prompt: #{complex_prompt.name}"
+
+rescue Langfuse::APIError => e
+  puts "Note: Complex prompt might already exist - #{e.message}"
+end
+
+# Create a prompt with conditional logic (using Ruby)
+class ConditionalPrompt
+  def self.generate(user_level:, topic:, include_examples: true)
+    base_prompt = "Explain {{topic}} for a {{user_level}} audience."
+
+    if include_examples
+      base_prompt += " Include practical examples."
+    end
+
+    if user_level == "beginner"
+      base_prompt += " Use simple language and avoid jargon."
+    elsif user_level == "advanced"
+      base_prompt += " Feel free to use technical terminology."
+    end
+
+    base_prompt
+  end
+end
+
+conditional_prompt_text = ConditionalPrompt.generate(
+  user_level: "beginner",
+  topic: "machine learning",
+  include_examples: true
+)
+
+puts "Conditional prompt: #{conditional_prompt_text}"
+
+# Use with template
+conditional_template = Langfuse::PromptTemplate.from_template(conditional_prompt_text)
+formatted_prompt = conditional_template.format(
+  topic: "neural networks",
+  user_level: "beginner"
+)
+
+puts "Formatted conditional prompt: #{formatted_prompt}"
+
+# Flush events
+puts "\n🔄 Flushing events..."
+client.flush
+
+puts "\n✅ Prompt management example completed!"
+puts "Check your Langfuse dashboard to see the prompts and traces."
+
+# Shutdown client
+client.shutdown

data/langfuse-ruby.gemspec

@@ -0,0 +1,51 @@
+require_relative 'lib/langfuse/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'langfuse-ruby'
+  spec.version       = Langfuse::VERSION
+  spec.authors       = ['Your Name']
+  spec.email         = ['your.email@example.com']
+  spec.summary       = 'Ruby SDK for Langfuse - Open source LLM engineering platform'
+  spec.description   = 'Ruby client library for Langfuse, providing tracing, prompt management, and evaluation capabilities for LLM applications'
+  spec.homepage      = 'https://github.com/your-username/langfuse-ruby'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.7.0'
+
+  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/your-username/langfuse-ruby'
+  spec.metadata['changelog_uri'] = 'https://github.com/your-username/langfuse-ruby/blob/main/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    if File.exist?('.git')
+      `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+    else
+      Dir.glob('**/*').reject do |f|
+        File.directory?(f) ||
+          f.match(%r{\A(?:test|spec|features)/}) ||
+          f.match(/\A\./) ||
+          f.match(/\.gem$/) ||
+          f.match(/test_.*\.rb$/)
+      end
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Dependencies
+  spec.add_dependency 'concurrent-ruby', '~> 1.0'
+  spec.add_dependency 'faraday', '~> 2.0'
+  spec.add_dependency 'faraday-net_http', '~> 3.0'
+  spec.add_dependency 'json', '~> 2.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'vcr', '~> 6.0'
+  spec.add_development_dependency 'webmock', '~> 3.0'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end