boxcars 0.8.3 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93e000d3596a656454fb5c76becff8c5d5b4bbb33fe75f91598aceb0526c8d48
-  data.tar.gz: 87d3db350a3faa94cb367fbd600749ed584f0868cd8298469b7bef6c9434e93e
+  metadata.gz: c1970a509d4c6eebaeaa06792993f7aaa1ba8d2d030e878138a8d6f821726fcc
+  data.tar.gz: 66ae9f13950ab9a0dd2369a1450fd14d4426faa95d8a62da7b4c7deeddbc6b3d
 SHA512:
-  metadata.gz: d3028c6cbaec10e84597c3a68e2f8f6c88b336b4be50144b04349662afa647d9c266d00debc14c0370bda0bb2150472cf69e347def8fcdc5d3682fc6c2d19512
-  data.tar.gz: 98a10191a8cd96cf85d91f9d5f1f38f07fa29fc7521f55bfd67c500a21fb23b3ef7d4ba7a16df1cc1d35f2a7486fe9ba18f11ab922e288895533ed2197766601
+  metadata.gz: 7e6d1f2f4788bb24de873a2e7270b52f44ce31017ccd39e1db321b91bd595d1f832c6c9aa4b9ca587626c3390928e70025014a360ba8052b9e870c50566ccb29
+  data.tar.gz: 4073745656e6944e8e686eee4502916038470ff32261990c1444e50d951a819288a24b993dc51659168b9246dab7020f40fd20f210b9421ab5890e6ec4402d66

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    boxcars (0.8.3)
+    boxcars (0.8.5)
       faraday-retry (~> 2.0)
       google_search_results (~> 2.2)
       gpt4all (~> 0.0.5)
@@ -47,7 +47,7 @@ GEM
       protocol-http1 (~> 0.19.0)
       protocol-http2 (~> 0.16.0)
       traces (>= 0.10.0)
-    async-http-faraday (0.21.0)
+    async-http-faraday (0.22.0)
       async-http (~> 0.42)
       faraday
     async-io (1.43.2)
@@ -67,7 +67,7 @@ GEM
       bigdecimal
       rexml
     date (3.4.1)
-    debug (1.10.0)
+    debug (1.11.0)
       irb (~> 1.10)
       reline (>= 0.3.8)
     diff-lcs (1.6.2)
@@ -83,11 +83,11 @@ GEM
       logger
     faraday-http-cache (2.5.1)
       faraday (>= 0.8)
-    faraday-multipart (1.1.0)
+    faraday-multipart (1.1.1)
       multipart-post (~> 2.0)
-    faraday-net_http (3.4.0)
+    faraday-net_http (3.4.1)
       net-http (>= 0.5.0)
-    faraday-retry (2.3.1)
+    faraday-retry (2.3.2)
       faraday (~> 2.0)
     fiber-annotation (0.2.0)
     fiber-local (1.1.0)
@@ -114,8 +114,8 @@ GEM
       domain_name (~> 0.5)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
-    intelligence (0.8.0)
-      dynamicschema (~> 1.0.0.beta03)
+    intelligence (1.0.0)
+      dynamicschema (~> 1.0)
       faraday (~> 2.7)
       json-repair (~> 0.2)
       mime-types (~> 3.6)
@@ -132,7 +132,7 @@ GEM
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2025.0603)
+    mime-types-data (3.2025.0624)
     minitest (5.25.5)
     multi_json (1.15.0)
     multipart-post (2.4.1)
@@ -186,7 +186,7 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.0)
-    rdoc (6.14.0)
+    rdoc (6.14.1)
       erb
       psych (>= 4.0.0)
     regexp_parser (2.10.0)
@@ -202,7 +202,7 @@ GEM
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.4)
+    rspec-core (3.13.5)
       rspec-support (~> 3.13.0)
     rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
@@ -211,7 +211,7 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.4)
-    rubocop (1.76.1)
+    rubocop (1.77.0)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -219,7 +219,7 @@ GEM
       parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 2.9.3, < 3.0)
-      rubocop-ast (>= 1.45.0, < 2.0)
+      rubocop-ast (>= 1.45.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
     rubocop-ast (1.45.1)
@@ -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.1-aarch64-linux-gnu)
+    sqlite3 (2.7.1-aarch64-linux-musl)
+    sqlite3 (2.7.1-arm-linux-gnu)
+    sqlite3 (2.7.1-arm-linux-musl)
+    sqlite3 (2.7.1-arm64-darwin)
+    sqlite3 (2.7.1-x86_64-darwin)
+    sqlite3 (2.7.1-x86_64-linux-gnu)
+    sqlite3 (2.7.1-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:,
@@ -82,13 +84,13 @@ module Boxcars
       # If there's an error, raise it to maintain backward compatibility with existing tests
       raise response_data[:error] if response_data[:error]
 
-      response_data
+      response_data[:parsed_json]
     end
 
     def run(question, **)
       prompt = Prompt.new(template: question)
-      response_data = client(prompt:, inputs: {}, **)
-      answer = _gemini_handle_call_outcome(response_data:)
+      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(