Metadata-Version: 2.5
Name: dashai-system-one-plugin
Version: 0.1.0
Summary: Local zero-shot text classification for DashAI with the open System One models Laya and GLiNER
Project-URL: Homepage, https://github.com/diegoolguinw/dashai_system_one_plugin
Project-URL: Documentation, https://github.com/diegoolguinw/dashai_system_one_plugin/tree/main/docs
Project-URL: Repository, https://github.com/diegoolguinw/dashai_system_one_plugin
Project-URL: Issues, https://github.com/diegoolguinw/dashai_system_one_plugin/issues
Project-URL: Changelog, https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/CHANGELOG.md
Author-email: Diego Olguin-Wende <dolguin@dim.uchile.cl>
License-Expression: MIT
License-File: LICENSE
Keywords: DashAI,GLiNER,Laya,SystemOne,local-inference,text-classification,zero-shot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: dashai>=0.9.7.post2; extra == 'all'
Requires-Dist: gliner2>=2.1.0; extra == 'all'
Requires-Dist: laya>=0.4.17; extra == 'all'
Requires-Dist: torch>=2.0.0; extra == 'all'
Provides-Extra: dashai
Requires-Dist: dashai>=0.9.7.post2; extra == 'dashai'
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Requires-Dist: twine>=7.0; extra == 'dev'
Provides-Extra: gliner
Requires-Dist: gliner2>=2.1.0; extra == 'gliner'
Requires-Dist: torch>=2.0.0; extra == 'gliner'
Provides-Extra: laya
Requires-Dist: laya>=0.4.17; extra == 'laya'
Requires-Dist: torch>=2.0.0; extra == 'laya'
Description-Content-Type: text/markdown

# dashai-system-one-plugin

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Plugin de modelos abiertos **System One** (decisiones neuronales rápidas y tipadas) para
[DashAI](https://github.com/DashAISoftware/dashAI). Añade a la tarea **Text Classification** de DashAI
modelos que clasifican texto *zero-shot* a partir de los nombres de las clases, con inferencia 100 % local
en CPU y Apple Silicon (MPS).

| Modelo | Checkpoint | En DashAI |
|---|---|---|
| Laya (EN / multilingüe) | `convaiinnovations/laya`, `convaiinnovations/laya-multilingual` | `LayaTextClassifier`, `LayaMultilingualTextClassifier` |
| GLiNER 2.5 Decide (EN / multilingüe) | `fastino/GLiNER2.5-Decide`, `fastino/GLiNER2.5-multi-Decide` | `GLiNERDecideTextClassifier`, `GLiNERMultiDecideTextClassifier` |

## Características

1. **Inferencia local.** Ninguna llamada a APIs externas durante la inferencia. Internet se usa una sola vez
   para descargar paquetes y pesos; con `HF_HUB_OFFLINE=1` el plugin funciona sin conexión (verificado con la
   red denegada a nivel de proceso).
2. **Contrato tipado unificado.** `choice`, `score` y `noul` (`core/contracts.py`). Laya y GLiNER implementan
   `choice`; `score` y `noul` quedan en el contrato para otros backends.
3. **Honestidad sobre las probabilidades.** Solo se exponen probabilidades que el modelo calcula. GLiNER solo
   da la etiqueta, así que entrega one-hot con `calibrated=False`; las de Laya se marcan `calibrated=False`
   porque están sobreconfiadas. Ver [ADR-002](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/adr/ADR-002-unified-contract.md).
4. **Integración con DashAI.** Aparecen en el catálogo de modelos de Text Classification con formulario
   bilingüe (ES/EN). Probado de punta a punta con DashAI 0.10.0.

## Resultados (resumen)

Zero-shot sobre MASSIVE (18 escenarios, 300 muestras por idioma, Apple M1 8 GB). Detalle, intervalos de
confianza, calibración, memoria y límites en [docs/benchmark-results.md](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/benchmark-results.md).

| Modelo | Idioma | Accuracy | Latencia p50 (CPU / MPS) | ECE |
|---|---|---|---|---|
| Laya | en | 0,51 | 215 / 134 ms | 0,38 |
| Laya multilingüe | en / es | 0,53 / 0,44 | 79 / 57 ms | 0,27 / 0,35 |
| GLiNER Decide | en | 0,63 | 253 / 128 ms | n/a (solo etiqueta) |
| GLiNER multi Decide | en / es | 0,53 / 0,44 | 86 / 48 ms | n/a (solo etiqueta) |

Son modelos pequeños para decisiones rápidas, no clasificadores afinados a tu dominio. Entre el 12 % y el 23 %
de las predicciones cambian al invertir el orden de las etiquetas. **Mide sobre una muestra etiquetada tuya
antes de automatizar decisiones.**

## Instalación

Requiere Python ≥ 3.10. Desde el código fuente:

```bash
git clone https://github.com/diegoolguinw/dashai_system_one_plugin.git && cd dashai_system_one_plugin
pip install -e ".[all]"          # DashAI + Laya + GLiNER
# o solo lo que necesites:
pip install -e ".[laya]"         # Laya
pip install -e ".[gliner]"       # GLiNER
pip install -e .                 # contratos y backend de prueba, sin modelos
```

Instálalo **en el mismo entorno que DashAI**.

## Uso en DashAI

1. Inicia DashAI con el intérprete de ese entorno: `python -m DashAI --no-browser`.
2. Sube un dataset con una columna de texto y una categórica (hay uno de ejemplo en
   [`examples/routing_sample.csv`](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/examples/routing_sample.csv)).
3. Crea una sesión de **Text Classification** y elige uno de los modelos de la tabla.
4. Ejecuta y compara métricas con el resto de modelos de DashAI.

Guía paso a paso con capturas: [docs/tutorial.md](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/tutorial.md).

## Uso en Python

```python
from dashai_system_one_plugin.backends import LayaBackend
from dashai_system_one_plugin.core.contracts import DecisionSpec, QuestionSpec

spec = DecisionSpec(
    state="I was charged twice for order 1182. Please refund one of the charges.",
    questions={
        "team": QuestionSpec(
            type="choice",
            instructions="Which team should handle this?",
            criteria={"billing": "Charges and refunds", "shipping": "Deliveries", "returns": "Exchanges"},
        )
    },
)

backend = LayaBackend()
backend.load("convaiinnovations/laya", device="auto")   # descarga los pesos la primera vez
answer = backend.predict(spec).answers["team"]
print(answer.value, answer.probabilities, answer.calibrated)
backend.unload()
```

Más ejemplos: [`examples/real_backends.py`](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/examples/real_backends.py) (Laya y GLiNER) y
[`examples/local_inference.py`](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/examples/local_inference.py) (sin dependencias, con `FakeBackend`).

## Documentación

- [Tutorial](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/tutorial.md) · [Solución de problemas](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/troubleshooting.md)
- [Modelos locales y modo sin conexión](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/local-models.md) · [Compatibilidad](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/compatibility.md)
- [Arquitectura](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/architecture.md) · [Decisiones (ADR)](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/adr/)
- [Protocolo de benchmark](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/benchmark-protocol.md) · [Resultados](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/docs/benchmark-results.md)

## Desarrollo

```bash
pip install -e ".[dev]"
ruff check .
pytest                      # suite unitaria (no descarga modelos)
pytest -m integration       # con checkpoints reales en la caché de Hugging Face
python benchmarks/prepare_data.py && python benchmarks/run_benchmark.py && python benchmarks/report.py
```

Las reglas de colaboración de los agentes del proyecto están en [AGENTS.md](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/AGENTS.md); ver también
[CONTRIBUTING.md](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/CONTRIBUTING.md).

## Limitaciones conocidas

- `batch_size` no acelera: el adaptador procesa las muestras una a una.
- GLiNER no devuelve probabilidades, solo la etiqueta.
- Solo se ha probado en macOS (Apple M1, CPU y MPS); CUDA no se ha verificado.
- Los modelos en español rinden claramente peor que en inglés en el benchmark.

## Licencia

El código se distribuye bajo la licencia [MIT](https://github.com/diegoolguinw/dashai_system_one_plugin/blob/main/LICENSE). Los pesos de los modelos tienen su propia licencia
(todos Apache-2.0 al momento de escribir esto).
