adaptive-xai 1.0.0b1__tar.gz

adaptive_xai-1.0.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Charan, Dhyan KJ, Jeevitha Shetty, Poorvi J Poojary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adaptive_xai-1.0.0b1/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: adaptive-xai
+Version: 1.0.0b1
+Summary: An adaptive explainable-AI framework for integrating XAI into machine learning projects.
+Author: Charan, Dhyan KJ, Jeevitha Shetty, Poorvi J Poojary
+License-Expression: MIT
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: nbformat
+Dynamic: license-file
+
+# Adaptive XAI Framework for Healthcare Systems
+
+An adaptive explainable-AI framework for helping developers integrate XAI into
+existing machine learning projects, especially healthcare and clinical modeling
+workflows.
+
+The framework analyzes a project, infers a model profile, selects a suitable XAI
+technique, prepares dependencies, generates an integration, and produces
+human-readable explanations for model predictions.
+
+## Overview
+
+Adaptive XAI is designed to support the following workflow:
+
+1. Analyze a project directory to infer the model type, architecture, input
+   modality, and available feature metadata.
+2. Select a suitable XAI technique from the inferred model profile.
+3. Prepare any required dependencies for the chosen technique.
+4. Generate a model integration that can run explanations against the project.
+5. Produce readable explanation output in a format suitable for downstream use,
+   reporting, and debugging.
+
+The framework is intended to work with existing ML projects without requiring the
+user to rebuild a separate example model or re-run the analysis repeatedly.
+
+## Package name and installation
+
+The Python package is published as:
+
+```bash
+adaptive-xai
+```
+
+Install it from PyPI with:
+
+```bash
+pip install adaptive-xai
+```
+
+This installs the package and registers the command-line tools defined in
+`pyproject.toml` in the target Python environment.
+
+## CLI commands
+
+### `adaptive-xai`
+
+Run the full framework workflow from the project root:
+
+```bash
+adaptive-xai
+```
+
+This starts the framework orchestration flow, including model analysis,
+selection, dependency preparation, and integration generation.
+
+### `analyze`
+
+Run the analyzer directly inside a target project directory:
+
+```bash
+analyze
+```
+
+This scans the project and generates or updates `model_report.json` in the
+current working directory.
+
+### `xai-select`
+
+Use an existing analysis report without rerunning the full analyzer:
+
+```bash
+xai-select
+```
+
+By default, it reads `model_report.json` from the current directory. It can also
+accept a path to a report file.
+
+### `convert`
+
+Convert one or more Jupyter notebooks into runnable Python scripts:
+
+```bash
+convert my_notebook.ipynb
+convert notebooks/
+```
+
+The generated `.py` file keeps the same base name as the notebook and preserves
+cell contents in plain Python while commenting out notebook magics and shell
+commands that are not valid in a normal script.
+
+## Framework architecture
+
+The repository is organized as follows:
+
+```text
+adaptive_xai/
+├── __init__.py
+├── run.py                     # orchestration entry point
+├── cli_display.py             # terminal output and UI helpers
+├── model_analyzer/           # project/model profiling
+├── xai_selector/             # technique selection logic
+├── dependency_manager/       # dependency preparation and validation
+├── xai_integration/          # model loading, plugin integration, execution
+├── explanation_generator/    # template-based explanation rendering
+├── notebook_converter.py     # notebook-to-Python conversion tool
+└── ...
+```
+
+## Module responsibilities
+
+### `adaptive_xai/model_analyzer/`
+
+Responsible for inferring project and model characteristics including:
+
+- ML framework
+- model architecture or category
+- task type
+- input modality
+- feature metadata
+- dataset and config signals
+
+It writes a `model_report.json` that summarizes the inferred profile.
+
+### `adaptive_xai/xai_selector/`
+
+Selects a compatible XAI method based on the model profile and other signals.
+It includes:
+
+- mapping rules and strategy logic
+- recommendation/ranking support
+- CLI tooling for continuing from a saved report
+
+### `adaptive_xai/dependency_manager/`
+
+Prepares dependencies required by the selected explanation method and checks
+whether required libraries are available.
+
+### `adaptive_xai/xai_integration/`
+
+Handles the execution side of XAI integration, including:
+
+- model loading
+- explanation execution
+- plugin generation and integration
+- output schema definition
+- persistent integration generation for project use
+
+### `adaptive_xai/explanation_generator/`
+
+Transforms structured XAI outputs into readable and presentation-friendly text.
+
+This module contains:
+
+- `template_engine.py` for JSON template loading and formatting
+- `generator.py` for rendering explanation output
+- `templates/*.json` for technique-specific output templates
+
+Supported techniques include:
+
+- SHAP
+- LIME
+- Feature Importance
+- Grad-CAM
+- Tree Interpreter
+
+This is the module added to the framework for explanation formatting and result
+presentation.
+
+## Typical workflow
+
+From a project directory:
+
+```bash
+analyze
+xai-select
+```
+
+or:
+
+```bash
+adaptive-xai
+```
+
+The workflow produces a `model_report.json`, identifies the best XAI approach,
+prepares dependencies, and generates the integration needed to explain model
+predictions.
+
+## Output artifacts
+
+The framework generates and relies on the following artifacts:
+
+- `model_report.json` — inferred project/model profile
+- generated XAI integration files
+- selected technique metadata and explanation output
+- template-based explanation reports
+
+## Example usage
+
+```bash
+cd /path/to/your/project
+analyze
+xai-select
+```
+
+Or directly:
+
+```bash
+cd /path/to/your/project
+adaptive-xai
+```
+
+## License
+
+This project is licensed under the terms of the LICENSE file included in this
+repository.

adaptive_xai-1.0.0b1/README.md

@@ -0,0 +1,215 @@
+# Adaptive XAI Framework for Healthcare Systems
+
+An adaptive explainable-AI framework for helping developers integrate XAI into
+existing machine learning projects, especially healthcare and clinical modeling
+workflows.
+
+The framework analyzes a project, infers a model profile, selects a suitable XAI
+technique, prepares dependencies, generates an integration, and produces
+human-readable explanations for model predictions.
+
+## Overview
+
+Adaptive XAI is designed to support the following workflow:
+
+1. Analyze a project directory to infer the model type, architecture, input
+   modality, and available feature metadata.
+2. Select a suitable XAI technique from the inferred model profile.
+3. Prepare any required dependencies for the chosen technique.
+4. Generate a model integration that can run explanations against the project.
+5. Produce readable explanation output in a format suitable for downstream use,
+   reporting, and debugging.
+
+The framework is intended to work with existing ML projects without requiring the
+user to rebuild a separate example model or re-run the analysis repeatedly.
+
+## Package name and installation
+
+The Python package is published as:
+
+```bash
+adaptive-xai
+```
+
+Install it from PyPI with:
+
+```bash
+pip install adaptive-xai
+```
+
+This installs the package and registers the command-line tools defined in
+`pyproject.toml` in the target Python environment.
+
+## CLI commands
+
+### `adaptive-xai`
+
+Run the full framework workflow from the project root:
+
+```bash
+adaptive-xai
+```
+
+This starts the framework orchestration flow, including model analysis,
+selection, dependency preparation, and integration generation.
+
+### `analyze`
+
+Run the analyzer directly inside a target project directory:
+
+```bash
+analyze
+```
+
+This scans the project and generates or updates `model_report.json` in the
+current working directory.
+
+### `xai-select`
+
+Use an existing analysis report without rerunning the full analyzer:
+
+```bash
+xai-select
+```
+
+By default, it reads `model_report.json` from the current directory. It can also
+accept a path to a report file.
+
+### `convert`
+
+Convert one or more Jupyter notebooks into runnable Python scripts:
+
+```bash
+convert my_notebook.ipynb
+convert notebooks/
+```
+
+The generated `.py` file keeps the same base name as the notebook and preserves
+cell contents in plain Python while commenting out notebook magics and shell
+commands that are not valid in a normal script.
+
+## Framework architecture
+
+The repository is organized as follows:
+
+```text
+adaptive_xai/
+├── __init__.py
+├── run.py                     # orchestration entry point
+├── cli_display.py             # terminal output and UI helpers
+├── model_analyzer/           # project/model profiling
+├── xai_selector/             # technique selection logic
+├── dependency_manager/       # dependency preparation and validation
+├── xai_integration/          # model loading, plugin integration, execution
+├── explanation_generator/    # template-based explanation rendering
+├── notebook_converter.py     # notebook-to-Python conversion tool
+└── ...
+```
+
+## Module responsibilities
+
+### `adaptive_xai/model_analyzer/`
+
+Responsible for inferring project and model characteristics including:
+
+- ML framework
+- model architecture or category
+- task type
+- input modality
+- feature metadata
+- dataset and config signals
+
+It writes a `model_report.json` that summarizes the inferred profile.
+
+### `adaptive_xai/xai_selector/`
+
+Selects a compatible XAI method based on the model profile and other signals.
+It includes:
+
+- mapping rules and strategy logic
+- recommendation/ranking support
+- CLI tooling for continuing from a saved report
+
+### `adaptive_xai/dependency_manager/`
+
+Prepares dependencies required by the selected explanation method and checks
+whether required libraries are available.
+
+### `adaptive_xai/xai_integration/`
+
+Handles the execution side of XAI integration, including:
+
+- model loading
+- explanation execution
+- plugin generation and integration
+- output schema definition
+- persistent integration generation for project use
+
+### `adaptive_xai/explanation_generator/`
+
+Transforms structured XAI outputs into readable and presentation-friendly text.
+
+This module contains:
+
+- `template_engine.py` for JSON template loading and formatting
+- `generator.py` for rendering explanation output
+- `templates/*.json` for technique-specific output templates
+
+Supported techniques include:
+
+- SHAP
+- LIME
+- Feature Importance
+- Grad-CAM
+- Tree Interpreter
+
+This is the module added to the framework for explanation formatting and result
+presentation.
+
+## Typical workflow
+
+From a project directory:
+
+```bash
+analyze
+xai-select
+```
+
+or:
+
+```bash
+adaptive-xai
+```
+
+The workflow produces a `model_report.json`, identifies the best XAI approach,
+prepares dependencies, and generates the integration needed to explain model
+predictions.
+
+## Output artifacts
+
+The framework generates and relies on the following artifacts:
+
+- `model_report.json` — inferred project/model profile
+- generated XAI integration files
+- selected technique metadata and explanation output
+- template-based explanation reports
+
+## Example usage
+
+```bash
+cd /path/to/your/project
+analyze
+xai-select
+```
+
+Or directly:
+
+```bash
+cd /path/to/your/project
+adaptive-xai
+```
+
+## License
+
+This project is licensed under the terms of the LICENSE file included in this
+repository.

adaptive_xai-1.0.0b1/adaptive_xai/__init__.py

@@ -0,0 +1 @@
+# Adaptive XAI Framework

adaptive_xai-1.0.0b1/adaptive_xai/cli_display.py

@@ -0,0 +1,175 @@
+def print_banner():
+    print(r"""
+    ────────────────────────────────────────────────────────────────────────────────────────────────────
+        ▄▖ ▌    ▗ ▘      ▖▖▄▖▄▖  ▄▖                ▌   ▐▘      ▖▖    ▜ ▗ ▌           ▄▖    ▗        
+        ▌▌▛▌▀▌▛▌▜▘▌▌▌█▌  ▚▘▌▌▐   ▙▖▛▘▀▌▛▛▌█▌▌▌▌▛▌▛▘▙▘  ▜▘▛▌▛▘  ▙▌█▌▀▌▐ ▜▘▛▌▛▘▀▌▛▘█▌  ▚ ▌▌▛▘▜▘█▌▛▛▌▛▘
+        ▛▌▙▌█▌▙▌▐▖▌▚▘▙▖  ▌▌▛▌▟▖  ▌ ▌ █▌▌▌▌▙▖▚▚▘▙▌▌ ▛▖  ▐ ▙▌▌   ▌▌▙▖█▌▐▖▐▖▌▌▙▖█▌▌ ▙▖  ▄▌▙▌▄▌▐▖▙▖▌▌▌▄▌
+            ▌                                                                          ▄▌    
+    ────────────────────────────────────────────────────────────────────────────────────────────────────       
+    """)
+
+
+def print_status(message):
+    print(f"[✓] {message}")
+
+def print_error(message):
+    print(f"[✗] {message}")
+
+def print_analysis_validation_error(reasons):
+    print()
+    print(
+        "\033[1;37;41m The selected folder may not be the correct "
+        "model project. \033[0m"
+    )
+    print("\033[1;31mSetup stopped because the analyzer could not identify:\033[0m")
+    for reason in reasons:
+        print(f"  - {reason}")
+    print(
+        "Check that you selected the project folder containing the model "
+        "source/configuration files, then rerun the setup."
+    )
+
+
+def print_model_compatibility_error(message):
+    print()
+    print("\033[1;37;41m MODEL VERSION INCOMPATIBILITY \033[0m")
+    print(f"\033[1;31m{message}\033[0m")
+    print(
+        "Retrain and save the model with the installed scikit-learn version, "
+        "or use a separate environment with a compatible Python and "
+        "scikit-learn version. The active environment was not downgraded."
+    )
+
+
+def print_model_load_error(error):
+    from .xai_integration.exceptions import ModelCompatibilityError
+
+    root_cause = error
+    seen = set()
+    while root_cause.__cause__ is not None and id(root_cause) not in seen:
+        seen.add(id(root_cause))
+        root_cause = root_cause.__cause__
+
+    detail = str(root_cause)
+    normalized_detail = detail.lower()
+    if (
+        isinstance(error, ModelCompatibilityError)
+        and error.package == "scikit-learn"
+        and error.saved_versions
+    ):
+        saved_versions = ", ".join(error.saved_versions)
+        suggested_version = error.saved_versions[0]
+        title = "SCIKIT-LEARN VERSION MISMATCH"
+        message = (
+            f"The model metadata says it was saved with scikit-learn "
+            f"{saved_versions}; this environment has scikit-learn "
+            f"{error.installed_version}. To try using it, create a separate "
+            "environment with a Python version supported by the saved "
+            f"scikit-learn release and install "
+            f"`scikit-learn=={suggested_version}`. A compatible NumPy version "
+            "may also be required. This is a best starting point, not a "
+            "guarantee; retraining and re-saving with the current environment "
+            "is the most reliable option."
+        )
+    elif isinstance(error, ModelCompatibilityError) or (
+        "node array from the pickle has an incompatible dtype"
+        in normalized_detail
+    ):
+        title = "MODEL VERSION INCOMPATIBILITY"
+        message = (
+            "The model was saved with a scikit-learn tree format that is "
+            "incompatible with the installed version. Retrain/re-save it "
+            "with the installed version or load it in a separate environment "
+            "using a compatible Python and scikit-learn version."
+        )
+    elif (
+        "sklearn.compose._column_transformer" in normalized_detail
+        and "_remaindercolslist" in normalized_detail
+    ):
+        title = "SCIKIT-LEARN PIPELINE VERSION MISMATCH"
+        message = (
+            "This pipeline uses an internal scikit-learn component that "
+            "differs from the version installed here. This is a model/library "
+            "compatibility issue, not a problem with adap_xai.py, and the "
+            "framework has not modified your model file. To continue, "
+            "preferably retrain and re-save the pipeline with the installed "
+            "scikit-learn version. If you cannot retrain, use a separate "
+            "environment with a compatible Python and the scikit-learn "
+            "version used to save the model; avoid downgrading a shared "
+            "environment."
+        )
+    elif (
+        "xgboost" in normalized_detail
+        and (
+            "estimator" in normalized_detail
+            or "xgboost.sklearn" in normalized_detail
+        )
+    ):
+        title = "XGBOOST MODEL INTERFACE UNAVAILABLE"
+        message = (
+            "XGBoost is required, but its scikit-learn estimator interface "
+            "is unavailable in the active Python environment. Verify the "
+            "installed XGBoost version and import path, then use an "
+            "environment that provides the interface/version used to save "
+            "this pickle. If possible, re-export the model in XGBoost's "
+            "native JSON or UBJ format."
+        )
+    elif isinstance(root_cause, ModuleNotFoundError):
+        title = "MODEL DEPENDENCY UNAVAILABLE"
+        module_name = root_cause.name or "a required module"
+        message = (
+            f"The model requires Python module '{module_name}', which could "
+            "not be imported. Install a compatible dependency in the active "
+            "Python environment or use the environment that created the model."
+        )
+    elif isinstance(root_cause, FileNotFoundError):
+        title = "MODEL FILE NOT FOUND"
+        message = "Check that the configured model path exists and is accessible."
+    else:
+        title = "MODEL LOAD FAILED"
+        message = (
+            "The model could not be loaded. Check that the selected file is "
+            "valid and compatible with the installed framework and dependency "
+            "versions."
+        )
+
+    print()
+    print(f"\033[1;37;41m {title} \033[0m")
+    print(f"\033[1;31m{message}\033[0m")
+    if detail:
+        print(f"Details: {detail}")
+
+def print_explanation_error(error):
+    detail = str(error)
+    if "background_data" in detail.lower():
+        title = "EXPLANATION BACKGROUND DATA REQUIRED"
+        message = (
+            "The selected tabular SHAP or LIME explanation needs representative "
+            "background rows. Add a matching CSV/Excel dataset to the project, "
+            "or edit BACKGROUND_DATA in adap_xai.py with rows in the same "
+            "feature order the model expects. The framework will not invent "
+            "or modify model inputs."
+        )
+    else:
+        title = "EXPLANATION FAILED"
+        message = (
+            "The model loaded, but the selected XAI technique could not produce "
+            "an explanation. Check the technique's input requirements and the "
+            "details below."
+        )
+
+    print()
+    print(f"\033[1;37;41m {title} \033[0m")
+    print(f"\033[1;31m{message}\033[0m")
+    if detail:
+        print(f"Details: {detail}")
+
+
+def print_section(title):
+    print("\n" + "─" * 62)
+    print(f"{title:^62}")
+    print("─" * 62)
+
+
+def print_step(message):
+    print(f"  → {message}")

adaptive_xai-1.0.0b1/adaptive_xai/dependency_manager/__init__.py

@@ -0,0 +1,3 @@
+from .manager import prepare_dependencies, prepare_model_dependencies
+
+__all__ = ["prepare_dependencies", "prepare_model_dependencies"]

adaptive_xai-1.0.0b1/adaptive_xai/dependency_manager/checker.py

@@ -0,0 +1,4 @@
+import importlib.util
+
+def is_installed(import_name):
+    return importlib.util.find_spec(import_name) is not None