boxcars 0.8.2 → 0.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 842e02d2d8d43ea2a989c5a0b5708022443cf532d7616ab4319a063705f808fa
-  data.tar.gz: 0c3349ae1dc50be9984bd440c520a74f2f972151338f1ff23aca5bc47d56837c
+  metadata.gz: 40c67f759e97f22570fba131b967c73b871b1f96cfbc97df78b1c0438bdf4291
+  data.tar.gz: 55f5e64fa79b8035e1bceb95912cbc5a8c587c29fa3b09d89a65ab83fe4375a6
 SHA512:
-  metadata.gz: 68c3560e8e67c59f711c6433ba5950b48e5ecc0d955b039280399c81baf26361bb659eae89660f2180064b8a2ec7cf799bf0950b42cb5bc8c28b224fa6eb6c53
-  data.tar.gz: 9f2538a7659b6ab4f236f23fbecb0a594f0ad0778e82b4fc634a2179e355fb40fb5f9ec54f6b9df6cda558a93ca5d2522c950ed8fe454d800cea1db16f5b72ba
+  metadata.gz: ba4b4434d263c9b4a875f5ab2db607d11a91795592f39c608143c058a38b773e6349ece90946f7a2137a6edd56d375ebd5992195921660ceac2fa5b4262e6ef5
+  data.tar.gz: c8d58cdfeb28d9a2d6bcba655478d7dd3572db4c2fbd72a566cca6a71c37941d0b7592c02c75f3430e8e7821dcf959942de2d960335864d70da1976e9f7ae63a

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [v0.8.2](https://github.com/BoxcarsAI/boxcars/tree/v0.8.2) (2025-06-04)
+
+[Full Changelog](https://github.com/BoxcarsAI/boxcars/compare/v0.8.1...v0.8.2)
+
+## [v0.8.1](https://github.com/BoxcarsAI/boxcars/tree/v0.8.1) (2025-06-03)
+
+[Full Changelog](https://github.com/BoxcarsAI/boxcars/compare/v0.8.0...v0.8.1)
+
 ## [v0.8.0](https://github.com/BoxcarsAI/boxcars/tree/v0.8.0) (2025-06-03)
 
 [Full Changelog](https://github.com/BoxcarsAI/boxcars/compare/v0.7.7...v0.8.0)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    boxcars (0.8.2)
+    boxcars (0.8.4)
       faraday-retry (~> 2.0)
       google_search_results (~> 2.2)
       gpt4all (~> 0.0.5)
@@ -56,10 +56,10 @@ GEM
       async (>= 1.25)
     base64 (0.3.0)
     benchmark (0.4.1)
-    bigdecimal (3.2.1)
+    bigdecimal (3.2.2)
     concurrent-ruby (1.3.5)
     connection_pool (2.5.3)
-    console (1.30.2)
+    console (1.31.0)
       fiber-annotation
       fiber-local (~> 1.1)
       json
@@ -74,7 +74,7 @@ GEM
     domain_name (0.6.20240107)
     dotenv (3.1.8)
     drb (2.2.3)
-    dynamicschema (1.0.0.beta04)
+    dynamicschema (1.0.0)
     erb (5.0.1)
     event_stream_parser (1.0.0)
     faraday (2.13.1)
@@ -132,7 +132,7 @@ GEM
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2025.0527)
+    mime-types-data (3.2025.0603)
     minitest (5.25.5)
     multi_json (1.15.0)
     multipart-post (2.4.1)
@@ -211,7 +211,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.4)
-    rubocop (1.75.8)
+    rubocop (1.76.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -219,10 +219,10 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.44.0, < 2.0)
+      rubocop-ast (>= 1.45.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.44.1)
+    rubocop-ast (1.45.1)
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     rubocop-rake (0.6.0)
@@ -243,14 +243,14 @@ GEM
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
     securerandom (0.4.1)
-    sqlite3 (2.6.0-aarch64-linux-gnu)
-    sqlite3 (2.6.0-aarch64-linux-musl)
-    sqlite3 (2.6.0-arm-linux-gnu)
-    sqlite3 (2.6.0-arm-linux-musl)
-    sqlite3 (2.6.0-arm64-darwin)
-    sqlite3 (2.6.0-x86_64-darwin)
-    sqlite3 (2.6.0-x86_64-linux-gnu)
-    sqlite3 (2.6.0-x86_64-linux-musl)
+    sqlite3 (2.7.0-aarch64-linux-gnu)
+    sqlite3 (2.7.0-aarch64-linux-musl)
+    sqlite3 (2.7.0-arm-linux-gnu)
+    sqlite3 (2.7.0-arm-linux-musl)
+    sqlite3 (2.7.0-arm64-darwin)
+    sqlite3 (2.7.0-x86_64-darwin)
+    sqlite3 (2.7.0-x86_64-linux-gnu)
+    sqlite3 (2.7.0-x86_64-linux-musl)
     stringio (3.1.7)
     strings-ansi (0.2.0)
     timeout (0.4.3)

data/README.md

@@ -388,7 +388,7 @@ Boxcars automatically tracks LLM calls with detailed metrics:
 
 ```ruby
 # This automatically generates observability events
-engine = Boxcars::Openai.new
+engine = Boxcars::Openai.new(user_id: USER_ID) # optional user_id. All engines take this.
 calc = Boxcars::Calculator.new(engine: engine)
 result = calc.run "what is 2 + 2?"
 ```
@@ -404,6 +404,7 @@ result = calc.run "what is 2 + 2?"
 - `error_message`: Error details if the call failed
 - `response_raw_body`: Raw API response
 - `api_call_parameters`: Parameters sent to the API
+- `distinct_id`: If you specify a user_id to your engine, it will be passed up.
 
 #### Manual Tracking
 

data/USER_CONTEXT_GUIDE.md

@@ -0,0 +1,435 @@
+# User Context in Boxcars Observations
+
+This guide explains how to use the new user context feature in Boxcars observations to track which user performed specific actions.
+
+## Overview
+
+The user context feature allows you to associate user information with Boxcars observations, enabling better tracking, debugging, and analytics. This is particularly useful when using Boxcars in web applications where you want to tie AI operations to specific users.
+
+## Key Features
+
+- **Non-intrusive**: Uses the existing `added_context` mechanism
+- **Backward compatible**: Existing code continues to work unchanged
+- **Flexible**: You control what user data is included
+- **Analytics-ready**: Automatically formats user data for analytics systems like PostHog
+- **Privacy-conscious**: Only includes data you explicitly provide
+
+## Enhanced Observation Class
+
+### New Methods
+
+#### `Observation.with_user(note, user_context:, status: :ok, **additional_context)`
+
+Creates an observation with user context.
+
+```ruby
+user_context = {
+  id: current_user.id,
+  email: current_user.email,
+  role: current_user.role
+}
+
+observation = Boxcars::Observation.with_user(
+  "User performed search",
+  user_context: user_context,
+  query: "machine learning",
+  results_count: 42
+)
+```
+
+#### `Observation.ok_with_user(note, user_context:, **additional_context)`
+
+Creates a successful observation with user context.
+
+```ruby
+observation = Boxcars::Observation.ok_with_user(
+  "Search completed successfully",
+  user_context: user_context,
+  processing_time_ms: 150
+)
+```
+
+#### `Observation.err_with_user(note, user_context:, **additional_context)`
+
+Creates an error observation with user context.
+
+```ruby
+observation = Boxcars::Observation.err_with_user(
+  "Search failed due to timeout",
+  user_context: user_context,
+  error_code: "TIMEOUT"
+)
+```
+
+### New Instance Methods
+
+#### `#user_context`
+
+Returns the user context hash if present, `nil` otherwise.
+
+```ruby
+observation.user_context
+# => {id: 123, email: "user@example.com", role: "admin"}
+```
+
+#### `#user_context?`
+
+Returns `true` if the observation has user context, `false` otherwise.
+
+```ruby
+observation.user_context?
+# => true
+```
+
+## Enhanced Observability System
+
+### Updated Track Method
+
+The `Boxcars::Observability.track` method now accepts an optional `observation` parameter:
+
+```ruby
+Boxcars::Observability.track(
+  event: 'user_action',
+  properties: { action_type: 'search' },
+  observation: observation_with_user_context
+)
+```
+
+When an observation with user context is provided, the user data is automatically merged into the tracking properties with `$user_` prefixes (PostHog compatible).
+
+### New Track Observation Method
+
+```ruby
+Boxcars::Observability.track_observation(
+  observation,
+  event: 'custom_event_name',  # optional, defaults to 'boxcar_observation'
+  additional_property: 'value'
+)
+```
+
+This method automatically:
+- Extracts observation details (note, status, timestamp)
+- Includes all additional context from the observation
+- Merges user context with `$user_` prefixes
+- Sends everything to your configured observability backend
+
+## Rails Integration Pattern
+
+### Controller Helper Methods
+
+Create helper methods in your `ApplicationController`:
+
+```ruby
+class ApplicationController < ActionController::Base
+  private
+
+  # Helper method to create observations with user context
+  def create_observation_with_user(note, status: :ok, **additional_context)
+    if current_user
+      Boxcars::Observation.with_user(
+        note,
+        user_context: current_user.to_user_context,
+        status: status,
+        **additional_context
+      )
+    else
+      Boxcars::Observation.new(note: note, status: status, **additional_context)
+    end
+  end
+
+  # Helper method for successful operations
+  def success_observation_with_user(note, **additional_context)
+    create_observation_with_user(note, status: :ok, **additional_context)
+  end
+
+  # Helper method for error operations
+  def error_observation_with_user(note, **additional_context)
+    create_observation_with_user(note, status: :error, **additional_context)
+  end
+end
+```
+
+### User Model Extension
+
+Add a method to your User model to convert user data to context:
+
+```ruby
+class User < ApplicationRecord
+  def to_user_context
+    {
+      id: id,
+      email: email,
+      role: role,
+      # Add other relevant fields, but be mindful of privacy
+      # Don't include sensitive data like passwords, tokens, etc.
+    }
+  end
+end
+```
+
+### Usage in Controllers
+
+```ruby
+class SearchController < ApplicationController
+  def search
+    query = params[:query]
+    
+    begin
+      # Perform search with Boxcars
+      results = perform_boxcar_search(query)
+      
+      # Track successful search
+      observation = success_observation_with_user(
+        "Search completed successfully",
+        query: query,
+        results_count: results.count,
+        processing_time_ms: 250
+      )
+      
+      Boxcars::Observability.track_observation(
+        observation,
+        event: 'search_completed',
+        controller: 'SearchController',
+        action: 'search'
+      )
+      
+      render json: { results: results }
+      
+    rescue StandardError => e
+      # Track search error
+      error_observation = error_observation_with_user(
+        "Search failed: #{e.message}",
+        query: query,
+        error_class: e.class.name
+      )
+      
+      Boxcars::Observability.track_observation(
+        error_observation,
+        event: 'search_failed',
+        controller: 'SearchController',
+        action: 'search'
+      )
+      
+      render json: { error: "Search failed" }, status: 500
+    end
+  end
+end
+```
+
+## Analytics Integration
+
+### PostHog Integration
+
+When using PostHog as your observability backend, user context is automatically formatted with `$user_` prefixes:
+
+```ruby
+# This user context:
+user_context = {
+  id: 123,
+  email: "user@example.com",
+  role: "admin"
+}
+
+# Becomes these PostHog properties:
+{
+  "$user_id" => 123,
+  "$user_email" => "user@example.com", 
+  "$user_role" => "admin"
+}
+```
+
+This allows PostHog to automatically associate events with users and enables user-based analytics and segmentation.
+
+### Custom Analytics Systems
+
+For other analytics systems, you can access the user context directly:
+
+```ruby
+observation = Boxcars::Observation.ok_with_user("Action completed", user_context: user_data)
+
+# Access user context
+user_info = observation.user_context
+# => {id: 123, email: "user@example.com", role: "admin"}
+
+# Include in your custom tracking
+your_analytics.track(
+  event: 'boxcar_action',
+  user_id: user_info[:id],
+  user_email: user_info[:email],
+  properties: observation.to_h
+)
+```
+
+## Privacy Considerations
+
+### What to Include
+
+**Safe to include:**
+- User ID (for tracking purposes)
+- Email (if needed for support)
+- Role/permissions level
+- Account type (free, premium, etc.)
+- Tenant/organization ID
+
+**Avoid including:**
+- Passwords or password hashes
+- API keys or tokens
+- Personal identification numbers
+- Credit card information
+- Any other sensitive personal data
+
+### Example Safe User Context
+
+```ruby
+def to_user_context
+  {
+    id: id,
+    email: email,
+    role: role,
+    account_type: subscription&.plan_name,
+    organization_id: organization_id,
+    created_at: created_at.iso8601,
+    last_login: last_sign_in_at&.iso8601
+  }
+end
+```
+
+## Testing
+
+### RSpec Examples
+
+```ruby
+RSpec.describe "User Context in Observations" do
+  let(:user_context) do
+    {
+      id: 123,
+      email: "test@example.com",
+      role: "admin"
+    }
+  end
+
+  it "creates observation with user context" do
+    observation = Boxcars::Observation.ok_with_user(
+      "Test action",
+      user_context: user_context
+    )
+
+    expect(observation.user_context?).to be true
+    expect(observation.user_context[:id]).to eq(123)
+    expect(observation.user_context[:email]).to eq("test@example.com")
+  end
+
+  it "tracks observation with user context" do
+    observation = Boxcars::Observation.ok_with_user(
+      "Test action",
+      user_context: user_context
+    )
+
+    expect(Boxcars::Observability).to receive(:track).with(
+      event: 'test_event',
+      properties: hash_including(
+        "$user_id" => 123,
+        "$user_email" => "test@example.com"
+      )
+    )
+
+    Boxcars::Observability.track(
+      event: 'test_event',
+      properties: {},
+      observation: observation
+    )
+  end
+end
+```
+
+## Migration Guide
+
+### Existing Code
+
+Your existing observation code continues to work unchanged:
+
+```ruby
+# This still works exactly as before
+observation = Boxcars::Observation.ok("Action completed", extra: "data")
+Boxcars::Observability.track(event: 'action', properties: { type: 'test' })
+```
+
+### Adding User Context
+
+To add user context to existing observations, simply replace:
+
+```ruby
+# Before
+observation = Boxcars::Observation.ok("Action completed")
+
+# After  
+observation = Boxcars::Observation.ok_with_user(
+  "Action completed",
+  user_context: current_user.to_user_context
+)
+```
+
+### Updating Tracking Calls
+
+To include user context in tracking:
+
+```ruby
+# Before
+Boxcars::Observability.track(
+  event: 'action_completed',
+  properties: { action_type: 'search' }
+)
+
+# After
+Boxcars::Observability.track_observation(
+  observation_with_user_context,
+  event: 'action_completed',
+  action_type: 'search'
+)
+```
+
+## Benefits
+
+1. **Better Debugging**: Quickly identify which user encountered an issue
+2. **User Analytics**: Segment usage patterns by user type, role, or other attributes
+3. **Compliance**: Track user actions for audit trails
+4. **Support**: Faster issue resolution with user context
+5. **Product Insights**: Understand how different user segments use AI features
+
+## Best Practices
+
+1. **Consistent Context**: Use the same user context structure across your application
+2. **Helper Methods**: Create controller helpers to reduce code duplication
+3. **Privacy First**: Only include necessary user data
+4. **Error Handling**: Always handle cases where `current_user` might be nil
+5. **Testing**: Write tests for both user and anonymous scenarios
+6. **Documentation**: Document what user data you're tracking and why
+
+## Troubleshooting
+
+### Common Issues
+
+**User context not appearing in analytics:**
+- Ensure your observability backend is configured
+- Check that you're using `track_observation` or passing the `observation` parameter to `track`
+- Verify the observation actually has user context with `user_context?`
+
+**Anonymous users causing errors:**
+- Always check for `current_user` presence before creating user context
+- Use helper methods that handle nil users gracefully
+
+**Missing user data:**
+- Ensure your `to_user_context` method returns a hash
+- Check that the user object has the expected attributes
+
+### Debug Example
+
+```ruby
+# Debug user context
+observation = Boxcars::Observation.ok_with_user("Test", user_context: user_data)
+puts "Has user context: #{observation.user_context?}"
+puts "User context: #{observation.user_context.inspect}"
+puts "Full observation: #{observation.to_h.inspect}"
+```
+
+This comprehensive user context system provides a clean, privacy-conscious way to associate user information with Boxcars operations, enabling better tracking, debugging, and analytics while maintaining backward compatibility.

data/lib/boxcars/engine/anthropic.rb

@@ -28,10 +28,11 @@ module Boxcars
     #        useful for when you need to use AI to answer questions. You should ask targeted questions".
     # @param prompts [Array<String>] The prompts to use when asking the engine. Defaults to [].
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], **kwargs)
+      user_id = kwargs.delete(:user_id)
       @llm_params = DEFAULT_PARAMS.merge(kwargs)
       @prompts = prompts
       @batch_size = 20
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     def conversation_model?(_model)
@@ -278,7 +279,8 @@ module Boxcars
       request_context = {
         prompt: call_context[:prompt_object],
         inputs: call_context[:inputs],
-        conversation_for_api: call_context[:api_request_params]
+        conversation_for_api: call_context[:api_request_params],
+        user_id:
       }
 
       track_ai_generation(

data/lib/boxcars/engine/cohere.rb

@@ -27,10 +27,11 @@ module Boxcars
     #        useful for when you need to use AI to answer questions. You should ask targeted questions".
     # @param prompts [Array<String>] The prompts to use when asking the engine. Defaults to [].
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], **kwargs)
+      user_id = kwargs.delete(:user_id)
       @llm_params = DEFAULT_PARAMS.merge(kwargs)
       @prompts = prompts
       @batch_size = 20
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     def conversation_model?(_model)
@@ -211,7 +212,8 @@ module Boxcars
       request_context = {
         prompt: call_context[:prompt_object],
         inputs: call_context[:inputs],
-        conversation_for_api: call_context[:api_request_params]
+        conversation_for_api: call_context[:api_request_params],
+        user_id:
       }
 
       track_ai_generation(

data/lib/boxcars/engine/gemini_ai.rb

@@ -19,10 +19,11 @@ module Boxcars
                           "You should ask targeted questions"
 
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 20, **kwargs)
+      user_id = kwargs.delete(:user_id)
       @llm_params = DEFAULT_PARAMS.merge(kwargs) # Corrected typo here
       @prompts = prompts
       @batch_size = batch_size
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     # Renamed from open_ai_client to gemini_client for clarity
@@ -68,7 +69,8 @@ module Boxcars
         request_context = {
           prompt: current_prompt_object,
           inputs:,
-          conversation_for_api: api_request_params&.dig(:messages) || []
+          conversation_for_api: api_request_params&.dig(:messages) || [],
+          user_id:
         }
         track_ai_generation(
           duration_ms:,
@@ -79,12 +81,16 @@ module Boxcars
         )
       end
 
-      _gemini_handle_call_outcome(response_data:)
+      # If there's an error, raise it to maintain backward compatibility with existing tests
+      raise response_data[:error] if response_data[:error]
+
+      response_data[:parsed_json]
     end
 
     def run(question, **)
       prompt = Prompt.new(template: question)
-      answer = client(prompt:, inputs: {}, **)
+      response = client(prompt:, inputs: {}, **)
+      answer = _extract_content_from_gemini_response(response)
       Boxcars.debug("Answer: #{answer}", :cyan)
       answer
     end

data/lib/boxcars/engine/gpt4all_eng.rb

@@ -19,10 +19,11 @@ module Boxcars
     }.freeze
 
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 2, **kwargs)
+      user_id = kwargs.delete(:user_id)
       @gpt4all_params = DEFAULT_PARAMS.merge(kwargs) # Store merged params
       @prompts = prompts
       @batch_size = batch_size # Retain if used by other methods
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     def client(prompt:, inputs: {}, **kwargs)
@@ -31,10 +32,8 @@ module Boxcars
       # current_params are the effective parameters for this call, including defaults and overrides
       current_params = @gpt4all_params.merge(kwargs)
       # api_request_params for GPT4All is just the input text.
-      api_request_params = nil
+      api_request_params, gpt4all_instance = nil
       current_prompt_object = prompt.is_a?(Array) ? prompt.first : prompt
-      gpt4all_instance = nil # To ensure it's in scope for ensure block
-
       begin
         gpt4all_instance = Gpt4all::ConversationalAI.new
         # prepare_resources might download models, could take time.
@@ -68,7 +67,8 @@ module Boxcars
         request_context = {
           prompt: current_prompt_object,
           inputs:,
-          conversation_for_api: api_request_params&.dig(:prompt) # The text prompt
+          conversation_for_api: api_request_params&.dig(:prompt),
+          user_id:
         }
 
         track_ai_generation(

data/lib/boxcars/engine/groq.rb

@@ -19,10 +19,11 @@ module Boxcars
                           "You should ask targeted questions"
 
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 20, **kwargs)
+      user_id = kwargs.delete(:user_id)
       @groq_params = DEFAULT_PARAMS.merge(kwargs) # Corrected typo here
       @prompts = prompts
       @batch_size = batch_size
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     # Renamed from open_ai_client to groq_client for clarity
@@ -60,7 +61,8 @@ module Boxcars
         request_context = {
           prompt: current_prompt_object,
           inputs:,
-          conversation_for_api: api_request_params&.dig(:messages)
+          conversation_for_api: api_request_params&.dig(:messages),
+          user_id:
         }
         track_ai_generation(
           duration_ms:,
@@ -71,22 +73,26 @@ module Boxcars
         )
       end
 
-      _groq_handle_call_outcome(response_data:)
+      # If there's an error, raise it to maintain backward compatibility with existing tests
+      raise response_data[:error] if response_data[:error]
+
+      response_data[:parsed_json]
     end
 
     def run(question, **)
       prompt = Prompt.new(template: question)
-      answer = client(prompt:, inputs: {}, **)
+      response = client(prompt:, inputs: {}, **)
+      answer = extract_answer(response)
       Boxcars.debug("Answer: #{answer}", :cyan)
       answer
     end
 
+    private
+
     def default_params
-      @groq_params # Use instance variable
+      @groq_params
     end
 
-    private
-
     # Helper methods for the client method
     def _prepare_groq_request_params(prompt_object, inputs, current_params)
       messages_hash_from_prompt = prompt_object.as_messages(inputs)

data/lib/boxcars/engine/intelligence_base.rb

@@ -17,10 +17,11 @@ module Boxcars
     # @param batch_size [Integer] The number of prompts to send to the Engine at a time.
     # @param kwargs [Hash] Additional parameters to pass to the Engine.
     def initialize(provider:, description:, name:, prompts: [], batch_size: 20, **kwargs)
+      user_id = kwargs.delete(:user_id)
       @provider = provider
       # Start with defaults, merge other kwargs, then explicitly set model if provided in initialize
       @all_params = default_model_params.merge(kwargs)
-      super(description:, name:, prompts:, batch_size:)
+      super(description:, name:, prompts:, batch_size:, user_id:)
     end
 
     # can be overridden by provider subclass
@@ -68,7 +69,7 @@ module Boxcars
 
       adapter = adapter(api_key:, params:)
       convo = prompt.as_intelligence_conversation(inputs:)
-      request_context = { prompt: prompt&.as_prompt(inputs:)&.[](:prompt), inputs:, conversation_for_api: convo.to_h }
+      request_context = { user_id:, prompt: prompt&.as_prompt(inputs:)&.[](:prompt), inputs:, conversation_for_api: convo.to_h }
       request = Intelligence::ChatRequest.new(adapter:)
 
       start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
@@ -118,17 +119,6 @@ module Boxcars
 
     private
 
-    def extract_answer(response)
-      # Handle different response formats
-      if response["choices"]
-        response["choices"].map { |c| c.dig("message", "content") || c["text"] }.join("\n").strip
-      elsif response["candidates"]
-        response["candidates"].map { |c| c.dig("content", "parts", 0, "text") }.join("\n").strip
-      else
-        response["output"] || response.to_s
-      end
-    end
-
     def check_response(response)
       return if response.is_a?(Hash) && response.key?("choices")
 

data/lib/boxcars/engine/ollama.rb

@@ -19,10 +19,11 @@ module Boxcars
                           "You should ask targeted questions"
 
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 2, **kwargs)
+      user_id = kwargs.delete(:user_id)
       @ollama_params = DEFAULT_PARAMS.merge(kwargs)
       @prompts = prompts
       @batch_size = batch_size # Retain if used by other methods
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     # Renamed from open_ai_client to ollama_client for clarity
@@ -63,7 +64,8 @@ module Boxcars
         request_context = {
           prompt: current_prompt_object,
           inputs:,
-          conversation_for_api: api_request_params&.dig(:messages)
+          conversation_for_api: api_request_params&.dig(:messages),
+          user_id:
         }
         track_ai_generation(
           duration_ms:,

data/lib/boxcars/engine/openai.rb

@@ -20,6 +20,7 @@ module Boxcars
                           "You should ask targeted questions"
 
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 20, **kwargs)
+      user_id = kwargs.delete(:user_id)
       @open_ai_params = DEFAULT_PARAMS.merge(kwargs)
       # Special handling for o1-mini model (deprecated?)
       if @open_ai_params[:model] =~ /^o/ && @open_ai_params[:max_tokens]
@@ -29,7 +30,7 @@ module Boxcars
 
       @prompts = prompts
       @batch_size = batch_size
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     def self.open_ai_client(openai_access_token: nil)
@@ -128,6 +129,7 @@ module Boxcars
     # Called by Engine#generate to check the response from the client.
     # @param response [Hash] The parsed JSON response from the OpenAI API.
     # @raise [Boxcars::Error] if the response contains an error.
+    # rubocop:disable Naming/PredicateMethod
     def check_response(response)
       if response.is_a?(Hash) && response["error"]
         err_details = response["error"]
@@ -136,6 +138,7 @@ module Boxcars
       end
       true
     end
+    # rubocop:enable Naming/PredicateMethod
 
     def run(question, **)
       prompt = Prompt.new(template: question)
@@ -229,6 +232,7 @@ module Boxcars
       request_context = {
         prompt: call_context[:prompt_object],
         inputs: call_context[:inputs],
+        user_id:,
         conversation_for_api: is_chat_model ? api_request_params[:messages] : api_request_params[:prompt]
       }
 

data/lib/boxcars/engine/perplexityai.rb

@@ -20,10 +20,11 @@ module Boxcars
                           "You should ask targeted questions"
 
     def initialize(name: DEFAULT_NAME, description: DEFAULT_DESCRIPTION, prompts: [], batch_size: 20, **kwargs)
+      user_id = kwargs.delete(:user_id)
       @perplexity_params = DEFAULT_PARAMS.merge(kwargs)
       @prompts = prompts
       @batch_size = batch_size # Retain if used by generate
-      super(description:, name:)
+      super(description:, name:, user_id:)
     end
 
     # Perplexity models are conversational.
@@ -96,6 +97,7 @@ module Boxcars
         request_context = {
           prompt: current_prompt_object,
           inputs:,
+          user_id:,
           conversation_for_api: api_request_params&.dig(:messages)
         }
         track_ai_generation(

data/lib/boxcars/engine/unified_observability.rb

@@ -52,7 +52,8 @@ module Boxcars
         '$ai_latency': duration_seconds,
         '$ai_http_status': extract_status_code(response_data) || (response_data[:success] ? 200 : 500),
         '$ai_base_url': get_base_url_for_provider(provider),
-        '$ai_is_error': !response_data[:success]
+        '$ai_is_error': !response_data[:success],
+        user_id:
       }
 
       # Add error details if present

data/lib/boxcars/engine.rb

@@ -3,18 +3,20 @@
 module Boxcars
   # @abstract
   class Engine
-    attr_reader :prompts, :batch_size
+    attr_reader :prompts, :batch_size, :user_id
 
     # An Engine is used by Boxcars to generate output from prompts
     # @param name [String] The name of the Engine. Defaults to classname.
     # @param description [String] A description of the Engine.
     # @param prompts [Array<Prompt>] The prompts to use for the Engine.
     # @param batch_size [Integer] The number of prompts to send to the Engine at a time.
-    def initialize(description: 'Engine', name: nil, prompts: [], batch_size: 20)
+    # @param user_id [String, Integer] The ID of the user using this Engine (optional for observability).
+    def initialize(description: 'Engine', name: nil, prompts: [], batch_size: 20, user_id: nil)
       @name = name || self.class.name
       @description = description
       @prompts = prompts
       @batch_size = batch_size
+      @user_id = user_id
     end
 
     # Get an answer from the Engine.
@@ -57,12 +59,33 @@ module Boxcars
       # Includes prompt, completion, and total tokens used.
       inkeys = %w[completion_tokens prompt_tokens total_tokens].freeze
       prompts.each_slice(batch_size) do |sub_prompts|
-        sub_prompts.each do |sprompts, inputs|
-          response = client(prompt: sprompts, inputs:, **params)
-          check_response(response)
-          choices.concat(response["choices"])
-          usage_keys = inkeys & response["usage"].keys
-          usage_keys.each { |key| token_usage[key] = token_usage[key].to_i + response["usage"][key] }
+        sub_prompts.each do |sprompt, inputs|
+          client_response = client(prompt: sprompt, inputs:, **params)
+
+          # All engines now return the parsed API response hash directly
+          api_response_hash = client_response
+
+          # Ensure we have a hash to work with
+          unless api_response_hash.is_a?(Hash)
+            raise TypeError, "Expected Hash from client method, got #{api_response_hash.class}: #{api_response_hash.inspect}"
+          end
+
+          check_response(api_response_hash)
+
+          current_choices = api_response_hash["choices"]
+          if current_choices.is_a?(Array)
+            choices.concat(current_choices)
+          else
+            Boxcars.logger&.warn "No 'choices' found in API response: #{api_response_hash.inspect}"
+          end
+
+          api_usage = api_response_hash["usage"]
+          if api_usage.is_a?(Hash)
+            usage_keys = inkeys & api_usage.keys
+            usage_keys.each { |key| token_usage[key] = token_usage[key].to_i + api_usage[key] }
+          else
+            Boxcars.logger&.warn "No 'usage' data found in API response: #{api_response_hash.inspect}"
+          end
         end
       end
 
@@ -74,6 +97,17 @@ module Boxcars
       end
       EngineResult.new(generations:, engine_output: { token_usage: })
     end
+
+    def extract_answer(response)
+      # Handle different response formats
+      if response["choices"]
+        response["choices"].map { |c| c.dig("message", "content") || c["text"] }.join("\n").strip
+      elsif response["candidates"]
+        response["candidates"].map { |c| c.dig("content", "parts", 0, "text") }.join("\n").strip
+      else
+        response["output"] || response.to_s
+      end
+    end
   end
 end
 

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.2"
+  VERSION = "0.8.4"
 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.2
+  version: 0.8.4
 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')