historiographer 4.1.2 → 4.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2281f88ad4a2145f68c25fe6898770ba38ca4792a5ab8f3f6cbcedeca2b8455d
-  data.tar.gz: de5faba8282b740969980c007e78060b2fb9c6161f3ec2471e4ce6f2cb8683fc
+  metadata.gz: 378dc2b078459333c3c0510904c394f27aab51358bec13097cdefdf84627e618
+  data.tar.gz: cc27a0afe8050aef01bbada81657f481277b21fcdc94fa5f32976d3f06c01969
 SHA512:
-  metadata.gz: 13622823469e2fd145ba26db17feec352c808ffbaf19488132bfb384c563d5c90ec13162e02894ac4aa4a9ddc09ef519261fb56777b0e5ef947485359830baf6
-  data.tar.gz: 772c250ad9a270d6c5d77a33f537a5b965833bde3ab593d46199f4fbd5004c0a9730c9679c6b8ae87d26244a4723ce1b4ed88c50e6c4b3915dd2750d7473afb3
+  metadata.gz: 28489a6de7ec69e1856f45d8336b0ce4f3de6ccdfcf6f9d3fa1e974cfc85dfbf5badc25a06fd121889c363d466dac8cb11ce2c2e836660ff629d594fe01ccb7c
+  data.tar.gz: 60082b9549d0b682e06760eb1af6491c14b0f6081ffbf92586ec70a030edc6021276344eef1ca66917f8e20fcddb50d3dbd67ff74bfc6f275041af001f20a184

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.name.underscore.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.3"
 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
@@ -352,6 +349,29 @@ 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?
+        attrs[self.class.inheritance_column] = history_class.name
+      end
+
+      attrs = attrs.except('id')
+
+      attrs
+    end
+
     private
 
     def history_user_absent_action
@@ -367,19 +387,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 +409,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 +439,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.3
 platform: ruby
 authors:
 - brettshollenberger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-08-22 00:00:00.000000000 Z
+date: 2024-11-18 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: []