boxcars 0.8.3 → 0.8.5

data/lib/boxcars/observability.rb

@@ -20,16 +20,58 @@ module Boxcars
       #
       # @param event [String, Symbol] The name of the event to track.
       # @param properties [Hash] A hash of properties associated with the event.
-      def track(event:, properties:)
+      # @param observation [Boxcars::Observation, nil] Optional observation object to extract user context from.
+      def track(event:, properties:, observation: nil)
         return unless backend
 
-        backend.track(event:, properties:)
+        # Merge user context from observation if present
+        final_properties = properties.dup
+        final_properties = merge_user_context(final_properties, observation.user_context) if observation&.user_context?
+
+        backend.track(event:, properties: final_properties)
       rescue StandardError
         # Fail silently as requested.
         # Optionally, if Boxcars had a central logger:
         # Boxcars.logger.warn "Boxcars::Observability: Backend error during track: #{e.message} (#{e.class.name})"
       end
 
+      # Tracks an observation event, automatically extracting user context if present
+      # @param observation [Boxcars::Observation] The observation to track
+      # @param event [String, Symbol] The event name (defaults to 'boxcar_observation')
+      # @param additional_properties [Hash] Additional properties to include
+      def track_observation(observation, event: 'boxcar_observation', **additional_properties)
+        properties = {
+          observation_note: observation.note,
+          observation_status: observation.status,
+          timestamp: Time.now.iso8601
+        }.merge(additional_properties)
+
+        # Add all observation context (including user_context) to properties
+        properties.merge!(observation.added_context) if observation.added_context
+
+        track(event:, properties:, observation:)
+      end
+
+      private
+
+      # Merge user context into properties with proper namespacing
+      # @param properties [Hash] The existing properties
+      # @param user_context [Hash] The user context to merge
+      # @return [Hash] The merged properties
+      def merge_user_context(properties, user_context)
+        return properties unless user_context.is_a?(Hash)
+
+        # Add user context with proper prefixing for analytics systems
+        user_properties = {}
+        user_context.each do |key, value|
+          # Use $user_ prefix for PostHog compatibility
+          user_key = key.to_s.start_with?('$user_') ? key : "$user_#{key}"
+          user_properties[user_key] = value
+        end
+
+        properties.merge(user_properties)
+      end
+
       # Flushes any pending events if the backend supports it.
       # This is useful for testing or when you need to ensure events are sent before the process exits.
       def flush

data/lib/boxcars/observability_backends/posthog_backend.rb

@@ -52,21 +52,9 @@ module Boxcars
     # @param properties [Hash] A hash of properties for the event.
     #   It's recommended to include a `:user_id` for user-specific tracking.
     def track(event:, properties:)
-      # Ensure properties is a hash, duplicate to avoid mutation by PostHog or other backends
-      tracking_properties = properties.is_a?(Hash) ? properties.dup : {}
-
-      distinct_id = tracking_properties.delete(:user_id) || tracking_properties.delete('user_id') || "anonymous_user"
-
-      # The PostHog gem's capture method handles distinct_id and properties.
-      # It's important that distinct_id is a string.
-      @posthog_client.capture(
-        distinct_id: distinct_id.to_s, # Ensure distinct_id is a string
-        event: event.to_s, # Ensure event name is a string
-        properties: tracking_properties
-      )
-      # The posthog-ruby client handles flushing events asynchronously.
-      # If immediate flushing is needed for testing or specific scenarios:
-      # @posthog_client.flush
+      properties = {} unless properties.is_a?(Hash)
+      distinct_id = properties.delete(:user_id) || current_user_id || "anonymous_user"
+      @posthog_client.capture(distinct_id:, event:, properties:)
     end
 
     # Flushes any pending events to PostHog immediately.
@@ -74,5 +62,12 @@ module Boxcars
     def flush
       @posthog_client.flush if @posthog_client.respond_to?(:flush)
     end
+
+    # in Rails, this is a way to find the current user id
+    def current_user_id
+      return unless defined?(::Current) && ::Current.respond_to?(:user)
+
+      ::Current.user&.id
+    end
   end
 end

data/lib/boxcars/observation.rb

@@ -52,5 +52,45 @@ module Boxcars
     def self.err(note, **)
       new(note:, status: :error, **)
     end
+
+    # create a new Observation with user context
+    # @param note [String] The text to use for the observation
+    # @param user_context [Hash] User information (e.g., { id: 123, email: "user@example.com", role: "admin" })
+    # @param status [Symbol] :ok or :error
+    # @param added_context [Hash] Any additional context to add to the result
+    # @return [Boxcars::Observation] The observation
+    def self.with_user(note, user_context:, status: :ok, **)
+      new(note:, status:, user_context:, **)
+    end
+
+    # create a new Observation with user context and status :ok
+    # @param note [String] The text to use for the observation
+    # @param user_context [Hash] User information (e.g., { id: 123, email: "user@example.com", role: "admin" })
+    # @param added_context [Hash] Any additional context to add to the result
+    # @return [Boxcars::Observation] The observation
+    def self.ok_with_user(note, user_context:, **)
+      with_user(note, user_context:, status: :ok, **)
+    end
+
+    # create a new Observation with user context and status :error
+    # @param note [String] The text to use for the observation
+    # @param user_context [Hash] User information (e.g., { id: 123, email: "user@example.com", role: "admin" })
+    # @param added_context [Hash] Any additional context to add to the result
+    # @return [Boxcars::Observation] The observation
+    def self.err_with_user(note, user_context:, **)
+      with_user(note, user_context:, status: :error, **)
+    end
+
+    # Extract user context from the observation
+    # @return [Hash, nil] The user context if present
+    def user_context
+      added_context[:user_context]
+    end
+
+    # Check if this observation has user context
+    # @return [Boolean] true if user context is present
+    def user_context?
+      !user_context.nil?
+    end
   end
 end

data/lib/boxcars/version.rb

@@ -2,5 +2,5 @@
 
 module Boxcars
   # The current version of the gem.
-  VERSION = "0.8.3"
+  VERSION = "0.8.5"
 end

data/lib/boxcars.rb

@@ -218,6 +218,7 @@ module Boxcars
 end
 
 require_relative "boxcars/version"
+require_relative "boxcars/observation"
 require_relative "boxcars/observability_backend"
 require_relative "boxcars/observability"
 # If users want it, they can require 'boxcars/observability_backends/multi_backend'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: boxcars
 version: !ruby/object:Gem::Version
-  version: 0.8.3
+  version: 0.8.5
 platform: ruby
 authors:
 - Francis Sullivan
@@ -139,9 +139,9 @@ files:
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- POSTHOG_TEST_README.md
 - README.md
 - Rakefile
+- USER_CONTEXT_GUIDE.md
 - bin/console
 - bin/setup
 - boxcars.gemspec

data/POSTHOG_TEST_README.md

@@ -1,118 +0,0 @@
-# Boxcars Engines PostHog Observability Test
-
-This test program demonstrates how to use the Boxcars library with PostHog observability backend to track AI engine usage.
-
-## Prerequisites
-
-1. **PostHog Ruby Gem**: Install the required gem
-   ```bash
-   gem install posthog-ruby
-   ```
-
-2. **Environment Variables**: Ensure your `.env` file contains:
-   ```
-   POSTHOG_API_KEY=your_posthog_project_api_key
-   POSTHOG_HOST=https://app.posthog.com  # or your self-hosted instance
-   ```
-
-3. **AI Provider API Keys**: For testing different engines, you'll need:
-   ```
-   openai_access_token=your_openai_token
-   GOOGLE_API_KEY=your_google_api_key
-   ANTHROPIC_API_KEY=your_anthropic_key
-   GROQ_API_KEY=your_groq_key
-   ```
-
-## Usage
-
-### Method 1: IRB Interactive Session (Recommended)
-
-Start IRB with the required dependencies:
-
-```bash
-irb -r dotenv/load -r boxcars -r debug -r boxcars/observability_backends/posthog_backend
-```
-
-Then in the IRB session:
-
-```ruby
-# Load and run the test
-load 'test_engines_with_posthog.rb'
-
-# Or set up PostHog backend manually:
-Boxcars::Observability.backend = Boxcars::PosthogBackend.new(
-  api_key: ENV['POSTHOG_API_KEY'],
-  host: ENV['POSTHOG_HOST']
-)
-
-# Run manual tests
-manual_test(model: 'gpt-4o', prompt: 'What is machine learning?')
-manual_test(model: 'flash', prompt: 'Explain Ruby in one sentence')
-manual_test(model: 'sonnet', prompt: 'Write a short poem about coding')
-```
-
-### Method 2: Direct Ruby Execution
-
-```bash
-ruby test_engines_with_posthog.rb
-```
-
-## What the Test Does
-
-1. **Initializes PostHog Backend**: Sets up the PostHog observability backend with your API credentials
-2. **Tests Multiple Engines**: Runs tests against various AI engines:
-   - Gemini Flash (Default)
-   - GPT-4o (OpenAI)
-   - Claude Sonnet (Anthropic)
-   - Groq Llama
-3. **Tracks Observability Events**: Each API call generates PostHog events with AI-specific properties
-4. **Provides Manual Testing**: Includes a `manual_test` function for interactive testing
-
-## PostHog Events
-
-The test will generate events in PostHog with properties like:
-
-- `$ai_model`: The AI model used (e.g., "gpt-4o", "gemini-2.5-flash")
-- `$ai_provider`: The provider (e.g., "openai", "google", "anthropic")
-- `$ai_input_tokens`: Number of input tokens
-- `$ai_output_tokens`: Number of output tokens
-- `$ai_latency`: Response time in seconds
-- `$ai_http_status`: HTTP status code
-- `$ai_trace_id`: Unique trace identifier
-- `$ai_is_error`: Boolean indicating if there was an error
-
-## Viewing Results
-
-After running the test:
-
-1. Go to your PostHog dashboard
-2. Navigate to Events or Live Events
-3. Look for events with AI-related properties
-4. You can create insights and dashboards to analyze AI usage patterns
-
-## Troubleshooting
-
-- **Missing PostHog gem**: Install with `gem install posthog-ruby`
-- **Missing API keys**: Check your `.env` file has the required keys
-- **Engine errors**: Some engines may fail if you don't have valid API keys for those providers
-- **No events in PostHog**: Check your PostHog API key and host configuration
-
-## Available Models
-
-You can test with these model aliases:
-
-- `flash` - Gemini 2.5 Flash
-- `gpt-4o` - OpenAI GPT-4o
-- `sonnet` - Claude Sonnet
-- `groq` - Groq Llama
-- `online` - Perplexity Sonar
-- And many more (see `lib/boxcars/engines.rb`)
-
-## Example Manual Tests
-
-```ruby
-# Test different models
-manual_test(model: 'flash', prompt: 'Explain quantum computing')
-manual_test(model: 'gpt-4o', prompt: 'Write a Python function to sort a list')
-manual_test(model: 'sonnet', prompt: 'What are the benefits of functional programming?')
-manual_test(model: 'groq', prompt: 'Describe the difference between AI and ML')