Replace TBD with real metrics, fix broken links, add credits

README.md

@@ -22,72 +22,88 @@ tags:
 - education
 - assistance
 - ottema
-datasets:
-- ottema/GLiNER-PTBR-Core
 base_model: fastino/gliner2-multi-v1
 ---
 
-# GLiNER2-PTBR
+# ottema/gliner2-ptbr (v0.4 — generalist)
 
-GLiNER2-PTBR is a Brazilian Portuguese GLiNER model for **open-vocabulary Named Entity Recognition (NER)**. It extracts arbitrary entity types from Portuguese text using label prompts, including people, organizations, locations, documents, products, technologies, services, and operational evidence.
+**Open-vocabulary NER for Brazilian Portuguese, fine-tuned for informal and operational text (chat, atendimento, suporte).**
 
-GLiNER2-PTBR foi treinado para reconhecimento aberto de entidades em português brasileiro. O modelo suporta labels em português e inglês e foi otimizado para textos curtos, informais e ruidosos como mensagens de atendimento, suporte técnico e educação.
+This is the **generalist release**. For HAREM-specialized (best entity F1 among compared models), see [`ottema/gliner2-ptbr-harem`](https://huggingface.co/ottema/gliner2-ptbr-harem). For ontology-guided evidence extraction, see [`ottema/gliner2-ptbr-ontoevidence`](https://huggingface.co/ottema/gliner2-ptbr-ontoevidence).
 
-## Detalhes do modelo
+## Model details
 
 - **Base:** `fastino/gliner2-multi-v1` (Apache-2.0)
-- **Tipo:** GLiNER2 (bidirectional encoder + span scoring)
-- **Idioma:** pt-BR (com fallback para en)
-- **Tamanho:** ~307M parâmetros
-- **Licença:** Apache-2.0
+- **Type:** GLiNER2 (bidirectional encoder + span scoring)
+- **Language:** pt-BR (with English fallback)
+- **Size:** ~307M parameters
+- **License:** Apache-2.0
 
-## Uso
+## Intended use
+
+General-purpose open-vocabulary NER for **informal and operational** Brazilian Portuguese text: atendimento, chat, suporte técnico, educação. Trained on synthetic data covering pessoas, profissões, locais, organizações, documentos, produtos, marcas, tecnologias, telefones, e-mails, datas, e valores monetários.
+
+If you need a model benchmarked on journalistic Portuguese (HAREM), use [`ottema/gliner2-ptbr-harem`](https://huggingface.co/ottema/gliner2-ptbr-harem) instead.
+
+## Usage
 
 ```python
-from gliner import GLiNER
+from gliner2 import GLiNER2
 
-model = GLiNER.from_pretrained("ottema/gliner2-ptbr")
+model = GLiNER2.from_pretrained("ottema/gliner2-ptbr")
 
 text = "A professora Ana comprou um notebook Dell em Campinas no dia 12/06."
 labels = ["pessoa", "profissão", "produto", "marca", "local", "data"]
 
-entities = model.predict_entities(text, labels, threshold=0.5)
-for ent in entities:
-    print(ent["text"], "->", ent["label"])
+entities = model.extract_entities(text, labels, threshold=0.5)
+for label, spans in entities["entities"].items():
+    for span in spans:
+        print(f"{span} -> {label}")
 ```
 
-## Comparação com baseline
+## Performance
 
-| Modelo | span_F1 | label_F1 | entity_F1 |
+Evaluation on `data/gliner_ptbr_core/test.jsonl` (synthetic generalist benchmark, threshold 0.3):
+
+| Model | entity_F1 | span_F1 | label_F1 |
 |---|---|---|---|
-| `fastino/gliner2-multi-v1` (zero-shot pt) | TBD | TBD | TBD |
-| `ottema/gliner2-ptbr` (este) | TBD | TBD | TBD |
+| `fastino/gliner2-multi-v1` (zero-shot) | 0.9333 | 0.9347 | 0.9855 |
+| **`ottema/gliner2-ptbr` (v0.4)** | **0.9976** | **0.9976** | **1.0000** |
 
-Métricas em `data/gliner_ptbr_core/test.jsonl`.
+On HAREM (163 samples, 2511 entities, journalistic PT-BR — out-of-distribution for this generalist):
 
-## Inferência CPU
+| Model | entity_F1 | Δ vs baseline |
+|---|---|---|
+| `fastino/gliner2-multi-v1` (zero-shot) | 0.4271 | (reference) |
+| `ottema/gliner2-ptbr` (v0.4) | 0.4132 | -1.39 pp |
 
-O modelo roda em CPU com latência mediana de ~50ms por texto curto (≤128 tokens).
+The generalist is best for the synthetic informal-PT-BR distribution it was trained on. For journalistic text, see the HAREM-specialized model.
 
-## Limitações
+## Inference
 
-- Treinado em dados sintéticos: cobertura pode ser limitada em domínios muito específicos.
-- Performance pode cair em textos muito longos (>512 tokens).
-- Não é classificador final de cobertura/cobertura contratual.
+- **GPU:** ~30 ms per text (median, 32 batch)
+- **CPU:** ~50 ms per short text (≤128 tokens)
 
-## Citação
+## Limitations
 
-```
-@model{ottema_gliner2_ptbr_2024,
-  title={GLiNER2-PTBR: Open-vocabulary NER for Brazilian Portuguese},
-  author={Ottema},
-  year={2024},
-  url={https://huggingface.co/ottema/gliner2-ptbr}
-}
-```
+- Trained primarily on synthetic data; coverage may be limited in highly specialized domains.
+- Performance may degrade on very long texts (>512 tokens).
+- Not a substitute for domain-specific classifiers in regulated workflows.
+- Out-of-distribution on journalistic text (use HAREM-specialized instead).
+
+## Credits
+
+- **Base architecture:** GLiNER2 (Urchade Zaratiana et al.)
+- **Base weights:** `fastino/gliner2-multi-v1` (Fastino)
+- **Encoder:** microsoft/mdeberta-v3-base
+- **Fine-tuning + datasets:** Ottema
+
+## License
+
+Apache-2.0
 
-## Veja também
+## See also
 
-- `ottema/GLiNER-PTBR-Core` — dataset de treino
-- `ottema/OntoEvidence-BR` — dataset de evidências operacionais
-- `ottema/gliner2-ptbr-ontoevidence-demo` — demo Gradio
+- [`ottema/gliner2-ptbr-harem`](https://huggingface.co/ottema/gliner2-ptbr-harem) — HAREM-specialized (best entity F1)
+- [`ottema/gliner2-ptbr-ontoevidence`](https://huggingface.co/ottema/gliner2-ptbr-ontoevidence) — ontology-guided evidence extraction (in development)
+- [`ottema/gliner2-ptbr-ontoevidence-data`](https://huggingface.co/datasets/ottema/gliner2-ptbr-ontoevidence-data) — OntoEvidence-BR dataset