decision_agent 0.1.3 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c8a831b21d5bb62dbb4948827cc0b4bc9bcf021b52f04a2d9141d1339287274
-  data.tar.gz: 97d80cab6513385dc9e9b4bddb7555da1e8629488ce358319aa0842e74cf41e1
+  metadata.gz: a6adecd350c20f336995ee4954e26f9be65dee45fb9d31838be996eda5928d3d
+  data.tar.gz: cb55474c53415d83a4d8a66598b8a4fcfd526472c5419612d9491df4ea02832f
 SHA512:
-  metadata.gz: dcfa8f3cc0a5931a1a163b97caf7586c17eddfee38850b52b832fa1a94d720342868c6823158597d0dafa14bf7df82b9d9b394fdffac3c74d06a556eca2b5c18
-  data.tar.gz: f183fc1b8c021e589571d0d9a97c3b2679fec3b529d2e73a76a4b7752a9792dcba77f4914de876c5448711416179dcbd0ba35b515fe1c4f2a74bcab27c1a873e
+  metadata.gz: f2f14271db7d5ba25d3e3604396c221cce07ed62824025d1686c4950a06cf2f064cd5498053aa49f613d09e8a0da62fccdc880f293209cb6e30dfe3119fe567c
+  data.tar.gz: b32ddb86d61e4588d4db68e6a4f441b2a35688918ddde831ef6b47a19782dfd36f68931d1cd9e1885f59fae1f63af96f683401c6f382e119c7fb23477940075c

data/README.md

@@ -11,11 +11,13 @@ A production-grade, deterministic, explainable, and auditable decision engine fo
 
 ## Why DecisionAgent?
 
+DecisionAgent is designed for applications that require **deterministic, explainable, and auditable** decision-making:
+
 - ✅ **Deterministic** - Same input always produces same output
 - ✅ **Explainable** - Every decision includes human-readable reasoning
 - ✅ **Auditable** - Reproduce any historical decision exactly
 - ✅ **Framework-agnostic** - Pure Ruby, works anywhere
-- ✅ **Production-ready** - Comprehensive testing, error handling, and versioning
+- ✅ **Production-ready** - Comprehensive testing ([Coverage Report](coverage.md)), error handling, and versioning
 
 ## Installation
 
@@ -24,6 +26,7 @@ gem install decision_agent
 ```
 
 Or add to your Gemfile:
+
 ```ruby
 gem 'decision_agent'
 ```
@@ -57,11 +60,38 @@ puts result.confidence    # => 0.9
 puts result.explanations  # => ["High value transaction"]
 ```
 
-## Web UI - Visual Rule Builder
+See [Code Examples](docs/CODE_EXAMPLES.md) for more comprehensive examples.
+
+## Key Features
+
+### Decision Making
+- **Multiple Evaluators** - Combine rule-based, ML, and custom logic
+- **Conflict Resolution** - Weighted average, consensus, threshold, max weight
+- **Rich Context** - Nested data, dot notation, flexible operators
+- **Advanced Operators** - String, numeric, date/time, collection, and geospatial operators
+
+### Auditability & Compliance
+- **Complete Audit Trails** - Every decision fully logged
+- **Deterministic Replay** - Reproduce historical decisions exactly
+- **RFC 8785 Canonical JSON** - Industry-standard deterministic hashing
+- **Compliance Ready** - HIPAA, SOX, regulatory compliance support
+
+### Developer Experience
+- **Pluggable Architecture** - Custom evaluators, scoring, audit adapters
+- **Framework Agnostic** - Works with Rails, Sinatra, or standalone
+- **JSON Rule DSL** - Non-technical users can write rules
+- **Visual Rule Builder** - Web UI for rule management
 
-The DecisionAgent Web UI provides a visual interface for building and testing rules.
+### Production Features
+- **Real-time Monitoring** - Live dashboard with WebSocket updates
+- **Prometheus Export** - Industry-standard metrics format
+- **Intelligent Alerting** - Anomaly detection with customizable rules
+- **Grafana Integration** - Pre-built dashboards and alert rules
+- **Version Control** - Full rule version control and rollback
+- **Thread-Safe** - Safe for multi-threaded servers and background jobs
+- **High Performance** - 10,000+ decisions/second, ~0.1ms latency
 
-### Standalone Usage
+## Web UI - Visual Rule Builder
 
 Launch the visual rule builder:
 
@@ -71,246 +101,50 @@ decision_agent web
 
 Open [http://localhost:4567](http://localhost:4567) in your browser.
 
-### Mount in Rails
-
-Add to your `config/routes.rb`:
+### Integration
 
+**Rails:**
 ```ruby
 require 'decision_agent/web/server'
-
 Rails.application.routes.draw do
-  # Mount DecisionAgent Web UI
-  mount DecisionAgent::Web::Server, at: '/decision_agent'
-end
-```
-
-Then visit `http://localhost:3000/decision_agent` in your browser.
-
-**With Authentication:**
-
-```ruby
-authenticate :user, ->(user) { user.admin? } do
   mount DecisionAgent::Web::Server, at: '/decision_agent'
 end
 ```
 
-### Mount in Rack/Sinatra Apps
-
+**Rack/Sinatra:**
 ```ruby
-# config.ru
 require 'decision_agent/web/server'
-
 map '/decision_agent' do
   run DecisionAgent::Web::Server
 end
 ```
 
-<img width="1622" height="820" alt="Screenshot" src="https://github.com/user-attachments/assets/687e9ff6-669a-40f9-be27-085c614392d4" />
-
-See [Web UI Rails Integration Guide](wiki/WEB_UI_RAILS_INTEGRATION.md) for detailed setup instructions.
+See [Web UI Integration Guide](docs/WEB_UI_RAILS_INTEGRATION.md) for detailed setup.
 
 ## Monitoring & Analytics
 
 Real-time monitoring, metrics, and alerting for production environments.
 
-### Quick Start
-
 ```ruby
 require 'decision_agent/monitoring/metrics_collector'
 require 'decision_agent/monitoring/dashboard_server'
 
-# Initialize metrics collection
 collector = DecisionAgent::Monitoring::MetricsCollector.new(window_size: 3600)
-
-# Start real-time dashboard
 DecisionAgent::Monitoring::DashboardServer.start!(
   port: 4568,
   metrics_collector: collector
 )
-
-# Record decisions
-agent = DecisionAgent::Agent.new(evaluators: [evaluator])
-result = agent.decide(context: { amount: 1500 })
-collector.record_decision(result, context, duration_ms: 25.5)
 ```
 
 Open [http://localhost:4568](http://localhost:4568) for the monitoring dashboard.
 
-### Features
-
-- **Real-time Dashboard** - Live metrics with WebSocket updates
-- **Prometheus Export** - Industry-standard metrics format
-- **Intelligent Alerting** - Anomaly detection with customizable rules
-- **Grafana Integration** - Pre-built dashboards and alert rules
-- **Custom KPIs** - Track business-specific metrics
-- **Thread-Safe** - Production-ready performance
-
-### Prometheus & Grafana
-
-```yaml
-# prometheus.yml
-scrape_configs:
-  - job_name: 'decision_agent'
-    static_configs:
-      - targets: ['localhost:4568']
-    metrics_path: '/metrics'
-```
-
-Import the pre-built Grafana dashboard from [grafana/decision_agent_dashboard.json](grafana/decision_agent_dashboard.json).
-
-### Alert Management
-
-```ruby
-alert_manager = DecisionAgent::Monitoring::AlertManager.new(
-  metrics_collector: collector
-)
+**Features:**
+- Real-time dashboard with WebSocket updates
+- Prometheus metrics export
+- Intelligent alerting with anomaly detection
+- Grafana integration with pre-built dashboards
 
-# Add alert rules
-alert_manager.add_rule(
-  name: 'High Error Rate',
-  condition: AlertManager.high_error_rate(threshold: 0.1),
-  severity: :critical
-)
-
-# Register alert handlers
-alert_manager.add_handler do |alert|
-  SlackNotifier.notify("🚨 #{alert[:message]}")
-end
-
-# Start monitoring
-alert_manager.start_monitoring(interval: 60)
-```
-
-See [Monitoring & Analytics Guide](wiki/MONITORING_AND_ANALYTICS.md) for complete documentation.
-
-
-## Key Features
-
-### Decision Making
-- **Multiple Evaluators** - Combine rule-based, ML, and custom logic
-- **Conflict Resolution** - Weighted average, consensus, threshold, max weight
-- **Rich Context** - Nested data, dot notation, flexible operators
-
-### Auditability
-- **Complete Audit Trails** - Every decision fully logged
-- **Deterministic Replay** - Reproduce historical decisions exactly
-- **Compliance Ready** - HIPAA, SOX, regulatory compliance support
-
-### Flexibility
-- **Pluggable Architecture** - Custom evaluators, scoring, audit adapters
-- **Framework Agnostic** - Works with Rails, Sinatra, or standalone
-- **JSON Rule DSL** - Non-technical users can write rules
-- **Visual Rule Builder** - Web UI for rule management
-
-### Monitoring & Observability
-- **Real-time Metrics** - Live dashboard with WebSocket updates (<1 second latency)
-- **Prometheus Export** - Industry-standard metrics format at `/metrics` endpoint
-- **Intelligent Alerting** - Anomaly detection with customizable rules and severity levels
-- **Grafana Integration** - Pre-built dashboards and alert configurations in `grafana/` directory
-- **Custom KPIs** - Track business-specific metrics with thread-safe operations
-- **MonitoredAgent** - Drop-in replacement that auto-records all metrics
-- **AlertManager** - Built-in anomaly detection (error rates, latency spikes, low confidence)
-
-### Production Ready
-- **Comprehensive Testing** - 90%+ code coverage
-- **Error Handling** - Clear, actionable error messages
-- **Versioning** - Full rule version control and rollback
-- **Performance** - Fast, zero external dependencies
-- **Thread-Safe** - Safe for multi-threaded servers and background jobs
-
-## Examples
-
-```ruby
-# Multiple evaluators with conflict resolution
-agent = DecisionAgent::Agent.new(
-  evaluators: [rule_evaluator, ml_evaluator],
-  scoring_strategy: DecisionAgent::Scoring::Consensus.new(minimum_agreement: 0.7),
-  audit_adapter: DecisionAgent::Audit::LoggerAdapter.new
-)
-
-# Complex rules with nested conditions
-rules = {
-  version: "1.0",
-  ruleset: "fraud_detection",
-  rules: [{
-    id: "suspicious_activity",
-    if: {
-      all: [
-        { field: "amount", op: "gt", value: 10000 },
-        { any: [
-          { field: "user.country", op: "in", value: ["XX", "YY"] },
-          { field: "velocity", op: "gt", value: 5 }
-        ]}
-      ]
-    },
-    then: { decision: "flag_for_review", weight: 0.95, reason: "Suspicious patterns detected" }
-  }]
-}
-```
-
-See [examples/](examples/) for complete working examples.
-
-## Thread-Safety Guarantees
-
-DecisionAgent is designed to be **thread-safe and FAST** for use in multi-threaded environments:
-
-### Performance
-- **10,000+ decisions/second** throughput
-- **~0.1ms average latency** per decision
-- **Zero performance overhead** from thread-safety
-- **Linear scalability** with thread count
-
-### Safe Concurrent Usage
-- **Agent instances** can be shared across threads safely
-- **Evaluators** are immutable after initialization
-- **Decisions and Evaluations** are deeply frozen
-- **File storage** uses mutex-protected operations
-
-### Best Practices
-```ruby
-# Safe: Reuse agent instance across threads
-agent = DecisionAgent::Agent.new(evaluators: [evaluator])
-
-Thread.new { agent.decide(context: { user_id: 1 }) }
-Thread.new { agent.decide(context: { user_id: 2 }) }
-
-# Safe: Share evaluators across agent instances
-evaluator = DecisionAgent::Evaluators::JsonRuleEvaluator.new(rules_json: rules)
-agent1 = DecisionAgent::Agent.new(evaluators: [evaluator])
-agent2 = DecisionAgent::Agent.new(evaluators: [evaluator])
-```
-
-### What's Frozen
-All data structures are deeply frozen to prevent mutation:
-- Decision objects (decision, confidence, explanations, evaluations)
-- Evaluation objects (decision, weight, reason, metadata)
-- Context data
-- Rule definitions in evaluators
-
-This ensures safe concurrent access without race conditions.
-
-### RFC 8785 Canonical JSON
-DecisionAgent uses **RFC 8785 (JSON Canonicalization Scheme)** for deterministic audit hashing:
-
-- **Industry Standard** - Official IETF specification for canonical JSON
-- **Cryptographically Sound** - Ensures deterministic hashing of decision payloads
-- **Reproducible** - Same decision always produces same audit hash
-- **Interoperable** - Compatible with other systems using RFC 8785
-
-Every decision includes a deterministic SHA-256 hash in the audit payload, enabling:
-- Tamper detection in audit logs
-- Exact replay verification
-- Regulatory compliance documentation
-
-Learn more: [RFC 8785 Specification](https://datatracker.ietf.org/doc/html/rfc8785)
-
-### Performance Benchmark
-Run the included benchmark to verify zero overhead:
-```bash
-ruby examples/thread_safe_performance.rb
-```
-
-See [THREAD_SAFETY.md](wiki/THREAD_SAFETY.md) for detailed implementation guide and [PERFORMANCE_AND_THREAD_SAFETY.md](wiki/PERFORMANCE_AND_THREAD_SAFETY.md) for detailed performance analysis.
+See [Monitoring & Analytics Guide](docs/MONITORING_AND_ANALYTICS.md) for complete documentation.
 
 ## When to Use DecisionAgent
 
@@ -328,31 +162,48 @@ See [THREAD_SAFETY.md](wiki/THREAD_SAFETY.md) for detailed implementation guide
 
 ## Documentation
 
-**Getting Started**
+### Getting Started
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [Examples](examples/README.md)
-
-**Core Features**
-- [Versioning System](wiki/VERSIONING.md) - Version control for rules
-- [Web UI](wiki/WEB_UI.md) - Visual rule builder
-- [Web UI Setup](wiki/WEB_UI_SETUP.md) - Setup guide
-- [Web UI Rails Integration](wiki/WEB_UI_RAILS_INTEGRATION.md) - Mount in Rails/Rack apps
-- [Monitoring & Analytics](wiki/MONITORING_AND_ANALYTICS.md) - Real-time monitoring, metrics, and alerting
-- [Monitoring Architecture](wiki/MONITORING_ARCHITECTURE.md) - System architecture and design
-
-**Performance & Thread-Safety**
-- [Performance & Thread-Safety Summary](wiki/PERFORMANCE_AND_THREAD_SAFETY.md) - Benchmarks and production readiness
-- [Thread-Safety Implementation](wiki/THREAD_SAFETY.md) - Technical implementation guide
-
-**Reference**
-- [API Contract](wiki/API_CONTRACT.md) - Full API reference
-- [Changelog](wiki/CHANGELOG.md) - Version history
-
-**More Resources**
-- [Wiki Home](wiki/README.md) - Documentation index
+- [Code Examples](docs/CODE_EXAMPLES.md) - Comprehensive code snippets
+- [Examples Directory](examples/README.md) - Working examples with explanations
+
+### Core Features
+- [Advanced Operators](docs/ADVANCED_OPERATORS.md) - String, numeric, date/time, collection, and geospatial operators
+- [Versioning System](docs/VERSIONING.md) - Version control for rules
+- [A/B Testing](docs/AB_TESTING.md) - Compare rule versions with statistical analysis
+- [Web UI](docs/WEB_UI.md) - Visual rule builder
+- [Web UI Setup](docs/WEB_UI_SETUP.md) - Setup guide
+- [Web UI Rails Integration](docs/WEB_UI_RAILS_INTEGRATION.md) - Mount in Rails/Rack apps
+- [Monitoring & Analytics](docs/MONITORING_AND_ANALYTICS.md) - Real-time monitoring, metrics, and alerting
+- [Monitoring Architecture](docs/MONITORING_ARCHITECTURE.md) - System architecture and design
+
+### Performance & Thread-Safety
+- [Performance & Thread-Safety Summary](docs/PERFORMANCE_AND_THREAD_SAFETY.md) - Benchmarks and production readiness
+- [Thread-Safety Implementation](docs/THREAD_SAFETY.md) - Technical implementation guide
+
+### Reference
+- [API Contract](docs/API_CONTRACT.md) - Full API reference
+- [Changelog](docs/CHANGELOG.md) - Version history
+- [Code Coverage Report](coverage.md) - Test coverage statistics
+
+### More Resources
+- [Documentation Home](docs/README.md) - Documentation index
 - [GitHub Issues](https://github.com/samaswin87/decision_agent/issues) - Report bugs or request features
 
+## Thread-Safety & Performance
+
+DecisionAgent is designed to be **thread-safe and FAST** for use in multi-threaded environments:
+
+- **10,000+ decisions/second** throughput
+- **~0.1ms average latency** per decision
+- **Zero performance overhead** from thread-safety
+- **Linear scalability** with thread count
+
+All data structures are deeply frozen to prevent mutation, ensuring safe concurrent access without race conditions.
+
+See [Thread-Safety Guide](docs/THREAD_SAFETY.md) and [Performance Analysis](docs/PERFORMANCE_AND_THREAD_SAFETY.md) for details.
+
 ## Contributing
 
 1. Fork the repository
@@ -363,8 +214,8 @@ See [THREAD_SAFETY.md](wiki/THREAD_SAFETY.md) for detailed implementation guide
 ## Support
 
 - **Issues**: [GitHub Issues](https://github.com/samaswin87/decision_agent/issues)
-- **Documentation**: [Wiki](wiki/README.md)
-- **Examples**: [examples/](examples/)
+- **Documentation**: [Documentation](docs/README.md)
+- **Examples**: [Examples Directory](examples/README.md)
 
 ## License
 

data/lib/decision_agent/ab_testing/ab_test.rb

@@ -0,0 +1,197 @@
+module DecisionAgent
+  module ABTesting
+    # Represents an A/B test configuration for comparing rule versions
+    class ABTest
+      attr_reader :id, :name, :champion_version_id, :challenger_version_id,
+                  :traffic_split, :start_date, :end_date, :status
+
+      # @param name [String] Name of the A/B test
+      # @param champion_version_id [String, Integer] ID of the current/champion version
+      # @param challenger_version_id [String, Integer] ID of the new/challenger version
+      # @param options [Hash] Optional configuration
+      # @option options [Hash] :traffic_split Traffic distribution (default: { champion: 90, challenger: 10 })
+      # @option options [Time] :start_date When the test starts (defaults to now)
+      # @option options [Time] :end_date When the test ends (optional)
+      # @option options [String] :status Test status: running, completed, cancelled, scheduled
+      # @option options [String, Integer] :id Optional ID (for persistence)
+      def initialize(
+        name:,
+        champion_version_id:,
+        challenger_version_id:,
+        **options
+      )
+        @id = options[:id]
+        @name = name
+        @champion_version_id = champion_version_id
+        @challenger_version_id = challenger_version_id
+        @traffic_split = normalize_traffic_split(options[:traffic_split] || { champion: 90, challenger: 10 })
+        @start_date = options[:start_date] || Time.now.utc
+        @end_date = options[:end_date]
+        @status = options[:status] || "scheduled"
+
+        validate!
+      end
+
+      # Assign a variant based on traffic split
+      # Uses consistent hashing to ensure same user gets same variant
+      # @param user_id [String, nil] Optional user identifier for consistent assignment
+      # @return [Symbol] :champion or :challenger
+      def assign_variant(user_id: nil)
+        raise TestNotRunningError, "Test '#{@name}' is not running (status: #{@status})" unless running?
+
+        if user_id
+          # Consistent hashing: same user always gets same variant
+          hash_value = Digest::SHA256.hexdigest("#{@id}:#{user_id}").to_i(16)
+          percentage = hash_value % 100
+        else
+          # Random assignment
+          percentage = rand(100)
+        end
+
+        percentage < @traffic_split[:champion] ? :champion : :challenger
+      end
+
+      # Get the version ID for the assigned variant
+      # @param variant [Symbol] :champion or :challenger
+      # @return [String, Integer] The version ID
+      def version_for_variant(variant)
+        case variant
+        when :champion
+          @champion_version_id
+        when :challenger
+          @challenger_version_id
+        else
+          raise ArgumentError, "Invalid variant: #{variant}. Must be :champion or :challenger"
+        end
+      end
+
+      # Check if test is currently running
+      # @return [Boolean]
+      def running?
+        return false unless @status == "running"
+        return false if @start_date && Time.now.utc < @start_date
+        return false if @end_date && Time.now.utc > @end_date
+
+        true
+      end
+
+      # Check if test is scheduled to start
+      # @return [Boolean]
+      def scheduled?
+        @status == "scheduled" && @start_date && Time.now.utc < @start_date
+      end
+
+      # Check if test is completed
+      # @return [Boolean]
+      def completed?
+        @status == "completed" || (@end_date && Time.now.utc > @end_date)
+      end
+
+      # Start the test
+      def start!
+        raise InvalidStatusTransitionError, "Cannot start test from status: #{@status}" unless can_start?
+
+        @status = "running"
+        @start_date = Time.now.utc if @start_date.nil? || @start_date > Time.now.utc
+      end
+
+      # Complete the test
+      def complete!
+        raise InvalidStatusTransitionError, "Cannot complete test from status: #{@status}" unless can_complete?
+
+        @status = "completed"
+        @end_date = Time.now.utc
+      end
+
+      # Cancel the test
+      def cancel!
+        raise InvalidStatusTransitionError, "Cannot cancel test from status: #{@status}" if @status == "completed"
+
+        @status = "cancelled"
+      end
+
+      # Convert to hash representation
+      # @return [Hash]
+      def to_h
+        {
+          id: @id,
+          name: @name,
+          champion_version_id: @champion_version_id,
+          challenger_version_id: @challenger_version_id,
+          traffic_split: @traffic_split,
+          start_date: @start_date,
+          end_date: @end_date,
+          status: @status
+        }
+      end
+
+      private
+
+      def validate!
+        raise ValidationError, "Test name is required" if @name.nil? || @name.strip.empty?
+        raise ValidationError, "Champion version ID is required" if @champion_version_id.nil?
+        raise ValidationError, "Challenger version ID is required" if @challenger_version_id.nil?
+        raise ValidationError, "Champion and challenger must be different versions" if @champion_version_id == @challenger_version_id
+
+        validate_traffic_split!
+        validate_dates!
+        validate_status!
+      end
+
+      def validate_traffic_split!
+        raise ValidationError, "Traffic split must be a Hash" unless @traffic_split.is_a?(Hash)
+
+        unless @traffic_split.key?(:champion) && @traffic_split.key?(:challenger)
+          raise ValidationError,
+                "Traffic split must have :champion and :challenger keys"
+        end
+
+        total = @traffic_split[:champion] + @traffic_split[:challenger]
+        raise ValidationError, "Traffic split must sum to 100, got #{total}" unless total == 100
+
+        raise ValidationError, "Traffic percentages must be non-negative" if @traffic_split.values.any?(&:negative?)
+      end
+
+      def validate_dates!
+        return unless @start_date && @end_date
+
+        raise ValidationError, "End date must be after start date" if @end_date <= @start_date
+      end
+
+      def validate_status!
+        valid_statuses = %w[scheduled running completed cancelled]
+        return if valid_statuses.include?(@status)
+
+        raise ValidationError, "Invalid status: #{@status}. Must be one of: #{valid_statuses.join(', ')}"
+      end
+
+      def normalize_traffic_split(split)
+        case split
+        when Hash
+          # Handle both string and symbol keys
+          {
+            champion: (split[:champion] || split["champion"] || 50).to_i,
+            challenger: (split[:challenger] || split["challenger"] || 50).to_i
+          }
+        when Array
+          # Handle array format [90, 10]
+          { champion: split[0].to_i, challenger: split[1].to_i }
+        else
+          raise ValidationError, "Traffic split must be a Hash or Array"
+        end
+      end
+
+      def can_start?
+        %w[scheduled].include?(@status)
+      end
+
+      def can_complete?
+        %w[running].include?(@status)
+      end
+    end
+
+    # Custom errors
+    class TestNotRunningError < StandardError; end
+    class InvalidStatusTransitionError < StandardError; end
+  end
+end

data/lib/decision_agent/ab_testing/ab_test_assignment.rb

@@ -0,0 +1,76 @@
+module DecisionAgent
+  module ABTesting
+    # Tracks individual assignments of users/requests to A/B test variants
+    class ABTestAssignment
+      attr_reader :id, :ab_test_id, :user_id, :variant, :version_id,
+                  :timestamp, :decision_result, :confidence, :context
+
+      # @param ab_test_id [String, Integer] The A/B test ID
+      # @param variant [Symbol] :champion or :challenger
+      # @param version_id [String, Integer] The rule version ID that was used
+      # @param options [Hash] Optional configuration
+      # @option options [String] :user_id User identifier (optional)
+      # @option options [Time] :timestamp When the assignment occurred
+      # @option options [String] :decision_result The decision outcome
+      # @option options [Float] :confidence Confidence score of the decision
+      # @option options [Hash] :context Additional context for the decision
+      # @option options [String, Integer] :id Optional ID (for persistence)
+      def initialize(
+        ab_test_id:,
+        variant:,
+        version_id:,
+        **options
+      )
+        @id = options[:id]
+        @ab_test_id = ab_test_id
+        @user_id = options[:user_id]
+        @variant = variant
+        @version_id = version_id
+        @timestamp = options[:timestamp] || Time.now.utc
+        @decision_result = options[:decision_result]
+        @confidence = options[:confidence]
+        @context = options[:context] || {}
+
+        validate!
+      end
+
+      # Update the assignment with decision results
+      # @param decision [String] The decision result
+      # @param confidence [Float] The confidence score
+      def record_decision(decision, confidence)
+        @decision_result = decision
+        @confidence = confidence
+      end
+
+      # Convert to hash representation
+      # @return [Hash]
+      def to_h
+        {
+          id: @id,
+          ab_test_id: @ab_test_id,
+          user_id: @user_id,
+          variant: @variant,
+          version_id: @version_id,
+          timestamp: @timestamp,
+          decision_result: @decision_result,
+          confidence: @confidence,
+          context: @context
+        }
+      end
+
+      private
+
+      def validate!
+        raise ValidationError, "AB test ID is required" if @ab_test_id.nil?
+        raise ValidationError, "Variant is required" if @variant.nil?
+        raise ValidationError, "Version ID is required" if @version_id.nil?
+
+        raise ValidationError, "Variant must be :champion or :challenger, got: #{@variant}" unless %i[champion challenger].include?(@variant)
+
+        return unless @confidence && (@confidence.negative? || @confidence > 1)
+
+        raise ValidationError, "Confidence must be between 0 and 1, got: #{@confidence}"
+      end
+    end
+  end
+end