easy_ml 0.1.4 → 0.2.0.pre.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 194dfdb77406b2509c29056d821804bbf388552d675d2fb08ee5bad296119c58
-  data.tar.gz: e456e94893d3f51f2432355f3b6ce94feda95066f7258f57499122549bebfbe5
+  metadata.gz: 62ec6069cb9e47af4d2fd29668202132af589b1fb526b93c8bd4766aec5df3b1
+  data.tar.gz: 6e06d4e607d50b74f8d7ad5a881380d05bed58f351bc22357bfa3e5038850322
 SHA512:
-  metadata.gz: 279ca003173f2acdd2dcc802cc96fb479658edfd86e6c773dca7615fe550aa3e80999c2c2c8e665ee5affe5fa5b10c888e78c0e426688dc2ce1978d420773722
-  data.tar.gz: 6443bb0f2e3560a0b9f28fe5d657b58bae75a56756db3193dd86bfa0772c19a66350d46d595b4ce133ab328dfdc3893ab1b06ae78c54330ae1a3174e9fc390a7
+  metadata.gz: 61eed2f9f210fd5ac38af1b0972d369d73e5853491a5889c0b04c9dd776e5509514ab98ac56ab8e3bd876223a72a5463c29baa238899220acd369ee5e58c3206
+  data.tar.gz: d266908a752c337c7817484af4235ba78b38e47495d25fe815feafad11b820cd63ca47300619c46f56971d810b2a475a3ebb2c436359026ff5f2f5f794cb0bd1

data/README.md

@@ -2,13 +2,33 @@
 
 # EasyML
 
-EasyML is a Ruby gem designed to simplify the process of building, deploying, and managing the lifecycle of machine learning models within a Ruby on Rails application. It is a plug-and-play, opinionated framework that currently supports XGBoost, with plans to expand support to a variety of models and infrastructures. EasyML aims to make deployment and lifecycle management straightforward and efficient.
+~~You can't do machine learning in Ruby.~~
+
+Deploy models in minutes.
+
+## What is EasyML?
+
+EasyML is a **low code/no code**, end-to-end machine learning framework for Ruby on Rails.
+
+**Get productionized models in minutes.** It takes the guesswork out of:
+
+- Preprocessing data
+- Storing and batch computing features
+- Training models
+- Metric visualization
+- Deployment and versioning
+- Evaluating model performance
+
+With a dead-simple point-and-click interface, EasyML makes it stupid easy to train and deploy.
+
+Oh yeah, and it's open source!
 
 ## Features
 
-- **Plug-and-Play Architecture**: EasyML is designed to be easily extendable, allowing for the integration of various machine learning models and data sources.
-- **Opinionated Framework**: Provides a structured approach to model management, ensuring best practices are followed.
-- **Model Lifecycle On Rails**: Seamlessly integrates with Ruby on Rails, allowing simplified deployment of models to production.
+- **No Code (if you want)**: EasyML ships as a Rails engine. Just mount it in your app and get started.
+- **Opinionated Framework**: Provides a structured approach to data and model management, ensuring best practices are followed.
+- **Model Lifecycle On Rails**: Want predictions directly from your Rails app? You can do that.
+- **Easily Extensible**: Want a model that's not supported? Send a pull request!
 
 ## Current and Planned Features
 
@@ -89,6 +109,14 @@ MyTrainer.predict(customer_data: "I am worth a lot of money")
 # prediction: true!
 ```
 
+## Mount The Engine
+
+```ruby
+Rails.application.routes.draw do
+  mount EasyML::Engine, at: "easy_ml"
+end
+```
+
 ## Data Management
 
 EasyML provides a comprehensive data management system that handles all preprocessing tasks, including splitting data into train, test, and validation sets, and avoiding data leakage. The primary abstraction for data handling is the `Dataset` class, which ensures data is properly managed and prepared for machine learning tasks.
@@ -153,12 +181,12 @@ EasyML offers a variety of preprocessing features to prepare your data for machi
   }
   ```
 
-- **Label Encoding**: Convert categorical variables into integer labels. Use this when you have categorical data that can be ordinally encoded.
+- **Ordinal Encoding**: Convert categorical variables into integer labels. Use this when you have categorical data that can be ordinally encoded.
 
   ```ruby
   loan_purpose: {
     categorical: {
-      encode_labels: true
+      ordinal_encoding: true
     }
   }
   ```
@@ -170,6 +198,198 @@ EasyML offers a variety of preprocessing features to prepare your data for machi
 - **Batch Processing**: Process data in batches to handle large datasets efficiently.
 - **Null Handling**: Alert and handle null values in datasets to ensure data quality.
 
+## Feature Store
+
+The Feature Store is a powerful component of EasyML that helps you manage, compute, and serve features for your machine learning models. Here's how to use it effectively:
+
+### Setting Up Features
+
+1. Create a `features` directory in your application:
+
+```bash
+mkdir app/features
+```
+
+2. Create feature classes in this directory. Each feature should include the `EasyML::Features` module:
+
+```ruby
+class MyFeature
+  include EasyML::Features
+
+  def transform(df, feature)
+    # Your feature transformation logic here
+  end
+
+  feature name: "My Feature",
+          description: "Description of what this feature does"
+end
+```
+
+### Feature Types and Configurations
+
+#### Simple Transform-Only Features
+
+For features that can be computed using only the input columns:
+
+```ruby
+class DidConvert
+  include EasyML::Features
+
+  def transform(df, feature)
+    df.with_column(
+      (Polars.col("rev") > 0).alias("did_convert")
+    )
+  end
+
+  feature name: "did_convert",
+          description: "Boolean indicating if conversion occurred"
+end
+```
+
+#### Batch Processing Features
+
+For features that require processing large datasets in chunks:
+
+```ruby
+class LastConversionTimeFeature
+  include EasyML::Features
+
+  def batch(reader, feature)
+    # Efficiently query only the company_id column for batching
+    # This will create batches of batch_size records (default 1000)
+    reader.query(select: ["company_id"], unique: true)["company_id"]
+  end
+
+  def fit(reader, feature, options = {})
+    batch_start = options.dig(:batch_start)
+    batch_end = options.dig(:batch_end)
+
+    # More efficient than is_in for continuous ranges
+    df = reader.query(
+      filter: Polars.col("company_id").is_between(batch_start, batch_end),
+      select: ["id", "company_id", "converted_at", "created_at"],
+      sort: ["company_id", "created_at"]
+    )
+
+    # For each company, find the last time they converted before each application
+    #
+    # This value will be cached in the feature store for fast inference retrieval
+    df.with_columns([
+      Polars.col("converted_at")
+        .shift(1)
+        .filter(Polars.col("converted_at").is_not_null())
+        .over("company_id")
+        .alias("last_conversion_time"),
+
+      # Also compute days since last conversion
+      (Polars.col("created_at") - Polars.col("last_conversion_time"))
+        .dt.days()
+        .alias("days_since_last_conversion")
+    ])[["id", "last_conversion_time", "days_since_last_conversion"]]
+  end
+
+  def transform(df, feature)
+    # Pull the pre-computed values from the feature store
+    stored_df = feature.query(filter: Polars.col("id").is_in(df["id"]))
+    return df if stored_df.empty?
+
+    df.join(stored_df, on: "id", how: "left")
+  end
+
+  feature name: "Last Conversion Time",
+          description: "Computes the last time a company converted before each application",
+          batch_size: 1000,  # Process 1000 companies at a time
+          primary_key: "id",
+          cache_for: 24.hours  # Cache feature values for 24 hours after running fit
+end
+```
+
+This example demonstrates several key concepts:
+
+1. **Efficient Batching**: The `batch` method uses the reader to lazily query only the necessary column for batching
+1. **Batches Groups Together**: All records with the same `company_id` need to be in the same batch to properly compute the feature, so we create a custom batch (instead of using the primary key `id` column, which would split up companies into different batches)
+1. **Column Selection**: Only selects required columns in the reader query
+1. **Feature Computation**: Computes multiple related features (last conversion time and days since) in a single pass.
+1. **Automatic Feature Store Caching**: The feature store automatically caches feature values returned from the `fit` method
+
+### Performance Optimization
+
+#### Caching During Development
+
+Use `cache_for` to save processing time during development:
+
+```ruby
+feature name: "My Feature",
+        cache_for: 24.hours # After running fit, this feature will be cached for 24 hours (unless new data is read from datasource, like S3)
+```
+
+#### Early Returns
+
+Always implement early returns in your transform method to avoid unnecessary reprocessing:
+
+```ruby
+def transform(df, feature)
+  return df if df["required_column"].nil?
+  # Feature computation logic
+end
+```
+
+#### Using Reader vs DataFrame
+
+- The Polars `reader` is a lazy reader that allows you to query data incrementally.
+- If your feature includes a `batch` method or uses the `batch_size` variable, you will receive a reader instead of a dataframe in the `fit` method
+
+```ruby
+def fit(reader, feature)
+  df = reader.query(select: ["column1", "column2"])
+  # Process only needed columns
+end
+```
+
+- If you don't have a `batch` method or don't use the `batch_size` variable, you will receive a dataframe in the `fit` method
+
+````ruby
+def fit(df, feature)
+  # process directly on dataframe
+end
+
+- To ensure you get a reader instead of a dataframe, include the `batch` method
+
+```ruby
+def batch(reader, feature)
+  reader.query(select: ["column1"])["column1"]
+end
+
+feature name: "My Feature", batch_size: 1_000
+````
+
+### Production Considerations
+
+#### Handling Missing Data
+
+When processing historical data:
+
+1. Check for missing dates:
+
+```ruby
+def transform(df, feature)
+  missing_dates = feature.store.missing_dates(start_date, end_date)
+  return df if missing_dates.empty?
+
+  # Process only missing dates
+  process_dates(df, missing_dates)
+end
+```
+
+### Best Practices
+
+1. Always specify a `primary_key` to allow the feature store to partition your data
+1. Use `batch/fit` to process large datasets in batches
+1. Use `batch/fit` to allow faster inference feature computation
+1. Use transform-only features when all required columns will be available on the inference dataset
+1. Use `cache_for` to save processing time during development
+1. Only query necessary columns using the reader
+
 ## Installation
 
 Install necessary Python dependencies
@@ -194,26 +414,6 @@ pip install optuna
    rails db:migrate
    ```
 
-3. **Configure CarrierWave for S3 storage**:
-
-   Ensure you have CarrierWave configured to use AWS S3. If not, add the following configuration:
-
-   ```ruby
-   # config/initializers/carrierwave.rb
-   CarrierWave.configure do |config|
-     config.fog_provider = 'fog/aws'
-     config.fog_credentials = {
-       provider: 'AWS',
-       aws_access_key_id: ENV['AWS_ACCESS_KEY_ID'],
-       aws_secret_access_key: ENV['AWS_SECRET_ACCESS_KEY'],
-       region: ENV['AWS_REGION'],
-     }
-     config.fog_directory = ENV['AWS_S3_BUCKET']
-     config.fog_public = false
-     config.storage = :fog
-   end
-   ```
-
 ## Usage
 
 To use EasyML in your Rails application, follow these steps:
@@ -251,6 +451,14 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
+1. Install Appraisals gemfiles:
+
+```bash
+bundle exec appraisal install
+```
+
+2. Ensure you run tests against all supported Rails versions
+
 Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/easy_ml. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/easy_ml/blob/main/CODE_OF_CONDUCT.md).
 
 ## License

data/Rakefile

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "sprockets/railtie"
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
@@ -10,3 +11,47 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[spec rubocop]
+
+Bundler.require(:default)
+
+# Load your gem's code
+require_relative "lib/easy_ml"
+
+# Load the annotate tasks
+require "annotate/annotate_models"
+
+task :environment do
+  require "combustion"
+  require "sprockets"
+  Combustion.path = "spec/internal"
+  Combustion.initialize! :active_record do |config|
+    config.assets = ActiveSupport::OrderedOptions.new # Stub to avoid errors
+    config.assets.enabled = false # Set false since assets are handled by Vite
+  end
+  EasyML::Engine.eager_load!
+end
+
+namespace :easy_ml do
+  task annotate_models: :environment do
+    model_dir = File.expand_path("app/models", EasyML::Engine.root)
+    $LOAD_PATH.unshift(model_dir) unless $LOAD_PATH.include?(model_dir)
+
+    AnnotateModels.do_annotations(
+      is_rake: true,
+      model_dir: [EasyML::Engine.root.join("app/models/easy_ml").to_s],
+      root_dir: [EasyML::Engine.root.join("app/models/easy_ml").to_s],
+      include_modules: true, # Include modules/namespaces in the annotation
+    )
+  end
+
+  task :create_test_migrations do
+    require "combustion"
+    require "rails/generators"
+    require_relative "lib/easy_ml/railtie/generators/migration/migration_generator"
+
+    db_files = Dir.glob(EasyML::Engine.root.join("spec/internal/db/migrate/**/*"))
+
+    FileUtils.rm(db_files)
+    Rails::Generators.invoke("easy_ml:migration", [], { destination_root: EasyML::Engine.root.join("spec/internal") })
+  end
+end

data/app/controllers/easy_ml/application_controller.rb

@@ -0,0 +1,67 @@
+require "action_controller"
+
+module EasyML
+  class ApplicationController < ActionController::Base
+    helper EasyML::ApplicationHelper
+
+    include InertiaRails::Controller
+    layout "easy_ml/application"
+
+    protect_from_forgery with: :exception
+
+    before_action :hot_reload
+
+    def hot_reload
+      return unless Rails.env.development? && ENV["EASY_ML_DEMO_APP"]
+
+      Dir[EasyML::Engine.root.join("lib/**/*")].select { |f| Pathname.new(f).extname == ".rb" }.each do |file|
+        load file
+      end
+    end
+
+    def settings_to_json(settings)
+      SettingsSerializer.new(settings).serializable_hash.dig(:data, :attributes)
+    end
+
+    def dataset_to_json(dataset)
+      DatasetSerializer.new(dataset).serializable_hash.dig(:data, :attributes)
+    end
+
+    def datasource_to_json(datasource)
+      DatasourceSerializer.new(datasource).serializable_hash.dig(:data, :attributes)
+    end
+
+    def model_to_json(model)
+      ModelSerializer.new(model).serializable_hash.dig(:data, :attributes)
+    end
+
+    def retraining_job_to_json(job)
+      RetrainingJobSerializer.new(job).serializable_hash.dig(:data, :attributes)
+    end
+
+    def retraining_run_to_json(run)
+      RetrainingRunSerializer.new(run).serializable_hash.dig(:data, :attributes)
+    end
+
+    def easy_ml_root
+      Rails.application.routes.routes.find { |r| r.app.app == EasyML::Engine }&.path&.spec&.to_s
+    end
+
+    inertia_share do
+      flash_messages = []
+
+      flash_messages << { type: "success", message: flash[:notice] } if flash[:notice]
+
+      flash_messages << { type: "error", message: flash[:alert] } if flash[:alert]
+
+      flash_messages << { type: "info", message: flash[:info] } if flash[:info]
+
+      {
+        rootPath: easy_ml_root,
+        url: request.path.gsub(Regexp.new(easy_ml_root), ""),
+        errors: session.delete(:errors) || {},
+        flash: flash_messages,
+      }
+    end
+  end
+end

data/app/controllers/easy_ml/columns_controller.rb

@@ -0,0 +1,38 @@
+# == Schema Information
+#
+# Table name: easy_ml_columns
+#
+#  id                  :bigint           not null, primary key
+#  dataset_id          :bigint           not null
+#  name                :string           not null
+#  description         :string
+#  datatype            :string
+#  polars_datatype     :string
+#  is_target           :boolean
+#  hidden              :boolean          default(FALSE)
+#  drop_if_null        :boolean          default(FALSE)
+#  preprocessing_steps :json
+#  sample_values       :json
+#  statistics          :json
+#  created_at          :datetime         not null
+#  updated_at          :datetime         not null
+#
+module EasyML
+  class ColumnsController < ApplicationController
+    def update
+      @column = EasyML::Column.find(params[:id])
+
+      if @column.update(column_params)
+        head :ok
+      else
+        render json: { errors: @column.errors }, status: :unprocessable_entity
+      end
+    end
+
+    private
+
+    def column_params
+      params.require(:column).permit(:hidden)
+    end
+  end
+end

data/app/controllers/easy_ml/datasets_controller.rb

@@ -0,0 +1,156 @@
+# == Schema Information
+#
+# Table name: easy_ml_datasets
+#
+#  id                      :bigint           not null, primary key
+#  name                    :string           not null
+#  description             :string
+#  dataset_type            :string
+#  status                  :string
+#  version                 :string
+#  datasource_id           :bigint
+#  root_dir                :string
+#  configuration           :json
+#  num_rows                :bigint
+#  workflow_status         :string
+#  statistics              :json
+#  preprocessor_statistics :json
+#  schema                  :json
+#  refreshed_at            :datetime
+#  created_at              :datetime         not null
+#  updated_at              :datetime         not null
+#
+module EasyML
+  class DatasetsController < ApplicationController
+    def index
+      datasets = Dataset.all
+
+      render inertia: "pages/DatasetsPage", props: {
+        datasets: datasets.map { |dataset| dataset_to_json(dataset) },
+        constants: Dataset.constants,
+      }
+    end
+
+    def new
+      render inertia: "pages/NewDatasetPage", props: {
+        constants: Dataset.constants,
+        datasources: Datasource.all.map { |datasource| datasource_to_json(datasource) },
+      }
+    end
+
+    def create
+      EasyML::Datasource.find_by(id: params.dig(:dataset, :datasource_id))
+      dataset = Dataset.new(dataset_params.to_h)
+
+      if dataset.save
+        redirect_to easy_ml_datasets_path, notice: "Dataset was successfully created."
+      else
+        redirect_to new_easy_ml_dataset_path, alert: dataset.errors.full_messages.join(", ")
+      end
+    end
+
+    def destroy
+      dataset = Dataset.find(params[:id])
+
+      if dataset.destroy
+        redirect_to easy_ml_datasets_path, notice: "Dataset was successfully deleted."
+      else
+        redirect_to easy_ml_datasets_path, alert: "Failed to delete dataset."
+      end
+    end
+
+    def show
+      dataset = Dataset.find(params[:id])
+
+      render inertia: "pages/DatasetDetailsPage", props: {
+        dataset: dataset_to_json(dataset),
+        constants: Dataset.constants,
+      }
+    end
+
+    def update
+      dataset = Dataset.find(params[:id])
+
+      # Iterate over columns to check and update preprocessing_steps
+      dataset_params[:columns_attributes]&.each do |_, column_attrs|
+        column_attrs[:preprocessing_steps] = nil if column_attrs.dig(:preprocessing_steps, :training, :method) == "none"
+      end
+
+      if dataset.update(dataset_params)
+        flash.now[:notice] = "Dataset configuration was successfully updated."
+        render inertia: "pages/DatasetDetailsPage", props: {
+          dataset: dataset_to_json(dataset),
+          constants: Dataset.constants,
+        }
+      else
+        flash.now[:error] = dataset.errors.full_messages.join(", ")
+        render inertia: "pages/DatasetDetailsPage", props: {
+          dataset: dataset_to_json(dataset),
+          constants: Dataset.constants,
+        }
+      end
+    end
+
+    def refresh
+      dataset = Dataset.find(params[:id])
+      dataset.refresh_async
+
+      redirect_to easy_ml_datasets_path, notice: "Dataset refresh has been initiated."
+    end
+
+    private
+
+    def preprocessing_params
+      [:method, { params: [:constant, :categorical_min, :one_hot, :ordinal_encoding, { clip: %i[min max] }] }]
+    end
+
+    def dataset_params
+      params.require(:dataset).permit(
+        :name,
+        :description,
+        :datasource_id,
+        :target,
+        drop_cols: [],
+        splitter_attributes: %i[
+          splitter_type
+          date_col
+          months_test
+          months_valid
+          train_ratio
+          test_ratio
+          valid_ratio
+          train_files
+          test_files
+          valid_files
+        ],
+        columns_attributes: [
+          :id,
+          :name,
+          :type,
+          :description,
+          :datatype,
+          :polars_datatype,
+          :is_target,
+          :hidden,
+          :drop_if_null,
+          :sample_values,
+          :_destroy,
+          {
+            preprocessing_steps: {
+              training: preprocessing_params,
+              inference: preprocessing_params,
+            },
+            statistics: %i[mean median min max null_count],
+          },
+        ],
+        features_attributes: %i[
+          id
+          name
+          feature_class
+          feature_position
+          _destroy
+        ],
+      )
+    end
+  end
+end