Metadata-Version: 2.5
Name: portuguese-openie
Version: 0.1.0
Summary: A unified Python API for Portuguese Open Information Extraction
Project-URL: Homepage, https://github.com/FORMAS/Portuguese-OpenIE
Project-URL: Documentation, https://github.com/FORMAS/Portuguese-OpenIE#readme
Project-URL: Issues, https://github.com/FORMAS/Portuguese-OpenIE/issues
Project-URL: Models, https://huggingface.co/bratao
Project-URL: PyPI, https://pypi.org/project/portuguese-openie/
Author: Bruno Souza Cabral
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: information extraction,nlp,open information extraction,openie,portuguese
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: <3.14,>=3.10
Requires-Dist: json-repair<1,>=0.30
Provides-Extra: all
Requires-Dist: accelerate<2,>=1.0; extra == 'all'
Requires-Dist: huggingface-hub<2,>=0.26; extra == 'all'
Requires-Dist: llama-cpp-python<1,>=0.3; extra == 'all'
Requires-Dist: portnoie[modern]<0.3,>=0.2.1; extra == 'all'
Requires-Dist: sentencepiece<1,>=0.2; extra == 'all'
Requires-Dist: torch<3,>=2.10; extra == 'all'
Requires-Dist: transformers<5,>=4.56.2; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: check-wheel-contents>=0.6; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: pyyaml<7,>=6; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=7.0; extra == 'dev'
Provides-Extra: gguf
Requires-Dist: huggingface-hub<2,>=0.26; extra == 'gguf'
Requires-Dist: llama-cpp-python<1,>=0.3; extra == 'gguf'
Provides-Extra: portnoie
Requires-Dist: portnoie[modern]<0.3,>=0.2.1; extra == 'portnoie'
Provides-Extra: transformers
Requires-Dist: accelerate<2,>=1.0; extra == 'transformers'
Requires-Dist: sentencepiece<1,>=0.2; extra == 'transformers'
Requires-Dist: torch<3,>=2.10; extra == 'transformers'
Requires-Dist: transformers<5,>=4.56.2; extra == 'transformers'
Description-Content-Type: text/markdown

# Portuguese OpenIE

[English version](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/README.en.md)

Biblioteca Python unificada para **Extração Aberta de Informação (OpenIE) em
português**. Ela oferece a mesma API para duas linhas de pesquisa desenvolvidas no
doutorado de Bruno Souza Cabral:

- **PortNOIE**, o extrator neural clássico por rotulagem de sequência, indicado para
  extrações estritamente presentes no texto;
- **modelos generativos** Qwen3OIE, PortugueseT5Oie e Llama-PortOIE3, publicados no
  [Hugging Face](https://huggingface.co/bratao), incluindo OpenIE abstrativa.

O resultado sempre é normalizado para triplas `ARG0`, `V`, `ARG1`, independentemente
do modelo escolhido.

## Instalação

A release suporta Python 3.10–3.13.

Para os modelos do Hugging Face:

```bash
pip install "portuguese-openie[transformers]"
```

O `Llama-PortOIE3` é publicado somente em GGUF e usa um extra separado:

```bash
pip install "portuguese-openie[gguf]"
```

Para o PortNOIE, incluindo o backend PyTorch e o downloader do checkpoint histórico:

```bash
pip install "portuguese-openie[portnoie]"
```

Para instalar todos os backends de uma vez:

```bash
pip install "portuguese-openie[all]"
```

Durante o desenvolvimento local:

```bash
git clone https://github.com/FORMAS/Portuguese-OpenIE.git
cd Portuguese-OpenIE
python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows: .venv\Scripts\activate
python -m pip install -e ".[transformers,dev]"
```

Não é necessário informar diretório de modelo. Os modelos neurais, o GGUF e o
checkpoint histórico do PortNOIE são resolvidos pelo enum e baixados do Hugging Face
na primeira extração. Nenhum wheel inclui pesos. Todos reutilizam cache nas chamadas seguintes.
Cada modelo remoto é fixado por padrão na revisão auditada registrada na biblioteca,
evitando que uma alteração futura em `main` mude silenciosamente os resultados.

## Uso rápido

```python
from portuguese_openie import Model, PortugueseOpenIE

extractor = PortugueseOpenIE(Model.QWEN3_OIE_0_6B)
triples = extractor.extract("A UFBA está localizada em Salvador.")

for triple in triples:
    print(triple.to_dict())
```

Saída normalizada:

```json
{"ARG0": "A UFBA", "V": "está localizada em", "ARG1": "Salvador"}
```

Para manter o texto bruto gerado e os metadados:

```python
result = extractor.extract_with_metadata(
    "A UFBA está localizada em Salvador."
)
print(result.raw_output)
print(result.to_dict())
```

## Linha de comando

```bash
portuguese-openie --model qwen3-oie-0.6b \
  "A Universidade Federal da Bahia fica em Salvador."
```

Também é possível usar entrada padrão:

```bash
echo "A UFBA fica em Salvador." | portuguese-openie --model portuguese-t5-oie-abstractive
```

Para ver todos os aliases:

```bash
portuguese-openie --list-models
```

Após uma primeira execução online, use `--local-files-only` para trabalhar offline.
`--cache-dir` escolhe o cache e `--revision` permite uma revisão explicitamente
diferente da versão auditada; nenhum desses argumentos é obrigatório.

## Modelos disponíveis

| Alias | Tipo | Tamanho | Quando usar |
|---|---|---:|---|
| [`qwen3-oie-0.6b`](https://huggingface.co/bratao/Qwen3OIE-0.6B) | abstrativo | 0,6B | menor modelo e ponto de partida recomendado |
| [`qwen3-oie-4b`](https://huggingface.co/bratao/Qwen3OIE-4B) | abstrativo | 4B | melhor *perfect match* entre os modelos ajustados |
| [`qwen3-oie-8b`](https://huggingface.co/bratao/Qwen3OIE-8B) | abstrativo | 8B | melhor F1 lexical reportado na tese |
| [`portuguese-t5-oie-abstractive`](https://huggingface.co/bratao/PortugueseT5OieAbstractive) | abstrativo | 770M | alternativa menor, validada ponta a ponta no snapshot público |
| [`portuguese-t5-oie`](https://huggingface.co/bratao/PortugueseT5Oie) | experimental | 770M | tarefa e prompt exatos ainda sem proveniência recuperada |
| [`llama-port-oie3`](https://huggingface.co/bratao/Llama-PortOIE3) | extrativo | GGUF 8B | linha generativa Llama 3/PortOIE via llama.cpp |
| [`portnoie`](https://huggingface.co/bratao/PortNOIE) | extrativo | PyTorch | spans do texto; migração moderna experimental do modelo de 2022 |

Detalhes, métricas e identificadores exatos estão no
[guia de modelos](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/docs/MODELS.md).
Veja também o [mapa dos projetos](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/docs/PROJECT_MAP.md), que separa PortNOIE 2022,
GenPtOIE, PTOIE/TransAlign e os datasets.

Os identificadores públicos são `Model.QWEN3_OIE_0_6B`, `Model.QWEN3_OIE_4B`,
`Model.QWEN3_OIE_8B`, `Model.PORTUGUESE_T5_OIE_ABSTRACTIVE`,
`Model.PORTUGUESE_T5_OIE`, `Model.LLAMA_PORT_OIE3` e `Model.PORTNOIE`. Os aliases em
string continuam aceitos para compatibilidade.
O registro também expõe `spec.status`: `validated` indica um teste ponta a ponta do
artefato, `research` indica evidência experimental documentada e `experimental`
indica que ainda há lacunas de proveniência ou equivalência. A CLI mostra esse estado
com `--list-models`.

## Usando o PortNOIE

O PortNOIE fica em um pacote separado por ter implementação e dependências próprias. O
backend padrão reconstrói o grafo em PyTorch atual; texto bruto também usa o modelo
linguístico `pt_core_news_lg`:

```bash
pip install "portnoie[modern]"
```

Na primeira extração, a biblioteca baixa o checkpoint histórico de cerca de **75 MB**
de [`bratao/PortNOIE`](https://huggingface.co/bratao/PortNOIE), na revisão fixada e
verificada por hashes. Para texto bruto, também instala `pt_core_news_lg==3.8.0`
se ausente: a wheel oficial tem **568.207.147 bytes**. A instalação usa `pip` ou
`uv` no Python em execução, com URL e SHA-256 fixados. Chamadas seguintes reutilizam
o checkpoint em cache e o pipeline carregado.

```python
from portuguese_openie import Model, PortugueseOpenIE

extractor = PortugueseOpenIE(Model.PORTNOIE)
print([triple.to_dict() for triple in extractor.extract(
    "Maria escreveu um livro."
)])
# [{'ARG0': 'Maria', 'V': 'escreveu', 'ARG1': 'um livro'}]
```

Veja o [guia do PortNOIE](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/docs/PORTNOIE.md)
para cache, checkpoint local e requisitos.

O checkpoint histórico de referência publicado com o código original
(LSTM 1×384 + Flair, 74,8 MB) é distribuído pelo Hugging Face, não pelo wheel.
O novo backend evita AllenNLP e os dois
downloads Flair externos, mas permanece marcado como experimental até ser comparado
numericamente com o pipeline legado. O melhor experimento BERTimbau Large da tese é
um artefato local diferente, de aproximadamente 1,38 GB, e não é apresentado como se
fosse o mesmo arquivo.

## Escolha entre OpenIE extrativa e abstrativa

**Extrativa** preserva a proveniência: os argumentos e a relação são trechos da frase.
É adequada para auditoria, destaque no texto e aplicações que exigem rastreabilidade.

**Abstrativa** pode resolver referências, normalizar relações e explicitar fatos
implícitos. É mais apropriada para consolidar conhecimento, mas o texto gerado deve ser
validado em aplicações sensíveis.

## Hardware

- `qwen3-oie-0.6b` e os modelos T5 são as opções mais acessíveis.
- Os modelos 4B/8B normalmente exigem GPU ou quantização/offload.
- `llama-port-oie3` baixa `llama3_finetune.gguf` (8,54 GB) e pode executar em CPU;
  configure `n_gpu_layers` para offload em GPU quando suportado.
- `device_map="auto"` e `dtype="auto"` são usados por padrão.
- Entradas Transformers são truncadas em 2.048 tokens por padrão, em linha com o
  comprimento usado no ajuste Qwen; altere com `max_input_tokens` se necessário.
- Para execução offline, faça uma primeira execução online para preencher o cache e
  depois use `local_files_only=True`.

```python
extractor = PortugueseOpenIE(
    Model.QWEN3_OIE_0_6B,
    local_files_only=True,
)
```

## Desenvolvimento e testes

```bash
python -m pip install -e ".[dev]"
ruff check .
pytest
```

Os testes unitários não baixam pesos. A validação ponta a ponta de cada modelo é
separada porque os artefatos variam de aproximadamente 0,6B a 8B parâmetros.
Os testes reais do Qwen3OIE-0.6B e do PortugueseT5OieAbstractive, com revisões e
checksums fixados, estão documentados em
[docs/VALIDATION.md](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/docs/VALIDATION.md).
Mantenedores podem seguir o
[guia de release](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/docs/RELEASING.md)
para publicar no PyPI e no GitHub sem tokens persistentes.

## Limitações

- OpenIE não garante factualidade; modelos generativos podem alucinar.
- A avaliação da tese usa corpora majoritariamente enciclopédicos e jornalísticos.
- O PortNOIE produz relações binárias e não cobre todas as sobreposições ou relações
  n-árias.
- O tempo e a memória dependem do modelo e do hardware.
- Os três repositórios Qwen têm licença Apache-2.0. Os repositórios T5 e
  Llama-PortOIE3 não declaram licença própria; confirme a licença antes de
  redistribuir pesos.
- Os estados de treino publicados para os modelos T5 parecem parciais, portanto a
  proveniência de treino ainda exige confirmação. Isso não invalida o teste E2E do
  snapshot `PortugueseT5OieAbstractive`, marcado `validated`; `PortugueseT5Oie`
  continua `experimental`, e os demais artefatos T5 não têm alias OpenIE nesta versão.
- O extra `[all]` inclui `llama-cpp-python`; em plataformas sem wheel binário
  compatível, a instalação pode exigir CMake e um compilador C/C++.

## Citação

Use o arquivo [CITATION.cff](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/CITATION.cff).
Como referência principal da linha
PortNOIE, cite também o artigo:

> Cabral, Bruno; Souza, Marlo; Claro, Daniela Barreiro. “PortNOIE: A Neural Framework
> for Open Information Extraction for the Portuguese Language.” PROPOR, 2022.

E, para o conjunto completo de modelos e dados:

> Cabral, Bruno Souza. “Evolving Open Information Extraction for Portuguese employing
> Language Models.” Tese de Doutorado, Universidade Federal da Bahia, 2025.

## Licença

O código desta biblioteca usa a
[licença Apache-2.0](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/LICENSE).
Pesos e datasets são
artefatos separados e mantêm as licenças indicadas em seus respectivos cartões ou
repositórios. Consulte o
[NOTICE](https://github.com/FORMAS/Portuguese-OpenIE/blob/main/NOTICE) antes de redistribuir.
