README.md

---
base_model: neuralmind/bert-base-portuguese-cased
library_name: transformers
pipeline_tag: token-classification
language:
  - pt
license: mit
tags:
  - speech-acts
  - atos-de-fala
  - dialogue-acts
  - portuguese
  - pt-br
  - bertimbau
  - token-classification
  - bioes
widget:
  - text: "Bom dia! Você pode revisar o relatório? Obrigado."
---

# Atos de Fala PT-BR — classificador de atos de fala (span-level)

Classificador de **atos de fala (speech acts)** para **português brasileiro**, em nível de
**span**: decompõe um texto em trechos contíguos e rotula a intenção de cada um (pedir,
perguntar, agradecer, discordar, prometer…). Até onde sabemos, é o **primeiro modelo aberto**
de atos de fala span-level para PT-BR.

Este é o **modelo completo** (BERTimbau fine-tunado, LoRA já mesclado) — carrega com
`transformers` puro, sem PEFT, e roda no `pipeline("token-classification")`.

- **Base:** `neuralmind/bert-base-portuguese-cased` (BERTimbau), token classifier **BIOES**.
- **Treino:** dados sintéticos destilados de um *teacher* LLM (DeepSeek), balanceados por ato.
- **Demo ao vivo:** https://huggingface.co/spaces/lucianfialho/atos-de-fala-ptbr
- **Coleta colaborativa + dataset aberto:** https://atos-de-fala.vercel.app
- **Código:** https://github.com/lucianfialho/atos-de-fala

## Taxonomia (13 atos → 53 labels BIOES)
`informar · perguntar · concordar · discordar · pedir · sugerir · oferecer · prometer ·
saudar · agradecer · desculpar · despedir · expressar_emocao` (ISO 24617-2 + Searle).

## Como usar
```python
from transformers import pipeline

clf = pipeline("token-classification", model="lucianfialho/atos-de-fala-ptbr",
               aggregation_strategy="none")
print(clf("Bom dia! Você pode revisar o relatório? Obrigado."))
# -> tags BIOES por token: B-saudar … E-saudar | B-pedir … E-pedir | B-agradecer …
```
Agrupe as tags BIOES (B/I/E/S por ato) em spans `(start, end, ato)`.

## Treino
- ~5.000 exemplos sintéticos (frases PT-BR + anotação span-level) gerados por um teacher
  DeepSeek, com balanceamento por ato.
- LoRA nos módulos de atenção (`query`/`value`) + cabeça `classifier`; fp16; loss ≈ 0,30.
  O adapter foi **mesclado** (`merge_and_unload`) neste modelo final.

## Avaliação (honesta)
Eval **sentence-level** no Porttinari (notícias; da Silva et al., PROPOR 2024), ato dominante:
- accuracy ≈ **0,83** · *lenient hit-rate* ≈ **0,94** (coarse, macro-classes).
- **Caveat:** Porttinari é notícia → mede bem `informar`/`perguntar`, mas é praticamente
  **cego** aos 11 atos sociais/diretivos/comissivos. Span-F1 exato ≈ 0 por granularidade
  (gold de frase vs spans). Qualitativamente acerta atos sociais e pedidos indiretos.

## Limitações
- v1: texto de treino **sintético** (sabor "LLM"), carrega o **viés do teacher**.
- Fronteiras de span podem errar por alguns caracteres.
- Falta gold humano conversacional — sendo coletado no jogo aberto para treinar o v2.

## Licença e contato
MIT (respeite a licença do modelo base, BERTimbau). "chomsky" é só o codinome interno; a
base teórica é pragmática (Searle/ISO), não a sintaxe chomskyana.
Contato: lucian@metricasboss.com.br