Version 0.3.1

(Release Date: June 25, 2025)

Focus: Backend Dependency Management & New GUI Application

This is a significant maintenance and usability release. It completely overhauls how the library handles its optional heavy dependencies to eliminate build errors and improve robustness. Furthermore, this version introduces the first version of the Subsidence PINN Mini GUI, a standalone desktop application designed to make the library’s PINN workflows accessible to a broader audience.

New Features

  • New Subsidence PINN Mini GUI: A new desktop application for end-to-end forecasting. Located in fusionlab.tools.app, this GUI allows users to load data, configure all model and training parameters, run the workflow, and visualize results without writing any code. It can be launched via:

    python -m fusionlab.tools.app.mini_forecaster_gui

  • New Centralized Manifest Registry: Introduced the ManifestRegistry, a singleton class that acts as the single source of truth for the location of all training run artifacts. This eliminates fragile file searches and provides a robust foundation for state management.

  • New Session-Only Mode for GUI: The ManifestRegistry can be initialized in a session_only mode, which creates a temporary directory for all outputs generated by the GUI. This directory is automatically deleted when the application is closed, ensuring the user’s system is not cluttered with intermediate files from experimental runs.

Improvements

  • Enhancement Centralized Configuration: Introduced a new internal module, fusionlab/_configs.py, which now serves as the single source of truth for all backend dependency mappings. Hardcoded dictionaries have been removed from individual modules.

  • Enhancement Config-Driven Dependency Loaders: The dependency loaders in fusionlab/compat/, such as KerasDependencies, now read directly from the central configuration. This makes them more robust and easier to maintain.

  • Enhancement Smart Dummy Objects: Introduced a new internal module, fusionlab/_dummies.py, which dynamically generates placeholder objects for uninstalled dependencies. This dummy system is also driven by the central configuration, ensuring it is always perfectly in sync with the real dependency loader.

  • Enhancement Simplified Module Imports: The __init__.py files for the nn and forecast_tuner subpackages now perform a single check for dependencies and create a single, authoritative KERAS_DEPS or KT_DEPS object. This eliminates the need for redundant if/else blocks and local dummy class definitions in individual model and utility files, making the codebase significantly cleaner.

  • Enhancement Decorator Refactoring: The multi-purpose _scigofast_set_X_compat decorator has been refactored into smaller, focused components. The new `adapt_sklearn_input` decorator now has the single responsibility of reshaping a 2D scikit-learn style array into the multi-input list required by fusionlab models.

  • Enhancement New Utility Function: The “concat” functionality from the old decorator has been extracted into a new, public utility function, concatenate_fusionlab_inputs, for converting a fusionlab multi-input list back into a single 2D array for use in standard scikit-learn pipelines.

API Changes

  • API Change The internal logic for handling optional dependencies has been completely refactored. While the public-facing API for models and functions remains the same, the mechanism for importing them is now centralized. This change is internal but represents a major architectural shift towards a more robust and scalable design.

  • API Change The internal decorator for scikit-learn compatibility has been renamed and simplified from _scigofast_set_X_compat to adapt_sklearn_input, with a more focused scope.

  • API Change The PredictionPipeline constructor has been simplified. It now takes a direct manifest_path instead of relying on a validation_data_path to heuristically locate artifacts.

Fixes

  • Fix Resolved Circular Import Errors: The primary motivation for this release. The new centralized dependency system, combined with the standard practice of using local imports for internal modules, definitively resolves the ImportExceptionGroup and ExtensionError failures that were occurring during documentation builds on Read the Docs.

  • Fix The automatic cleanup for GUI session_only mode is now more robust, correctly identifying and removing the temporary run directory on application exit across different operating systems.

Tests

  • Tests The internal test suite has been updated to validate the new dependency loading mechanism, ensuring that both the real and dummy objects are created and accessed correctly.

  • Tests Added a comprehensive test suite for the new ManifestRegistry, validating both persistent and session_only modes, as well as the latest_manifest() and import_manifest() functionality.

  • Tests Expanded tests for the PredictionPipeline to ensure it initializes correctly with the refactored manifest logic.

Documentation

Contributors