br-address-normalize 0.3.0.dev20260406155612

Biblioteca de normalização de endereços brasileiros

Pipeline de Normalização de Endereços

Sistema de normalização de endereços brasileiros com expansão de abreviações e tratamento de encoding corrompido.

Arquitetura Geral

+-------------------------------------------------------------------------------------------+
|                                     NormalizerFacade                                      |
|                                                                                           |
|  +----------+  +----------+  +----------+  +----------+  +-------------+  +----------+   |
|  |Uppercase |->| Encoding |->| Accents  |->|Abbreviation|->|Preprocessing|->| Numero |   |
|  |  Step    |  |   Step   |  |   Step   |  |    Step    |  |    Step     |  |  Step  |   |
|  +----------+  +----------+  +----------+  +----------+  +-------------+  +----------+   |
|                                                                                           |
|  Novidades v0.4.0:                                                                       |
|  - EncodingStep: +municipio, +apóstrofos legítimos, +padrão $AO→CAO                     |
|  - AbbreviationStep: +VL, +JD, +contexto bairro para PQ                                 |
|  - PreprocessingStep: 98 placeholders carregados do JSON                                |
+-------------------------------------------------------------------------------------------+

Fluxo de Processamento

O pipeline processa endereços em 6 etapas sequenciais (v0.4.0: adicionado EncodingStep antes de RemoveAccentsStep). A ordem é crítica: acentos e caracteres especiais (como ç) são removidos logo após o uppercase para que a correção de encoding e as abreviações operem sobre texto padronizado. Abreviações são expandidas antes da limpeza para que a remoção de prefixo duplicado funcione corretamente.

1. UppercaseStep

Converte todos os campos de texto para UPPERCASE. Executado primeiro para garantir que tokens sejam identificados corretamente nas etapas seguintes.

Campos processados: logradouro, numero, complemento, bairro, municipio, uf

Arquivo: src/pipeline/steps/uppercase.py

2. EncodingStep (Correção de Encoding e Apóstrofos)

Corrige três tipos de corrupção de encoding e normaliza apóstrofos legítimos. Executado após a remoção de acentos para tratar casos residuais de caracteres corrompidos.

Novidades em v0.4.0:

• Campo municipio agora processado
• Normalização de apóstrofos legítimos (D'AGUA, SANT'ANA)
• Novo padrão $AO→CAO no MOJIBAKE_MAPPING

Campos processados: logradouro, complemento, bairro, municipio

Arquivo: src/pipeline/steps/encoding.py

3. RemoveAccentsStep (Remoção de Acentos e Caracteres Especiais)

Remove acentos e diacríticos de todos os campos de texto. Esta etapa é obrigatória e garante a padronização básica do texto.

Utiliza normalização Unicode NFD para separar caracteres base de seus diacríticos.

Exemplos:

• São João → Sao Joao
• José → Jose
• República → Republica
• Praça → Praca

Campos processados: logradouro, complemento, bairro, municipio

Arquivo: src/pipeline/steps/remove_accents.py

4. AbbreviationStep (Expansão de Abreviações)

Expande abreviações usando o provider configurado (local, API ou orchestrator). Executado antes da limpeza para que tipos expandidos sejam reconhecidos na remoção de prefixo duplicado (ex: R RUA SILVA → RUA RUA SILVA → RUA SILVA).

Novidades em v0.4.0:

• Novas abreviações: VL→VILA, JD→JARDIM
• Contexto bairro adicionado para PQ→PARQUE

Campos processados: logradouro, complemento, bairro

Arquitetura L1/L2:

• L1 (Determinística): Regras hardcoded com confiança 100%
• L2 (Probabilística): Fallback opcional via API externa

Arquivo principal: src/modules/abbreviation/orchestrator.py

5. PreprocessingStep (Limpeza)

Normaliza e limpa dados brutos.

Operações (em ordem):

1. Remoção de placeholders (98 tokens carregados do JSON em v0.4.0)
2. Remoção de prefixos duplicados/triplicados (RUA RUA RUA → RUA, LADEIRA LADEIRA → LADEIRA)

Campos processados: todos

Arquivo: src/modules/preprocessing.py

---

Sistema de Abreviações (Detalhado)

Camada L1 — Gates de Decisão

O motor determinístico processa tokens através de 8 gates em ordem:

Gate	Nome	Descrição	Ação
1	TOKENS_TO_REMOVE_FIELD	ND, NINF	Nulifica campo inteiro
1.5	SIGLA_SISTEMA	NI, END	Expande + flag para consumidor
2	DO_NOT_EXPAND	Siglas de órgãos	Preserva sem tocar
3	BCO	Ambiguidade BECO/BANCO	Resolução posicional
4	PENDING_SAMPLE	Tokens em análise	Preserva + flag
5	POSITIONAL_AMBIGUOUS	CD, CM, PA, LG, GL, BX	Resolução contextual
6	Dicionários por Categoria	Ver tabela abaixo	Expansão por campo
7	Dicionário Geral	Injetado/configurado	Fallback
8	SIGLA+dígito	Padrão ABC123	Flag código interno

Arquivo: src/modules/abbreviation/deterministic.py

Dicionários por Categoria

Dicionário	Campos Aplicáveis	Posições
TIPO_LOGRADOURO	logradouro, bairro	0-1 (logradouro), qualquer (bairro)
TITULO_PROPRIO	logradouro, bairro	qualquer
MUNICIPIO_SAFE	municipio	qualquer
COMPLEMENTO	complemento	qualquer

Arquivo de regras: src/modules/abbreviation/entity_rules.py

Resolução de Ambiguidades

BCO (Beco vs Banco):

• Posição 0 em logradouro → BECO
• Outras posições → BANCO

PA (Passagem vs Projeto de Assentamento):

• Em logradouro → PASSAGEM
• Em complemento com zona_rural=True → PROJETO DE ASSENTAMENTO

---

Arquivos de Dados

Todos os dicionários de abreviações ficam centralizados em src/data/ para fácil manutenção:

Arquivo	Descrição
abbreviations.json	Dicionário geral de abreviações
complement_expansions.json	Expansões específicas de complemento
null_markers.json	Marcadores de campo vazio/nulo
brasilia_prefixes.json	Prefixos de Brasília para expansão contextual
whitelist.json	Nomes que não devem ser alterados

---

Abreviações Implementadas

Tipos de Logradouro

Sigla	Expansão
R	Rua
AV	Avenida
TV, TRA	Travessa
RD, ROD	Rodovia
AL	Alameda
RM, RAM	Ramal
ET, ESTR	Estrada
PCA	Praça
BEC, BCO	Beco
PSG	Passagem
VIL, VLA	Vila
CGO, CRG	Córrego
FZ	Fazenda
IG	Igarapé
JRD	Jardim
CHAC	Chácara
DIST	Distrito
LG	Largo
PQ, PARQ, PQE	Parque
COND	Condomínio
CONJ	Conjunto
BALN	Balneário
UNIV	Universidade
ST	Setor
QD	Quadra
VC	Vicinal
LIN, LI	Linha
LD, LADER	Ladeira
SIT	Sítio
GRJ	Granja

Títulos e Tratamentos

Sigla	Expansão
PRES	Presidente
GEN	General
MAL	Marechal
CAP	Capitão
CEL	Coronel
DR	Doutor
PE	Padre
PROF, PRF	Professor
VER	Vereador
SEN	Senador
DEP	Deputado
GOV	Governador
PREF	Prefeito
DES	Desembargador
DQ	Duque
MARQ	Marquês
CDE	Conde
CDR, CDOR	Comendador
DNA	Dona
FCO	Francisco
JOS	José
JORN	Jornalista
MNS	Monsenhor
NS	Nossa Senhora
NSA	Nossa Senhora Aparecida
NSRA	Nossa Senhora
JK	Juscelino Kubitschek
JR	Júnior
FREI	Frei
STA	Santa
STO	Santo

Complemento

Sigla	Expansão
APTO, APT	Apartamento
BL, BLC	Bloco
QD, QDA	Quadra
LT	Lote
SL	Sala
LJ	Loja
AND	Andar
COND	Condomínio
CONJ	Conjunto
EDIF	Edifício
FD, FUND	Fundos
FR	Frente
KIT	Kitnet
MOD	Módulo
NR	Número
PV	Pavimento
PROX, PX	Próximo
SOB	Sobrado
SS	Subsolo
ST	Setor
BX	Box
KM	Quilômetro

Siglas de Órgãos (Preservadas)

Estas siglas são preservadas sem expansão:

ABC, CEEE, CTG, DAER, DNER, IBGE, PTB, SESI, SHIS, DF, KVA

---

Módulo de Apóstrofo (v0.4.0)

Normalização de Apóstrofos Legítimos

O novo módulo apostrophe.py distingue apóstrofos legítimos (nomes próprios) de apóstrofos-lixo.

Padrão Legítimo: LETRA'LETRA (ex: D'AGUA, SANT'ANA, MONT'ALVERNE)

Operações:

1. Normaliza variantes tipográficas (U+2019, U+02BC, U+0060) para ASCII U+0027
2. Preserva tokens no padrão [A-Z]+'[A-Z]+
3. Remove apóstrofo de tokens em posição inválida (início, fim, isolado, duplo, adjacente a dígito)

Exemplos:

• D'AGUA → D'AGUA (preservado)
• SANT'ANA → SANT'ANA (preservado)
• 'LIXO → LIXO (removido do início)
• LIXO' → LIXO (removido do fim)
• D''AGUA → D'AGUA (duplo normalizado)

Integração: Executado dentro do EncodingStep para os campos logradouro, bairro, complemento e municipio, após a correção de mojibake.

Arquivo: src/address_normalizer/modules/apostrophe.py

---

Placeholders Expandidos (v0.4.0)

Conjunto Completo de Marcadores Nulos

O arquivo null_markers.json foi expandido de 9 para 98 tokens, cobrindo variações de:

• Abreviações de "não informado" (NI, NC, NAO, N.I., N/D, etc)
• Placeholders genéricos (XXXX, XXXXXX, TESTE, ASDF, etc)
• Valores de sistema (NULL, NONE, UNDEFINED, NAN, [OBJECT OBJECT])
• Variações de "sem número" (S/N, SN, S N, S.N, SNZ, SNC, etc)
• Campos de sistema (LOGRADOURO, ENDERECO, COMPLEMENTO, BAIRRO, NUMERO, CEP, CIDADE, MUNICIPIO)

Carregamento Dinâmico: O Preprocessor agora carrega os tokens do JSON na inicialização com fallback seguro para os 9 tokens originais se o arquivo estiver ausente ou malformado.

Arquivo: src/address_normalizer/data/null_markers.json

---

Extensões de Encoding (v0.4.0)

Padrão $AO→CAO

Novo padrão adicionado ao MOJIBAKE_MAPPING para corrigir mojibake específico do Windows-1252 onde Ç é corrompido para $.

Exemplos:

• CONTINUA$AO → CONTINUACAO
• EXTEN$AO → EXTENSAO
• INFORMA$AO → INFORMACAO

Segurança: A sequência $AO não é válida em nomes de logradouros brasileiros, então a substituição é segura.

Campo Município no EncodingStep

O campo municipio agora é processado pelo EncodingStep, recebendo as mesmas correções de encoding que logradouro, bairro e complemento.

Exemplos:

• SANT'ANA DO LIVRAMENTO → preservado (apóstrofo legítimo)
• PINGO D'AGUA → preservado (apóstrofo legítimo)

---

Abreviações Novas (v0.4.0)

VL→VILA e JD→JARDIM

Duas novas abreviações foram adicionadas ao dicionário abbreviations_unified.json:

Sigla	Expansão	Contextos
VL	VILA	logradouro (pos 0, 1), bairro
JD	JARDIM	logradouro (pos 0, 1), bairro

Exemplos:

• VL DAS FLORES (bairro) → VILA DAS FLORES
• JD AMERICA (bairro) → JARDIM AMERICA
• VL JOSE (logradouro) → VILA JOSE

Contexto bairro para PQ→PARQUE

A abreviação PQ agora também é expandida quando aparece no campo bairro.

Exemplos:

• PQ INDUSTRIAL (bairro) → PARQUE INDUSTRIAL
• PQ DAS FLORES (bairro) → PARQUE DAS FLORES

---

Contrato de Entrada/Saída

Entrada

Dicionário com campos raw do endereço:

input = {
    "logradouro": "R. CAP ENEAS 315 APTO 304",
    "numero": "315 APTO 304",
    "complemento": "",
    "bairro": "CENTRO",
    "municipio": "JUIZ DE FORA",
    "uf": "MG",
    "cep": "36010-000"
}

Saída (NormalizationResult)

result.original        # dict — entrada original preservada intacta
result.normalizado     # dict — campos normalizados
result.etapas_aplicadas  # list[str] — steps executados pelo pipeline
result.metadata        # NormalizationMetadata:
    .transformacoes    #   list[dict] — cada transformação aplicada
    .flags             #   list[str] — sinalizações para etapas futuras
    .confianca         #   dict[str, float] — score 0-1 por campo


# Saída: dicionário normalizado + metadados
output = {
    "logradouro_normalizado": "RUA CAPITAO ENEAS",
    "numero_normalizado": "315",
    "complemento_normalizado": "APTO 304",
    "bairro_normalizado": "CENTRO",
    "municipio_normalizado": "JUIZ DE FORA",
    "uf_normalizado": "MG",
    "cep_normalizado": "36010000",
    "metadata": {
        "transformacoes": [
            {"campo": "logradouro", "regra": "expansao_abreviacao", "de": "R.", "para": "RUA"},
            {"campo": "logradouro", "regra": "expansao_abreviacao", "de": "CAP", "para": "CAPITAO"},
            {"campo": "numero", "regra": "extracao_complemento", "numero": "315", "complemento": "APTO 304"},
        ],
        "flags": [],
        "confianca": {  # score 0-1 por campo
            "logradouro": 0.95,
            "numero": 0.99,
            "complemento": 0.90,
            "bairro": 1.0,
        }
    }
}

Princípios do contrato:

• Toda transformação é registrada em metadata.transformacoes
• Campos que não foram transformados mantêm o valor original
• flags sinalizam suspeitas para tratamento posterior (ex: "placeholder_removido", "logradouro_sem_tipo")
• confianca permite que camadas superiores decidam se confiam no resultado
• O normalizador é idempotente: normalize(normalize(x)) == normalize(x)
• O normalizador é stateless e determinístico: sem chamadas externas, sem efeitos colaterais

Propriedades retrocompatíveis

result.transformacoes  # alias para result.metadata.transformacoes
result.flags           # alias para result.metadata.flags
result.confianca       # alias para result.metadata.confianca

---

Uso do Pipeline

from address_normalizer.facade import NormalizerFacade
from address_normalizer.modules.abbreviation.local_provider import LocalAbbreviationProvider

# Inicializar provider
abbreviation_provider = LocalAbbreviationProvider()

# Criar facade (configuração padrão)
normalizer = NormalizerFacade(
    abbreviation_provider=abbreviation_provider,
)

# Normalizar endereço (acentos são removidos automaticamente)
endereco = {
    "logradouro": "R DR JOÃO SILVA",
    "numero": "123",
    "complemento": "APTO 45",
    "bairro": "JRD AMÉRICA",
    "municipio": "SÃO PAULO",
    "uf": "SP",
    "cep": "01234567",
}

result = await normalizer.normalize(endereco)

# Acessar resultado
print(result.normalizado["logradouro"])  # "RUA DOUTOR JOAO SILVA"
print(result.transformacoes)              # [{campo, tipo, de, para}, ...]
print(result.metadata.confianca)          # {"logradouro": 1.0, ...}
print(result.metadata.flags)              # ["placeholder_removido", ...]
print(result.etapas_aplicadas)            # ["uppercase", "remove_accents", ...]

# Batch
results = await normalizer.normalize_batch([endereco1, endereco2])

---

Parâmetros de Configuração

NormalizerFacade

Parâmetro	Tipo	Default	Descrição
abbreviation_provider	AbbreviationProvider	-	Provider de abreviações (Local, API ou Orchestrator)
normalizar_cep	bool	False	Ativa normalização de CEP (padding, detecção de inválidos)

ExpanderConfig

Parâmetro	Tipo	Default	Descrição
use_default_dictionaries	bool	True	Carrega dicionários padrão
custom_general_dict	dict	{}	Dicionário adicional customizado
preserve_unknown_codes	bool	True	Preserva códigos internos (ABC123)
l2_caller	Callable	None	Função async para L2 probabilístico
min_l2_confidence	float	0.85	Confiança mínima para aceitar L2
nullify_sistema_siglas	bool	False	Nulifica siglas de sistema (NI, END)

---

Estrutura de Diretórios

src/
├── core/
│   └── base.py                 # Interface PipelineStep (ABC)
├── data/
│   ├── __init__.py             # Funções de carregamento de dados
│   ├── abbreviations_unified.json  # Dicionário unificado de abreviações
│   ├── null_markers.json       # Marcadores nulos (98 tokens)
│   ├── brasilia_prefixes.json  # Prefixos de Brasília
│   └── whitelist.json          # Whitelist ortográfica
├── facade.py                   # NormalizerFacade — ponto de entrada público
├── schemas/
│   └── endereco.py             # NormalizationResult, NormalizationMetadata, EnderecoInput
├── modules/
│   ├── abbreviation/
│   │   ├── base.py             # Interface AbbreviationProvider
│   │   ├── api_provider.py     # Provider via API externa
│   │   ├── local_provider.py   # Provider via JSON local
│   │   ├── orchestrator.py     # Orquestrador L1/L2
│   │   ├── orchestrator_adapter.py  # Adapter para interface Provider
│   │   ├── deterministic.py    # Camada L1 determinística
│   │   ├── entity_rules.py     # Regras por campo
│   │   ├── heuristics.py       # Heurísticas de confiança L2
│   │   ├── models.py           # Dataclasses do módulo
│   │   └── complement_expander.py  # Expansor específico de complemento
│   ├── apostrophe.py           # Normalização de apóstrofos legítimos (v0.4.0)
│   ├── encoding.py             # Correção de encoding corrompido
│   └── preprocessing.py        # Limpeza e normalização
├── pipeline/
│   ├── orchestrator.py         # Pipeline principal
│   └── steps/
│       ├── uppercase.py        # Step de uppercase
│       ├── encoding.py         # Step de encoding
│       ├── remove_accents.py   # Step de remoção de acentos
│       ├── abbreviation.py     # Step de abreviações
│       └── preprocessing.py    # Step de limpeza
tests/
├── conftest.py                 # Fixtures compartilhadas
└── test_integration.py         # Testes end-to-end do pipeline

---

Inconsistências Arquiteturais Identificadas

⚠️ Duplicação: Encoding e Preprocessing

Problema: Lógica está em modules/ mas steps em pipeline/steps/ são apenas wrappers.

• src/address_normalizer/modules/encoding.py (450 linhas) → src/address_normalizer/pipeline/steps/encoding.py (15 linhas)
• src/address_normalizer/modules/preprocessing.py (300 linhas) → src/address_normalizer/pipeline/steps/preprocessing.py (20 linhas)

Impacto: Confusão arquitetural, difícil manutenção, código redundante.

Solução: Consolidar lógica nos steps, remover módulos duplicados. Ver .kiro/steering/refactoring-roadmap.md para detalhes.

⚠️ Inconsistência: Providers de Abbreviation

Problema: Duas implementações fazem a mesma coisa de formas diferentes.

• LocalAbbreviationProvider reimplementa lógica de AddressExpander
• OrchestratorAdapter adapta AddressExpander para AbbreviationProvider

Impacto: Comportamento inconsistente dependendo de qual provider é usado.

Solução: Fazer LocalAbbreviationProvider usar OrchestratorAdapter. Ver .kiro/steering/refactoring-roadmap.md para detalhes.

⚠️ Separação Confusa: Módulos vs Steps

Problema: Responsabilidades ambíguas entre modules/ e pipeline/steps/.

• Alguns steps têm módulos correspondentes (encoding, preprocessing)
• Alguns módulos têm steps (abbreviation)
• Alguns steps não têm módulos (uppercase, remove_accents)

Impacto: Difícil de entender onde adicionar nova lógica.

Solução: Padronizar: steps contêm lógica, módulos são apenas para código compartilhado. Ver .kiro/steering/project-standards.md para padrões.

---

Boas Práticas do Projeto

📋 Regra: Nunca Criar Documentação .md Nova

Regra: Não criar novos arquivos .md para documentação. Sempre atualizar o README.md.

Exceções:

• Arquivos de configuração (.kiro/steering/, .kiro/skills/)
• Documentação de especificações (.kiro/specs/)

Quando Adicionar Informação:

1. Mudança de arquitetura → Atualizar seção "Arquitetura" do README
2. Novo módulo → Adicionar em "Módulos" do README
3. Novo step → Adicionar em "Pipeline" do README
4. Novo provider → Adicionar em "Providers" do README
5. Mudança de API → Atualizar "Uso" do README

🏗️ Padrão de Step

Todos os steps devem:

from address_normalizer.core.base import PipelineStep

class MyStep(PipelineStep):
    def name(self) -> str:
        return "my_step"
    
    async def process(self, data: dict, context: dict) -> tuple[dict, list[dict]]:
        transformacoes = []
        # Lógica aqui
        return data, transformacoes

Retorno:

• data: Dicionário do endereço completo (modificado)
• transformacoes: Lista de transformações aplicadas

Estrutura de Transformação:

{
    "campo": "logradouro",      # Campo modificado
    "tipo": "my_step",          # Tipo de transformação
    "de": "valor_original",     # Valor antes
    "para": "valor_novo",       # Valor depois
    "regra_aplicada": "regra_x" # (opcional) Qual regra foi aplicada
}

🔍 Validação de Código

Antes de fazer commit:

• Código segue padrões do projeto (ver .kiro/steering/project-standards.md)
• Sem duplicação (usar grepSearch para verificar)
• Interfaces são consistentes
• Testes passam
• Sem erros de tipo/lint (usar getDiagnostics)
• README foi atualizado (se necessário)
• Docstrings foram adicionadas
• Sem código morto

📚 Skills e Steering Files

O projeto inclui skills e steering files para guiar desenvolvimento:

• .kiro/skills/refactoring-guide.md - Guia de refatoração
• .kiro/skills/architecture-validation.md - Validação arquitetural
• .kiro/skills/testing-strategy.md - Estratégia de testes
• .kiro/skills/code-quality-review.md - Revisão de qualidade
• .kiro/steering/project-standards.md - Padrões do projeto
• .kiro/steering/refactoring-roadmap.md - Roadmap de refatoração

🔗 Hooks Automáticos

O projeto inclui hooks que automatizam validações:

• update-readme-on-change - Lembra de atualizar README
• validate-architecture - Valida padrões arquiteturais
• check-duplications - Procura por duplicações
• validate-on-save - Valida código ao salvar

---

Histórico de Versões

v0.4.0 (Atual)

• FASE V1-GAPS: Implementação dos 7 gaps identificados em v1.0 e v1.1
  • Gap 1 (S03b): Novo módulo apostrophe.py para normalização de apóstrofos legítimos (D'AGUA, SANT'ANA)
  • Gap 2 & 6: Expansão de null_markers.json de 9 para 98 tokens de placeholder
  • Gap 3: Campo municipio agora processado pelo EncodingStep
  • Gap 4: Padrão $AO→CAO adicionado ao MOJIBAKE_MAPPING (CONTINUA$AO → CONTINUACAO)
  • Gap 5: Abreviações VL→VILA e JD→JARDIM adicionadas ao dicionário
  • Gap 7: Contexto bairro adicionado à expansão de PQ→PARQUE
• Preprocessor agora carrega placeholders dinamicamente do JSON com fallback seguro
• Testes de regressão com 50 endereços reais dos 6 estados
• Property-based tests para validar idempotência e correctness properties

v0.3.0

• FASE N0: Contrato de entrada/saída definido com NormalizationMetadata (transformacoes, flags, confianca)
• FASE N0: Testes de integração end-to-end (21 testes: contrato, pipeline, batch, idempotência)
• FASE N0: Pipeline atualizado para popular metadata com scores de confiança por campo
• Refatoração arquitetural iniciada
• Consolidação de módulos de encoding e preprocessing
• Unificação de providers de abreviação
• Adição de skills e steering files para guiar desenvolvimento
• Implementação de hooks automáticos para validação

v0.2.1

• Versão anterior com funcionalidades base de normalização

---

Notas de Implementação

1. Ordem do Pipeline (v0.4.0): Uppercase → Encoding → Remoção de Acentos → Abreviações → Limpeza. EncodingStep agora vem antes de RemoveAccentsStep para corrigir mojibake e normalizar apóstrofos antes da remoção de acentos. Abreviações vêm antes da limpeza para que R RUA seja expandido para RUA RUA e depois deduplicado.

2. Ordem dos Gates: A ordem dos gates no DeterministicLayer é crítica. Gates anteriores têm prioridade sobre posteriores.

3. Apóstrofos Legítimos (v0.4.0): O padrão LETRA'LETRA é preservado (ex: D'AGUA, SANT'ANA). Apóstrofos em posição inválida são removidos.

4. Placeholders Dinâmicos (v0.4.0): O Preprocessor carrega 98 tokens do null_markers.json com fallback para 9 tokens originais se o arquivo estiver ausente.

5. Resolução Posicional: Tokens como BCO, PA, BX têm significados diferentes dependendo do campo e posição.

6. L2 Probabilístico: Só é acionado para posição 0 do logradouro e requer l2_caller configurado.

7. Encoding: O módulo de encoding usa regex ordenadas por especificidade (mais longas primeiro).

8. Conflitos Conhecidos:

   • PRF: No sistema = Professor. Na lista de referência = Polícia Rodoviária Federal. Mantido como Professor por ser mais comum em endereços.
   • PA: Tratado como PASSAGEM em logradouro, PROJETO DE ASSENTAMENTO em complemento rural.