Metadata-Version: 2.4
Name: aibox-nlp
Version: 0.1.0
Summary: AiBox Natural Language Processing Toolkit.
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: scikit-learn>=1.3.2
Requires-Dist: torch>=2.5.0
Requires-Dist: numpy>=1.23.2
Requires-Dist: pandas>=2.0.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: tqdm>=4.65.0
Requires-Dist: joblib>=1.4.0
Requires-Dist: kagglehub>=0.3.0
Requires-Dist: importlib_resources>=5.0; python_version < "3.9"
Provides-Extra: trees
Requires-Dist: lightgbm>=4.2.0; extra == "trees"
Requires-Dist: catboost>=1.2.2; extra == "trees"
Requires-Dist: xgboost>=2.0.3; extra == "trees"
Provides-Extra: embeddings
Requires-Dist: fasttext>=0.9.2; extra == "embeddings"
Provides-Extra: br
Requires-Dist: pyspellchecker>=0.7.0; extra == "br"
Requires-Dist: spacy>=3.7.0; extra == "br"
Requires-Dist: transformers>=4.37.0; extra == "br"
Requires-Dist: sentence-transformers>=3.0.0; extra == "br"
Requires-Dist: cogroo4py>=0.5.0; extra == "br"
Requires-Dist: language-tool-python>=2.7.0; extra == "br"
Requires-Dist: python-Levenshtein>=0.21.0; extra == "br"
Requires-Dist: polyfuzz>=0.4.0; extra == "br"
Requires-Dist: lexical-diversity>=0.1.0; extra == "br"
Requires-Dist: fuzzywuzzy>=0.18.0; extra == "br"
Requires-Dist: fuzzysearch>=0.7.0; extra == "br"
Requires-Dist: cohmetrix-br-lib>=0.1.2; extra == "br"
Requires-Dist: py-rouge==1.1; extra == "br"
Requires-Dist: TRUNAJOD>=0.1.0; extra == "br"
Requires-Dist: unidecode>=1.3.7; extra == "br"
Requires-Dist: scipy<1.13.0,>=1.11.4; extra == "br"
Requires-Dist: kenlm>=0.3.0; extra == "br"
Requires-Dist: gensim>=4.3.0; extra == "br"
Requires-Dist: nltk>=3.8.1; extra == "br"
Provides-Extra: dev
Requires-Dist: uv>=0.7.0; extra == "dev"
Requires-Dist: pre-commit>=4.0.0; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: lightgbm>=4.2.0; extra == "all"
Requires-Dist: catboost>=1.2.2; extra == "all"
Requires-Dist: xgboost>=2.0.3; extra == "all"
Requires-Dist: fasttext>=0.9.2; extra == "all"
Requires-Dist: pyspellchecker>=0.7.0; extra == "all"
Requires-Dist: spacy>=3.7.0; extra == "all"
Requires-Dist: transformers>=4.37.0; extra == "all"
Requires-Dist: sentence-transformers>=3.0.0; extra == "all"
Requires-Dist: cogroo4py>=0.5.0; extra == "all"
Requires-Dist: language-tool-python>=2.7.0; extra == "all"
Requires-Dist: python-Levenshtein>=0.21.0; extra == "all"
Requires-Dist: polyfuzz>=0.4.0; extra == "all"
Requires-Dist: lexical-diversity>=0.1.0; extra == "all"
Requires-Dist: fuzzywuzzy>=0.18.0; extra == "all"
Requires-Dist: fuzzysearch>=0.7.0; extra == "all"
Requires-Dist: cohmetrix-br-lib>=0.1.2; extra == "all"
Requires-Dist: py-rouge==1.1; extra == "all"
Requires-Dist: TRUNAJOD>=0.1.0; extra == "all"
Requires-Dist: unidecode>=1.3.7; extra == "all"
Requires-Dist: scipy<1.13.0,>=1.11.4; extra == "all"
Requires-Dist: kenlm>=0.3.0; extra == "all"
Requires-Dist: gensim>=4.3.0; extra == "all"
Requires-Dist: nltk>=3.8.1; extra == "all"
Requires-Dist: scikit-learn>=1.3.2; extra == "all"
Requires-Dist: torch>=2.5.0; extra == "all"
Requires-Dist: numpy>=1.23.2; extra == "all"
Requires-Dist: pandas>=2.0.0; extra == "all"
Requires-Dist: platformdirs>=4.0.0; extra == "all"
Requires-Dist: tqdm>=4.65.0; extra == "all"
Requires-Dist: joblib>=1.4.0; extra == "all"
Requires-Dist: kagglehub>=0.3.0; extra == "all"
Requires-Dist: importlib_resources>=5.0; python_version < "3.9" and extra == "all"
Dynamic: license-file

<h1 align="center">
  <br>
  <a href="https://aiboxlab.org/en/"><img src="https://aiboxlab.org/img/logo-aibox.png" alt="AiBox Lab" width="200"></a>
  <br>
  aibox-nlp
  <br>
</h1>

<h4 align="center">Uma biblioteca de Processamento de Linguagem Natural para o Português Brasileiro.</h4>

<p align="center">
  <a href="#funcionalidades">Funcionalidades</a> •
  <a href="#quick-start">Quick Start</a> •
  <a href="#instalação">Instalação</a>
</p>


[![Python](https://img.shields.io/pypi/pyversions/aibox-nlp.svg)](https://badge.fury.io/py/aibox-nlp)
[![PyPI](https://badge.fury.io/py/aibox-nlp.svg)](https://badge.fury.io/py/aibox-nlp)
[![Acesse no Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/aiboxlab/nlp/blob/main/examples/intro.ipynb)

## Funcionalidades

* **315+ características textuais** para o Português Brasileiro
  * CohMetrix-BR, NILCMetrix, Características Gramaticais, e outras!
* Classificadores e Regressores **clássicos**
  * SVM, SVR, XGBoost, CatBoost, LGBM, RF, e outros!
* Classificação e Regressão com **Deep Learning**
  * BERT, LSTM, BI-LSTM, CharCNN, entre outros!
* **Várias Estratégias de Vetorização**
  * Vetorização baseada em Embeddings (nível de sentença, nível de palavra), baseada em TF-IDF, e outros!
* **Reprodutibilidade**
  * Todos experimentos são reprodutíveis, basta indicar uma seed;
* **AutoML**: experimentação automática, selecione um conjunto de dados e a biblioteca procura o melhor classificador/regressor!
  * Backend com `optuna` para otimização de parâmetros e motores de busca;

> [!IMPORTANT]  
> Acesse a [wiki da biblitoeca](https://github.com/aiboxlab/nlp/wiki) para obter mais informações! 

## Quick Start

A biblioteca se baseia em 3 entidades básicas:

* **Dataset**
  * Um dataset representa um conjunto de pares de **textos** e **targets** (classes, ou valores), que devem ser utilizados para resolver um problema de classificação ou regressão.
* **Metric**
  * Uma métrica permite as saídas de um dado estimador com os valores ground-truth do dataset.
  * Por exemplo, Precisão, Revocação e F1-score são métricas para avaliação.
  * Também existem outras métricas como o Kappa e Kappa Vizinho.
* **Pipeline**
  * Representam um conjunto de 3 componentes:
    1. **Estratégia de Vetorização**
       * Converte um texto para sua representação numérica.
       * Alguns exemplos são extratores de características, extração de Embeddings (BERT, FastText, etc), ou TF-IDF.
    2. **Estimador**
       * Representam um algoritmo para classificação/regressão.
       * Alguns exemplos são SVM, SVR, Árvores de Decisão, Redes Neurais.
    3. **Pós-processamento**
       * Estratégia aplicada após a predição pelo estimador.
       * Pode ser utilizada para garantir os limites da saída, ou conversão de regressão para classificação.

Um **Experimento** permite comparar múltiplas **Pipelines** com as **Métricas** escolhidas em um dado **Dataset**. Para construir um experimento, é possível utilizar as classes presentes em `aibox.nlp.experiments` ou utilizar os padrões factory/builder presentes em `aibox.nlp.factory`. Um exemplo básico pode ser encontrado abaixo:

```python
from aibox.nlp.factory.experiment import SimpleExperimentBuilder

# === Construindo um experimento para classificação no Essay-BR ===
# Por simplicidade, vamos instanciar um experimento
#   para comparar algumas abordagens para classificação
#   da competência 1 do dataset Essay-BR.
builder = SimpleExperimentBuilder()

# Inicialmente, vamos definir o dataset
builder.dataset('essayBR',
                extended=False,
                target_competence='C1')

# Vamos definir o tipo do problema
builder.classification()

# Vamos definir a seed randômica
builder.seed(42)

# Depois, vamos definir algumas métricas
#   que devem ser calculadas
builder.add_metric('precision', average='weighted')
builder.add_metric('recall', average='weighted')
builder.add_metric('f1', average='weighted')
builder.add_metric('kappa')
builder.add_metric('neighborKappa')

# Depois, vamos definir qual a métrica
#   que deve ser utilizar para escolher a
#   melhor pipeline
builder.best_criteria('precision', average='weighted')

# Agora, vamos adicionar algumas pipelines baseadas
#   em extração de característica
builder.add_feature_pipeline(
    features=['textualSimplicityBR'],
    estimators=['svm'],
    names=['svm+textual_simplicity'])

builder.add_feature_pipeline(
    features=['readabilityBR'],
    estimators=['svm'],
    names=['svm+readability'])

# Uma vez que tenhamos configurado o experimento,
#   podemos obter uma instância:
experiment = builder.build()

# === Executando o experimento ===
result = experiment.run()

# === Inspecionando os resultados ===
result.best_pipeline.name
# svm+textual_simplicity

result.best_metrics
# {
#   "svm+textual_simplicity": {
#     "Weighted Precision": 0.33119142,
#     "Weighted Recall": 0.5754923,
#     "Weighted F1-score": 0.42042914,
#     "Kappa": 0.0,
#     "Neighbor Kappa": 0.0
#   },
#   "svm+readability": {
#     "Weighted Precision": 0.33119142,
#     "Weighted Recall": 0.5754923,
#     "Weighted F1-score": 0.42042914,
#     "Kappa": 0.0,
#     "Neighbor Kappa": 0.0
#   }
# }
```

Para mais exemplos, acesse a [documentação](examples).


## Instalação

A biblioteca pode ser instalada através do seu gerenciador de pacote preferido (e.g., `pip`, `uv`) ou através do `git clone`:

### 1. Instalando com um gerenciador de pacotes

```bash
# Configurar ambiente virtual
# ...

# Instalar através do pip
$ pip install --upgrade pip uv
$ uv pip install aibox-nlp

# Adicionalmente, instalar dependências opcionais:

# BR contém características para PT-BR
$ pip install aibox-nlp[BR]

# trees contém estimadores baseados em árvore
$ pip install aibox-nlp[trees]

# embeddings contém vetorizadores baseados em modelos
$ pip install aibox-nlp[embeddings]

# Ou, instalar todas:
$ pip install aibox-nlp[all]
```

### 2. Instalando localmente

```bash
# Clonar repositório
$ git clone https://github.com/aiboxlab/nlp

# Acessar diretório
$ cd nlp

# Configurar ambiente virtual
# ...

# Instalar através do pip
$ pip install --upgrade pip uv
$ uv pip install -e .

# Adicionalmente, instalar dependências
#   desejadas opcionais
$ uv pip install -e .[BR]
$ uv pip install -e .[trees]
$ uv pip install -e .[embeddings]

# Também é possível baixar todas as opcionais:
$ uv pip install -e .[all]
```

## License

MIT

---
