legate 0.1.0

data/lib/legate/rails/railtie.rb

@@ -0,0 +1,43 @@
+# File: lib/legate/rails/railtie.rb
+# frozen_string_literal: true
+
+# In a booted Rails app these are already loaded; require them explicitly so a
+# cold `require 'legate/rails'` (e.g. in tests) doesn't trip on missing
+# ActiveSupport core extensions that rails/railtie assumes.
+require 'active_support'
+require 'active_support/core_ext/module/delegation'
+require 'rails/railtie'
+
+module Legate
+  module Rails
+    # Integrates Legate with a host Rails application. Loaded via
+    # `require 'legate/rails'` (e.g. `gem 'legate', require: 'legate/rails'`),
+    # never by `require 'legate'`.
+    #
+    # It registers the `legate:install` generator and exposes `config.legate`.
+    # The wiring itself (pointing the session store at ActiveRecord, reading the
+    # API key) lives in the generated `config/initializers/legate.rb`, so apps
+    # stay in control — the Railtie forces nothing.
+    class Railtie < ::Rails::Railtie
+      config.legate = ::ActiveSupport::OrderedOptions.new
+
+      # Make `rails generate legate:install` discoverable.
+      generators do
+        require 'legate/generators/legate/install_generator'
+      end
+
+      # Optional convenience: if the app sets `config.legate.use_active_record_store`
+      # truthy, point Legate at the ActiveRecord store after initialization
+      # (when the DB connection is ready). Apps that prefer to do this themselves
+      # in the initializer simply leave it unset.
+      initializer 'legate.session_store' do |app|
+        if app.config.legate.use_active_record_store
+          require 'legate/session_service/active_record'
+          Legate.configure do |c|
+            c.session_service = Legate::SessionService::ActiveRecord.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/legate/rails.rb

@@ -0,0 +1,9 @@
+# File: lib/legate/rails.rb
+# frozen_string_literal: true
+
+# Opt-in Rails integration. Require this (not just 'legate') inside a Rails app —
+# e.g. in the Gemfile: `gem 'legate', require: 'legate/rails'`. It loads the
+# Railtie, which registers the `legate:install` generator and the optional
+# ActiveRecord session-store wiring. `require 'legate'` alone never touches Rails.
+require 'legate'
+require_relative 'rails/railtie'

data/lib/legate/redaction.rb

@@ -0,0 +1,32 @@
+# File: lib/legate/redaction.rb
+# frozen_string_literal: true
+
+module Legate
+  # Strips secrets out of strings before they're logged or surfaced to users.
+  #
+  # LLM/HTTP client errors routinely embed the request URL — which for Gemini
+  # carries the API key as a `?key=...` query parameter — so error messages and
+  # logs must be scrubbed before they leave the process.
+  module Redaction
+    module_function
+
+    REPLACEMENT = '[REDACTED]'
+
+    # `key=`, `api_key=`, `access_token=`, `token=` query/form parameters.
+    SECRET_PARAM = /([?&](?:key|api[_-]?key|access_token|token)=)[^&\s"']+/i
+    # `Authorization: Bearer <token>`.
+    BEARER = %r{(Bearer\s+)[A-Za-z0-9\-._~+/]+=*}i
+    # Google API keys by their `AIza` prefix — a belt-and-suspenders catch even
+    # if the key shows up somewhere the patterns above don't match.
+    GOOGLE_KEY = /AIza[0-9A-Za-z\-_]{10,}/
+
+    # @param text [Object] anything stringifiable
+    # @return [String] the text with known secret shapes replaced
+    def redact(text)
+      text.to_s
+          .gsub(SECRET_PARAM, "\\1#{REPLACEMENT}")
+          .gsub(BEARER, "\\1#{REPLACEMENT}")
+          .gsub(GOOGLE_KEY, REPLACEMENT)
+    end
+  end
+end

data/lib/legate/session.rb

@@ -0,0 +1,299 @@
+# File: lib/legate/session.rb
+# frozen_string_literal: true
+
+require 'concurrent'
+require 'securerandom'
+require 'json'
+require_relative 'event' # Require the new Event class
+require_relative 'errors'
+
+module Legate
+  # Represents a single, ongoing conversation thread between a user and an agent system.
+  # It holds the history of interactions (Events) and temporary session-specific data (State).
+  class Session
+    VALID_PREFIXES = %w[user app temp].freeze
+
+    attr_reader :id, :app_name, :user_id, :created_at
+    attr_accessor :updated_at, :session_service
+
+    # Initializes a new session. Typically called by a SessionService.
+    # @param id [String] A unique identifier for the session (defaults to UUID).
+    # @param app_name [String] Identifier for the agent application.
+    # @param user_id [String] Identifier for the user initiating the session.
+    # @param initial_state [Hash] Optional initial data for the session state. Keys are symbolized.
+    # @param events [Array<Legate::Event>] Optional initial list of events (for reloading).
+    # @param session_service [Legate::SessionService::Base] The session service to use for persistence
+    def initialize(app_name:, user_id:, id: nil, initial_state: {}, events: [], session_service: nil)
+      @id = id || SecureRandom.uuid
+      @app_name = app_name
+      @user_id = user_id
+      @created_at = Time.now.utc # Use UTC
+      @updated_at = @created_at
+      @session_service = session_service
+      @mutex = Mutex.new
+      # Use Concurrent::Map for thread-safe state storage within the session object itself
+      @state = Concurrent::Map.new
+      # Ensure initial_state keys are symbols and manually populate the map
+      initial_state = {} unless initial_state.is_a?(Hash) # Ensure it's a hash
+      symbolized_initial_state = initial_state.transform_keys { |k|
+        begin
+          k.to_sym
+        rescue StandardError
+          k
+        end
+      }
+      symbolized_initial_state.each_pair do |key, value|
+        @state[key] = value
+      end
+      # Events array stores the history, ensure it's mutable if passed and validate contents
+      @events = events.map do |e|
+        if e.is_a?(Legate::Event)
+          e
+        else
+          (Legate.logger.warn("Session Init: Invalid event data skipped: #{e.inspect}")
+           nil)
+        end
+      end.compact
+      Legate.logger.debug("Session initialized: id=#{@id}, app=#{@app_name}, user=#{@user_id}, event_count=#{@events.size}")
+    end
+
+    # Thread-safe accessor for session events.
+    # @return [Array<Legate::Event>] A frozen snapshot of the event history.
+    def events
+      @mutex.synchronize { @events.dup.freeze }
+    end
+
+    # Provides access to the session's temporary state data.
+    # @return [Hash] The current session state (immutable view).
+    def state
+      # Ensure external modifications don't affect internal state directly.
+      @state.dup # Return a shallow copy
+    end
+
+    # Adds an event to the session's history and updates state if needed.
+    # @param event [Legate::Event] The event to add
+    # @return [Legate::Event, nil] The added event or nil if invalid
+    def add_event(event)
+      return nil unless event.is_a?(Legate::Event)
+
+      @mutex.synchronize do
+        @events << event
+        @updated_at = Time.now.utc
+      end
+
+      # Apply the event's state delta OUTSIDE the mutex: update_state may call the
+      # session service (save_scoped_state), and holding the non-reentrant @mutex
+      # across that external call risks deadlock if a service implementation calls
+      # back into the session (e.g. #events/#to_h). @state is a Concurrent::Map, so
+      # it is safe without the lock.
+      update_state(event.state_delta) if event.state_delta && !event.state_delta.empty?
+
+      Legate.logger.debug("Session #{@id}: Event added - Role: #{event.role}, Tool: #{event.tool_name || 'N/A'}")
+      event
+    end
+
+    # --- State Management Methods ---
+
+    # Gets a value from the session state.
+    # @param key [Symbol, String] The key to retrieve.
+    # @return [Object, nil] The value associated with the key, or nil if not found.
+    def get_state(key)
+      prefix, real_key = parse_key(key)
+      validate_prefix!(prefix) if prefix # match set/update/delete: reads and writes agree on what a key means
+      if prefix
+        @session_service&.load_scoped_state(scoped_namespace(prefix), real_key)
+      else
+        @state[real_key.to_sym]
+      end
+    end
+
+    # Sets a value in the session state.
+    # @param key [Symbol, String] The key to set.
+    # @param value [Object] The value to store.
+    # @raise [Legate::StateValidationError] If the value cannot be serialized
+    # @raise [Legate::InvalidPrefixError] If an invalid prefix is used
+    # @return [Object] The value that was set.
+    def set_state(key, value)
+      validate_serializable!(value)
+      prefix, real_key = parse_key(key)
+      validate_prefix!(prefix) if prefix
+
+      touch!
+      if prefix
+        @session_service&.save_scoped_state(scoped_namespace(prefix), real_key, value)
+      else
+        @state[real_key.to_sym] = value
+      end
+      value
+    end
+
+    # Merges a hash into the session state.
+    # @param hash [Hash] The hash to merge into the state.
+    # @raise [Legate::StateValidationError] If any value cannot be serialized
+    # @raise [Legate::InvalidPrefixError] If any key has an invalid prefix
+    def update_state(hash)
+      return unless hash.is_a?(Hash)
+
+      touch!
+      hash.each do |k, v|
+        validate_serializable!(v)
+        prefix, real_key = parse_key(k)
+        validate_prefix!(prefix) if prefix
+
+        if prefix
+          @session_service&.save_scoped_state(scoped_namespace(prefix), real_key, v)
+        else
+          @state[real_key.to_sym] = v
+        end
+      end
+    end
+
+    # Deletes a key from the session state.
+    # @param key [Symbol, String] The key to delete.
+    # @return [Object, nil] The value of the deleted key, or nil if not found.
+    def delete_state(key)
+      prefix, real_key = parse_key(key)
+      validate_prefix!(prefix) if prefix
+
+      touch!
+      if prefix
+        @session_service&.clear_scoped_state(scoped_namespace(prefix), real_key)
+      else
+        @state.delete(real_key.to_sym)
+      end
+    end
+
+    # Clears all key-value pairs from the session state.
+    def clear_state!
+      touch!
+      @state.clear
+      VALID_PREFIXES.each do |prefix|
+        @session_service&.clear_scoped_state(scoped_namespace(prefix), '*')
+      end
+    end
+
+    # Provides a plain Hash representation of the current state.
+    # @return [Hash] A copy of the session state.
+    def state_to_h
+      # Convert Concurrent::Map to a regular Hash
+      Hash[@state.to_enum(:each_pair).to_a]
+    end
+
+    # --- Serialization Helpers ---
+
+    # Serializes the entire session object to a Hash suitable for JSON conversion.
+    # @return [Hash] Hash representation of the session.
+    def to_h
+      serialized_events = @mutex.synchronize { @events.map(&:to_h) }
+      {
+        id: @id,
+        app_name: @app_name,
+        user_id: @user_id,
+        created_at: @created_at.iso8601(3),
+        updated_at: @updated_at.iso8601(3),
+        state: state_to_h,
+        events: serialized_events
+      }
+    end
+
+    # Deserializes session data from a hash into a Session object.
+    # @param hash [Hash] Hash containing session data (typically from JSON).
+    # @return [Legate::Session] A new Session object.
+    def self.from_h(hash)
+      sym_hash = hash.transform_keys(&:to_sym) # Ensure keys are symbols
+      events_data = sym_hash[:events] || []
+      events = events_data.map { |event_hash| Legate::Event.from_h(event_hash.transform_keys(&:to_sym)) }.compact
+
+      new(
+        id: sym_hash[:id],
+        app_name: sym_hash[:app_name],
+        user_id: sym_hash[:user_id],
+        initial_state: sym_hash[:state] || {},
+        events: events
+      ).tap do |session|
+        # Set timestamps after initialization
+        session.instance_variable_set(:@created_at, Time.iso8601(sym_hash[:created_at])) if sym_hash[:created_at]
+        session.instance_variable_set(:@updated_at, Time.iso8601(sym_hash[:updated_at])) if sym_hash[:updated_at]
+      end
+    rescue ArgumentError, TypeError => e
+      Legate.logger.error("Session.from_h: Failed to deserialize session data. Error: #{e.message}. Data: #{hash.inspect}")
+      nil # Return nil on deserialization error
+    end
+
+    private
+
+    # Records a state mutation by bumping @updated_at under the mutex, so the
+    # timestamp write doesn't race add_event's. The external scoped-state I/O is
+    # intentionally left outside the lock (see add_event).
+    def touch!
+      @mutex.synchronize { @updated_at = Time.now.utc }
+    end
+
+    def parse_key(key)
+      key_str = key.to_s
+      if key_str.include?(':')
+        prefix, real_key = key_str.split(':', 2)
+        [prefix, real_key]
+      else
+        [nil, key_str]
+      end
+    end
+
+    # Builds the identity-qualified namespace passed to the session service for a
+    # scoped-state prefix, so scoped state is isolated by owner instead of sharing
+    # one global slot per prefix:
+    #   user → per (app, user), shared across that user's sessions
+    #   app  → per app, shared across the app's users
+    #   temp → per session
+    # The session service treats this whole string as an opaque scope, so wildcard
+    # clears (clear_scoped_state(ns, '*')) only touch the caller's own subtree.
+    # @param prefix [String] One of VALID_PREFIXES.
+    # @return [String] The namespace string.
+    def scoped_namespace(prefix)
+      case prefix
+      when 'user' then "user:#{escape_ns(@app_name)}:#{escape_ns(@user_id)}"
+      when 'app'  then "app:#{escape_ns(@app_name)}"
+      when 'temp' then "temp:#{escape_ns(@id)}"
+      else prefix
+      end
+    end
+
+    # Escapes ':' in identity components so a crafted app_name/user_id/id cannot
+    # traverse into another owner's namespace.
+    def escape_ns(component)
+      component.to_s.gsub(':', '%3A')
+    end
+
+    def validate_prefix!(prefix)
+      return if prefix.nil?
+      return if VALID_PREFIXES.include?(prefix)
+
+      raise Legate::InvalidPrefixError, "Invalid state key prefix: #{prefix}. Valid prefixes: #{VALID_PREFIXES.join(', ')}"
+    end
+
+    # Recursively checks if a value is JSON-serializable (basic types, nil, nested Hashes/Arrays thereof)
+    def is_json_serializable?(value)
+      case value
+      when String, Integer, TrueClass, FalseClass, NilClass
+        true
+      when Float
+        value.finite? # NaN/Infinity are Floats but JSON.generate raises on them — reject up front
+      when Hash
+        # Ensure all keys are strings/symbols and all values are serializable
+        value.all? { |k, v| (k.is_a?(String) || k.is_a?(Symbol)) && is_json_serializable?(v) }
+      when Array
+        value.all? { |v| is_json_serializable?(v) }
+      else
+        false # Other types (Time, Set, Object, etc.) are not serializable
+      end
+    end
+
+    # Raises error if value is not serializable
+    def validate_serializable!(value)
+      return if is_json_serializable?(value)
+
+      raise Legate::SerializationError,
+            "Value must be JSON-serializable (basic types, nil, Hash, Array): #{value.inspect}"
+    end
+  end # End Session class
+end # End Legate module

data/lib/legate/session_service/active_record.rb

@@ -0,0 +1,300 @@
+# File: lib/legate/session_service/active_record.rb
+# frozen_string_literal: true
+
+# Opt-in: this file is NOT loaded by `require 'legate'`. Require it explicitly
+# (and have ActiveRecord available + a connection established) to use a durable,
+# ActiveRecord-backed session store. In Rails, `require 'legate/rails'` wires
+# this up and `rails g legate:install` creates the migration.
+require 'active_record'
+require 'json'
+require_relative 'base'
+require_relative 'event_broadcast'
+require_relative '../session'
+require_relative '../event'
+
+module Legate
+  module SessionService
+    # Durable session store backed by ActiveRecord (subsumes R2 persistence).
+    #
+    # Semantics mirror InMemory — repeated get_session within a process returns
+    # the same Session object so a run's mutations accumulate — but every
+    # mutation is written through to the database, so a restart or another
+    # process re-hydrates the committed history and state from rows.
+    #
+    # The host application owns the AR connection (Rails does this for you;
+    # standalone users call ActiveRecord::Base.establish_connection). Tables are
+    # created by the generated migration, or ad hoc via {.create_tables!}.
+    class ActiveRecord < Base
+      include EventBroadcast
+
+      # Abstract base so every Legate table shares the host's connection.
+      class Record < ::ActiveRecord::Base
+        self.abstract_class = true
+      end
+
+      # A persisted conversation (id is the Session UUID).
+      class SessionRecord < Record
+        self.table_name = 'legate_sessions'
+        serialize :state, coder: JSON
+        has_many :event_records, -> { order(:position) },
+                 class_name: 'Legate::SessionService::ActiveRecord::EventRecord',
+                 foreign_key: :legate_session_id, inverse_of: :session_record
+      end
+
+      # One appended event, ordered within its session by `position`.
+      class EventRecord < Record
+        self.table_name = 'legate_events'
+        serialize :content, coder: JSON
+        serialize :state_delta, coder: JSON
+        belongs_to :session_record,
+                   class_name: 'Legate::SessionService::ActiveRecord::SessionRecord',
+                   foreign_key: :legate_session_id, inverse_of: :event_records
+      end
+
+      # Scoped (user:/app:/temp:) state, keyed by the namespaced scope + key.
+      class ScopedStateRecord < Record
+        self.table_name = 'legate_scoped_states'
+        serialize :value, coder: JSON
+      end
+
+      # Creates the three Legate tables if absent. Convenience for tests and
+      # standalone (non-migration) setups; Rails apps use the generated migration.
+      # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter]
+      def self.create_tables!(connection: Record.connection)
+        unless connection.table_exists?(:legate_sessions)
+          connection.create_table :legate_sessions, id: :string do |t|
+            t.string :app_name
+            t.string :user_id
+            t.text :state
+            t.timestamps
+          end
+        end
+
+        unless connection.table_exists?(:legate_events)
+          connection.create_table :legate_events do |t|
+            t.string :legate_session_id, null: false, index: true
+            t.integer :position, null: false, default: 0
+            t.string :role
+            t.text :content
+            t.string :tool_name
+            t.text :state_delta
+            t.string :event_timestamp
+            t.string :event_id
+            t.timestamps
+          end
+        end
+
+        return if connection.table_exists?(:legate_scoped_states)
+
+        connection.create_table :legate_scoped_states do |t|
+          t.string :scope, null: false
+          t.string :state_key, null: false
+          t.text :value
+          t.timestamps
+        end
+        connection.add_index :legate_scoped_states, %i[scope state_key], unique: true,
+                                                                         name: 'index_legate_scoped_states_on_scope_and_key'
+      end
+
+      # Cap on cached Session objects. The cache gives a run a stable Session
+      # identity and avoids re-hydrating on every get_session; because every
+      # mutation is written through, an evicted session re-hydrates correctly
+      # from the database. LRU eviction only ever reclaims idle sessions — an
+      # active run keeps touching (and so keeps) its own session.
+      DEFAULT_MAX_CACHED_SESSIONS = 1_000
+
+      # @param max_cached_sessions [Integer] LRU bound for the in-process cache
+      def initialize(max_cached_sessions: DEFAULT_MAX_CACHED_SESSIONS)
+        super()
+        @cache = {} # insertion order = LRU order; guarded by @cache_mutex
+        @cache_mutex = Mutex.new
+        @max_cached_sessions = max_cached_sessions
+        Legate.logger.info('ActiveRecord session service initialized.')
+      end
+
+      def persistent?
+        true
+      end
+
+      def create_session(app_name:, user_id:, session_id: nil, initial_state: {})
+        session = Legate::Session.new(
+          app_name: app_name, user_id: user_id, id: session_id,
+          initial_state: symbolize(initial_state), session_service: self
+        )
+        SessionRecord.create!(
+          id: session.id, app_name: app_name, user_id: user_id, state: session.state_to_h
+        )
+        cache_put(session.id, session)
+        Legate.logger.info("Created persistent session: #{session.id} for app:#{app_name}, user:#{user_id}")
+        session
+      end
+
+      def get_session(session_id:)
+        cached = cache_get(session_id)
+        return cached if cached
+
+        record = SessionRecord.find_by(id: session_id)
+        unless record
+          Legate.logger.warn("Session not found: #{session_id}")
+          return nil
+        end
+
+        session = hydrate(record)
+        cache_put(session_id, session)
+        session
+      end
+
+      def append_event(session_id:, event:)
+        session = get_session(session_id: session_id)
+        return false unless session
+
+        session.add_event(event) # merges state_delta into the cached Session
+        # The event row and the merged session state must land together, or
+        # neither — otherwise a crash between them leaves history and state
+        # inconsistent.
+        SessionRecord.transaction do
+          insert_event(session_id, event)
+          write_session_state(session_id, session)
+        end
+        broadcast_event(session_id, event) # notify any streaming subscribers (R3)
+        true
+      rescue ::ActiveRecord::ActiveRecordError => e
+        Legate.logger.error("ActiveRecord session service: append_event failed for '#{session_id}': #{e.message}")
+        # The write rolled back but the cached Session already holds the event;
+        # drop it so the next get_session re-hydrates the committed truth.
+        cache_evict(session_id)
+        false
+      end
+
+      def delete_session(session_id:)
+        cache_evict(session_id)
+        EventRecord.where(legate_session_id: session_id).delete_all
+        deleted = SessionRecord.where(id: session_id).delete_all
+        if deleted.positive?
+          Legate.logger.info("Deleted persistent session: #{session_id}")
+          true
+        else
+          Legate.logger.warn("Attempted to delete non-existent session: #{session_id}")
+          false
+        end
+      end
+
+      def list_sessions(app_name: nil, user_id: nil)
+        scope = SessionRecord.all
+        scope = scope.where(app_name: app_name) if app_name
+        scope = scope.where(user_id: user_id) if user_id
+        scope.pluck(:id).filter_map { |id| get_session(session_id: id) }
+      end
+
+      def save_scoped_state(scope, key, value)
+        record = ScopedStateRecord.find_or_initialize_by(scope: scope.to_s, state_key: key.to_s)
+        record.value = value
+        record.save!
+      end
+
+      def load_scoped_state(scope, key)
+        ScopedStateRecord.find_by(scope: scope.to_s, state_key: key.to_s)&.value
+      end
+
+      def clear_scoped_state(scope, key)
+        relation = ScopedStateRecord.where(scope: scope.to_s)
+        relation = relation.where(state_key: key.to_s) unless key == '*'
+        relation.delete_all
+      end
+
+      def set_state(session_id:, key:, value:)
+        session = get_session(session_id: session_id)
+        unless session
+          Legate.logger.warn("ActiveRecord session service: Session not found '#{session_id}' when setting state for '#{key}'.")
+          return nil
+        end
+
+        session.set_state(key, value)
+        # Scoped keys are already persisted via save_scoped_state; write through
+        # the plain-key state so it survives a restart.
+        write_session_state(session_id, session)
+        nil
+      rescue Legate::SerializationError => e
+        Legate.logger.error("ActiveRecord session service: Error setting state for '#{session_id}', key '#{key}': #{e.message}")
+        nil
+      end
+
+      def get_state(session_id:, key:)
+        session = get_session(session_id: session_id)
+        return session.get_state(key) if session
+
+        Legate.logger.warn("ActiveRecord session service: Session not found '#{session_id}' when getting state for '#{key}'.")
+        nil
+      end
+
+      private
+
+      # --- Bounded LRU session cache (guarded by @cache_mutex) ---
+
+      # Return the cached session and mark it most-recently-used.
+      def cache_get(session_id)
+        @cache_mutex.synchronize do
+          session = @cache.delete(session_id)
+          @cache[session_id] = session if session # reinsert at the tail (MRU)
+          session
+        end
+      end
+
+      # Cache the session as most-recently-used, evicting the LRU entry if over cap.
+      def cache_put(session_id, session)
+        @cache_mutex.synchronize do
+          @cache.delete(session_id)
+          @cache[session_id] = session
+          @cache.delete(@cache.keys.first) if @cache.size > @max_cached_sessions
+        end
+      end
+
+      def cache_evict(session_id)
+        @cache_mutex.synchronize { @cache.delete(session_id) }
+      end
+
+      def insert_event(session_id, event)
+        next_position = (EventRecord.where(legate_session_id: session_id).maximum(:position) || 0) + 1
+        EventRecord.create!(
+          legate_session_id: session_id, position: next_position,
+          role: event.role&.to_s, content: event.content, tool_name: event.tool_name&.to_s,
+          state_delta: event.state_delta, event_timestamp: event.timestamp&.iso8601(3), event_id: event.event_id
+        )
+      end
+
+      # Write-through the session's plain-key state (scoped state is persisted
+      # separately via save_scoped_state). Shared by append_event and set_state.
+      def write_session_state(session_id, session)
+        SessionRecord.find_by(id: session_id)&.update!(state: session.state_to_h, updated_at: session.updated_at)
+      end
+
+      def hydrate(record)
+        events = record.event_records.map { |er| hydrate_event(er) }.compact
+        session = Legate::Session.new(
+          id: record.id, app_name: record.app_name, user_id: record.user_id,
+          initial_state: record.state || {}, events: events, session_service: self
+        )
+        session.instance_variable_set(:@created_at, record.created_at) if record.created_at
+        session.updated_at = record.updated_at if record.updated_at
+        session
+      end
+
+      def hydrate_event(record)
+        Legate::Event.from_h(
+          role: record.role, content: record.content, timestamp: record.event_timestamp,
+          tool_name: record.tool_name, state_delta: record.state_delta, event_id: record.event_id
+        )
+      end
+
+      def symbolize(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.transform_keys do |k|
+          k.to_sym
+        rescue StandardError
+          k
+        end
+      end
+    end
+  end
+end