Metadata-Version: 2.4
Name: hmb-helpers
Version: 0.1.0
Summary: A comprehensive suite of helper modules for image processing, text generation, PDF handling, and ML workflows.
Home-page: https://github.com/HossamBalaha/HMB-Helpers-Package
Author: Hossam Magdy Balaha
Author-email: h3ossam@gmail.com
License: MIT
Project-URL: Bug Tracker, https://github.com/HossamBalaha/HMB-Helpers-Package/issues
Project-URL: Documentation, https://github.com/HossamBalaha/HMB-Helpers-Package/tree/main/source
Project-URL: Source Code, https://github.com/HossamBalaha/HMB-Helpers-Package
Keywords: image-processing,segmentation,deep-learning,pytorch,tensorflow,nlp,pdf,utilities,computer-vision,medical-imaging,whole-slide-images,yolo,transformers,timm,ultralytics,pydicom,nibabel,openslide
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2
Requires-Dist: pillow>=9.0.0
Provides-Extra: scientific
Requires-Dist: scipy>=1.7.0; extra == "scientific"
Requires-Dist: pandas>=1.3.0; extra == "scientific"
Requires-Dist: scikit-learn>=1.0.0; extra == "scientific"
Requires-Dist: scikit-image>=0.19.0; extra == "scientific"
Provides-Extra: cv
Requires-Dist: opencv-python>=4.5.0; extra == "cv"
Requires-Dist: opencv-contrib-python>=4.5.0; extra == "cv"
Requires-Dist: imagehash>=4.2.0; extra == "cv"
Requires-Dist: brisque>=0.0.17; extra == "cv"
Requires-Dist: simpleitk>=2.0.0; extra == "cv"
Requires-Dist: PyWavelets>=1.1.0; extra == "cv"
Requires-Dist: pyvips>=2.1.0; extra == "cv"
Requires-Dist: patchify>=0.2.0; extra == "cv"
Provides-Extra: pytorch
Requires-Dist: torch>=2.0.0; extra == "pytorch"
Requires-Dist: torchvision>=0.15.0; extra == "pytorch"
Requires-Dist: torchaudio>=2.0.0; extra == "pytorch"
Provides-Extra: tensorflow
Requires-Dist: tensorflow>=2.12.0; extra == "tensorflow"
Requires-Dist: keras>=2.12.0; extra == "tensorflow"
Requires-Dist: tf-keras>=2.12.0; extra == "tensorflow"
Provides-Extra: timm
Requires-Dist: timm>=0.9.0; extra == "timm"
Provides-Extra: transformers
Requires-Dist: transformers>=4.30.0; extra == "transformers"
Requires-Dist: sentence-transformers>=2.2.0; extra == "transformers"
Provides-Extra: ultralytics
Requires-Dist: ultralytics>=8.0.0; extra == "ultralytics"
Provides-Extra: medical
Requires-Dist: pydicom>=2.3.0; extra == "medical"
Requires-Dist: nibabel>=5.0.0; extra == "medical"
Requires-Dist: openslide-python>=1.1.2; extra == "medical"
Provides-Extra: pdf
Requires-Dist: PyMuPDF>=1.22.0; extra == "pdf"
Requires-Dist: PyPDF2>=3.0.0; extra == "pdf"
Requires-Dist: tabula-py>=2.7.0; extra == "pdf"
Requires-Dist: jpype1>=1.4.0; extra == "pdf"
Provides-Extra: nlp
Requires-Dist: nltk>=3.8.0; extra == "nlp"
Requires-Dist: spacy>=3.5.0; extra == "nlp"
Requires-Dist: textblob>=0.17.0; extra == "nlp"
Requires-Dist: gensim>=4.3.0; extra == "nlp"
Requires-Dist: qalsadi>=0.4.0; extra == "nlp"
Requires-Dist: langdetect>=1.0.9; extra == "nlp"
Requires-Dist: gtts>=2.3.0; extra == "nlp"
Requires-Dist: wordcloud>=1.9.0; extra == "nlp"
Requires-Dist: emoji>=2.0.0; extra == "nlp"
Requires-Dist: contractions>=0.1.0; extra == "nlp"
Requires-Dist: textstat>=0.7.0; extra == "nlp"
Requires-Dist: rouge>=1.0.0; extra == "nlp"
Provides-Extra: audio
Requires-Dist: librosa>=0.10.0; extra == "audio"
Requires-Dist: spafe>=0.3.0; extra == "audio"
Requires-Dist: praat-parselmouth>=0.4.0; extra == "audio"
Provides-Extra: ml
Requires-Dist: xgboost>=1.7.0; extra == "ml"
Requires-Dist: catboost>=1.2.0; extra == "ml"
Requires-Dist: lightgbm>=4.0.0; extra == "ml"
Requires-Dist: imbalanced-learn>=0.11.0; extra == "ml"
Requires-Dist: optuna>=3.0.0; extra == "ml"
Requires-Dist: keras-tuner>=1.3.0; extra == "ml"
Requires-Dist: libsvm-official>=3.30.0; extra == "ml"
Requires-Dist: spams-bin>=2.6.0; extra == "ml"
Requires-Dist: skfeature-chappers>=1.0.0; extra == "ml"
Provides-Extra: plotting
Requires-Dist: matplotlib>=3.7.0; extra == "plotting"
Requires-Dist: seaborn>=0.12.0; extra == "plotting"
Requires-Dist: plotly>=5.15.0; extra == "plotting"
Requires-Dist: kaleido>=0.2.0; extra == "plotting"
Requires-Dist: ptitprince>=0.2.0; extra == "plotting"
Requires-Dist: squarify>=0.4.0; extra == "plotting"
Provides-Extra: utils
Requires-Dist: tqdm>=4.65.0; extra == "utils"
Requires-Dist: sympy>=1.11.0; extra == "utils"
Requires-Dist: shapely>=2.0.0; extra == "utils"
Requires-Dist: trimesh>=3.0.0; extra == "utils"
Requires-Dist: pyglet>=1.5.0; extra == "utils"
Requires-Dist: split-folders>=0.5.0; extra == "utils"
Requires-Dist: gputil>=1.4.0; extra == "utils"
Requires-Dist: shutup>=0.2.0; extra == "utils"
Requires-Dist: py7zr>=0.20.0; extra == "utils"
Requires-Dist: rarfile>=4.0.0; extra == "utils"
Requires-Dist: albumentations>=1.3.0; extra == "utils"
Requires-Dist: shap>=0.42.0; extra == "utils"
Requires-Dist: grad-cam>=1.4.0; extra == "utils"
Requires-Dist: statsmodels>=0.14.0; extra == "utils"
Requires-Dist: medmnist>=3.0.0; extra == "utils"
Requires-Dist: huggingface-hub>=0.16.0; extra == "utils"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: sphinx>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.18.0; extra == "docs"
Provides-Extra: all
Requires-Dist: scipy>=1.7.0; extra == "all"
Requires-Dist: pandas>=1.3.0; extra == "all"
Requires-Dist: scikit-learn>=1.0.0; extra == "all"
Requires-Dist: scikit-image>=0.19.0; extra == "all"
Requires-Dist: opencv-python>=4.5.0; extra == "all"
Requires-Dist: opencv-contrib-python>=4.5.0; extra == "all"
Requires-Dist: imagehash>=4.2.0; extra == "all"
Requires-Dist: brisque>=0.0.17; extra == "all"
Requires-Dist: simpleitk>=2.0.0; extra == "all"
Requires-Dist: PyWavelets>=1.1.0; extra == "all"
Requires-Dist: pyvips>=2.1.0; extra == "all"
Requires-Dist: patchify>=0.2.0; extra == "all"
Requires-Dist: torch>=2.0.0; extra == "all"
Requires-Dist: torchvision>=0.15.0; extra == "all"
Requires-Dist: torchaudio>=2.0.0; extra == "all"
Requires-Dist: tensorflow>=2.12.0; extra == "all"
Requires-Dist: keras>=2.12.0; extra == "all"
Requires-Dist: tf-keras>=2.12.0; extra == "all"
Requires-Dist: timm>=0.9.0; extra == "all"
Requires-Dist: transformers>=4.30.0; extra == "all"
Requires-Dist: sentence-transformers>=2.2.0; extra == "all"
Requires-Dist: ultralytics>=8.0.0; extra == "all"
Requires-Dist: pydicom>=2.3.0; extra == "all"
Requires-Dist: nibabel>=5.0.0; extra == "all"
Requires-Dist: openslide-python>=1.1.2; extra == "all"
Requires-Dist: PyMuPDF>=1.22.0; extra == "all"
Requires-Dist: PyPDF2>=3.0.0; extra == "all"
Requires-Dist: tabula-py>=2.7.0; extra == "all"
Requires-Dist: jpype1>=1.4.0; extra == "all"
Requires-Dist: nltk>=3.8.0; extra == "all"
Requires-Dist: spacy>=3.5.0; extra == "all"
Requires-Dist: textblob>=0.17.0; extra == "all"
Requires-Dist: gensim>=4.3.0; extra == "all"
Requires-Dist: qalsadi>=0.4.0; extra == "all"
Requires-Dist: langdetect>=1.0.9; extra == "all"
Requires-Dist: gtts>=2.3.0; extra == "all"
Requires-Dist: wordcloud>=1.9.0; extra == "all"
Requires-Dist: emoji>=2.0.0; extra == "all"
Requires-Dist: contractions>=0.1.0; extra == "all"
Requires-Dist: textstat>=0.7.0; extra == "all"
Requires-Dist: rouge>=1.0.0; extra == "all"
Requires-Dist: librosa>=0.10.0; extra == "all"
Requires-Dist: spafe>=0.3.0; extra == "all"
Requires-Dist: praat-parselmouth>=0.4.0; extra == "all"
Requires-Dist: xgboost>=1.7.0; extra == "all"
Requires-Dist: catboost>=1.2.0; extra == "all"
Requires-Dist: lightgbm>=4.0.0; extra == "all"
Requires-Dist: imbalanced-learn>=0.11.0; extra == "all"
Requires-Dist: optuna>=3.0.0; extra == "all"
Requires-Dist: keras-tuner>=1.3.0; extra == "all"
Requires-Dist: libsvm-official>=3.30.0; extra == "all"
Requires-Dist: spams-bin>=2.6.0; extra == "all"
Requires-Dist: skfeature-chappers>=1.0.0; extra == "all"
Requires-Dist: matplotlib>=3.7.0; extra == "all"
Requires-Dist: seaborn>=0.12.0; extra == "all"
Requires-Dist: plotly>=5.15.0; extra == "all"
Requires-Dist: kaleido>=0.2.0; extra == "all"
Requires-Dist: ptitprince>=0.2.0; extra == "all"
Requires-Dist: squarify>=0.4.0; extra == "all"
Requires-Dist: tqdm>=4.65.0; extra == "all"
Requires-Dist: sympy>=1.11.0; extra == "all"
Requires-Dist: shapely>=2.0.0; extra == "all"
Requires-Dist: trimesh>=3.0.0; extra == "all"
Requires-Dist: pyglet>=1.5.0; extra == "all"
Requires-Dist: split-folders>=0.5.0; extra == "all"
Requires-Dist: gputil>=1.4.0; extra == "all"
Requires-Dist: shutup>=0.2.0; extra == "all"
Requires-Dist: py7zr>=0.20.0; extra == "all"
Requires-Dist: rarfile>=4.0.0; extra == "all"
Requires-Dist: albumentations>=1.3.0; extra == "all"
Requires-Dist: shap>=0.42.0; extra == "all"
Requires-Dist: grad-cam>=1.4.0; extra == "all"
Requires-Dist: statsmodels>=0.14.0; extra == "all"
Requires-Dist: medmnist>=3.0.0; extra == "all"
Requires-Dist: huggingface-hub>=0.16.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HMB Helpers Package

[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/HossamBalaha/HMB-Helpers-Package/blob/main/LICENSE)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0%2B-EE4C2C.svg?logo=pytorch&logoColor=white)](https://pytorch.org/)
[![TensorFlow](https://img.shields.io/badge/TensorFlow-2.0%2B-FF6F00.svg?logo=tensorflow&logoColor=white)](https://www.tensorflow.org/)
[![Tests](https://img.shields.io/badge/tests-530%2B%20passing-brightgreen.svg)](tests/)
[![Code Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)](tests/)
[![Documentation](https://img.shields.io/badge/docs-Sphinx-blue.svg)](https://www.sphinx-doc.org/)
[![Code Style](https://img.shields.io/badge/code%20style-PEP8-blue.svg)](https://www.python.org/dev/peps/pep-0008/)
[![Modules](https://img.shields.io/badge/modules-40%2B-orange.svg)](https://github.com/HossamBalaha/HMB-Helpers-Package/tree/main/HMB)
[![Contributions](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/HossamBalaha/HMB-Helpers-Package/blob/main/CONTRIBUTING.md)
[![Maintenance](https://img.shields.io/badge/maintained-yes-green.svg)](https://github.com/HossamBalaha/HMB-Helpers-Package)
[![Release](https://img.shields.io/badge/release-v0.1.0-blue.svg)](https://github.com/HossamBalaha/HMB-Helpers-Package/releases)

A comprehensive collection of helper modules for image processing, segmentation, deep learning workflows, text/PDF
utilities, and scientific computing in PyTorch, TensorFlow, and beyond.

---

## Table of Contents

- [Motivation](#motivation)
- [Installation](#installation)
- [Dependencies](#dependencies)
- [Features & Modules](#features--modules)
- [Documentation](#documentation)
- [Testing](#testing)
- [Contributing](#contributing)
- [Citation & License](#citation--license)
- [Support & Contact](#support--contact)

---

## Motivation

HMB Helpers Package aims to accelerate research and development in computer vision, deep learning, and text analytics by
providing ready-to-use, well-tested utility modules that simplify common tasks, reduce boilerplate code, and promote
reproducibility in scientific projects.

## Installation

### Minimal Install (Recommended)

Install only core dependencies (`numpy`, `pillow`):

```bash
pip install hmb-helpers
```

### Install with Optional Features

Add only the features you need:

```bash
# Computer vision & PyTorch
pip install "hmb-helpers[cv,pytorch]"

# NLP & text processing
pip install "hmb-helpers[nlp]"

# PDF handling
pip install "hmb-helpers[pdf]"

# Full installation (all optional dependencies)
pip install "hmb-helpers[all]"
```

### Development Install

For modifying the package source:

```bash
git clone https://github.com/HossamBalaha/HMB-Helpers-Package.git
cd HMB-Helpers-Package
pip install -e ".[dev]"
```

### GPU Support (PyTorch CUDA)

The `pytorch` extra installs CPU wheels by default. For CUDA:

```bash
pip install "hmb-helpers[pytorch]"
pip uninstall torch torchvision torchaudio -y
pip install torch==2.7.1+cu128 torchvision==0.22.1+cu128 torchaudio==2.7.1+cu128 \
  --extra-index-url https://download.pytorch.org/whl/cu128
```

Or use the [official PyTorch installer](https://pytorch.org/get-started/locally/) for your platform.

## Dependencies

### Core Dependencies (Always Installed)

- `numpy<2`: Numerical computing
- `pillow>=9.0.0`: Image I/O and basic processing

### Optional Feature Groups

Install only what you need via extras:

| Feature              | Command        | Key Packages                              |
|----------------------|----------------|-------------------------------------------|
| **Scientific Stack** | `[scientific]` | scipy, pandas, scikit-learn, scikit-image |
| **Computer Vision**  | `[cv]`         | opencv-python, imagehash, pyvips          |
| **PyTorch**          | `[pytorch]`    | torch, torchvision, torchaudio            |
| **TensorFlow**       | `[tensorflow]` | tensorflow, keras, tf-keras               |
| **NLP**              | `[nlp]`        | nltk, spacy, transformers, gensim         |
| **PDF**              | `[pdf]`        | PyMuPDF, PyPDF2, tabula-py                |
| **Audio**            | `[audio]`      | librosa, spafe, praat-parselmouth         |
| **Medical Imaging**  | `[medical]`    | pydicom, nibabel, openslide-python        |
| **Classical ML**     | `[ml]`         | xgboost, catboost, lightgbm, optuna       |
| **Visualization**    | `[plotting]`   | matplotlib, seaborn, plotly               |
| **Utilities**        | `[utils]`      | tqdm, albumentations, shap, trimesh       |

See `requirements.txt` for exact version pins used in development.

## Features & Modules

### Core Modules

- **AgentsHelper**: AI agent orchestration and interaction utilities.
- **ArabicTextHelper**: Specialized tools for Arabic text processing and analysis.
- **AttentionMapsHelper**: Tools for generating and visualizing attention maps in deep learning models.
- **AudioHelper**: Audio processing, feature extraction, and manipulation utilities.
- **CompressionsHelper**: Data compression and decompression utilities.
- **DataAugmentationHelper**: Image and data augmentation pipelines.
- **DatasetsHelper**: Utilities to detect, prepare, and validate image classification datasets (train/val/test layouts).
- **EmbeddingsToTextHelper**: Convert between embeddings and text representations for NLP tasks.
- **ExplainabilityHelper**: Model explainability and interpretability (e.g., SHAP analysis).
- **HandCraftedFeatures**: Feature extraction utilities for images and tabular data.
- **ImagesComparisonMetrics**: Image comparison metrics (SSIM, PSNR, MSE, etc.).
- **ImageSegmentationMetrics**: Segmentation evaluation metrics (IoU, Dice, pixel accuracy).
- **ImagesHelper**: Comprehensive image loading, saving, resizing, cropping, and manipulation.
- **ImagesNormalization**: Image normalization, standardization, and color space conversion.
- **ImagesToEmbeddings**: Extract embeddings from images using timm and transformers models.
- **Initializations**: Model and layer initialization helpers for deep learning frameworks.
- **MachineLearningHelper**: ML workflow helpers (data splitting, cross-validation, model selection).
- **MetaheuristicsHelper**: Metaheuristic optimization algorithms (e.g., MRFO).
- **PDFHelper**: PDF reading, extraction, manipulation, and annotation.
- **PerformanceMetrics**: Comprehensive performance metrics for classification and regression.
- **PlotsHelper**: Plotting and visualization helpers (wrappers around matplotlib/seaborn utilities).
- **PyTorchClassificationLosses**: Custom classification loss functions for PyTorch.
- **PyTorchHelper**: PyTorch utilities for models, tensors, device management, and checkpointing.
- **PyTorchModelMemoryProfiler**: Utilities to profile PyTorch model memory usage.
- **PyTorchSegmentationLosses**: Custom segmentation losses (Dice, BCE, DiceBCE, Focal, Tversky, IoU).
- **PyTorchTabularModelsZoo**: Collection of tabular model utilities and reference architectures.
- **PyTorchTrainingPipeline**: Training pipeline helpers for PyTorch experiments (data loaders, trainers, schedulers).
- **PyTorchUNetModelsZoo**: UNet architecture implementations and utilities for PyTorch.
- **StatisticalAnalysisHelper**: Statistical analysis and data exploration tools.
- **StringsHelper**: String manipulation and text processing utilities.
- **TextGenerationMetrics**: Metrics for text generation models (ROUGE, BLEU, METEOR).
- **TextHelper**: Text normalization, cleaning, tokenization, and NLP utilities.
- **TFAttentionBlocks**: TensorFlow/Keras attention mechanism implementations.
- **TFHelper**: TensorFlow/Keras utilities and helpers (Grad-CAM, etc.).
- **TFSegmentationLosses**: TensorFlow/Keras segmentation loss implementations.
- **TFUNetHelper**: TensorFlow/Keras UNet-related helpers and utilities.
- **Utils**: Miscellaneous utilities for file I/O, configuration, and data handling.
- **VectorsHelper**: Vector operations and geometric computations.
- **VideosHelper**: Video processing and frame extraction utilities.
- **VotingHelper**: Ensemble voting methods for machine learning.
- **WSIHelper**: Whole Slide Image (WSI) processing for digital pathology.
- **YOLOHelper**: YOLO model training and inference utilities.

## Documentation

Full documentation is available in the `build/html/` directory after building with Sphinx.

On POSIX systems with make available (Linux, macOS):

```bash
cd source
make html
```

On Windows (cmd.exe) there is a helper `make.bat` at the project root which wraps `sphinx-build`:

```bat
call make.bat html
```

Or view the source documentation files in the `source/` directory:

- Each module has a corresponding `.rst` file with detailed API documentation
- Examples and usage patterns are included in module docstrings
- Complete API reference available at `build/html/index.html`

Examples
--------

The repository includes several example Python scripts under `HMB/Examples` and
platform-specific wrapper scripts grouped under `HMB/Examples/BAT Files` and
`HMB/Examples/SH Files`. There is no single top-level `run_examples` script; use
the per-example wrapper that matches your platform.

Common examples (see `HMB/Examples` for the full list):

- `PyTorch_UNet_Segmentation.py`
- `TF_UNet_Training.py`
- `TF_UNet_EvalPredict.py`
- `Timm_FineTune_Classification.py`
- `Timm_Statistics_Analysis_Ablations.py`
- `Train TF Pretrained Attention Model from DataFrame.py`
- `Explain TF Pretrained Attention Model from DataFrame.py`
- `Machine_Learning_Pipeline.py`

Run a Windows wrapper from the repository root (cmd.exe), for example:

```bat
call "HMB\Examples\BAT Files\Timm_Statistics_Analysis_Ablations.bat"
```

Or run the equivalent POSIX wrapper (bash):

```bash
bash "HMB/Examples/SH Files/Timm_Statistics_Analysis_Ablations.sh"
```

To run an example Python file directly, quote the path if it contains spaces. Examples:

```bat
python "HMB\Examples\Timm_Statistics_Analysis_Ablations.py"
```

```bash
python3 "HMB/Examples/Timm_Statistics_Analysis_Ablations.py"
```

## Testing

The package includes comprehensive unit tests for all modules. Run tests using
the provided test runner or with pytest directly.

Run the bundled test runner:

```bash
# Run all tests.
python tests/run_tests.py

# Run a specific test file.
python tests/run_tests.py Test_ImagesHelper.py
```

Run tests with pytest (recommended if you have pytest installed):

```bash
pytest -q
# or run a specific test file
pytest -q tests/Test_ImagesHelper.py
```

Test coverage includes:

- Unit tests for all core modules
- Edge case validation
- Integration tests for complex workflows
- Performance and regression tests

Current test status: **530+ tests passing**

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -am 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Guidelines

- Write comprehensive docstrings for all functions and classes
- Add unit tests for new functionality
- Follow PEP 8 style guidelines
- Update documentation when adding new features
- Ensure all tests pass before submitting PR

See `CONTRIBUTING.md` in the repository root for more detailed contribution
guidelines (if present): https://github.com/HossamBalaha/HMB-Helpers-Package/blob/main/CONTRIBUTING.md

## Citation & License

This project is licensed under the MIT License. See the LICENSE file for details.

Full license text is available in the repository: https://github.com/HossamBalaha/HMB-Helpers-Package/blob/main/LICENSE

If you use this package in your research, please cite the relevant modules as described in their headers.

### Attribution Requirement

If you use this package in your work, please:

1. Include a copy of the LICENSE file with any distribution
2. Credit the author in documentation or publications:
   ```bibtex
   @software{balaha_hmb_helpers_2026_010,
     author = {Balaha, Hossam Magdy},
     title = {HMB-Helpers-Package},
     year = {2026},
     version = {0.1.0},
     url = {https://github.com/HossamBalaha/HMB-Helpers-Package}
   }

## Support & Contact

For questions, bug reports, or contributions, please contact the author:

- Hossam Magdy Balaha
- Email: h3ossam@gmail.com
- Or open an issue on GitHub

---

Happy coding!
