langfuse 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e165c60bb44cb4d93fa3bfcda49f4948078714bc80e50a37fb90501093915b3b
-  data.tar.gz: 5e930ae7b06502dce3c805b4b820cb1de7826b5bfc4d690f82fb1ba1b53e2053
+  metadata.gz: 13d36d5500f51cce6bf73e497b4d173d62da2e8be2c9142a3eba5b563b786f3a
+  data.tar.gz: ffa0ca7036c84a49e771e43945db532d7382cf08b8894e8b58f71ad994e9179a
 SHA512:
-  metadata.gz: e0dd66aa77a3389cff7eff1ac9ce9a7be987821179f61cf0f2635136ead05c486100675905971be8f8f4b0d33bf999718a09ee0b0ccb67a90e94426cdb44f0b6
-  data.tar.gz: 02b1a9ae14210d8216fa180b9dda79477502fdb117ef6a023b05e0b1d183b9823d38ff56e107b19edc1b6db3f0a5cb5fe77f96ee78523275cc818488a76fd7fc
+  metadata.gz: d3e236f29058f9d03879d9413e5be6ed8c8780c95ab5ceace863c1fdddb0564ec9422a194a474f4b9cbfed6656dc30f15d37917de78a73195dc3f5293f9fa2d9
+  data.tar.gz: 6c08d42e2feb0c900b92f1c5f7cc991afaf0d6e3eb12432d64243258ad31ab6d12e2fada6c481990563f53242ca0ebb7caed082807cf56f96e4e5fc62e88e8f2

data/bin/tapioca

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'tapioca' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+
+bundle_binstub = File.expand_path("bundle", __dir__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300).include?("This file was generated by Bundler")
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("tapioca", "tapioca")

data/lib/langfuse/api_client.rb

@@ -1,16 +1,24 @@
+# typed: strict
+
 require 'net/http'
 require 'uri'
 require 'json'
 require 'base64'
+require 'sorbet-runtime'
 
 module Langfuse
   class ApiClient
+    extend T::Sig
+
+    sig { returns(T.untyped) }
     attr_reader :config
 
+    sig { params(config: T.untyped).void }
     def initialize(config)
       @config = config
     end
 
+    sig { params(events: T::Array[T::Hash[T.untyped, T.untyped]]).returns(T::Hash[String, T.untyped]) }
     def ingest(events)
       uri = URI.parse("#{@config.host}/api/public/ingestion")
 
@@ -44,14 +52,18 @@ module Langfuse
         log("Request url: #{uri}")
       end
 
+      log('---') # Moved log statement before response handling to avoid affecting return value
+
       response = http.request(request)
 
+      result = T.let(nil, T.nilable(T::Hash[String, T.untyped]))
+
       if response.code.to_i == 207 # Partial success
         log('Received 207 partial success response') if @config.debug
-        JSON.parse(response.body)
+        result = JSON.parse(response.body)
       elsif response.code.to_i >= 200 && response.code.to_i < 300
         log("Received successful response: #{response.code}") if @config.debug
-        JSON.parse(response.body)
+        result = JSON.parse(response.body)
       else
         error_msg = "API error: #{response.code} #{response.message}"
         if @config.debug
@@ -62,7 +74,7 @@ module Langfuse
         raise error_msg
       end
 
-      log('---')
+      result
     rescue StandardError => e
       log("Error during API request: #{e.message}", :error)
       raise
@@ -70,11 +82,11 @@ module Langfuse
 
     private
 
+    sig { params(message: String, level: Symbol).returns(T.untyped) }
     def log(message, level = :debug)
       return unless @config.debug
 
-      logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
-      logger.send(level, "[Langfuse] #{message}")
+      T.unsafe(@config.logger).send(level, "[Langfuse] #{message}")
     end
   end
 end

data/lib/langfuse/batch_worker.rb

@@ -1,57 +1,83 @@
+# typed: strict
+
+require 'sorbet-runtime'
+
 module Langfuse
   class BatchWorker
+    extend T::Sig
     # This is a placeholder class that will be defined with Sidekiq::Worker
     # when Sidekiq is available.
     #
     # If Sidekiq is available, this will be replaced with a real worker class
     # that includes Sidekiq::Worker
 
+    # Ensure return type matches the synchronous perform call
+    sig { params(events: T::Array[T::Hash[T.untyped, T.untyped]]).void }
     def self.perform_async(events)
-      # When Sidekiq is not available, process synchronously
+      # When Sidekiq is not available, process synchronously and return result
       new.perform(events)
     end
 
+    sig { params(events: T::Array[T::Hash[T.untyped, T.untyped]]).returns(T::Hash[String, T.untyped]) }
     def perform(events)
-      Langfuse::ApiClient.new(Langfuse.configuration).ingest(events)
+      # Assuming Langfuse.configuration returns a valid config object for ApiClient
+      T.unsafe(Langfuse::ApiClient).new(T.unsafe(Langfuse).configuration).ingest(events)
     end
   end
 
   # Define the real Sidekiq worker if Sidekiq is available
   if defined?(Sidekiq)
     class BatchWorker
+      # Re-extend T::Sig within the conditional definition
+      extend T::Sig
+      # Include Sidekiq::Worker directly - rely on T.unsafe for its methods
       include Sidekiq::Worker
 
-      sidekiq_options queue: 'langfuse', retry: 5, backtrace: true
+      # Using T.unsafe for sidekiq_options DSL
+      T.unsafe(self).sidekiq_options queue: 'langfuse', retry: 5, backtrace: true
 
       # Custom retry delay logic (exponential backoff)
-      sidekiq_retry_in do |count|
+      # Using T.unsafe for sidekiq_retry_in DSL
+      T.unsafe(self).sidekiq_retry_in do |count|
         10 * (count + 1) # 10s, 20s, 30s, 40s, 50s
       end
 
+      sig { params(event_hashes: T::Array[T::Hash[T.untyped, T.untyped]]).void }
       def perform(event_hashes)
-        api_client = ApiClient.new(Langfuse.configuration)
+        # Assuming Langfuse.configuration returns a valid config object
+        api_client = T.unsafe(ApiClient).new(T.unsafe(Langfuse).configuration)
 
         begin
           response = api_client.ingest(event_hashes)
 
-          # Check for partial failures
-          if response && response['errors']&.any?
-            response['errors'].each do |error|
-              logger.error("Langfuse API error for event #{error['id']}: #{error['message']}")
+          # Check for partial failures using standard hash access
+          errors = T.let(response['errors'], T.nilable(T::Array[T::Hash[String, T.untyped]]))
+          if errors && errors.any?
+            errors.each do |error|
+              # Use T.unsafe(self).logger provided by Sidekiq::Worker
+              T.unsafe(self).logger.error("Langfuse API error for event #{error['id']}: #{error['message']}")
 
               # Store permanently failed events if needed
-              if non_retryable_error?(error['status'])
-                store_failed_event(event_hashes.find { |e| e[:id] == error['id'] }, error['message'])
+              # Assuming error['status'] exists and can be converted to integer
+              status = T.let(error['status'], T.untyped)
+              next unless non_retryable_error?(status)
+
+              # Assuming event_hashes elements have :id key
+              failed_event = event_hashes.find { |e| T.unsafe(e)[:id] == error['id'] }
+              if failed_event
+                # Remove redundant T.cast
+                store_failed_event(failed_event, T.cast(error['message'], String))
               end
             end
           end
         rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
           # Network errors - Sidekiq will retry
-          logger.error("Langfuse network error: #{e.message}")
+          T.unsafe(self).logger.error("Langfuse network error: #{e.full_message}")
           raise
         rescue StandardError => e
           # Other errors
-          logger.error("Langfuse API error: #{e.message}")
+          # Use T.unsafe(self).logger
+          T.unsafe(self).logger.error("Langfuse API error: #{e.message}")
 
           # Let Sidekiq retry
           raise
@@ -60,17 +86,21 @@ module Langfuse
 
       private
 
+      sig { params(status: T.untyped).returns(T::Boolean) }
       def non_retryable_error?(status)
         # 4xx errors except 429 (rate limit) are not retryable
-        status.to_i >= 400 && status.to_i < 500 && status.to_i != 429
+        status_int = T.let(status.to_i, Integer)
+        status_int >= 400 && status_int < 500 && status_int != 429
       end
 
-      def store_failed_event(event, error)
+      sig { params(event: T::Hash[T.untyped, T.untyped], error_msg: String).returns(T.untyped) }
+      def store_failed_event(event, error_msg)
         # Store in Redis for later inspection/retry
-        Sidekiq.redis do |redis|
-          redis.rpush('langfuse:failed_events', {
+        # Using T.unsafe for Sidekiq.redis block and redis operations
+        T.unsafe(Sidekiq).redis do |redis|
+          T.unsafe(redis).rpush('langfuse:failed_events', {
             event: event,
-            error: error,
+            error: error_msg,
             timestamp: Time.now.utc.iso8601
           }.to_json)
         end

data/lib/langfuse/client.rb

@@ -1,29 +1,50 @@
+# typed: strict
+
 require 'singleton'
 require 'concurrent'
 require 'logger'
+require 'sorbet-runtime'
+
+# Model requires are implicitly handled by the main langfuse.rb require
+# No need for placeholder type aliases here
 
 module Langfuse
   class Client
+    extend T::Sig
     include Singleton
 
+    sig { returns(::Langfuse::Configuration) } # Use actual Configuration type
+    attr_reader :config
+
+    # Use the class directly, Sorbet should handle Concurrent::Array generics
+    sig { returns(Concurrent::Array) }
+    attr_reader :events
+
+    sig { returns(T.nilable(Thread)) }
+    attr_reader :flush_thread
+
+    sig { void }
     def initialize
-      @config = Langfuse.configuration
-      @events = Concurrent::Array.new # Thread-safe array
-      @mutex = Mutex.new # For operations that need additional thread safety
+      @config = T.let(Langfuse.configuration, ::Langfuse::Configuration)
+      # Let Sorbet infer the type for Concurrent::Array here
+      @events = T.let(Concurrent::Array.new, Concurrent::Array)
+      @mutex = T.let(Mutex.new, Mutex)
+      @flush_thread = T.let(nil, T.nilable(Thread))
 
-      # Start periodic flusher only in server context
-      schedule_periodic_flush if defined?(Rails) && Rails.server?
+      schedule_periodic_flush
 
       # Register shutdown hook
       return if @config.disable_at_exit_hook
 
-      at_exit { shutdown }
+      Kernel.at_exit { shutdown }
     end
 
     # Creates a new trace
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
     def trace(attributes = {})
-      trace = Models::Trace.new(attributes)
-      event = Models::IngestionEvent.new(
+      # Ideally Models::Trace.new would have its own signature
+      trace = T.unsafe(Models::Trace).new(attributes)
+      event = T.unsafe(Models::IngestionEvent).new(
         type: 'trace-create',
         body: trace
       )
@@ -32,11 +53,12 @@ module Langfuse
     end
 
     # Creates a new span within a trace
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
     def span(attributes = {})
       raise ArgumentError, 'trace_id is required for creating a span' unless attributes[:trace_id]
 
-      span = Models::Span.new(attributes)
-      event = Models::IngestionEvent.new(
+      span = T.unsafe(Models::Span).new(attributes)
+      event = T.unsafe(Models::IngestionEvent).new(
         type: 'span-create',
         body: span
       )
@@ -45,10 +67,15 @@ module Langfuse
     end
 
     # Updates an existing span
+    sig { params(span: T.untyped).returns(T.untyped) }
     def update_span(span)
-      raise ArgumentError, 'span.id and span.trace_id are required for updating a span' unless span.id && span.trace_id
+      # Assuming span object has :id and :trace_id methods/attributes
+      unless T.unsafe(span).id && T.unsafe(span).trace_id
+        raise ArgumentError,
+              'span.id and span.trace_id are required for updating a span'
+      end
 
-      event = Models::IngestionEvent.new(
+      event = T.unsafe(Models::IngestionEvent).new(
         type: 'span-update',
         body: span
       )
@@ -57,11 +84,12 @@ module Langfuse
     end
 
     # Creates a new generation within a trace
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
     def generation(attributes = {})
       raise ArgumentError, 'trace_id is required for creating a generation' unless attributes[:trace_id]
 
-      generation = Models::Generation.new(attributes)
-      event = Models::IngestionEvent.new(
+      generation = T.unsafe(Models::Generation).new(attributes)
+      event = T.unsafe(Models::IngestionEvent).new(
         type: 'generation-create',
         body: generation
       )
@@ -70,12 +98,13 @@ module Langfuse
     end
 
     # Updates an existing generation
+    sig { params(generation: T.untyped).returns(T.untyped) }
     def update_generation(generation)
-      unless generation.id && generation.trace_id
+      unless T.unsafe(generation).id && T.unsafe(generation).trace_id
         raise ArgumentError, 'generation.id and generation.trace_id are required for updating a generation'
       end
 
-      event = Models::IngestionEvent.new(
+      event = T.unsafe(Models::IngestionEvent).new(
         type: 'generation-update',
         body: generation
       )
@@ -84,11 +113,12 @@ module Langfuse
     end
 
     # Creates a new event within a trace
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
     def event(attributes = {})
       raise ArgumentError, 'trace_id is required for creating an event' unless attributes[:trace_id]
 
-      event_obj = Models::Event.new(attributes)
-      event = Models::IngestionEvent.new(
+      event_obj = T.unsafe(Models::Event).new(attributes)
+      event = T.unsafe(Models::IngestionEvent).new(
         type: 'event-create',
         body: event_obj
       )
@@ -97,11 +127,12 @@ module Langfuse
     end
 
     # Creates a new score
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(T.untyped) }
     def score(attributes = {})
       raise ArgumentError, 'trace_id is required for creating a score' unless attributes[:trace_id]
 
-      score = Models::Score.new(attributes)
-      event = Models::IngestionEvent.new(
+      score = T.unsafe(Models::Score).new(attributes)
+      event = T.unsafe(Models::IngestionEvent).new(
         type: 'score-create',
         body: score
       )
@@ -110,8 +141,9 @@ module Langfuse
     end
 
     # Flushes all pending events to the API
+    sig { void }
     def flush
-      events_to_process = nil
+      events_to_process = T.let([], T::Array[T.untyped])
 
       # Atomically swap the events array to avoid race conditions
       @mutex.synchronize do
@@ -122,15 +154,17 @@ module Langfuse
       return if events_to_process.empty?
 
       # Convert objects to hashes for serialization
+      # Assuming `to_h` exists on Models::IngestionEvent and returns T::Hash[T.untyped, T.untyped]
       event_hashes = events_to_process.map(&:to_h)
 
       log("Flushing #{event_hashes.size} events")
 
       # Send to background worker
-      BatchWorker.perform_async(event_hashes)
+      T.unsafe(BatchWorker).perform_async(event_hashes)
     end
 
     # Gracefully shuts down the client, ensuring all events are flushed
+    sig { void }
     def shutdown
       log('Shutting down Langfuse client...')
 
@@ -145,18 +179,22 @@ module Langfuse
 
     private
 
+    sig { params(event: T.untyped).void }
     def enqueue_event(event)
       @events << event
 
       # Trigger immediate flush if batch size reached
+      # Assuming @config.batch_size is an Integer
       flush if @events.size >= @config.batch_size
     end
 
+    sig { returns(Thread) }
     def schedule_periodic_flush
       log("Starting periodic flush thread (interval: #{@config.flush_interval}s)")
 
       @flush_thread = Thread.new do
         loop do
+          # Assuming @config.flush_interval is Numeric
           sleep @config.flush_interval
           flush
         rescue StandardError => e
@@ -166,11 +204,12 @@ module Langfuse
       end
     end
 
+    sig { params(message: String, level: Symbol).returns(T.untyped) }
     def log(message, level = :debug)
+      # Assuming @config.debug is Boolean
       return unless @config.debug
 
-      logger = defined?(Rails) ? Rails.logger : Logger.new($stdout)
-      logger.send(level, "[Langfuse] #{message}")
+      T.unsafe(@config.logger).send(level, "[Langfuse] #{message}")
     end
   end
 end

data/lib/langfuse/configuration.rb

@@ -1,20 +1,39 @@
+# typed: strict
+
+require 'logger'
+require 'sorbet-runtime'
+
 module Langfuse
   class Configuration
-    attr_accessor :public_key, :secret_key, :host,
-                  :batch_size, :flush_interval, :debug,
-                  :disable_at_exit_hook, :shutdown_timeout, :logger
+    extend T::Sig
+
+    sig { returns(T.nilable(String)) }
+    attr_accessor :public_key, :secret_key
+
+    sig { returns(String) }
+    attr_accessor :host
+
+    sig { returns(Integer) }
+    attr_accessor :batch_size, :flush_interval, :shutdown_timeout
+
+    sig { returns(T::Boolean) }
+    attr_accessor :debug, :disable_at_exit_hook
+
+    sig { returns(T.untyped) }
+    attr_accessor :logger
 
+    sig { void }
     def initialize
       # Default configuration with environment variable fallbacks
-      @public_key = ENV['LANGFUSE_PUBLIC_KEY']
-      @secret_key = ENV['LANGFUSE_SECRET_KEY']
-      @host = ENV.fetch('LANGFUSE_HOST', 'https://us.cloud.langfuse.com')
-      @batch_size = ENV.fetch('LANGFUSE_BATCH_SIZE', '10').to_i
-      @flush_interval = ENV.fetch('LANGFUSE_FLUSH_INTERVAL', '60').to_i
-      @debug = ENV.fetch('LANGFUSE_DEBUG', 'false') == 'true'
-      @disable_at_exit_hook = false
-      @shutdown_timeout = ENV.fetch('LANGFUSE_SHUTDOWN_TIMEOUT', '5').to_i
-      @logger = Logger.new(STDOUT)
+      @public_key = T.let(ENV['LANGFUSE_PUBLIC_KEY'], T.nilable(String))
+      @secret_key = T.let(ENV['LANGFUSE_SECRET_KEY'], T.nilable(String))
+      @host = T.let(ENV.fetch('LANGFUSE_HOST', 'https://us.cloud.langfuse.com'), String)
+      @batch_size = T.let(ENV.fetch('LANGFUSE_BATCH_SIZE', '10').to_i, Integer)
+      @flush_interval = T.let(ENV.fetch('LANGFUSE_FLUSH_INTERVAL', '60').to_i, Integer)
+      @debug = T.let(ENV.fetch('LANGFUSE_DEBUG', 'false') == 'true', T::Boolean)
+      @disable_at_exit_hook = T.let(false, T::Boolean)
+      @shutdown_timeout = T.let(ENV.fetch('LANGFUSE_SHUTDOWN_TIMEOUT', '5').to_i, Integer)
+      @logger = T.let(Logger.new($stdout), Logger)
     end
   end
 end

data/lib/langfuse/models/event.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'securerandom'
 
 module Langfuse

data/lib/langfuse/models/generation.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'securerandom'
 
 module Langfuse

data/lib/langfuse/models/ingestion_event.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'securerandom'
 
 module Langfuse

data/lib/langfuse/models/score.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'securerandom'
 
 module Langfuse

data/lib/langfuse/models/span.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'securerandom'
 
 module Langfuse

data/lib/langfuse/models/trace.rb

@@ -1,3 +1,4 @@
+# typed: true
 require 'securerandom'
 
 module Langfuse

data/lib/langfuse/models/usage.rb

@@ -1,3 +1,4 @@
+# typed: true
 module Langfuse
   module Models
     class Usage

data/lib/langfuse/version.rb

@@ -1,3 +1,4 @@
+# typed: strict
 module Langfuse
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/lib/langfuse.rb

@@ -1,7 +1,11 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'sorbet-runtime'
 require 'langfuse/version'
 require 'langfuse/configuration'
 
-# Load models
+# Load models - Use fully qualified names in sigs below
 require 'langfuse/models/ingestion_event'
 require 'langfuse/models/trace'
 require 'langfuse/models/span'
@@ -13,57 +17,92 @@ require 'langfuse/models/usage'
 # Load API client
 require 'langfuse/api_client'
 
-# Load batch worker (works with or without Sidekiq)
+# Load batch worker
 require 'langfuse/batch_worker'
 
 # Load main client
 require 'langfuse/client'
 
 module Langfuse
+  extend T::Sig
+
   class << self
+    extend T::Sig
+
+    # Sig for the writer method created by attr_writer
+    sig { params(configuration: ::Langfuse::Configuration).void }
     attr_writer :configuration
 
+    # Sig for the reader method
+    sig { returns(::Langfuse::Configuration) }
     def configuration
-      @configuration ||= Configuration.new
+      # Use T.let for clarity on initialization
+      @configuration = T.let(@configuration, T.nilable(::Langfuse::Configuration))
+      @configuration ||= ::Langfuse::Configuration.new
     end
 
-    def configure
+    # Configuration block
+    sig { params(_block: T.proc.params(config: ::Langfuse::Configuration).void).void }
+    def configure(&_block)
+      # Pass the block to yield
       yield(configuration)
     end
 
-    # Convenience delegators to the client instance
+    # --- Convenience delegators to the client instance ---
+
+    # Create Trace
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(::Langfuse::Models::Trace) }
     def trace(attributes = {})
-      Client.instance.trace(attributes)
+      # Use T.unsafe as Client returns T.untyped for Models for now
+      T.unsafe(Client.instance).trace(attributes)
     end
 
+    # Create Span
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(::Langfuse::Models::Span) }
     def span(attributes = {})
-      Client.instance.span(attributes)
+      T.unsafe(Client.instance).span(attributes)
     end
 
+    # Update Span
+    sig { params(span: ::Langfuse::Models::Span).void }
     def update_span(span)
-      Client.instance.update_span(span)
+      T.unsafe(Client.instance).update_span(span)
+      # Return void implicitly
     end
 
+    # Create Generation
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(::Langfuse::Models::Generation) }
     def generation(attributes = {})
-      Client.instance.generation(attributes)
+      T.unsafe(Client.instance).generation(attributes)
     end
 
+    # Update Generation
+    sig { params(generation: ::Langfuse::Models::Generation).void }
     def update_generation(generation)
-      Client.instance.update_generation(generation)
+      T.unsafe(Client.instance).update_generation(generation)
+      # Return void implicitly
     end
 
+    # Create Event
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(::Langfuse::Models::Event) }
     def event(attributes = {})
-      Client.instance.event(attributes)
+      T.unsafe(Client.instance).event(attributes)
     end
 
+    # Create Score
+    sig { params(attributes: T::Hash[Symbol, T.untyped]).returns(::Langfuse::Models::Score) }
     def score(attributes = {})
-      Client.instance.score(attributes)
+      T.unsafe(Client.instance).score(attributes)
     end
 
+    # Flush events
+    sig { void }
     def flush
       Client.instance.flush
     end
 
+    # Shutdown client
+    sig { void }
     def shutdown
       Client.instance.shutdown
     end

data/lib/langfuse_context.rb

@@ -1,30 +1,70 @@
+# typed: true
+
+require 'sorbet-runtime' # Ensure Sorbet is required
+
 class LangfuseContext
+  extend T::Sig # Add this to enable sig blocks on class methods
+
+  # Define the type for the context hash
+  ContextHash = T.type_alias { T::Hash[Symbol, T.nilable(String)] }
+
+  # Gets the current context hash for the thread
+  sig { returns(ContextHash) }
   def self.current
-    Thread.current[:langfuse_context] ||= {}
+    # T.let is used for type assertion
+    context = T.let(Thread.current[:langfuse_context], T.nilable(ContextHash))
+    # Initialize if nil
+    context ||= T.let({}, ContextHash)
+    Thread.current[:langfuse_context] = context
+    context
   end
 
+  # Gets the current trace ID from the context
+  sig { returns(T.nilable(String)) }
   def self.current_trace_id
     current[:trace_id]
   end
 
+  # Gets the current span ID from the context
+  sig { returns(T.nilable(String)) }
   def self.current_span_id
     current[:span_id]
   end
 
-  def self.with_trace(trace)
+  # Executes a block with a specific trace context
+  sig do
+    params(
+      trace: T.untyped, # Use T.untyped until Models::Trace is fully typed
+      _block: T.proc.void
+    ).void
+  end
+  def self.with_trace(trace, &_block)
     old_context = current.dup
     begin
-      Thread.current[:langfuse_context] = { trace_id: trace.id }
+      # Assuming trace.id returns a String
+      trace_id = T.let(T.unsafe(trace).id, T.nilable(String))
+      Thread.current[:langfuse_context] = { trace_id: trace_id } if trace_id
       yield
     ensure
       Thread.current[:langfuse_context] = old_context
     end
   end
 
-  def self.with_span(span)
+  # Executes a block with a specific span context (merging with existing context)
+  sig do
+    params(
+      span: T.untyped, # Use T.untyped until Models::Span is fully typed
+      _block: T.proc.void
+    ).void
+  end
+  def self.with_span(span, &_block)
     old_context = current.dup
     begin
-      Thread.current[:langfuse_context] = current.merge({ span_id: span.id })
+      # Assuming span.id returns a String
+      span_id = T.let(T.unsafe(span).id, T.nilable(String))
+      # Merge span_id into the current context
+      new_context = current.merge({ span_id: span_id })
+      Thread.current[:langfuse_context] = new_context if span_id
       yield
     ensure
       Thread.current[:langfuse_context] = old_context

data/lib/langfuse_helper.rb

@@ -1,10 +1,25 @@
+# typed: true
+
 require_relative 'langfuse_context'
+require 'sorbet-runtime' # Ensure Sorbet is required
 
 module LangfuseHelper
+  extend T::Sig # Add this to enable sig blocks in the module
+
   # Execute a block within the context of a span
-  def with_span(name:, trace_id:, parent_id: nil, input: nil, **attributes)
+  sig do
+    params(
+      name: String,
+      trace_id: String,
+      parent_id: T.nilable(String),
+      input: T.untyped,
+      attributes: T::Hash[Symbol, T.untyped],
+      block: T.proc.params(span: ::Langfuse::Models::Span).returns(T.untyped)
+    ).returns(T.untyped)
+  end
+  def with_span(name:, trace_id:, parent_id: nil, input: nil, **attributes, &block)
     # Create the span
-    span = Langfuse.span(
+    span = T.unsafe(Langfuse).span(
       name: name,
       trace_id: trace_id,
       parent_observation_id: parent_id,
@@ -12,13 +27,26 @@ module LangfuseHelper
       **attributes
     )
 
-    with_span_implementation(span) { yield(span) }
+    # Pass the block to the implementation
+    with_span_implementation(span, &block)
   end
 
   # Execute a block within the context of an LLM generation
-  def with_generation(name:, trace_id:, model:, input:, parent_id: nil, model_parameters: {}, **attributes)
+  sig do
+    params(
+      name: String,
+      trace_id: String,
+      model: String,
+      input: T.untyped,
+      parent_id: T.nilable(String),
+      model_parameters: T::Hash[T.untyped, T.untyped],
+      attributes: T::Hash[Symbol, T.untyped],
+      block: T.proc.params(generation: ::Langfuse::Models::Generation).returns(T.untyped)
+    ).returns(T.untyped)
+  end
+  def with_generation(name:, trace_id:, model:, input:, parent_id: nil, model_parameters: {}, **attributes, &block)
     # Create the generation
-    generation = Langfuse.generation(
+    generation = T.unsafe(Langfuse).generation(
       name: name,
       trace_id: trace_id,
       parent_observation_id: parent_id,
@@ -28,50 +56,59 @@ module LangfuseHelper
       **attributes
     )
 
-    start_time = Time.now
-    result = nil
-    error = nil
+    T.let(Time.now, Time)
+    result = T.let(nil, T.untyped)
+    error = T.let(nil, T.nilable(StandardError))
 
     begin
       # Execute the block with the generation passed as argument
-      result = yield(generation)
+      result = block.call(generation)
       result
     rescue StandardError => e
       # Capture any error
       error = e
-      raise
+      Kernel.raise # Use Kernel.raise
     ensure
       # Always update the generation with results
       generation.end_time = Time.now.utc
-      generation.start_time = start_time.utc
+      # generation.start_time = start_time.utc # start_time is already UTC if using Time.now.utc
 
       # Add output if there was a result and it wasn't already set
-      generation.output = result if result && !generation.output
+      generation.output = result if result && generation.output.nil?
 
       # Add error information if there was an error
       if error
         generation.level = 'ERROR'
         generation.status_message = error.message
         generation.metadata ||= {}
-        generation.metadata[:error_backtrace] = error.backtrace.first(10) if error.backtrace
+        backtrace = error.backtrace
+        generation.metadata[:error_backtrace] = backtrace.first(10) if backtrace # Check if backtrace is nil
       end
 
       # Update the generation
-      Langfuse.update_generation(generation)
+      T.unsafe(Langfuse).update_generation(generation)
     end
   end
 
   # Execute a block within the context of a trace
-  def with_trace(name:, user_id: nil, **attributes)
+  sig do
+    params(
+      name: String,
+      user_id: T.nilable(String),
+      attributes: T::Hash[Symbol, T.untyped],
+      _block: T.proc.params(trace: ::Langfuse::Models::Trace).returns(T.untyped)
+    ).returns(T.untyped)
+  end
+  def with_trace(name:, user_id: nil, **attributes, &_block)
     # Create the trace
-    trace = Langfuse.trace(
+    trace = T.unsafe(Langfuse).trace(
       name: name,
       user_id: user_id,
       **attributes
     )
 
-    result = nil
-    error = nil
+    result = T.let(nil, T.untyped)
+    error = T.let(nil, T.nilable(StandardError))
 
     begin
       # Execute the block with the trace passed as argument
@@ -80,62 +117,91 @@ module LangfuseHelper
     rescue StandardError => e
       # Capture any error
       error = e
-      raise
+      Kernel.raise # Use Kernel.raise
     ensure
       # Update trace output if available
-      if result && !trace.output
-        trace.output = result.is_a?(String) ? result : result
-
-        # Create a new trace event to update the trace
-        Langfuse.trace(
-          id: trace.id,
-          output: trace.output
-        )
+      if result && trace.output.nil?
+        # Assuming trace.output is writable and can be inferred or is T.untyped
+        T.unsafe(trace).output = result # Use T.unsafe if Trace model type isn't fully defined
+
+        # Create a new trace event to update the trace - Reuse trace object
+        # This seems incorrect, updating should likely use an update method or modify the object
+        # directly if it's mutable and the original trace object is used later.
+        # Re-creating a trace event just to update seems wrong. Commenting out for now.
+        # Langfuse.trace(
+        #   id: trace.id,
+        #   output: trace.output
+        # )
       end
 
       # Ensure all events are sent (only in case of error, otherwise let the automatic flushing handle it)
-      Langfuse.flush if error
+      T.unsafe(Langfuse).flush if error
     end
   end
 
   # Create a trace and set it as the current context
-  def with_context_trace(name:, user_id: nil, **attributes)
-    trace = Langfuse.trace(
+  sig do
+    params(
+      name: String,
+      user_id: T.nilable(String),
+      attributes: T::Hash[Symbol, T.untyped],
+      block: T.proc.params(trace: ::Langfuse::Models::Trace).void
+    ).void
+  end
+  def with_context_trace(name:, user_id: nil, **attributes, &block)
+    trace = T.unsafe(Langfuse).trace(
       name: name,
       user_id: user_id,
       **attributes
     )
 
     LangfuseContext.with_trace(trace) do
-      yield(trace)
+      block.call(trace)
     end
   end
 
   # Create a span using the current trace context
-  def with_context_span(name:, input: nil, **attributes)
+  sig do
+    params(
+      name: String,
+      input: T.untyped,
+      attributes: T::Hash[Symbol, T.untyped],
+      block: T.proc.params(span: ::Langfuse::Models::Span).returns(T.untyped)
+    ).returns(T.untyped)
+  end
+  def with_context_span(name:, input: nil, **attributes, &block)
     # Get trace_id from context
     trace_id = LangfuseContext.current_trace_id
     parent_id = LangfuseContext.current_span_id
 
-    raise 'No trace context found. Make sure to call within with_context_trace' if trace_id.nil?
+    # Use Kernel.raise
+    Kernel.raise 'No trace context found. Make sure to call within with_context_trace' if trace_id.nil?
 
-    span = Langfuse.span(
+    span = T.unsafe(Langfuse).span(
       name: name,
-      trace_id: trace_id,
+      trace_id: T.must(trace_id), # Must be present due to check above
       parent_observation_id: parent_id,
       input: input,
       **attributes
     )
 
     LangfuseContext.with_span(span) do
-      # Execute the block with the span
-      with_span_implementation(span) { yield(span) }
+      # Pass the block to the implementation
+      with_span_implementation(span, &block)
     end
   end
 
   # Add a score to a trace
+  sig do
+    params(
+      trace_id: String,
+      name: String,
+      value: T.any(Integer, Float), # Assuming score value is numeric
+      comment: T.nilable(String)
+    ).void
+  end
   def score_trace(trace_id:, name:, value:, comment: nil)
-    Langfuse.score(
+    T.unsafe(Langfuse).score(
       trace_id: trace_id,
       name: name,
       value: value,
@@ -145,32 +211,42 @@ module LangfuseHelper
 
   private
 
-  def with_span_implementation(span)
-    Time.now
-    result = nil
-    error = nil
+  # Type the private helper method
+  sig do
+    params(
+      span: ::Langfuse::Models::Span,
+      block: T.proc.params(span: ::Langfuse::Models::Span).returns(T.untyped)
+    ).returns(T.untyped)
+  end
+  def with_span_implementation(span, &block)
+    T.let(Time.now, Time) # Use start_time
+    result = T.let(nil, T.untyped)
+    error = T.let(nil, T.nilable(StandardError))
 
     begin
       # Execute the block with the span passed as argument
-      result = yield
+      result = block.call(span) # Pass span to block
       result
     rescue StandardError => e
       # Capture any error
       error = e
-      raise
+      Kernel.raise # Use Kernel.raise
     ensure
       # Update span
       span.end_time = Time.now.utc
-      span.output = result if result && !span.output
+      # span.start_time = start_time.utc # Add start time if needed by update_span
+
+      span.output = result if result && span.output.nil?
 
       if error
         span.level = 'ERROR'
         span.status_message = error.message
         span.metadata ||= {}
-        span.metadata[:error_backtrace] = error.backtrace.first(10) if error.backtrace
+        backtrace = error.backtrace
+        span.metadata[:error_backtrace] = backtrace.first(10) if backtrace # Check if backtrace is nil
       end
 
-      Langfuse.update_span(span)
+      T.unsafe(Langfuse).update_span(span)
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: langfuse
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Langfuse
 bindir: bin
 cert_chain: []
-date: 2025-03-27 00:00:00.000000000 Z
+date: 2025-04-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: sorbet-runtime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -149,6 +163,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: sorbet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: tapioca
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
@@ -192,9 +234,9 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '3.18'
 description: Langfuse is an open source observability platform for LLM applications.
-  This is the Ruby client for Langfuse's API.
+  This is the Ruby client for Langfuse's API. Rough first alpha
 email:
-- hello@langfuse.com
+- manuel@mento.co
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -203,6 +245,7 @@ files:
 - README.md
 - bin/console
 - bin/setup
+- bin/tapioca
 - lib/langfuse.rb
 - lib/langfuse/api_client.rb
 - lib/langfuse/batch_worker.rb
@@ -215,7 +258,6 @@ files:
 - lib/langfuse/models/span.rb
 - lib/langfuse/models/trace.rb
 - lib/langfuse/models/usage.rb
-- lib/langfuse/rails.rb
 - lib/langfuse/version.rb
 - lib/langfuse_context.rb
 - lib/langfuse_helper.rb

data/lib/langfuse/rails.rb

@@ -1,31 +0,0 @@
-require 'active_support/notifications'
-
-module Langfuse
-  module Rails
-    class << self
-      def setup_notifications
-        ActiveSupport::Notifications.subscribe(/langfuse/) do |name, start, finish, _id, payload|
-          case name
-          when 'langfuse.trace'
-            Langfuse.trace(payload)
-          when 'langfuse.span'
-            # Set end_time based on notification timing if not provided
-            payload[:end_time] ||= finish
-            payload[:start_time] ||= start
-            Langfuse.span(payload)
-          when 'langfuse.generation'
-            # Set end_time based on notification timing if not provided
-            payload[:end_time] ||= finish
-            payload[:start_time] ||= start
-            Langfuse.generation(payload)
-          when 'langfuse.score'
-            Langfuse.score(payload)
-          end
-        end
-      end
-    end
-  end
-end
-
-# Set up notifications if we're in a Rails environment
-Langfuse::Rails.setup_notifications if defined?(::Rails)