thiagoambiel/sonar_municipal_ptt5_ementa2action

Sonar Municipal — PTT5 base Ementa→Ação

T5 model (PTT5 base, 220M params) fine-tuned for semantic textualization of Brazilian municipal legislative bill summaries (ementas) into a direct, imperative action form (ação). Fine-tuned with LoRA (PEFT) and distributed as a merged checkpoint — no peft dependency required at inference time. Base: unicamp-dl/ptt5-base-portuguese-vocab (Apache-2.0).

Companion to the ICMC-USP undergraduate thesis "Mineração de Dados e Busca Semântica Aplicadas à Análise de Projetos de Lei Municipais" (Sonar Municipal project). Archival mirror with DOI: 10.5281/zenodo.20564326.

Model description

Converts Portuguese municipal bill ementas into action-form summaries suitable for semantic search, policy diffusion analysis, and topic clustering. Key behaviors learned during fine-tuning:

• Semantic rewriting (not merely syntactic): e.g., "Institui o Projeto Criança Cidadã para emissão de registro de nascimento dentro das maternidades públicas" → "Emitir registros de nascimento dentro das maternidades públicas" (the action is the underlying intervention, not the legal instrument of creating a project).
• Removal of juridical boilerplate (E DÁ OUTRAS PROVIDÊNCIAS, Dispõe sobre, Autoriza o Poder Executivo a, etc.).
• Typographic normalization (ALL-CAPS → sentence case, preserving technical acronyms like LIBRAS, SUS, TEA, CIPED, Castramóvel).
• Toponym generalization (MUNICÍPIO DE MARABÁ → município), except where the locale is policy-relevant (e.g., bairro São Félix preserved).
• Compression of conditional clauses into direct verb-object phrases (infinitive verb + direct object).

Model details

Attribute	Value
Developed by	Thiago Ambiel (ICMC-USP)
Supervised by	Prof. André C. P. L. F. de Carvalho (ICMC-USP)
Supported by	AI4PEP — Artificial Intelligence for Public Health Emergency Preparedness network (acknowledgement only; no structured grant identifier)
Model type	T5 seq2seq (merged LoRA fine-tune; distributed as full checkpoint)
Language	Portuguese (pt-BR)
License	Apache-2.0 (inherits from base PTT5)
Finetuned from	unicamp-dl/ptt5-base-portuguese-vocab (220M params)
Tokenizer	Redistributed verbatim from the base under Apache-2.0

Uses

Direct use

• Textualizing ementas of Brazilian municipal PLs into action form for semantic search and policy clustering.
• Pre-processing input for dense retrievers (the action form consistently outperforms the raw ementa as the encoded text — see the benchmark in the dataset companion).

Downstream use

• Feature engineering for legislative-text classifiers, topic models, and diffusion analyses.
• Foundation for further fine-tuning on related Portuguese legal rewriting tasks.

Out-of-scope use

• Legal advice or court-ready summarization — output may drop juridically relevant nuance.
• Automated decision-making on bill merit — the model summarizes intent, not legality, constitutionality, or impact.
• Non-municipal Portuguese legal text (federal/state bills, judicial decisions) without revalidation.
• European Portuguese — training data is exclusively Brazilian.

Bias, risks, and limitations

• Trained on a modest set of 999 supervised pairs stratified by UF and year; coverage of policy subdomains is uneven.
• Seed labels generated by GPT-5.1-Thinking with manual quality control of all pairs by the thesis author (correcting recurring error patterns: polarity reversals, fantasy-name preservation, object omission, juridical sense shifts) — the model may carry biases of that upstream model toward simplification or particular normative framings.
• Distribution across Brazilian states is non-uniform; smaller municipalities and certain UFs are under-represented.
• Action form may simplify intentional juridical nuance present in the original ementa.

Recommendations

• Validate outputs before any operational use (e.g., supporting prefectural decisions, drafting policy briefs).
• Do not use as the sole source for any legally consequential decision.

How to get started

import torch
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer, GenerationConfig

torch.manual_seed(42)

REPO = "thiagoambiel/sonar_municipal_ptt5_ementa2action"
INSTR_PROMPT = (
    "Converta a ementa de projeto de lei em uma recomendação de ação "
    "imperativa, curta e fiel ao texto; {texto}\nSaída:"
)

model = AutoModelForSeq2SeqLM.from_pretrained(REPO).eval()
tokenizer = AutoTokenizer.from_pretrained(REPO)
gen_config = GenerationConfig.from_pretrained(REPO)  # generation_config.json

ementa = "DISPÕE SOBRE A IMPLANTAÇÃO DE ESTUFAS COM HORTAS PRODUZIDAS COM GARRAFAS PET NAS ESCOLAS MUNICIPAIS DE MARABÁ E DA OUTRAS PROVIDÊNCIAS."
prompt = INSTR_PROMPT.format(texto=ementa.lower())
inputs = tokenizer(prompt, return_tensors="pt", truncation=True, max_length=256)
out = model.generate(**inputs, generation_config=gen_config)
print(tokenizer.decode(out[0], skip_special_tokens=True))
# → "Instalar estufas com hortas produzidas com garrafas pet nas escolas municipais."

A complete inference_example.py is bundled in this repo.

Examples

Real pairs from the published 241k corpus, showcasing the learned behaviors:

Ementa (input)	Ação (output)
DISPÕE SOBRE A IMPLANTAÇÃO DE ESTUFAS COM HORTAS PRODUZIDAS COM GARRAFAS PET NAS ESCOLAS MUNICIPAIS DE MARABÁ E DA OUTRAS PROVIDÊNCIAS.	Instalar estufas com hortas produzidas com garrafas pet nas escolas municipais.
INSTITUI A INCLUSÃO DA LÍNGUA BRASILEIRA DE SINAIS – LIBRAS, NO CURRÍCULO ESCOLAR NO ÂMBITO DA REDE MUNICIPAL DE EDUCAÇÃO DO MUNICÍPIO DE MARABÁ E DÁ OUTRAS PROVIDÊNCIAS.	Incluir a Língua Brasileira de Sinais (LIBRAS) no currículo escolar da rede municipal de ensino.
AUTORIZA O PODER EXECUTIVO A INSTITUIR TARIFA ZERO PARA O TRANSPORTE COLETIVO URBANO NO MUNICÍPIO, E DÁ OUTRAS PROVIDÊNCIAS	Implantar tarifa zero para o transporte coletivo urbano no município.
Dispõe sobre a implementação do programa de castração de cães e gatos por meio de Unidade Móvel (Castramóvel) no Município de Marabá, Estado do Pará, visando o controle populacional e a promoção da saúde animal.	Implementar programa de castração de cães e gatos por meio de unidade móvel (Castramóvel) no município.

A full table of 16 canonical examples is in the Zenodo bundle (MODEL_CARD.md). 20 additional examples for regression testing are in examples/ementas.jsonl paired with examples/expected_outputs.jsonl.

Training details

• Training data: 999 supervised pairs stratified by UF and year (855 distinct ementas after normalization; ~14% repeated). See thiagoambiel/sonar-municipal-pl-actions and the dataset DOI for full provenance.
• Split: 900 train / 99 validation (deterministic, seed 42).
• Hyperparameters:

Hyperparameter	Value
Optimizer	AdamW
Learning rate	3e-4
Scheduler	Cosine with 3% warmup
Batch size	16 × gradient_accumulation 2 (effective 32)
Epochs	30
Weight decay	0.01
Seed	42
Mixed precision	bf16
LoRA rank (r)	16
LoRA alpha (α)	32
LoRA dropout	0.05
LoRA target modules	q, v, k, o, wi, wo
Quantization	4-bit NF4 with double-quantization
Trainable params	≈ 6.5M (~2.95% of 220M)

The public training notebook (shipped in the source-code companion) demonstrates the pipeline on a smaller subset (~835 pairs, 752/83 split) due to free-tier GPU constraints on Colab/Kaggle. The model published here was trained on the full 999/900-99 set.

Evaluation

• Test data: held-out 99 pairs (seed 42).
• Metric: BERTScore-F1 (multilingual, language pt).
• Result: BERTScore-F1 = 0.849 on validation.

Surface-overlap metrics (ROUGE-L, BLEU) are deliberately not reported: the task is paraphrase-style rewriting, for which n-gram overlap is a weak proxy. BERTScore is the single appropriate metric here.

Environmental impact

The LoRA fine-tune ran ≈ 17 min on a single NVIDIA Tesla T4 (~2.42×10¹⁸ FLOPs, 30 epochs): estimated ≈ 0.02–0.03 kWh, ≈ 0.01 kgCO₂eq — a negligible footprint for parameter-efficient fine-tuning (estimated via the ML CO2 Impact methodology).

Citation

@software{ambiel_sonar_municipal_model_2026,
  title     = {Sonar Municipal PTT5 base fine-tuned (LoRA, merged) for ementa-to-action textualization},
  author    = {Ambiel, Thiago},
  year      = 2026,
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20564326},
  version   = {1.0.0},
  note      = {Mirror on Hugging Face Hub: thiagoambiel/sonar\_municipal\_ptt5\_ementa2action.}
}

ABNT NBR 6023 (PT-BR):

AMBIEL, Thiago. Sonar Municipal: PTT5 base ajustado (LoRA, mergeado) para textualização ementa→ação (versão 1.0.0). [Modelo]. Zenodo, 2026. DOI: 10.5281/zenodo.20564326.

Glossary

• Ementa — Official short summary of a Brazilian legislative bill, appearing as the opening header of every PL in SAPL.
• Ação — Rewritten action form: the underlying intervention expressed as a direct imperative verb phrase.
• PL — Projeto de Lei (bill).
• SAPL — Sistema de Apoio ao Processo Legislativo.
• LoRA — Low-Rank Adaptation, a parameter-efficient fine-tuning method.

Acknowledgements

This model was developed with support from the AI4PEP network (Artificial Intelligence for Public Health Emergency Preparedness), funded by the International Development Research Centre (IDRC, Canada). Special thanks to Prof. André C. P. L. F. de Carvalho (ICMC-USP) for academic supervision, and to Unicamp-DL for the open release of the base PTT5 model.

Tokenizer files in this repository are redistributed verbatim from unicamp-dl/ptt5-base-portuguese-vocab (Apache-2.0).

Contact

Thiago Ambiel — thiago.ambiel@usp.br