historiographer 4.1.2 → 4.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2281f88ad4a2145f68c25fe6898770ba38ca4792a5ab8f3f6cbcedeca2b8455d
-  data.tar.gz: de5faba8282b740969980c007e78060b2fb9c6161f3ec2471e4ce6f2cb8683fc
+  metadata.gz: ec4560a7984db99bb67a91f6ed46ffd5e0e0b68b208b9f5c56079d5d0c967c06
+  data.tar.gz: 558f4f69363da666c55ad58bdf4aa1108e405c96d54e2ae4d96f4d7baa87e4a0
 SHA512:
-  metadata.gz: 13622823469e2fd145ba26db17feec352c808ffbaf19488132bfb384c563d5c90ec13162e02894ac4aa4a9ddc09ef519261fb56777b0e5ef947485359830baf6
-  data.tar.gz: 772c250ad9a270d6c5d77a33f537a5b965833bde3ab593d46199f4fbd5004c0a9730c9679c6b8ae87d26244a4723ce1b4ed88c50e6c4b3915dd2750d7473afb3
+  metadata.gz: 803285240c47f720ae89ba027d1143e7b0e63ed765bb26399b7d126e2c04449664604a7488553f8996f89c3736d86909ed52702fcc5fb4bf7df2cb2fa5de4a44
+  data.tar.gz: 263c7cd005f3cd3589a1ed47c62d7127844686c5b945e1835995b99151b0bbceb6b72c86bac80e09b17efde796e3eeef2b34a0d9f33fb99945915e14b1c9aef8

data/README.md

@@ -130,7 +130,174 @@ This can be useful when:
 - You're versioning training data for machine learning models
 - You need to maintain immutable audit trails at specific checkpoints
 
-# Getting Started
+## Single Table Inheritance (STI)
+
+Historiographer fully supports Single Table Inheritance, both with the default `type` column and with custom inheritance columns.
+
+### Default STI with `type` column
+
+```ruby
+class Post < ApplicationRecord
+  include Historiographer
+end
+
+class PrivatePost < Post
+end
+
+# The history classes follow the same inheritance pattern:
+class PostHistory < ApplicationRecord
+  include Historiographer::History
+end
+
+class PrivatePostHistory < PostHistory
+end
+```
+
+History records automatically maintain the correct STI type:
+
+```ruby
+private_post = PrivatePost.create(title: "Secret", history_user_id: current_user.id)
+private_post.snapshot
+
+# History records are the correct subclass
+history = PostHistory.last
+history.is_a?(PrivatePostHistory) #=> true
+history.type #=> "PrivatePostHistory"
+```
+
+### Custom Inheritance Columns
+
+You can also use a custom column for STI instead of the default `type`:
+
+```ruby
+class MLModel < ApplicationRecord
+  include Historiographer
+  self.inheritance_column = :model_type
+end
+
+class XGBoost < MLModel
+  self.table_name = "ml_models"
+end
+
+# History classes use the same custom column
+class MLModelHistory < MLModel
+  self.inheritance_column = :model_type
+  self.table_name = "ml_model_histories"
+end
+
+class XGBoostHistory < MLModelHistory
+end
+```
+
+Migration for custom inheritance column:
+
+```ruby
+create_table :ml_models do |t|
+  t.string :name
+  t.string :model_type  # Custom inheritance column
+  t.jsonb :parameters
+  t.timestamps
+
+  t.index :model_type
+end
+
+create_table :ml_model_histories do |t|
+  t.histories  # Includes all columns from parent table
+end
+```
+
+The custom inheritance column works just like the default `type`:
+
+```ruby
+model = XGBoost.create(name: "My Model", history_user_id: current_user.id)
+model.snapshot
+
+# History records maintain the correct subclass
+history = MLModelHistory.last
+history.is_a?(XGBoostHistory) #=> true
+history.model_type #=> "XGBoostHistory"
+```
+
+### STI and Snapshots: Perfect for Model Versioning
+
+Single Table Inheritance combined with Historiographer's snapshot feature is particularly powerful for versioning machine learning models and other complex systems that need immutable historical records. Here's why:
+
+1. **Type-Safe History**: When you snapshot an ML model, both the model and its parameters are preserved with their exact implementation type. This ensures that when you retrieve historical versions, you get back exactly the right subclass with its specific behavior:
+
+```ruby
+# Create and configure an XGBoost model
+model = XGBoost.create(
+  name: "Customer Churn Predictor v1",
+  parameters: { max_depth: 3, eta: 0.1 },
+  history_user_id: current_user.id
+)
+
+# Take a snapshot before training
+model.snapshot
+
+# Update the model after training
+model.update(
+  name: "Customer Churn Predictor v2",
+  parameters: { max_depth: 5, eta: 0.2 },
+  history_user_id: current_user.id
+)
+
+# Later, retrieve the exact pre-training version
+historical_model = MLModel.latest_snapshot
+historical_model.is_a?(XGBoostHistory) #=> true
+historical_model.parameters #=> { max_depth: 3, eta: 0.1 }
+```
+
+2. **Implementation Versioning**: Different model types often have different parameters, preprocessing steps, or scoring methods. STI ensures these differences are preserved in history:
+
+```ruby
+class XGBoost < MLModel
+  def predict(data)
+    # XGBoost-specific prediction logic
+  end
+end
+
+class RandomForest < MLModel
+  def predict(data)
+    # RandomForest-specific prediction logic
+  end
+end
+
+# Your historical records maintain these implementation differences
+old_model = MLModel.latest_snapshot
+old_model.predict(data) # Uses the exact prediction logic from that point in time
+```
+
+3. **Reproducibility**: Essential for ML workflows where you need to reproduce results or audit model behavior:
+
+```ruby
+# Create model and snapshot at each significant stage
+model = XGBoost.create(name: "Risk Scorer v1", history_user_id: current_user.id)
+
+# Snapshot after initial configuration
+model.snapshot(metadata: { stage: "configuration" })
+
+# Snapshot after training
+model.update(parameters: trained_parameters)
+model.snapshot(metadata: { stage: "post_training" })
+
+# Snapshot after validation
+model.update(parameters: validated_parameters)
+model.snapshot(metadata: { stage: "validated" })
+
+# Later, you can retrieve any version to reproduce results
+initial_version = model.histories.find_by(metadata: { stage: "configuration" })
+trained_version = model.histories.find_by(metadata: { stage: "post_training" })
+```
+
+This combination of STI and snapshots is particularly valuable for:
+- Model governance and compliance
+- A/B testing different model types
+- Debugging model behavior
+- Reproducing historical predictions
+- Maintaining audit trails for regulatory requirements
+
+## Getting Started
 
 Whenever you include the `Historiographer` gem in your ActiveRecord model, it allows you to insert, update, or delete data as you normally would.
 

data/lib/historiographer/history.rb

@@ -88,6 +88,7 @@ module Historiographer
       # "RetailerProductHistory."
       #
       foreign_class_name = base.name.gsub(/History$/) {}        # e.g. "RetailerProductHistory" => "RetailerProduct"
+      foreign_class = foreign_class_name.constantize
       association_name   = foreign_class_name.split("::").last.underscore.to_sym # e.g. "RetailerProduct" => :retailer_product
 
       #
@@ -115,6 +116,14 @@ module Historiographer
         belongs_to association_name, class_name: foreign_class_name
       end
 
+      # Enable STI for history classes
+      if foreign_class.sti_enabled?
+        self.inheritance_column = 'type'
+      end
+
+      # Ensure we can't destroy history records
+      before_destroy { |record| raise "Cannot destroy history records" }
+
       #
       # A History record should never be destroyed.
       #
@@ -158,19 +167,31 @@ module Historiographer
       # Orders by history_started_at and id to handle cases where multiple records
       # have the same history_started_at timestamp
       scope :latest_snapshot, -> {
-        where.not(snapshot_id: nil).order('id DESC').limit(1)&.first
+        where.not(snapshot_id: nil).order('id DESC').limit(1)&.first || none
       }
     end
 
     class_methods do
-
       #
       # The foreign key to the primary class.
       #
       # E.g. PostHistory.history_foreign_key => post_id
       #
       def history_foreign_key
-        name.gsub(/History$/) {}.foreign_key
+        return @history_foreign_key if @history_foreign_key
+
+        @history_foreign_key = sti_base_class.table_name.singularize.foreign_key
+      end
+
+      def sti_base_class
+        return @sti_base_class if @sti_base_class
+
+        base_name = name.gsub(/History$/, '')
+        base_class = base_name.constantize
+        while base_class.superclass != ActiveRecord::Base
+          base_class = base_class.superclass
+        end
+        @sti_base_class = base_class
       end
     end
   end

data/lib/historiographer/relation.rb

@@ -36,13 +36,7 @@ module Historiographer
       history_user_id = updates[:history_user_id]
 
       new_histories = records.map do |record|
-        attrs         = record.attributes.clone
-        foreign_key   = history_class.history_foreign_key
-  
-        attrs.merge!(foreign_key => attrs["id"], history_started_at: now, history_user_id: history_user_id)
-  
-        attrs = attrs.except("id")
-
+        attrs = record.history_attrs(now: now)
         record.histories.build(attrs)
       end
 
@@ -72,14 +66,9 @@ module Historiographer
 
           if records.first.respond_to?(:paranoia_destroy)
             new_histories = records.map do |record|
-              attrs         = record.attributes.clone
-              foreign_key   = history_class.history_foreign_key
-        
-              now = UTC.now
-              attrs.merge!(foreign_key => attrs["id"], history_started_at: now, history_user_id: history_user_id, deleted_at: now)
-        
-              attrs = attrs.except("id")
-
+              attrs = record.history_attrs(now: now)
+              attrs[:history_user_id] = history_user_id
+              attrs[:deleted_at] = now
               record.histories.build(attrs)
             end
             history_class.import new_histories

data/lib/historiographer/version.rb

@@ -1,3 +1,3 @@
 module Historiographer
-  VERSION = "4.1.2"
+  VERSION = "4.1.4"
 end

data/lib/historiographer.rb

@@ -2,6 +2,7 @@
 
 require 'active_support/all'
 require 'securerandom'
+require_relative './historiographer/configuration'
 require_relative './historiographer/history'
 require_relative './historiographer/postgres_migration'
 require_relative './historiographer/safe'
@@ -84,10 +85,6 @@ module Historiographer
     after_save :record_history, if: :should_record_history?
     validate :validate_history_user_id_present, if: :should_validate_history_user_id_present?
 
-    # Add scope to fetch latest histories
-    scope :latest_snapshot, -> {
-      history_class.latest_snapshot
-    }
 
     def should_alert_history_user_id_present?
       !snapshot_mode? && !is_history_class? && Thread.current[:skip_history_user_id_validation] != true
@@ -188,12 +185,30 @@ module Historiographer
     begin
       class_name.constantize
     rescue StandardError
+      # Get the base table name without _histories suffix
+      base_table = base.table_name.sub(/_histories$/, '')
+      
       history_class_initializer = Class.new(base) do
-        self.table_name = "#{base.table_name}_histories"
-        self.inheritance_column = nil
+        self.table_name = "#{base_table}_histories"
+        
+        # Handle STI properly
+        self.inheritance_column = base.inheritance_column if base.respond_to?(:inheritance_column)
       end
 
-      Object.const_set(class_name, history_class_initializer)
+      # Split the class name into module parts and the actual class name
+      module_parts = class_name.split('::')
+      final_class_name = module_parts.pop
+
+      # Navigate through module hierarchy
+      target_module = module_parts.inject(Object) do |mod, module_name|
+        mod.const_defined?(module_name) ? mod.const_get(module_name) : mod.const_set(module_name, Module.new)
+      end
+
+      # Set the constant in the correct module
+      history_class = target_module.const_set(final_class_name, history_class_initializer)
+      
+      # Now that the class is named, include the History module and extend class methods
+      history_class.send(:include, Historiographer::History)
     end
 
     klass = class_name.constantize
@@ -262,21 +277,13 @@ module Historiographer
       end
     end)
 
-    if base.respond_to?(:histories)
-      raise "#{base} already has histories. Talk to Brett if this is a legit use case."
-    else
-      opts = { class_name: class_name }
-      opts[:foreign_key] = klass.history_foreign_key if klass.respond_to?(:history_foreign_key)
-      if RUBY_VERSION.to_i >= 3
-        has_many :histories, **opts
-        has_one :current_history, -> { current }, **opts
-      else
-        has_many :histories, opts
-        has_one :current_history, -> { current }, opts
-      end
+    def histories
+      history_class.where(history_class.history_foreign_key => self.send(self.class.primary_key))
     end
 
-    klass.send(:include, Historiographer::History) unless klass.ancestors.include?(Historiographer::History)
+    def current_history
+      history_class.where(history_class.history_foreign_key => self.send(self.class.primary_key)).current&.first
+    end
 
     #
     # The acts_as_paranoid gem, which we tend to use with our History classes,
@@ -352,6 +359,30 @@ module Historiographer
       end
     end
 
+    def history_class
+      self.class.history_class
+    end
+
+    def history_attrs(snapshot_id: nil, now: nil)
+      attrs = attributes.clone
+      history_class = self.class.history_class
+      foreign_key = history_class.history_foreign_key
+
+      now ||= UTC.now
+      attrs.merge!(foreign_key => attrs['id'], history_started_at: now, history_user_id: history_user_id)
+      attrs.merge!(snapshot_id: snapshot_id) if snapshot_id.present?
+
+      # For STI, ensure we use the correct history class type
+      if self.class.sti_enabled?
+        type_column = self.class.inheritance_column
+        attrs[type_column] = "#{self.class.name}History"
+      end
+
+      attrs = attrs.except('id')
+
+      attrs
+    end
+
     private
 
     def history_user_absent_action
@@ -367,19 +398,11 @@ module Historiographer
     def record_history(snapshot_id: nil)
       history_user_absent_action if history_user_id.nil? && should_alert_history_user_id_present?
 
-      attrs = attributes.clone
-      history_class = self.class.history_class
-      foreign_key = history_class.history_foreign_key
-
       now = UTC.now
-      attrs.merge!(foreign_key => attrs['id'], history_started_at: now, history_user_id: history_user_id)
-      attrs.merge!(snapshot_id: snapshot_id) if snapshot_id.present?
-
-      attrs = attrs.except('id')
-
+      attrs = history_attrs(snapshot_id: snapshot_id, now: now)
       current_history = histories.where(history_ended_at: nil).order('id desc').limit(1).last
 
-      if foreign_key.present? && history_class.present?
+      if history_class.history_foreign_key.present? && history_class.present?
         history_class.create!(attrs).tap do |history|
           current_history.update!(history_ended_at: now) if current_history.present?
         end
@@ -397,6 +420,11 @@ module Historiographer
   end
 
   class_methods do
+    def latest_snapshot
+      instance = history_class.latest_snapshot
+      instance.is_a?(history_class) ? instance : nil
+    end
+
     def is_history_class?
       name.match?(/History$/)
     end
@@ -422,6 +450,10 @@ module Historiographer
     def get_historiographer_mode
       @historiographer_mode || Historiographer::Configuration.mode
     end
+
+    def sti_enabled?
+      columns.map(&:name).include?(inheritance_column)
+    end
   end
 
   def is_history_class?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: historiographer
 version: !ruby/object:Gem::Version
-  version: 4.1.2
+  version: 4.1.4
 platform: ruby
 authors:
 - brettshollenberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-22 00:00:00.000000000 Z
+date: 2024-11-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -220,7 +220,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Creates separate tables for each history table
+description: Append-only histories + chained snapshots of your ActiveRecord tables
 email: brett.shollenberger@gmail.com
 executables: []
 extensions: []