This major release introduces image embedding support, improved data streaming efficiency, and enhanced caching performance monitoring, alongside multiple stability and documentation updates.

With the introduction of Image Embeddings, multiple core refactors, and the publication of the API Reference, BaseModel officially reaches version 1.00.

New features

• Image embedding support
  Users can now add images, and BaseModel automatically generates image embeddings that integrate seamlessly with behavioral, text, and tabular data for complete multimodal modeling. Learn more in the Data & Feature Types guide.

• Unix timestamp support
  Users can now use Unix timestamps directly in time-related functions for greater flexibility in data processing.

Improvements

• Improved data streaming efficiency
  Reduced memory usage and increased performance for large datasets, resulting in smoother and faster data handling.

• Revamped timezone handling
  Enhanced timestamp alignment across multiple data sources for consistent temporal comparisons.

• Robust handling of missing numerical data
  More stable aggregation and event computations when numerical values are partially missing.

• Optimized data transformations
  Improved efficiency when processing large data structures within pipelines.

• Simplified async stream handling
  Streamlined background data operations for greater reliability and maintainability.

• Improved query consistency
  More predictable and stable query behavior across data modules, enhancing reliability in data access.

• Additional caching performance benchmarks
  Improved cache performance benchmarking across supported databases, enabling further optimization to achieve faster data retrieval and more consistent caching efficiency.

Fixes

• Correct trainer loss logging
  Fixed an issue where train_loss_epoch could log as NaN during certain training configurations.

• Revised time series handling
  Corrected how time series model manages series of counts, ensuring accurate scaling and alignment.

• Improved checkpoint reliability
  Fixed a checkpointing issue that could prevent model state from saving correctly during long training sessions.

• Minor bugs and code maintenance
  Fixed various small issues and improved overall code stability and maintainability.

Documentation

• Comprehensive API Reference
  Users can now access a complete API Reference section describing all classes and functions available in BaseModel.

• New guides and FAQ
  Added a new FAQ section in the About BaseModel block and a detailed guide on Data Types & Features, explaining how different data types are transformed into model features and how users can influence this process, including text, image, and time-series features.

This technical release focuses on stability and model robustness improvements.

New features

• Custom metrics support
  Users can now define and register custom evaluation metrics within downstream models. This includes full compatibility with torchmetrics, duplicate-name checks, and consistent integration across training, validation, and monitoring phases.

Improvements

• Improved stability and speed of real-time inference
  Optimized the inference server interface and pipeline for more stable initialization, better resource utilization, and faster CI execution.

• Improved numerical stability of training on highly multimodal data
  Enhanced buffer sampling and shuffling to ensure better coverage of training examples, smoother convergence, and improved overall training stability.

• Improved regression and classification predictions
  Revised the random splitting strategy and application a uniform mixture to raw scores, leading to more balanced score distributions and reduced training bias.

Fixes

• Sketch width and optimal depth alignment
  Prevented potential crashes caused by conflicting sketch dimensions when handling certain class counts.

• Date parsing for time series not working with formatted data
  Fixed an issue where date columns were not parsed or sanitized in time-series data when a date format was provided.

• Invalid one-hot recommendation metrics for low number of candidates
  Prevented crashes on OneHotRecommendationTask models when the candidate pool was smaller than k.

• Text embedding stability
  Fixed occasional crashes during text model training under specific edge conditions.

• Short time-series handling
  Resolved a crash that occurred when the time-series length was shorter than the kernel size.

• Insufficient training data handling
  Introduced graceful exit with a clear and informative message when the available data is insufficient to fill a full batch across all selected devices.

New Features

• Time window slicing for event data
  Event data sources can now be restricted to a defined start and end timestamp with the new slice_time_window function. This allows analyses and training runs to focus on specific periods (e.g., campaigns, weeks, or test windows) without extra preprocessing.

• Direct access to date columns
  Event data sources now expose a date column (timestamps), allowing time-based filtering and grouping with filter() and groupBy() functions.

Improvements

• Simplified interpretation output
  The interpret function now produces cleaner results by removing non-essential fields, making logs and monitoring pipelines easier to read and consume.

• Improved window shuffling defaults
  The buffer size has been changed to 100k, enhancing randomness in shuffled windows and improving generalization during training.

Fixes

• Loss computation – refined loss calculations in downstream models.
• Module visibility – ensured consistent access to essential modules.
• Date handling – added support for numeric date formats and fixed timestamp edge cases.
• Split point generation – restricted to explicitly defined data sources.

Documentation

Expanded sample target functions
A new set of ready-to-use target functions has been added, to help prototype and compare approaches quicker, and demonstrate how to use new functions.

New features - Core BaseModel Repository:

• New recommendation task for limited item pool
  When fine-tuning for recommendation problem, users can now choose from two specialised classes:
  
  • OneHotRecommendationTask, where the target is a fixed-size vector corresponding to the total number of recommendable entities.
    
  • RecommendationTask where the target is a probabilistic sketch representation. The one-hot variant is especially beneficial when the number of recommendable entities is relatively low (e.g.,<5,000) where it often leads to better predictive performance.
  
  
• Loss weighting for One-Hot Recommendation and Multilabel Classification
  Users can now optionally return weights in the target function to control the relative importance of individual target elements. This is particularly useful in use cases like training acquisition models, where only products not previously purchased should be considered during model training.

• Entity filtering
  Users can now define which targets should be included or excluded from predictions and ground truth using the predictions_to_include_fn and predictions_to_exclude_fn parameters in both load_from_foundation_module and load_from_checkpoint.
  • This change provides more precise control over evaluation behavior in multiclass classification, multi-label classification, one-hot recommendation, and sketch recommendation.
    
  • As part of this update, the predictions_to_include parameter has been removed from TrainingParams to avoid redundancy.
  • Please note that while entity filtering functions affect scoring, ground truth, and metrics during the validation, prediction, and test phases, they do not impact model training. To exclude targets during training, loss weighting should be used instead.
  
  
• Adjustable number of split points for random sampling strategy
  The maximum number of split points per observation used during a single epoch has been increased from 1 to the square root of the number of event timestamps when target_sampling_strategy="random" is selected.
  • As a result, the maximum_splitpoints_per_entity parameter will now also influence the number of split points in the random sampling strategy.
  • This change ensures consistency across sampling strategies, as maximum_splitpoints_per_entity previously applied only to the valid strategy.
  
  
• Flexible entity split
  Entity split parameters such as training, validation, test, training_validation_end can now be changed during scenario model training. This enables iterative experimentation and fine-tuning without the need to retrain the foundation model, allowing user to adapt data splits to insights discovered during training.

• Sketch merging support
  Sketches derived from shared entity columns can now be added to other sketches.
  • This capability is particularly useful when building advanced target functions, as it allows users to combine different behavioral signals into a single, richer representation. For example, in datasets with very few product purchase transactions, a hybrid sketch can be created by adding a transaction-based sketch to a product view-based sketch.
  • The hybrid sketch captures a broader range of product interactions and serves as a strong proxy for the sparse transaction data, improving model robustness and generalization.

• Retention policy support during training
  User can now use the entity_history_limit parameter to define the maximum history time range for a single observation per data source during training. This allows simulation of retention policies used by certain databases that store only recent events.

• Extended logging in ML experiment tracking tools
  The number of validation batches is now logged in model lifecycle management tools, such as Neptune and MLflow.

Improvements:

• Consistent entity split
  Entity split into training, validation and test is now consistent between fit and training Foundation Model phases.

Fixes:

• Fixed an error when date column containing time zone caused errors during fit phase.
• Resolved an issue when Snowflake token authorization was used always if token was present, even if different authorization method was configured.
• Fixed an issue when overwrite setting removed checkpoint files during training with multi-GPU.
• Restored cache creation when enabled in configuration.

New features - Core BaseModel Repository:

• Hybrid train/test split
  Users can now combine entity-based training and validation splits with a time-based test set. This mirrors production scenarios more closely by ensuring that the test set simulates future data while respecting entity isolation during training.

• Limited end date of training and validation
  Introduced the training_validation_end parameter to limit the latest date included in training and validation splits when using entity-based partitioning.

• Flexible training validation interval
  Introduced check_val_every_n_steps and check_val_every_n_epochs parameters for more granular control over validation frequency during training.

• Reproducible results
  A seed parameter has been added to key methods (fit_behavioral_representation, train_foundation_model, pretrain, fit, evaluate, predict, and test) to ensure consistent and reproducible outputs across runs.

• Flexible Kerberos configuration
  [BREAKING CHANGE]: In Hive connection configuration separate realm for Kerberos can now be defined with kinit_realm parameter while realm for connection string can be defined in ini file.

Improvements:

• Refactored run continuation logic
  The overwrite and resume parameters must now be passed directly to the fit method rather than being read from TrainingParams.

• Refined interpretability date specification
  The target date for interpretation should now be provided via the prediction_date parameter instead of being inferred from split.

• Normalized feature importance in interpretability
  Feature importance scores are now normalized based on each feature’s input size, enabling fairer comparisons between features of different scales.

• Improved Parquet cache behavior
  
  • Cache is automatically refreshed if the source Parquet file has changed—no manual deletion required.
  • The cache_path parameter is now optional. However, disabling the cache is not recommended, as it can significantly increase runtime and slow down data processing.

• Optimized training behavior
  The warm_start_steps parameter has been removed following internal improvements to the training loop.

• Accelerated training
  Multiple internal optimizations have led to 2–3× faster performance on benchmark datasets, including:

  • Accelerated data loading pipeline
  • More efficient handling of time-based features for entities with long histories
  • Streamlined data validation and comparison logic

Fixes:

• Resolved an issue where complex column types (e.g., lists of strings) caused errors during preprocessing. These types are now skipped with a warning.
• Fixed excessive memory usage during the prediction phase.

New features:

• Entity-based splits
  Users will now be able to separate training, validation and testing sets based on time range or entity ID (e.g. create user hold-out rather than temporal one).

• New method for selecting entity IDs
  Users now have more flexible control over which entity IDs are included in training and testing:

  • A new entity_ids parameter can be added to the YAML configuration to act as a global filter during foundation model training, prior to training and validation splits.
  • The sameentity_ids parameter is now available in TrainingParams and TestingParams to control entity selection during specific scenario training or testing runs.
  • [BREAKING CHANGE]: the previously used entities_ids_subquery parameter has been removed.

Improvements:

• Refactoring of feature loading pipeline
  

  • Improvements to ensure stability, clarity of error messages and to prevent accidental misconfiguration when training scenario models or two-stage pretraining.

  • [BREAKING CHANGE]: The parameters use_recency_sketches and use_last_basket_sketches are no longer read from data_params block in YAML configuration file and must be passed directly to the pretrain() or train_foundation_model functions.

  • [BREAKING CHANGE]: the features_path can no longer be modified at scenario training stage, to eliminate the risk of misconfiguration. The path is now always derived from the checkpoint path so that features are in predictable location in the checkpoint.

  • [BREAKING CHANGE]: the data_loading_params block has been removed from the configuration file. The following parameters must now be defined as follows:

    • limit_entity_num_events → limit_entity_num_eventsunder the data_params block
    • cache_dir → cache_pathunder the data_params block.

  • Serialization is now enabled for all modalities.

• Enhanced BiqQuery connector (minimum viable feature)
  Users can now specify a different project as computation engine and a different one as data location.

• Standardised Dependency Error Messages
  All optional dependency checks generate standardized error messages with clear instruction to install missing packages.

Fixes:

• Fixed an error when validation set starting date could be picked in a way that resulted with empty history.
• Fixed an error when the starting date of testing set could be treated as history.
• Fixed an error when a column with less than two values overridden to the categorical type was causing preprocessing stage to fail.
• Fixed an error when interpretability returned duplicated modality names.
• Fixed an error where classification tasks required thresholds even when the user did not expect predicted labels and output type was set to SEMANTIC.
• Updated packages to improve performance, improve security and for compatibility with the latest features.

New features - Core BaseModel Repository:

• Modular foundation model training
  • The two components of the pretrain stage — data preprocessing & representation fitting, and FM training — can now be run independently, or together, as before:
    • Two respective functions: fit_behavioral_representation and train_foundation_model were added to compute features and train foundation model separately.
    • Changed monad.pretrain command name to monad.run with optional --fit and --fm arguments to compute only features or foundation model.
• Flexible prediction outputs
  • Introduced different types of predicted output defined by mandatoryoutput_type parameter. This requires changes to previously written scripts.
  • Added functions readout_sketch and read_target_entity_ids to map recommendation outputs to feature values.
• Enhanced model training with early stopping
  • Introduced early_stopping parameter to prevent overfitting.
• Expanded model interpretability
  • Introduced interpret_entity function to compute event-level attributions for a single main entity.
• Automated model testing
  • Introduced test method to compute metrics based on predictions and ground truth.
• Flexible BigQuery connection
  • Added project_id parameter to define project different from the one in the service account.

New features - GUI Application (Snowflake Native):

• Cascading run execution – enables dependent jobs/runs to trigger in sequence.
• Run and job status tracking – added detailed status tracking for better monitoring.
• New table designs – updated tables with improved layout and readability.
• Validation improvements – enhanced input and data validation across the platform.
• Multi-GPU training – enabled distributed model training across multiple GPUs.
• Listing state restoration – automatically restores UI state when returning to listings.

Fixes:

• Fixed an issue where all main entities were loaded on one GPU when distributed training across multiple GPUs was used.
• Fixed an issue where default multiclass metric was returning an error.
• Fixed an issue where interpretability attributions for time-series features were empty.

Dependencies

• The dask library is no longer a dependency.

New features:

• Expanded model scalability
  Added support for FSDP2 to enable distributed training across multiple GPUs.
• Flexible inference customization
  Introduced targets_to_include and targets_to_exclude parameters for more control over inference outputs.
• Enhanced diagnostics and issue tracking
  Improved exception handling and logging during inference for better troubleshooting.
• Advanced interpretability for time series
  Enabled support for interpreting time-series variables in model explanations, enhancing transparency.

Fixes:

• Fixed an error that prevented models with time-series features from resuming properly.
• Fixed an issue where the parameter controlling the use of the foundation model head was not properly passed.
• Updated packages to improve performance, improve security and for compatibility with the latest features.

New features:

• Enhancements to Foundation Model training
  Improvements to the foundation model training process, leading to better performance in downstream applications.

  • Simplified configuration by removing the need to predefine certain time-based parameters incl.check_target_for_next_n_days parameter.
    This requires changes to previously written configuration files.
  • Optimized training with an updated optimizer that eliminates the need for manual learning rate scheduling.
  • Improved feature representation through automated parameter tuning.
  • Performance gains from optimized data handling and more efficient training strategies.
    

• Improved Parquet File Support
  Faster and more scalable data processing with an upgraded backend engine.

  • Enhanced memory management and stability for large-scale data.
  • Expanded support for advanced query operations on parquet data sources.
    

• Interpretability
  Added support for event-level interpretability in classification and regression models.
  

Fixes

• Fixed an issue where the _FINISHED flag for column fit tasks was occasionally set incorrectly, resulting in an unstable resume option.
  
• Fixed an issue where the log in main.log file was empty, incomplete or incorrectly written during model training.
  
• Fixed an issue where `next_n_hours' parameter used in target function was excluding starting time stamp.
  
• Updated packages to improve performance, improve security and for compatibility with the latest features.

New features:

• Improved handling of time series (BETA)
  Users can now enable improved handling of time series by declaring selected numeric columns as time-series. This feature provides superior representation of event sequences and intervals.
  
• Automated sanitization and qualification of column names inwhere_condition
  The resolve() function function can now be used in where_condition to enhance consistency and reduce the risk of errors.
  
• Optimised memory utilization for datasources in parquet file format
  More stable handling of parquet files used as data sources, including filtering data at an early stage and reading parquet files in chunks to reduce peak memory usage.
  
• Enhanced history / future splitting
  Additional sampling strategy ("existing") supports more modeling scenarios, such as basket context for next purchase prediction. Regular timestamps are now used for split points instead of day timestamps.\
  
• Enhanced interpretability of time-based features
  Provides deeper insight on the impact of time-based features by separating out periodical counts, sums, and means.
  
• Event aggregations without grouping:
  Users can now perform aggregation operations such as sum(), count(), mean(), min() and max() in the target function without needing to group events.
  
• Capping number of CPU resources at fit stage
  Users can now limit the utilization of computation resources during the fit stage with the num_cpus argument.
  

Fixes

• Fixed an issue where certain custom metrics were not automatically cast to the appropriate data type.
  
• Fixed an issue where certain features were not saved after a pretraining failure.
  
• Fixed an issue where the most frequently interacting entities could be partially ignored when calculating validation metrics in recommendation tasks.
  
• Fixed an issue where repeating column names across joined data sources might result in conflict.
  
• Fixed an issue where the percentage of NaN values was incorrectly calculated for columns containing both NaN values and empty strings.
  
• Fixed an issue where the CPU cap set with the num_cpus argument was ignored.
  
• Fixed an issue where a .csv suffix was expected instead of .tsv for the predictions file.
  
• Fixed an issue where a file lock set during event grouping resulted in a FileExistsError in case of slow storage.
  
• Fixed an issue where interpret() resulted in an error for data sources with shared entities.
  
• Fixed an issue where interpret() resulted in an error in case of empty quantiles for groups with no events.
  
• Updated packages to improve performance, security, and compatibility with the latest features.