Add comprehensive API documentation with GitHub Pages deployment

.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+name: Deploy Documentation to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install sphinx sphinx-autodoc-typehints
+          pip install -e .
+
+      - name: Build documentation
+        run: |
+          cd docs
+          make html
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build/html
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    # Only deploy on push to main/master branch
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master')
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

README.rst

@@ -58,12 +58,12 @@ Image Data
 Text Data
 ---------
 
-* 🚧 **Work in Progress** - Coming soon!
+* **LIME** - Local Interpretable Model-agnostic Explanations for text classification
 
 Time Series Data
 ----------------
 
-* 🚧 **Work in Progress** - Coming soon!
+* **LASTS** - Local Agnostic Subsequence-based Time Series explanations
 
 |
 
@@ -110,19 +110,24 @@ Here's a simple example of using LIME for tabular data explanation:
 
 .. code-block:: python
 
-   from xailib import Explainer
+   from xailib.explainers.lime_explainer import LimeXAITabularExplainer
+   from xailib.models.sklearn_classifier_wrapper import sklearn_classifier_wrapper
 
-   # Initialize your black-box model
-   # model = YourModel()
+   # Wrap your scikit-learn model
+   bb = sklearn_classifier_wrapper(your_trained_model)
 
-   # Create an explainer
-   explainer = Explainer(model, method='lime')
+   # Create and fit the LIME explainer
+   explainer = LimeXAITabularExplainer(bb)
+   explainer.fit(df, 'target_column', config={
+       'discretize_continuous': True,
+       'feature_selection': 'auto'
+   })
 
-   # Generate explanation for a sample
-   explanation = explainer.explain(sample_data)
+   # Generate explanation for an instance
+   explanation = explainer.explain(instance, num_samples=1000)
 
-   # Visualize the explanation
-   explainer.visualize(explanation)
+   # Visualize feature importance
+   explanation.plot_features_importance()
 
 For more examples and detailed usage, please check the `examples/ <https://github.com/kdd-lab/XAI-Lib/tree/main/examples>`_ directory.
 
@@ -133,10 +138,18 @@ For more examples and detailed usage, please check the `examples/ <https://githu
 
 For detailed documentation, tutorials, and API reference, visit:
 
-* **Documentation**: `https://xai-lib.readthedocs.io/ <https://xai-lib.readthedocs.io/>`_
+* **GitHub Pages Documentation**: `https://kdd-lab.github.io/XAI-Lib/ <https://kdd-lab.github.io/XAI-Lib/>`_
+* **Read the Docs**: `https://xai-lib.readthedocs.io/ <https://xai-lib.readthedocs.io/>`_
 * **GitHub Repository**: `https://github.com/kdd-lab/XAI-Lib <https://github.com/kdd-lab/XAI-Lib>`_
 * **Issue Tracker**: `https://github.com/kdd-lab/XAI-Lib/issues <https://github.com/kdd-lab/XAI-Lib/issues>`_
 
+The documentation includes:
+
+* **Getting Started Guide**: Installation and quick start tutorials
+* **API Reference**: Complete documentation of all classes and methods
+* **Examples**: Practical examples for tabular, image, and text data
+* **Contributing Guide**: How to contribute to the project
+
 |
 
 🤝 Contributing
@@ -165,17 +178,13 @@ This project is licensed under the MIT License - see the `LICENSE <LICENSE.txt>`
 
 |
 
-🙏 Acknowledgments
+Acknowledgments
 ==================
 
 This library is developed as part of the **XAI Project** (`https://xai-project.eu/ <https://xai-project.eu/>`_), a European initiative dedicated to advancing explainable artificial intelligence.
 
-The XAI Project aims to:
+The Xai project focuses on the urgent open challenge of how to construct meaningful explanations of opaque AI/ML systems in the context of ai based decision making, aiming at empowering individual against undesired effects of automated decision making, implementing the right of explanation, helping people make better decisions preserving (and expand) human autonomy.
 
-* Develop new methods for explainable AI
-* Create practical tools for AI transparency
-* Foster collaboration between research and industry
-* Promote responsible AI development
 
 For more information about the XAI Project, visit `https://xai-project.eu/ <https://xai-project.eu/>`_.
 

docs/requirements.txt

@@ -2,4 +2,5 @@
 # To build the module reference correctly, make sure every external package
 # under `install_requires` in `setup.cfg` is also listed here!
 sphinx>=3.2.1
+sphinx-autodoc-typehints>=1.12.0
 # sphinx_rtd_theme

src/xailib/__init__.py

@@ -0,0 +1,121 @@
+"""
+XAI-Lib: An Integrated Python Library for Explainable AI.
+
+**XAI-Lib** provides a unified interface for various explanation methods,
+making machine learning models more interpretable and transparent. The library
+simplifies the process of explaining black-box models across different data types.
+
+This project is part of the `XAI Project <https://xai-project.eu/>`_ - a European
+initiative focused on advancing explainable artificial intelligence research
+and applications.
+
+Main Modules
+------------
+
+Core Classes
+~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: _autosummary
+
+    xailib.xailib_base
+    xailib.xailib_tabular
+    xailib.xailib_image
+    xailib.xailib_text
+    xailib.xailib_ts
+    xailib.xailib_transparent_by_design
+
+Explainers
+~~~~~~~~~~
+
+.. autosummary::
+    :toctree: _autosummary
+
+    xailib.explainers.lime_explainer
+    xailib.explainers.shap_explainer_tab
+    xailib.explainers.lore_explainer
+    xailib.explainers.gradcam_explainer
+    xailib.explainers.rise_explainer
+    xailib.explainers.intgrad_explainer
+    xailib.explainers.abele_explainer
+    xailib.explainers.lasts_explainer
+    xailib.explainers.nam_explainer_tab
+
+Model Wrappers
+~~~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: _autosummary
+
+    xailib.models.bbox
+    xailib.models.sklearn_classifier_wrapper
+    xailib.models.keras_classifier_wrapper
+    xailib.models.pytorch_classifier_wrapper
+
+Data Loaders
+~~~~~~~~~~~~
+
+.. autosummary::
+    :toctree: _autosummary
+
+    xailib.data_loaders.dataframe_loader
+
+Metrics
+~~~~~~~
+
+.. autosummary::
+    :toctree: _autosummary
+
+    xailib.metrics.insertiondeletion
+
+Quick Start
+-----------
+
+Here's a simple example using LIME for tabular data explanation::
+
+    from xailib.explainers.lime_explainer import LimeXAITabularExplainer
+    from xailib.models.sklearn_classifier_wrapper import sklearn_classifier_wrapper
+
+    # Wrap your scikit-learn model
+    bb = sklearn_classifier_wrapper(your_sklearn_model)
+
+    # Create and fit the explainer
+    explainer = LimeXAITabularExplainer(bb)
+    explainer.fit(df, 'target_column', config={})
+
+    # Generate explanation for an instance
+    explanation = explainer.explain(instance)
+
+    # Visualize feature importance
+    explanation.plot_features_importance()
+
+For more examples, see the `examples/ <https://github.com/kdd-lab/XAI-Lib/tree/main/examples>`_
+directory in the repository.
+
+License
+-------
+
+This project is licensed under the MIT License.
+
+Acknowledgments
+---------------
+
+This library is developed as part of the **XAI Project** (https://xai-project.eu/),
+a European initiative dedicated to advancing explainable artificial intelligence.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("XAI-Library")
+except PackageNotFoundError:
+    __version__ = "unknown"
+
+# Import main classes for convenient access
+from xailib.xailib_base import Explainer, Explanation
+
+__all__ = [
+    "__version__",
+    "Explainer",
+    "Explanation",
+]

src/xailib/data_loaders/__init__.py

@@ -0,0 +1,19 @@
+"""
+Data loading utilities for XAI-Lib.
+
+This subpackage provides utilities for loading and preparing data
+for use with XAI-Lib explainers.
+
+Available Loaders
+-----------------
+
+- :func:`~xailib.data_loaders.dataframe_loader.prepare_dataframe`:
+  Prepare a pandas DataFrame for use with XAI-Lib explainers.
+
+Example
+-------
+>>> from xailib.data_loaders.dataframe_loader import prepare_dataframe
+>>>
+>>> df, feature_names, class_values, numeric_columns, \\
+...     rdf, real_feature_names, features_map = prepare_dataframe(df, 'target')
+"""

src/xailib/data_loaders/dataframe_loader.py

@@ -1,5 +1,53 @@
+"""
+DataFrame loading and preparation utilities for XAI-Lib.
+
+This module provides utilities for loading and preparing pandas DataFrames
+for use with XAI-Lib tabular data explainers.
+
+Functions:
+    prepare_dataframe: Prepare a DataFrame for use with explainers.
+
+Example:
+    >>> from xailib.data_loaders.dataframe_loader import prepare_dataframe
+    >>>
+    >>> df, feature_names, class_values, numeric_columns, \\
+    ...     rdf, real_feature_names, features_map = prepare_dataframe(df, 'target')
+"""
+
 from lore_explainer.datamanager import prepare_dataset
 
 
 def prepare_dataframe(df, class_field):
+    """
+    Prepare a pandas DataFrame for use with XAI-Lib explainers.
+
+    This function wraps the LORE library's prepare_dataset function to
+    process a DataFrame for use with various XAI-Lib explainers. It
+    handles feature encoding, categorical variable mapping, and other
+    preprocessing steps.
+
+    Args:
+        df (pd.DataFrame): Input DataFrame containing features and target.
+        class_field (str): Name of the target/class column in the DataFrame.
+
+    Returns:
+        tuple: A tuple containing:
+            - df: Processed DataFrame
+            - feature_names: List of feature column names
+            - class_values: List of unique class values
+            - numeric_columns: List of numeric column names
+            - rdf: Reconstructed DataFrame with original encoding
+            - real_feature_names: Original feature names before encoding
+            - features_map: Mapping of encoded to original features
+
+    Example:
+        >>> import pandas as pd
+        >>> df = pd.DataFrame({
+        ...     'age': [25, 30, 35],
+        ...     'income': [50000, 60000, 70000],
+        ...     'approved': [0, 1, 1]
+        ... })
+        >>> result = prepare_dataframe(df, 'approved')
+        >>> df_processed, feature_names, class_values, *rest = result
+    """
     return prepare_dataset(df, class_field)