exact-ai 0.1.0__tar.gz

exact_ai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GurenMashu
+
+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.

exact_ai-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include src/EXACT

exact_ai-0.1.0/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.4
+Name: exact-ai
+Version: 0.1.0
+Summary: Comprehensive Library for explainable AI (XAI) methods.
+Author-email: Glenn Mathews <glennmathews18@gmail.com>, Harishankar S M <harishankarsm2004@gmail.com>, Afzina Sadiq <afzinasadiq180@gmail.com>, Nandana Murali <nandanalmurali2003@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 GurenMashu
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/GurenMashu/E.X.A.C.T-by-GHAN
+Project-URL: Source, https://github.com/GurenMashu/E.X.A.C.T-by-GHAN
+Keywords: xai,explainability,gradcam,lime,shap,ml,ai
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Requires-Dist: torchvision
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: pillow
+Requires-Dist: grad-cam
+Requires-Dist: lime
+Requires-Dist: shap
+Dynamic: license-file
+
+# EXACT
+A plug-and-play XAI library for pytorch models.
+Meant for beginners and anyone interested in venturing into the XAI space, this package enables users to use any of the supported explainability methods with very few lines of code.
+
+## Key Functionalities
+ - Plug-and-play with the user's trained models and input data.
+ - Specialized evaluators to evaluate quality of generated explainability results.
+ - Specialized comparators to compare between mutliple xai methods to find the best one for your needs.
+ - All results visualized cleanly and saved locally.
+
+## Setup
+As of now you may clone the repo to use EXACT as PyPI deployment will be done later.
+```bash
+git clone "https...."
+cd E.X.A.C.T-BY-GHAN
+```
+
+Install the dependencies
+```bash
+python -m venv your_env
+source path_to_your_env/bin/activate    #for linux
+pip install -r requirements.txt
+pip install -e.    #to build the EXACT package.
+```
+
+## Usage
+All implemented explainers have detailed instruction docstrings and are structures similarly for ease of use.
+```bash
+from EXACT.explainers import SaliencyMap
+explainer = SaliencyMap(model = your_trained_model)
+result = explainer.explain(input_tensor, method = "guided", save_png = True)
+```
+
+Evaluator usage example
+```bash
+from EXACT.explainers import GradCAM
+from EXACT.evaluators import SharpnessEvaluator
+
+explainer = GradCAM(model = your_trained_model)
+result = explainer.explain(input_tensor, input_image, method = "xgradcam")
+
+sharp_ev = SharpnessEvaluator()
+sharp_result = sharp_ev.evaluate(explainer_result = result)
+sharp_ev.report(sharp_result)
+sharp_ev.plot(sharp_result, save_png=True)
+```
+
+Comparator usage example
+```bash
+from EXACT.explainers import GradCAM, IGImageExplainer
+from EXACT.comparators import HeatmapComparator
+
+explainer = GradCAM(your_trained_model)
+ig_explainer = IGImageExplainer(model = your_trained_model)
+
+gradcam_result = explainer.explain(input_tensor, input_image, method="gradcam", save_png=True)
+gradcampp_result = explainer.explain(input_tensor, input_image, method="gradcam++", save_png=True)
+ig_result = ig_explainer.explain(input_tensor, input_image, save_png = True)
+
+cmp = HeatmapComparator(model = your_trained_model, device = device, stability_enabled = False) 
+results = cmp.compare(
+    entries = {
+        "GradCAM": (gradcam_result, explainer, {"method": "gradcam"}),
+        "GradCAM++": (gradcampp_result, explainer, {"method": "gradcam++"}),
+        "IG": (ig_result, ig_explainer, {})
+    },
+    input_tensor,
+    input_image
+)
+cmp.report(results)
+cmp.plot(results, save_png = True)
+```
+
+# System overview
+## Architecture
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 
+    'primaryColor': '#1e3a5f',
+    'primaryTextColor': '#e0e0e0',
+    'primaryBorderColor': '#4a9eff',
+    'lineColor': '#4a9eff',
+    'secondaryColor': '#2d4a2d',
+    'tertiaryColor': '#3d3d3d',
+    'fontFamily': 'Segoe UI, Arial, sans-serif',
+    'nodeBorder': '#4a9eff',
+    'clusterBkg': '#1a1a2e',
+    'clusterBorder': '#4a9eff',
+    'titleColor': '#ffffff',
+    'edgeLabelBackground': '#16213e'
+}}}%%
+
+flowchart TB
+    %% Input
+    A["User Model + Input Data"]:::inputClass
+    
+    %% Decision Block
+    B{"Preprocessing<br/>Required?"}:::decisionClass
+    
+    %% Preprocessing
+    C["Data Preprocessing<br/>"]:::processClass
+    
+    %% Explainers
+    subgraph EXPLAINERS["EXPLAINERS MODULE"]
+        direction TB
+        E_SEL["Select XAI Explainer"]:::selectClass
+        E_PARAMS["Execute XAI method"]:::subClass
+        E_RES["Explanation<br/>Results"]:::resultClass
+    end
+    
+    %% Comparator
+    subgraph COMPARATOR["COMPARATORS MODULE"]
+        direction TB
+        C_SEL["Compare Multiple<br/>Explainers"]:::selectClass
+        C_COMPAT["Compatibility<br/>Ensurer"]:::subClass
+        C_METHODS["Comparison<br/>Methods"]:::subClass
+        C_RES["Comparison<br/>Results"]:::resultClass
+    end
+    
+    %% Evaluators
+    subgraph EVALUATORS["EVALUATORS MODULE"]
+        direction TB
+        V_SEL["Select Compatible<br/>Evaluator"]:::selectClass
+        V_COMPAT["Compatibility<br/>Ensurer"]:::subClass
+        V_RES["Evaluation<br/>Results"]:::resultClass
+    end
+    
+    %% Output
+    subgraph OUTPUT["OUTPUT LAYER"]
+        direction LR
+        OUT1["Visualize<br/>& Save"]:::outputClass
+        OUT2["Dashboard/Report<br/>Visualize & Save"]:::outputClass
+        OUT3["Report<br/>Visualize & Save"]:::outputClass
+    end
+    
+    %% Flows
+    A --> B
+    B -->|Yes| C
+    B -->|No| E_SEL
+    C --> E_SEL
+    
+    %% Explainers Module Flow
+    E_SEL --> E_PARAMS
+    E_PARAMS --> E_RES
+    
+    %% Workflow A: Single Explainer
+    E_RES --> OUT1
+    
+    %% Workflow B: Multiple Explainers + Comparator
+    E_RES --> C_SEL
+    C_SEL --> C_COMPAT
+    C_COMPAT --> C_METHODS
+    C_METHODS --> C_RES
+    C_RES --> OUT2
+    
+    %% Workflow C: Explainer + Evaluator
+    E_RES --> V_SEL
+    V_SEL --> V_COMPAT
+    V_COMPAT --> V_RES
+    V_RES --> OUT3
+    
+    %% Styling
+    classDef inputClass fill:#1e3a5f,stroke:#4a9eff,stroke-width:2px,color:#ffffff
+    classDef decisionClass fill:#5c3a1e,stroke:#f59e0b,stroke-width:2px,color:#ffffff
+    classDef processClass fill:#2d5016,stroke:#7ec850,stroke-width:2px,color:#ffffff
+    classDef selectClass fill:#2d4a5f,stroke:#60a5fa,stroke-width:2px,color:#ffffff
+    classDef subClass fill:#1a2f3a,stroke:#4a9eff,stroke-width:1px,color:#e0e0e0
+    classDef resultClass fill:#1a4a4a,stroke:#2dd4bf,stroke-width:2px,color:#ffffff
+    classDef outputClass fill:#4a1a4a,stroke:#c084fc,stroke-width:2px,color:#ffffff
+    
+    style EXPLAINERS fill:#0f172a,stroke:#4ade80,stroke-width:2px
+    style COMPARATOR fill:#0f172a,stroke:#fbbf24,stroke-width:2px
+    style EVALUATORS fill:#0f172a,stroke:#c084fc,stroke-width:2px
+    style OUTPUT fill:#0f172a,stroke:#c084fc,stroke-width:2px
+```
+
+
+## Contribution
+Accepting contributions

exact_ai-0.1.0/README.md

@@ -0,0 +1,178 @@
+# EXACT
+A plug-and-play XAI library for pytorch models.
+Meant for beginners and anyone interested in venturing into the XAI space, this package enables users to use any of the supported explainability methods with very few lines of code.
+
+## Key Functionalities
+ - Plug-and-play with the user's trained models and input data.
+ - Specialized evaluators to evaluate quality of generated explainability results.
+ - Specialized comparators to compare between mutliple xai methods to find the best one for your needs.
+ - All results visualized cleanly and saved locally.
+
+## Setup
+As of now you may clone the repo to use EXACT as PyPI deployment will be done later.
+```bash
+git clone "https...."
+cd E.X.A.C.T-BY-GHAN
+```
+
+Install the dependencies
+```bash
+python -m venv your_env
+source path_to_your_env/bin/activate    #for linux
+pip install -r requirements.txt
+pip install -e.    #to build the EXACT package.
+```
+
+## Usage
+All implemented explainers have detailed instruction docstrings and are structures similarly for ease of use.
+```bash
+from EXACT.explainers import SaliencyMap
+explainer = SaliencyMap(model = your_trained_model)
+result = explainer.explain(input_tensor, method = "guided", save_png = True)
+```
+
+Evaluator usage example
+```bash
+from EXACT.explainers import GradCAM
+from EXACT.evaluators import SharpnessEvaluator
+
+explainer = GradCAM(model = your_trained_model)
+result = explainer.explain(input_tensor, input_image, method = "xgradcam")
+
+sharp_ev = SharpnessEvaluator()
+sharp_result = sharp_ev.evaluate(explainer_result = result)
+sharp_ev.report(sharp_result)
+sharp_ev.plot(sharp_result, save_png=True)
+```
+
+Comparator usage example
+```bash
+from EXACT.explainers import GradCAM, IGImageExplainer
+from EXACT.comparators import HeatmapComparator
+
+explainer = GradCAM(your_trained_model)
+ig_explainer = IGImageExplainer(model = your_trained_model)
+
+gradcam_result = explainer.explain(input_tensor, input_image, method="gradcam", save_png=True)
+gradcampp_result = explainer.explain(input_tensor, input_image, method="gradcam++", save_png=True)
+ig_result = ig_explainer.explain(input_tensor, input_image, save_png = True)
+
+cmp = HeatmapComparator(model = your_trained_model, device = device, stability_enabled = False) 
+results = cmp.compare(
+    entries = {
+        "GradCAM": (gradcam_result, explainer, {"method": "gradcam"}),
+        "GradCAM++": (gradcampp_result, explainer, {"method": "gradcam++"}),
+        "IG": (ig_result, ig_explainer, {})
+    },
+    input_tensor,
+    input_image
+)
+cmp.report(results)
+cmp.plot(results, save_png = True)
+```
+
+# System overview
+## Architecture
+```mermaid
+%%{init: {'theme': 'base', 'themeVariables': { 
+    'primaryColor': '#1e3a5f',
+    'primaryTextColor': '#e0e0e0',
+    'primaryBorderColor': '#4a9eff',
+    'lineColor': '#4a9eff',
+    'secondaryColor': '#2d4a2d',
+    'tertiaryColor': '#3d3d3d',
+    'fontFamily': 'Segoe UI, Arial, sans-serif',
+    'nodeBorder': '#4a9eff',
+    'clusterBkg': '#1a1a2e',
+    'clusterBorder': '#4a9eff',
+    'titleColor': '#ffffff',
+    'edgeLabelBackground': '#16213e'
+}}}%%
+
+flowchart TB
+    %% Input
+    A["User Model + Input Data"]:::inputClass
+    
+    %% Decision Block
+    B{"Preprocessing<br/>Required?"}:::decisionClass
+    
+    %% Preprocessing
+    C["Data Preprocessing<br/>"]:::processClass
+    
+    %% Explainers
+    subgraph EXPLAINERS["EXPLAINERS MODULE"]
+        direction TB
+        E_SEL["Select XAI Explainer"]:::selectClass
+        E_PARAMS["Execute XAI method"]:::subClass
+        E_RES["Explanation<br/>Results"]:::resultClass
+    end
+    
+    %% Comparator
+    subgraph COMPARATOR["COMPARATORS MODULE"]
+        direction TB
+        C_SEL["Compare Multiple<br/>Explainers"]:::selectClass
+        C_COMPAT["Compatibility<br/>Ensurer"]:::subClass
+        C_METHODS["Comparison<br/>Methods"]:::subClass
+        C_RES["Comparison<br/>Results"]:::resultClass
+    end
+    
+    %% Evaluators
+    subgraph EVALUATORS["EVALUATORS MODULE"]
+        direction TB
+        V_SEL["Select Compatible<br/>Evaluator"]:::selectClass
+        V_COMPAT["Compatibility<br/>Ensurer"]:::subClass
+        V_RES["Evaluation<br/>Results"]:::resultClass
+    end
+    
+    %% Output
+    subgraph OUTPUT["OUTPUT LAYER"]
+        direction LR
+        OUT1["Visualize<br/>& Save"]:::outputClass
+        OUT2["Dashboard/Report<br/>Visualize & Save"]:::outputClass
+        OUT3["Report<br/>Visualize & Save"]:::outputClass
+    end
+    
+    %% Flows
+    A --> B
+    B -->|Yes| C
+    B -->|No| E_SEL
+    C --> E_SEL
+    
+    %% Explainers Module Flow
+    E_SEL --> E_PARAMS
+    E_PARAMS --> E_RES
+    
+    %% Workflow A: Single Explainer
+    E_RES --> OUT1
+    
+    %% Workflow B: Multiple Explainers + Comparator
+    E_RES --> C_SEL
+    C_SEL --> C_COMPAT
+    C_COMPAT --> C_METHODS
+    C_METHODS --> C_RES
+    C_RES --> OUT2
+    
+    %% Workflow C: Explainer + Evaluator
+    E_RES --> V_SEL
+    V_SEL --> V_COMPAT
+    V_COMPAT --> V_RES
+    V_RES --> OUT3
+    
+    %% Styling
+    classDef inputClass fill:#1e3a5f,stroke:#4a9eff,stroke-width:2px,color:#ffffff
+    classDef decisionClass fill:#5c3a1e,stroke:#f59e0b,stroke-width:2px,color:#ffffff
+    classDef processClass fill:#2d5016,stroke:#7ec850,stroke-width:2px,color:#ffffff
+    classDef selectClass fill:#2d4a5f,stroke:#60a5fa,stroke-width:2px,color:#ffffff
+    classDef subClass fill:#1a2f3a,stroke:#4a9eff,stroke-width:1px,color:#e0e0e0
+    classDef resultClass fill:#1a4a4a,stroke:#2dd4bf,stroke-width:2px,color:#ffffff
+    classDef outputClass fill:#4a1a4a,stroke:#c084fc,stroke-width:2px,color:#ffffff
+    
+    style EXPLAINERS fill:#0f172a,stroke:#4ade80,stroke-width:2px
+    style COMPARATOR fill:#0f172a,stroke:#fbbf24,stroke-width:2px
+    style EVALUATORS fill:#0f172a,stroke:#c084fc,stroke-width:2px
+    style OUTPUT fill:#0f172a,stroke:#c084fc,stroke-width:2px
+```
+
+
+## Contribution
+Accepting contributions

exact_ai-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "exact-ai"                  # Your package name on PyPI
+version = "0.1.0"                  # Semantic version
+description = "Comprehensive Library for explainable AI (XAI) methods."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Glenn Mathews", email = "glennmathews18@gmail.com" },
+  { name = "Harishankar S M", email = "harishankarsm2004@gmail.com" },
+  { name = "Afzina Sadiq", email = "afzinasadiq180@gmail.com" },
+  { name = "Nandana Murali", email = "nandanalmurali2003@gmail.com" }
+]
+keywords = ["xai", "explainability", "gradcam", "lime", "shap", "ml", "ai"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence"
+]
+requires-python = ">=3.8"
+
+# Runtime dependencies (all required)
+dependencies = [
+    "torch",
+    "torchvision",
+    "numpy",
+    "matplotlib",
+    "pillow",
+    "grad-cam",
+    "lime",
+    "shap"
+]  
+
+[project.urls]
+Homepage = "https://github.com/GurenMashu/E.X.A.C.T-by-GHAN"
+#Documentation = "https://github.com/yourusername/mlmodels/wiki"
+Source = "https://github.com/GurenMashu/E.X.A.C.T-by-GHAN"
+#Tracker = "https://github.com/yourusername/mlmodels/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}   # tells setuptools where your code lives
+
+[tool.setuptools.packages.find]
+where = ["src"]
+exclude = ["tests*"]         # don’t ship tests to PyPI

exact_ai-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exact_ai-0.1.0/src/EXACT/comparators/__init__.py

@@ -0,0 +1 @@
+from .heatmap_comp import HeatmapComparator