Metadata-Version: 2.4
Name: Twotuples
Version: 2.0.0
Summary: Libreria para clasificar texto
Home-page: https://github.com/crgv7/TwotuplesClasificator
Author: Carlos Garcia Vargas
Author-email: 
License: MIT
Description-Content-Type: text/markdown
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: sentiment-analysis-spanish
Requires-Dist: tqdm
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: requires-dist
Dynamic: summary

# Twotuples: Clasificador de Texto con Lógica Difusa (High-Speed Lexicon Edition)

[![GitHub Repo](https://img.shields.io/badge/GitHub-Repository-blue?logo=github)](https://github.com/crgv7/TwotuplesClasificator)

La librería **twotuples** tiene como objetivo clasificar opiniones o comentarios en tres categorías: positivo (POS), negativo (NEG) o neutral (NEU). 

A diferencia de las librerías basadas en pesados modelos de Deep Learning, **Twotuples** es un "Machete Láser": un motor híbrido multi-agente extremadamente rápido y ligero que combina lógica semántica, probabilidad estadística y diccionarios mediante **Lógica Difusa (Fuzzy Logic)**.

En su versión 2.0.0, la arquitectura ha sido validada con un dataset de 21,847 comentarios, logrando resultados consistentes procesando miles de comentarios en segundos sin necesidad de GPU.

## Características Principales
- **Arquitectura Triunvirato Multi-Agente:**
  - `Sentiment_Spanish`: IA de sentimientos optimizada para lenguaje natural.
  - `Lexicon_JSON`: Diccionario experto nativo con soporte para negaciones, intensificadores (muy, poco) y contrastes (pero).
  - `Senticon_XML`: Diccionario semántico estructurado en XML basado en el léxico Elhuyar, que complementa la precisión en ciertas palabras clave.
- **Lógica de Bigramas (NUEVO):** El sistema escanea y "consume" frases compuestas ("nada_mal", "pesimo_servicio") antes de procesar palabras individuales, elevando drásticamente el entendimiento contextual.
- **Velocidad Extrema:** Ejecución puramente secuencial en CPU, ideal para entornos de producción de alto volumen.
- **Decisión Difusa:** Los tres agentes votan (30%, 40%, 30%) y el resultado se mapea en un espacio difuso (2-tuplas) para la decisión final.

## Instalación

Puedes instalar la librería directamente desde PyPI. 

```bash
pip install Twotuples==2.0.0
```

> [!TIP]
> **Rendimiento:** A diferencia de versiones iniciales, Twotuples 1.9.8 es ultra-ligero. No requiere descargar modelos base de `transformers` masivos, por lo que puede correr perfectamente en cualquier entorno local.

## Uso Rápido (Quickstart)

### 1. Clasificación Difusa de Opiniones

Esta es la funcionalidad principal. Toma un archivo Excel con una columna de textos, ejecuta los tres agentes, aplica la lógica difusa y devuelve archivos Excel con las predicciones.

```python
from Twotuples import Twotuples

# 1. Definimos la ruta al archivo y la columna a analizar
archivo_excel = "data.xlsx"
nombre_columna = "Opinion"

# 2. Ejecutamos el clasificador
Twotuples.difuso_clasificator(data=archivo_excel, ColumnName=nombre_columna)
```

**Archivos generados tras la ejecución:**
- `score.xlsx`: **Archivo final recomendado.** Contiene el texto original y la columna `Clasicacion_Difusa` con las etiquetas finales (POS, NEG, NEU), junto con las predicciones individuales de cada agente.

### 2. Evaluación de Métricas

Si tu archivo Excel original contiene una columna con las etiquetas reales o esperadas (Ground Truth), puedes comparar las predicciones del triunvirato con la realidad utilizando la función `Metric`.

```python
# Reporte de métricas (Precision, Recall, F1-Score)
# Sustituye 'Etiqueta_Real' por el nombre de la columna que contiene los valores esperados.
Twotuples.Metric(etiqueta='Etiqueta_Real', metric='ClassificationReport', sorter='difuse', ClassNumber=3)

# Mostrar la matriz de confusión de forma gráfica
Twotuples.Metric(etiqueta='Etiqueta_Real', metric='ConfusionMatrix', sorter='difuse', ClassNumber=3)
```

## Referencia de la API

### `Twotuples.difuso_clasificator(data, ColumnName)`
Ejecuta la predicción sobre un dataset completo.
- **`data`** *(str)*: Ruta al archivo `.xlsx` que contiene los datos.
- **`ColumnName`** *(str)*: Nombre de la columna en el Excel que contiene el texto a analizar.

### `Twotuples.Metric(etiqueta, metric='ClassificationReport', sorter='difuse', ClassNumber=3)`
Evalúa y visualiza el rendimiento de las predicciones.
- **`etiqueta`** *(str)*: Nombre de la columna con las clasificaciones manuales/reales.
- **`metric`** *(str, opcional)*: Tipo de visualización. Opciones: `'ClassificationReport'` o `'ConfusionMatrix'`.
- **`sorter`** *(str, opcional)*: Define qué modelo evaluar individualmente. Opciones: `'difuse'`, `'lexicon'`, `'sentiment'`, `'senticon'`. Por defecto es `'difuse'` (Consenso total).
- **`ClassNumber`** *(int, opcional)*: Cantidad de clases de salida. Valores válidos son `2` o `3`. Por defecto es `3`.

## Tecnologías Usadas
* **Lógica Fuzzy 2-Tuple**: Implementación matemática nativa para ponderación de votaciones.
* **Sentiment-Analysis-Spanish**: Base de IA pre-entrenada para análisis contextual.
* **scikit-learn**: Generación de métricas y evaluación de modelos.
* **Otras dependencias**: `pandas`, `numpy`, `matplotlib`, `tqdm`.
