Metadata-Version: 2.2
Name: smer-visual
Version: 0.0.1
Summary: This package provides means of explainable classification of images with LLM-generated text descriptions, that are then analyzed using the Self Model Entities Related (SMER) explanation technique.
Author-email: Vojtěch Balek <vojta.balek@gmail.com>, Julija Jeršova <poty01@vse.cz>
License: Copyright (c) 2025 Vojtěch Balek, Julija Jeršova, Tomáš Kliegr, Michael Ahmet Ay
        
        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/vojtech-balek/SMERVisual
Project-URL: Bug Tracker, https://github.com/vojtech-balek/SMERVisual/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas==2.2.3
Requires-Dist: numpy==1.26.4
Requires-Dist: scikit-learn
Requires-Dist: torch==2.4.1
Requires-Dist: openai==1.52.2
Requires-Dist: transformers==4.48.0
Requires-Dist: spacy==3.8.2
Requires-Dist: matplotlib==3.9.2
Requires-Dist: seaborn==0.13.2
Requires-Dist: tqdm==4.65.0
Requires-Dist: lime
Requires-Dist: Pillow
Requires-Dist: opencv-python

# **SMERVisual**

SMERVisual is a Python package designed for explainable machine learning using the **SMER method**. It provides an intuitive interface for analyzing image classification models by highlighting key features and generating bounding boxes around important words in source images.

The package supports both **OpenAI API** models and **local language models**, offering flexibility in model selection.

---

## **Installation**
Install SMERVisual using pip:
```sh
pip install smer-image-classification
```

---

## **Features**

### **ImageClassifier**
The `ImageClassifier` class performs **logistic regression-based classification** on image datasets while computing **LIME** and **SMER** values for explainability. Key features include:

- Classification of image datasets using pre-trained language models
- Computation of **LIME and SMER scores** for each word in the dataset
- Visualization of **most important words** for explainability

### **BoundingBoxGenerator**
The `BoundingBoxGenerator` class enhances model interpretability by overlaying bounding boxes on images, highlighting **critical words** identified in classification. It:

- Uses **ImageClassifier output** to detect significant words
- Supports **vision models from OpenAI** and **open-source alternatives**
- Enables **zero-shot object detection** for explainable AI

---

## **Usage Example**
Here's a simple way to use **SMERVisual** for explainable image classification:

```python
from smer_visual import ImageClassifier, BoundingBoxGenerator

# Initialize and train the classifier
classifier = ImageClassifier(model="openai", dataset="path/to/dataset")
classifier()
influential_words = classifier.get_top_words()

# Generate bounding boxes for top words
bbox_generator = BoundingBoxGenerator(data='path/to/dataset', top_words = influential_words, 
                                      local_model_path='path/to/local/model')
bbox_generator("path/to/image.jpg")
```

---

## **Why Use SMERVisual?**

- **Explainable AI** – Provides insight into model decision-making
- **Model-Agnostic** – Compatible with OpenAI APIs and open-source models
- **Zero-Shot Detection** – No additional training data required
- **Easy Integration** – Simple API for seamless use with existing machine learning workflows

---

## **Contributing**
Contributions are welcome. If you’d like to contribute, follow these steps:

1. Fork the repository
2. Create a new branch (`git checkout -b feature-branch`)
3. Commit changes (`git commit -m "Add new feature"`)
4. Push to the branch (`git push origin feature-branch`)
5. Open a pull request

---

## **License**
SMERVisual is released under the **MIT License**.

---
