torchtextclassifiers 0.0.1__tar.gz

torchtextclassifiers-0.0.1/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.3
+Name: torchtextclassifiers
+Version: 0.0.1
+Summary: An implementation of the https://github.com/facebookresearch/fastText supervised learning algorithm for text classification using Pytorch.
+Keywords: fastText,text classification,NLP,automatic coding,deep learning
+Author: Tom Seimandi, Julien Pramil, Meilame Tayebjee, Cédric Couralet
+Author-email: Tom Seimandi <tom.seimandi@gmail.com>, Julien Pramil <julien.pramil@insee.fr>, Meilame Tayebjee <meilame.tayebjee@insee.fr>, Cédric Couralet <cedric.couralet@insee.fr>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Dist: numpy>=1.26.4
+Requires-Dist: pytorch-lightning>=2.4.0
+Requires-Dist: unidecode ; extra == 'explainability'
+Requires-Dist: nltk ; extra == 'explainability'
+Requires-Dist: captum ; extra == 'explainability'
+Requires-Dist: unidecode ; extra == 'preprocess'
+Requires-Dist: nltk ; extra == 'preprocess'
+Requires-Python: >=3.11
+Provides-Extra: explainability
+Provides-Extra: preprocess
+Description-Content-Type: text/markdown
+
+# torchTextClassifiers
+
+A unified, extensible framework for text classification built on [PyTorch](https://pytorch.org/) and [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/).
+
+## 🚀 Features
+
+- **Unified API**: Consistent interface for different classifier wrappers
+- **Extensible**: Easy to add new classifier implementations through wrapper pattern
+- **FastText Support**: Built-in FastText classifier with n-gram tokenization
+- **Flexible Preprocessing**: Each classifier can implement its own text preprocessing approach
+- **PyTorch Lightning**: Automated training with callbacks, early stopping, and logging
+
+
+## 📦 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/InseeFrLab/torchTextClassifiers.git
+cd torchtextClassifiers
+
+# Install with uv (recommended)
+uv sync
+
+# Or install with pip
+pip install -e .
+```
+
+## 🎯 Quick Start
+
+### Basic FastText Classification
+
+```python
+import numpy as np
+from torchTextClassifiers import create_fasttext
+
+# Create a FastText classifier
+classifier = create_fasttext(
+    embedding_dim=100,
+    sparse=False,
+    num_tokens=10000,
+    min_count=2,
+    min_n=3,
+    max_n=6,
+    len_word_ngrams=2,
+    num_classes=2
+)
+
+# Prepare your data
+X_train = np.array([
+    "This is a positive example",
+    "This is a negative example",
+    "Another positive case",
+    "Another negative case"
+])
+y_train = np.array([1, 0, 1, 0])
+
+X_val = np.array([
+    "Validation positive",
+    "Validation negative"
+])
+y_val = np.array([1, 0])
+
+# Build the model
+classifier.build(X_train, y_train)
+
+# Train the model
+classifier.train(
+    X_train, y_train, X_val, y_val,
+    num_epochs=50,
+    batch_size=32,
+    patience_train=5,
+    verbose=True
+)
+
+# Make predictions
+X_test = np.array(["This is a test sentence"])
+predictions = classifier.predict(X_test)
+print(f"Predictions: {predictions}")
+
+# Validate on test set
+accuracy = classifier.validate(X_test, np.array([1]))
+print(f"Accuracy: {accuracy:.3f}")
+```
+
+### Custom Classifier Implementation
+
+```python
+import numpy as np
+from torchTextClassifiers import torchTextClassifiers
+from torchTextClassifiers.classifiers.simple_text_classifier import SimpleTextWrapper, SimpleTextConfig
+
+# Example: TF-IDF based classifier (alternative to tokenization)
+config = SimpleTextConfig(
+    hidden_dim=128,
+    num_classes=2,
+    max_features=5000,
+    learning_rate=1e-3,
+    dropout_rate=0.2
+)
+
+# Create classifier with TF-IDF preprocessing
+wrapper = SimpleTextWrapper(config)
+classifier = torchTextClassifiers(wrapper)
+
+# Text data
+X_train = np.array(["Great product!", "Terrible service", "Love it!"])
+y_train = np.array([1, 0, 1])
+
+# Build and train
+classifier.build(X_train, y_train)
+# ... continue with training
+```
+
+
+### Training Customization
+
+```python
+# Custom PyTorch Lightning trainer parameters
+trainer_params = {
+    'accelerator': 'gpu',
+    'devices': 1,
+    'precision': 16,  # Mixed precision training
+    'gradient_clip_val': 1.0,
+}
+
+classifier.train(
+    X_train, y_train, X_val, y_val,
+    num_epochs=100,
+    batch_size=64,
+    patience_train=10,
+    trainer_params=trainer_params,
+    verbose=True
+)
+```
+
+## 🔬 Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=torchTextClassifiers
+
+# Run specific test file
+uv run pytest tests/test_torchTextClassifiers.py -v
+```
+
+
+## 📚 Examples
+
+See the [examples/](examples/) directory for:
+- Basic text classification
+- Multi-class classification
+- Mixed features (text + categorical)
+- Custom classifier implementation
+- Advanced training configurations
+
+
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

torchtextclassifiers-0.0.1/README.md

@@ -0,0 +1,165 @@
+# torchTextClassifiers
+
+A unified, extensible framework for text classification built on [PyTorch](https://pytorch.org/) and [PyTorch Lightning](https://lightning.ai/docs/pytorch/stable/).
+
+## 🚀 Features
+
+- **Unified API**: Consistent interface for different classifier wrappers
+- **Extensible**: Easy to add new classifier implementations through wrapper pattern
+- **FastText Support**: Built-in FastText classifier with n-gram tokenization
+- **Flexible Preprocessing**: Each classifier can implement its own text preprocessing approach
+- **PyTorch Lightning**: Automated training with callbacks, early stopping, and logging
+
+
+## 📦 Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/InseeFrLab/torchTextClassifiers.git
+cd torchtextClassifiers
+
+# Install with uv (recommended)
+uv sync
+
+# Or install with pip
+pip install -e .
+```
+
+## 🎯 Quick Start
+
+### Basic FastText Classification
+
+```python
+import numpy as np
+from torchTextClassifiers import create_fasttext
+
+# Create a FastText classifier
+classifier = create_fasttext(
+    embedding_dim=100,
+    sparse=False,
+    num_tokens=10000,
+    min_count=2,
+    min_n=3,
+    max_n=6,
+    len_word_ngrams=2,
+    num_classes=2
+)
+
+# Prepare your data
+X_train = np.array([
+    "This is a positive example",
+    "This is a negative example",
+    "Another positive case",
+    "Another negative case"
+])
+y_train = np.array([1, 0, 1, 0])
+
+X_val = np.array([
+    "Validation positive",
+    "Validation negative"
+])
+y_val = np.array([1, 0])
+
+# Build the model
+classifier.build(X_train, y_train)
+
+# Train the model
+classifier.train(
+    X_train, y_train, X_val, y_val,
+    num_epochs=50,
+    batch_size=32,
+    patience_train=5,
+    verbose=True
+)
+
+# Make predictions
+X_test = np.array(["This is a test sentence"])
+predictions = classifier.predict(X_test)
+print(f"Predictions: {predictions}")
+
+# Validate on test set
+accuracy = classifier.validate(X_test, np.array([1]))
+print(f"Accuracy: {accuracy:.3f}")
+```
+
+### Custom Classifier Implementation
+
+```python
+import numpy as np
+from torchTextClassifiers import torchTextClassifiers
+from torchTextClassifiers.classifiers.simple_text_classifier import SimpleTextWrapper, SimpleTextConfig
+
+# Example: TF-IDF based classifier (alternative to tokenization)
+config = SimpleTextConfig(
+    hidden_dim=128,
+    num_classes=2,
+    max_features=5000,
+    learning_rate=1e-3,
+    dropout_rate=0.2
+)
+
+# Create classifier with TF-IDF preprocessing
+wrapper = SimpleTextWrapper(config)
+classifier = torchTextClassifiers(wrapper)
+
+# Text data
+X_train = np.array(["Great product!", "Terrible service", "Love it!"])
+y_train = np.array([1, 0, 1])
+
+# Build and train
+classifier.build(X_train, y_train)
+# ... continue with training
+```
+
+
+### Training Customization
+
+```python
+# Custom PyTorch Lightning trainer parameters
+trainer_params = {
+    'accelerator': 'gpu',
+    'devices': 1,
+    'precision': 16,  # Mixed precision training
+    'gradient_clip_val': 1.0,
+}
+
+classifier.train(
+    X_train, y_train, X_val, y_val,
+    num_epochs=100,
+    batch_size=64,
+    patience_train=10,
+    trainer_params=trainer_params,
+    verbose=True
+)
+```
+
+## 🔬 Testing
+
+Run the test suite:
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with coverage
+uv run pytest --cov=torchTextClassifiers
+
+# Run specific test file
+uv run pytest tests/test_torchTextClassifiers.py -v
+```
+
+
+## 📚 Examples
+
+See the [examples/](examples/) directory for:
+- Basic text classification
+- Multi-class classification
+- Mixed features (text + categorical)
+- Custom classifier implementation
+- Advanced training configurations
+
+
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

torchtextclassifiers-0.0.1/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "torchtextclassifiers"
+description = "An implementation of the https://github.com/facebookresearch/fastText supervised learning algorithm for text classification using Pytorch."
+authors = [
+    { name = "Tom Seimandi", email = "tom.seimandi@gmail.com" },
+    { name = "Julien Pramil", email = "julien.pramil@insee.fr" },
+    { name = "Meilame Tayebjee", email = "meilame.tayebjee@insee.fr" },
+    { name = "Cédric Couralet", email = "cedric.couralet@insee.fr" },
+]
+readme = "README.md"
+repository = "https://github.com/InseeFrLab/torchTextClassifiers"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+keywords = ["fastText", "text classification", "NLP", "automatic coding", "deep learning"]
+dependencies = [
+    "numpy>=1.26.4",
+    "pytorch-lightning>=2.4.0",
+]
+requires-python = ">=3.11"
+version="0.0.1"
+
+
+[dependency-groups]
+dev = [
+  "pytest >=8.1.1,<9",
+  "pandas",
+  "scikit-learn",
+  "nltk",
+  "unidecode",
+  "captum",
+  "pyarrow"
+]
+docs = [
+  "sphinx>=5.0.0",
+  "sphinx-rtd-theme>=1.2.0",
+  "sphinx-autodoc-typehints>=1.19.0",
+  "sphinxcontrib-napoleon>=0.7",
+  "sphinx-copybutton>=0.5.0",
+  "myst-parser>=0.18.0",
+  "sphinx-design>=0.3.0"
+]
+
+[project.optional-dependencies]
+explainability = ["unidecode", "nltk", "captum"]
+preprocess =     ["unidecode", "nltk"]
+
+[build-system]
+requires = ["uv_build>=0.8.3,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+
+
+[tool.uv.build-backend]
+module-name="torchTextClassifiers"
+module-root = ""
+
+
+

torchtextclassifiers-0.0.1/torchTextClassifiers/__init__.py

@@ -0,0 +1,68 @@
+"""torchTextClassifiers: A unified framework for text classification.
+
+This package provides a generic, extensible framework for building and training
+different types of text classifiers. It currently supports FastText classifiers
+with a clean API for building, training, and inference.
+
+Key Features:
+- Unified API for different classifier types
+- Built-in support for FastText classifiers
+- PyTorch Lightning integration for training
+- Extensible architecture for adding new classifier types
+- Support for both text-only and mixed text/categorical features
+
+Quick Start:
+    >>> from torchTextClassifiers import create_fasttext
+    >>> import numpy as np
+    >>> 
+    >>> # Create classifier
+    >>> classifier = create_fasttext(
+    ...     embedding_dim=100,
+    ...     sparse=False,
+    ...     num_tokens=10000,
+    ...     min_count=2,
+    ...     min_n=3,
+    ...     max_n=6,
+    ...     len_word_ngrams=2,
+    ...     num_classes=2
+    ... )
+    >>> 
+    >>> # Prepare data
+    >>> X_train = np.array(["positive text", "negative text"])
+    >>> y_train = np.array([1, 0])
+    >>> X_val = np.array(["validation text"])
+    >>> y_val = np.array([1])
+    >>> 
+    >>> # Build and train
+    >>> classifier.build(X_train, y_train)
+    >>> classifier.train(X_train, y_train, X_val, y_val, num_epochs=10, batch_size=32)
+    >>> 
+    >>> # Predict
+    >>> predictions = classifier.predict(np.array(["new text sample"]))
+"""
+
+from .torchTextClassifiers import torchTextClassifiers
+
+# Convenience imports for FastText
+try:
+    from .classifiers.fasttext.core import FastTextFactory
+    
+    # Expose FastText convenience methods at package level for easy access
+    create_fasttext = FastTextFactory.create_fasttext
+    build_fasttext_from_tokenizer = FastTextFactory.build_from_tokenizer
+    
+except ImportError:
+    # FastText module not available - define placeholder functions
+    def create_fasttext(*args, **kwargs):
+        raise ImportError("FastText module not available")
+    
+    def build_fasttext_from_tokenizer(*args, **kwargs):
+        raise ImportError("FastText module not available")
+
+__all__ = [
+    "torchTextClassifiers",
+    "create_fasttext",
+    "build_fasttext_from_tokenizer",
+]
+
+__version__ = "1.0.0"

torchtextclassifiers-0.0.1/torchTextClassifiers/classifiers/base.py

@@ -0,0 +1,83 @@
+from typing import Optional, Union, Type, List, Dict, Any
+from dataclasses import dataclass, field, asdict
+from abc import ABC, abstractmethod
+import numpy as np
+
+class BaseClassifierConfig(ABC):
+    """Abstract base class for classifier configurations."""
+    
+    @abstractmethod
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert configuration to dictionary."""
+        pass
+    
+    @classmethod
+    @abstractmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "BaseClassifierConfig":
+        """Create configuration from dictionary."""
+        pass
+
+class BaseClassifierWrapper(ABC):
+    """Abstract base class for classifier wrappers.
+    
+    Each classifier wrapper is responsible for its own text processing approach.
+    Some may use tokenizers, others may use different preprocessing methods.
+    """
+    
+    def __init__(self, config: BaseClassifierConfig):
+        self.config = config
+        self.pytorch_model = None
+        self.lightning_module = None
+        self.trained: bool = False
+        self.device = None
+        # Remove tokenizer from base class - it's now wrapper-specific
+    
+    @abstractmethod
+    def prepare_text_features(self, training_text: np.ndarray) -> None:
+        """Prepare text features for the classifier.
+        
+        This could involve tokenization, vectorization, or other preprocessing.
+        Each classifier wrapper implements this according to its needs.
+        """
+        pass
+    
+    @abstractmethod
+    def _build_pytorch_model(self) -> None:
+        """Build the PyTorch model."""
+        pass
+    
+    @abstractmethod
+    def _check_and_init_lightning(self, **kwargs) -> None:
+        """Initialize Lightning module."""
+        pass
+    
+    @abstractmethod
+    def predict(self, X: np.ndarray, **kwargs) -> np.ndarray:
+        """Make predictions."""
+        pass
+    
+    @abstractmethod
+    def validate(self, X: np.ndarray, Y: np.ndarray, **kwargs) -> float:
+        """Validate the model."""
+        pass
+    
+    @abstractmethod
+    def create_dataset(self, texts: np.ndarray, labels: np.ndarray, categorical_variables: Optional[np.ndarray] = None):
+        """Create dataset for training/validation."""
+        pass
+    
+    @abstractmethod
+    def create_dataloader(self, dataset, batch_size: int, num_workers: int = 0, shuffle: bool = True):
+        """Create dataloader from dataset."""
+        pass
+    
+    @abstractmethod
+    def load_best_model(self, checkpoint_path: str) -> None:
+        """Load best model from checkpoint."""
+        pass
+    
+    @classmethod
+    @abstractmethod
+    def get_config_class(cls) -> Type[BaseClassifierConfig]:
+        """Return the configuration class for this wrapper."""
+        pass

torchtextclassifiers-0.0.1/torchTextClassifiers/classifiers/fasttext/__init__.py

@@ -0,0 +1,25 @@
+"""FastText classifier package.
+
+Provides FastText text classification with PyTorch Lightning integration.
+This folder contains 4 main files:
+- core.py: Configuration, losses, and factory methods
+- tokenizer.py: NGramTokenizer implementation
+- model.py: PyTorch model, Lightning module, and dataset
+- wrapper.py: High-level wrapper interface
+"""
+
+from .core import FastTextConfig, OneVsAllLoss, FastTextFactory
+from .tokenizer import NGramTokenizer
+from .model import FastTextModel, FastTextModule, FastTextModelDataset
+from .wrapper import FastTextWrapper
+
+__all__ = [
+    "FastTextConfig",
+    "OneVsAllLoss", 
+    "FastTextFactory",
+    "NGramTokenizer",
+    "FastTextModel",
+    "FastTextModule", 
+    "FastTextModelDataset",
+    "FastTextWrapper",
+]