boxcars 0.7.7 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c0b63da11bca5d10f8de95aa51f42d6acea996881e636e3006b98337f01e564
-  data.tar.gz: 63d7554f52d4c29f0e58511c827f490f38215b26b45003413309f12df150e534
+  metadata.gz: e76c5930ad4510169e7b27bca16789e5e8b72f1627f8e05546fe6450a649416a
+  data.tar.gz: 7a3a1f3e8eb58674481f57e814b68d797135f5ea41856629bbbae9f17743e429
 SHA512:
-  metadata.gz: da06e0a21403d259342a5e516519bed361328737ab3601a262a926009ea5199e26d36d0a3a52b77f7089f016741bc991bc46c605f6502d17fcdc48cedb9f10fa
-  data.tar.gz: 828c9799e4a9405a72b2975819f70656c7fb284868f103b0ea090e27319d1a54c828b51f7af6ebdb11cbe0b2028f5c2ff691a70b8bbc6c9426f88f6f0cabe5ba
+  metadata.gz: 0b660877e4644a88e4a024512be55b2eeb5ea5cae8fb72a66f117a7ebfca2eefce6f2cfc10587afd9083b03b40e38c0fb30ca56ffbd4ce6723c09f2bf886acdf
+  data.tar.gz: f17d7b1cc975749780feecf2dfca65056332e98bb6b2a3ef40cbe0663820ed66ee51f88776910590b8c27a8ec4fcfe586c188ee7126c99127e4dd410d4e7f8fb

data/.rubocop.yml

@@ -6,7 +6,7 @@ plugins:
 
 
 AllCops:
-  TargetRubyVersion: 3
+  TargetRubyVersion: 3.2
   Exclude:
     - 'bin/{rails,rake}'
     - 'node_modules/**/*'
@@ -72,7 +72,7 @@ Metrics/BlockLength:
     - 'spec/**/*'
 
 Metrics/MethodLength:
-  Max: 35
+  Max: 40
   Exclude:
     - 'spec/**/*'
 
@@ -95,7 +95,7 @@ Naming/AccessorMethodName:
   Enabled: false
 
 Metrics/PerceivedComplexity:
-  Max: 10
+  Max: 20
 
 Style/RescueStandardError:
   Enabled: false
@@ -171,3 +171,6 @@ RSpec/ExampleLength:
 
 RSpec/MultipleExpectations:
   Enabled: false
+
+RSpec/BeforeAfterAll:
+  Enabled: false

data/.ruby-version

@@ -1 +1 @@
-3.3.5
+3.4.4

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## [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)
+
+**Closed issues:**
+
+- ActiveRecord translations [\#249](https://github.com/BoxcarsAI/boxcars/issues/249)
+- Any chance of getting AWS Bedrock as a provider? [\#239](https://github.com/BoxcarsAI/boxcars/issues/239)
+
+**Merged pull requests:**
+
+- Add observability hooks [\#251](https://github.com/BoxcarsAI/boxcars/pull/251) ([francis](https://github.com/francis))
+
+## [v0.7.7](https://github.com/BoxcarsAI/boxcars/tree/v0.7.7) (2025-04-23)
+
+[Full Changelog](https://github.com/BoxcarsAI/boxcars/compare/v0.7.6...v0.7.7)
+
 ## [v0.7.6](https://github.com/BoxcarsAI/boxcars/tree/v0.7.6) (2025-04-22)
 
 [Full Changelog](https://github.com/BoxcarsAI/boxcars/compare/v0.7.5...v0.7.6)

data/Gemfile

@@ -5,36 +5,26 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in boxcars.gemspec
 gemspec
 
-gem "debug", "~> 1.9"
-
 gem "dotenv", "~> 3.1"
-
 gem "rake", "~> 13.2"
-
 gem "sqlite3", "~> 2.0"
-
 gem "async", "~>1.32.1"
-
 gem "activerecord", "~> 7.1"
-
-gem "github_changelog_generator", "~> 1.16"
-
 gem "faraday-retry", "~> 2.0"
-
 gem "activesupport", "~> 7.1"
-
 gem "rest-client", "~> 2.1"
-
 gem "hnswlib", "~> 0.9.0"
-
 gem "pg", "~> 1.5"
 gem "pgvector", "~> 0.2.2"
 
 group :development, :test do
+  gem "debug", "~> 1.9"
   gem "rspec", "~> 3.13"
   gem "rubocop", "~> 1.67"
   gem "vcr", "~> 6.3.1"
   gem "webmock", "~> 3.24.0"
   gem "rubocop-rake", "~> 0.6.0"
   gem "rubocop-rspec", "~> 3.2"
+  gem "posthog-ruby", require: false
+  gem "github_changelog_generator", "~> 1.16", require: false
 end

data/Gemfile.lock

@@ -1,13 +1,13 @@
 PATH
   remote: .
   specs:
-    boxcars (0.7.7)
+    boxcars (0.8.1)
+      faraday-retry (~> 2.0)
       google_search_results (~> 2.2)
       gpt4all (~> 0.0.5)
       hnswlib (~> 0.9)
       intelligence (>= 0.8)
       nokogiri (~> 1.18)
-      pgvector (~> 0.2)
       ruby-anthropic (~> 0.4)
       ruby-openai (>= 7.3)
 
@@ -54,11 +54,11 @@ GEM
       async
     async-pool (0.10.3)
       async (>= 1.25)
-    base64 (0.2.0)
-    benchmark (0.4.0)
-    bigdecimal (3.1.9)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.2.1)
     concurrent-ruby (1.3.5)
-    connection_pool (2.5.1)
+    connection_pool (2.5.3)
     console (1.30.2)
       fiber-annotation
       fiber-local (~> 1.1)
@@ -70,13 +70,14 @@ GEM
     debug (1.10.0)
       irb (~> 1.10)
       reline (>= 0.3.8)
-    diff-lcs (1.6.1)
+    diff-lcs (1.6.2)
     domain_name (0.6.20240107)
     dotenv (3.1.8)
-    drb (2.2.1)
+    drb (2.2.3)
     dynamicschema (1.0.0.beta04)
+    erb (5.0.1)
     event_stream_parser (1.0.0)
-    faraday (2.13.0)
+    faraday (2.13.1)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
@@ -106,7 +107,7 @@ GEM
       faraday (~> 2.7)
       os (~> 1.1)
       tty-progressbar (~> 0.18.2)
-    hashdiff (1.1.2)
+    hashdiff (1.2.0)
     hnswlib (0.9.0)
     http-accept (1.7.0)
     http-cookie (1.0.8)
@@ -123,15 +124,15 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.10.2)
+    json (2.12.2)
     json-repair (0.2.0)
-    language_server-protocol (3.17.0.4)
+    language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
-    mime-types (3.6.2)
+    mime-types (3.7.0)
       logger
-      mime-types-data (~> 3.2015)
-    mime-types-data (3.2025.0415)
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2025.0527)
     minitest (5.25.5)
     multi_json (1.15.0)
     multipart-post (2.4.1)
@@ -165,6 +166,8 @@ GEM
       racc
     pg (1.5.9)
     pgvector (0.2.2)
+    posthog-ruby (3.0.1)
+      concurrent-ruby (~> 1)
     pp (0.6.2)
       prettyprint
     prettyprint (0.2.0)
@@ -176,14 +179,15 @@ GEM
     protocol-http2 (0.16.0)
       protocol-hpack (~> 1.4)
       protocol-http (~> 0.18)
-    psych (5.2.3)
+    psych (5.2.6)
       date
       stringio
-    public_suffix (6.0.1)
+    public_suffix (6.0.2)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.2.1)
-    rdoc (6.13.1)
+    rake (13.3.0)
+    rdoc (6.14.0)
+      erb
       psych (>= 4.0.0)
     regexp_parser (2.10.0)
     reline (0.6.1)
@@ -194,20 +198,20 @@ GEM
       mime-types (>= 1.16, < 4.0)
       netrc (~> 0.8)
     rexml (3.4.1)
-    rspec (3.13.0)
+    rspec (3.13.1)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
       rspec-mocks (~> 3.13.0)
-    rspec-core (3.13.3)
+    rspec-core (3.13.4)
       rspec-support (~> 3.13.0)
-    rspec-expectations (3.13.3)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.2)
+    rspec-mocks (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-support (3.13.2)
-    rubocop (1.75.2)
+    rspec-support (3.13.4)
+    rubocop (1.75.8)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -292,6 +296,7 @@ DEPENDENCIES
   hnswlib (~> 0.9.0)
   pg (~> 1.5)
   pgvector (~> 0.2.2)
+  posthog-ruby
   rake (~> 13.2)
   rest-client (~> 2.1)
   rspec (~> 3.13)

data/POSTHOG_TEST_README.md

@@ -0,0 +1,118 @@
+# 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')

data/README.md

@@ -149,6 +149,311 @@ Also, if you set this flag: `Boxcars.configuration.log_prompts = true`
 The actual prompts handed to the connected Engine will be logged. This is off by default because it is very wordy, but handy if you are debugging prompts.
 
 Otherwise, we print to standard out.
+
+### Engine Factory (Engines)
+
+Boxcars provides a convenient factory class `Boxcars::Engines` that simplifies creating engine instances using model names and aliases instead of remembering full class names and model strings.
+
+#### Basic Usage
+
+```ruby
+# Using default model (gemini-2.5-flash-preview-05-20)
+engine = Boxcars::Engines.engine
+
+# Using specific models with convenient aliases
+gpt_engine = Boxcars::Engines.engine(model: "gpt-4o")
+claude_engine = Boxcars::Engines.engine(model: "sonnet")
+gemini_engine = Boxcars::Engines.engine(model: "flash")
+groq_engine = Boxcars::Engines.engine(model: "groq")
+```
+
+#### Supported Model Aliases
+
+**OpenAI Models:**
+- `"gpt-4o"`, `"gpt-3.5-turbo"`, `"o1-preview"` - Creates `Boxcars::Openai` engines
+
+**Anthropic Models:**
+- `"anthropic"`, `"sonnet"` - Creates `Boxcars::Anthropic` with Claude Sonnet
+- `"opus"` - Creates `Boxcars::Anthropic` with Claude Opus
+- `"claude-3-5-sonnet"`, etc. - Any model starting with "claude-"
+
+**Groq Models:**
+- `"groq"` - Creates `Boxcars::Groq` with Llama 3.3 70B
+- `"deepseek"` - Creates `Boxcars::Groq` with DeepSeek R1
+- `"mistral"` - Creates `Boxcars::Groq` with Mistral
+- Models starting with `"mistral-"`, `"meta-llama/"`, or `"deepseek-"`
+
+**Gemini Models:**
+- `"flash"`, `"gemini-flash"` - Creates `Boxcars::GeminiAi` with Gemini 2.5 Flash
+- `"gemini-pro"` - Creates `Boxcars::GeminiAi` with Gemini 2.5 Pro
+- Any model starting with `"gemini-"`
+
+**Perplexity Models:**
+- `"online"`, `"sonar"` - Creates `Boxcars::Perplexityai` with Sonar
+- `"sonar-pro"`, `"huge"` - Creates `Boxcars::Perplexityai` with Sonar Pro
+- Models containing `"-sonar-"`
+
+**Together AI Models:**
+- `"together-model-name"` - Creates `Boxcars::Together` (strips "together-" prefix)
+
+#### JSON-Optimized Engines
+
+For applications requiring JSON responses, use the `json_engine` method:
+
+```ruby
+# Creates engine optimized for JSON output
+json_engine = Boxcars::Engines.json_engine(model: "gpt-4o")
+
+# Automatically removes response_format for models that don't support it
+json_claude = Boxcars::Engines.json_engine(model: "sonnet")
+```
+
+#### Passing Additional Parameters
+
+```ruby
+# Pass any additional parameters to the underlying engine
+engine = Boxcars::Engines.engine(
+  model: "gpt-4o",
+  temperature: 0.7,
+  max_tokens: 1000,
+  top_p: 0.9
+)
+```
+
+#### Using with Boxcars
+
+```ruby
+# Use the factory with any Boxcar
+engine = Boxcars::Engines.engine(model: "sonnet")
+calc = Boxcars::Calculator.new(engine: engine)
+result = calc.run "What is 15 * 23?"
+
+# Or in a Train
+boxcars = [
+  Boxcars::Calculator.new(engine: Boxcars::Engines.engine(model: "gpt-4o")),
+  Boxcars::GoogleSearch.new(engine: Boxcars::Engines.engine(model: "flash"))
+]
+train = Boxcars.train.new(boxcars: boxcars)
+```
+
+### Overriding the Default Engine Model
+
+Boxcars provides several ways to override the default engine model used throughout your application. The default model is currently `"gemini-2.5-flash-preview-05-20"`, but you can customize this behavior.
+
+#### Global Configuration
+
+Set a global default model that will be used by `Boxcars::Engines.engine()` when no model is specified:
+
+```ruby
+# Set the default model globally
+Boxcars.configuration.default_model = "gpt-4o"
+
+# Now all engines created without specifying a model will use GPT-4o
+engine = Boxcars::Engines.engine  # Uses gpt-4o
+calc = Boxcars::Calculator.new    # Uses gpt-4o via default engine
+```
+
+#### Configuration Block
+
+Use a configuration block for more organized setup:
+
+```ruby
+Boxcars.configure do |config|
+  config.default_model = "sonnet"  # Use Claude Sonnet as default
+  config.logger = Rails.logger     # Set custom logger
+  config.log_prompts = true        # Enable prompt logging
+end
+```
+
+#### Per-Instance Override
+
+Override the model for specific engine instances:
+
+```ruby
+# Global default is gemini-flash, but use different models per boxcar
+default_engine = Boxcars::Engines.engine                    # Uses global default
+gpt_engine = Boxcars::Engines.engine(model: "gpt-4o")       # Uses GPT-4o
+claude_engine = Boxcars::Engines.engine(model: "sonnet")    # Uses Claude Sonnet
+
+# Use different engines for different boxcars
+calc = Boxcars::Calculator.new(engine: gpt_engine)
+search = Boxcars::GoogleSearch.new(engine: claude_engine)
+```
+
+#### Environment-Based Configuration
+
+Set the default model via environment variables or initialization:
+
+```ruby
+# In your application initialization (e.g., Rails initializer)
+if Rails.env.production?
+  Boxcars.configuration.default_model = "gpt-4o"      # Use GPT-4o in production
+elsif Rails.env.development?
+  Boxcars.configuration.default_model = "flash"       # Use faster Gemini Flash in development
+else
+  Boxcars.configuration.default_model = "groq"        # Use Groq for testing
+end
+```
+
+#### Model Resolution Priority
+
+The `Boxcars::Engines.engine()` method resolves the model in this order:
+
+1. **Explicit model parameter**: `Boxcars::Engines.engine(model: "gpt-4o")`
+2. **Global configuration**: `Boxcars.configuration.default_model`
+3. **Built-in default**: `"gemini-2.5-flash-preview-05-20"`
+
+#### Supported Model Aliases
+
+When setting `default_model`, you can use any of the supported model aliases:
+
+```ruby
+# These are all valid default_model values:
+Boxcars.configuration.default_model = "gpt-4o"        # OpenAI GPT-4o
+Boxcars.configuration.default_model = "sonnet"        # Claude Sonnet
+Boxcars.configuration.default_model = "flash"         # Gemini Flash
+Boxcars.configuration.default_model = "groq"          # Groq Llama
+Boxcars.configuration.default_model = "online"        # Perplexity Sonar
+```
+
+#### Legacy Engine Configuration
+
+You can also override the default engine class (though this is less common):
+
+```ruby
+# Override the default engine class entirely
+Boxcars.configuration.default_engine = Boxcars::Anthropic
+
+# Now Boxcars.engine returns Anthropic instead of OpenAI
+default_engine = Boxcars.engine  # Returns Boxcars::Anthropic instance
+```
+
+**Note**: When using `default_engine`, the `default_model` setting is ignored since you're specifying the engine class directly.
+
+### Observability
+
+Boxcars includes a comprehensive observability system that allows you to track and monitor AI operations across your application. The system provides insights into LLM calls, performance metrics, errors, and usage patterns.
+
+#### Core Components
+
+**Observability Class**: The central tracking interface that provides a simple `track` method for recording events.
+
+**ObservabilityBackend Module**: An interface that defines how tracking backends should be implemented. All backends must include this module and implement a `track` method.
+
+**Built-in Backends**:
+- **PosthogBackend**: Sends events to PostHog for analytics and user behavior tracking
+- **MultiBackend**: Allows sending events to multiple backends simultaneously
+
+#### Configuration
+
+Set up observability by configuring a backend:
+
+```ruby
+# Using PostHog backend
+require 'boxcars/observability_backends/posthog_backend'
+
+Boxcars.configure do |config|
+  config.observability_backend = Boxcars::PosthogBackend.new(
+    api_key: ENV['POSTHOG_API_KEY'] || 'your_posthog_api_key',
+    host: 'https://app.posthog.com' # or your self-hosted instance
+  )
+end
+
+# Using multiple backends
+require 'boxcars/observability_backends/multi_backend'
+backend1 = Boxcars::PosthogBackend.new(api_key: ENV['POSTHOG_API_KEY'])
+backend2 = YourCustomBackend.new
+
+Boxcars.configure do |config|
+  config.observability_backend = Boxcars::MultiBackend.new([backend1, backend2])
+end
+```
+
+#### Automatic Tracking
+
+Boxcars automatically tracks LLM calls with detailed metrics:
+
+```ruby
+# This automatically generates observability events
+engine = Boxcars::Openai.new
+calc = Boxcars::Calculator.new(engine: engine)
+result = calc.run "what is 2 + 2?"
+```
+
+**Tracked Properties Include**:
+- `provider`: The LLM provider (e.g., "openai", "anthropic")
+- `model_name`: The specific model used
+- `prompt_content`: The conversation messages sent to the LLM
+- `inputs`: Any template inputs provided
+- `duration_ms`: Request duration in milliseconds
+- `success`: Whether the call succeeded
+- `status_code`: HTTP response status
+- `error_message`: Error details if the call failed
+- `response_raw_body`: Raw API response
+- `api_call_parameters`: Parameters sent to the API
+
+#### Manual Tracking
+
+You can also track custom events:
+
+```ruby
+Boxcars::Observability.track(
+  event: 'custom_operation',
+  properties: {
+    user_id: 'user_123',
+    operation_type: 'data_processing',
+    duration_ms: 150,
+    success: true
+  }
+)
+```
+
+#### Creating Custom Backends
+
+Implement your own backend by including the `ObservabilityBackend` module:
+
+```ruby
+class CustomBackend
+  include Boxcars::ObservabilityBackend
+  
+  def track(event:, properties:)
+    # Your custom tracking logic here
+    puts "Event: #{event}, Properties: #{properties}"
+  end
+end
+
+Boxcars.configure do |config|
+  config.observability_backend = CustomBackend.new
+end
+```
+
+#### Error Handling
+
+The observability system is designed to fail silently to prevent tracking issues from disrupting your main application flow. If a backend raises an error, it will be caught and ignored, ensuring your AI operations continue uninterrupted.
+
+#### PostHog Integration
+
+The PostHog backend requires the `posthog-ruby` gem:
+
+```ruby
+# Add to your Gemfile
+gem 'posthog-ruby'
+
+# Configure the backend
+Boxcars.configure do |config|
+  config.observability_backend = Boxcars::PosthogBackend.new(
+    api_key: ENV['POSTHOG_API_KEY'],
+    host: 'https://app.posthog.com',
+    on_error: proc { |status, body| 
+      Rails.logger.warn "PostHog error: #{status} - #{body}" 
+    }
+  )
+end
+```
+
+Events are automatically associated with users when a `user_id` property is provided. Anonymous events use a default identifier.
+
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.