colsemantics 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,362 @@
1
+ """Detectores de evidência semântica.
2
+
3
+ Cada detector olha para uma fonte diferente e emite `Evidencia`. Nenhum
4
+ decide sozinho — quem decide é o combinador em `evidence`. Isso é o que
5
+ permite o caso difícil: um nome opaco (`f27`, `cd_dpto_lot`) que o dicionário
6
+ não conhece pode ser resolvido pelo conteúdo, pela abreviatura reconstruída ou
7
+ pelo contexto das colunas vizinhas.
8
+ """
9
+ from dataclasses import dataclass, field
10
+
11
+ from rapidfuzz.distance import JaroWinkler
12
+
13
+ from . import _taxonomy as config
14
+ from .evidence import EIXO_DOMINIO, EIXO_PAPEL, Evidencia
15
+ from .tokens import expandir_abreviatura, normalizar, tokens_expandidos
16
+ from .vocabulary import GAZETTEERS
17
+
18
+ # Papéis que definem sozinhos o tratamento de ETL da coluna: se a coluna é uma
19
+ # chave ou uma data, isso importa mais para o pipeline do que o assunto dela.
20
+ PAPEIS_ESTRUTURAIS = frozenset({
21
+ config.SEMANTICA_CHAVE_ID,
22
+ config.SEMANTICA_DATA_CALENDARIO,
23
+ "Valor Financeiro",
24
+ "Quantidade / Métrica",
25
+ "Contato / Rede",
26
+ "Status / Indicador / Flag",
27
+ "Resultado de Avaliação",
28
+ })
29
+
30
+ _MAPA_PADRAO_SEMANTICA: dict[str, tuple[str, str]] = {
31
+ "CPF": (config.SEMANTICA_CHAVE_ID, EIXO_PAPEL),
32
+ "CNPJ": (config.SEMANTICA_CHAVE_ID, EIXO_PAPEL),
33
+ "UUID": (config.SEMANTICA_CHAVE_ID, EIXO_PAPEL),
34
+ "E-mail": ("Contato / Rede", EIXO_PAPEL),
35
+ "Telefone": ("Contato / Rede", EIXO_PAPEL),
36
+ "CEP": ("Localização Geográfica", EIXO_DOMINIO),
37
+ }
38
+
39
+ # Índice invertido token -> categorias fortes que o contêm.
40
+ _INDICE_TOKEN_FORTE: dict[str, list[str]] = {}
41
+ for _categoria, _palavras in config.CATEGORIAS_FORTES.items():
42
+ for _palavra in _palavras:
43
+ _INDICE_TOKEN_FORTE.setdefault(_palavra, []).append(_categoria)
44
+
45
+ _DECAIMENTO_POSICIONAL = 0.03
46
+
47
+ # Prefixo que cobre mais que isto da palavra-alvo continua sendo evidência
48
+ # cheia; abaixo disso vira palpite proporcional ao que cobre. 0,7 é o piso —
49
+ # `forma` cobre 0,625 de `formacao` e ainda assim é uma palavra comum demais
50
+ # para valer como evidência plena de "Curso / Treinamento".
51
+ _COBERTURA_MINIMA_PREFIXO = 0.7
52
+
53
+
54
+ @dataclass
55
+ class PerfilConteudo:
56
+ """O que os detectores de conteúdo precisam saber sobre a coluna.
57
+
58
+ Construído diretamente pelo chamador a partir do que já sabe sobre a
59
+ coluna (amostra de valores, cardinalidade, forma dos dados) — nenhum
60
+ campo é recomputado internamente.
61
+ """
62
+ tipo_dados: str = ""
63
+ valores_distintos: list[str] = field(default_factory=list)
64
+ n_unicos: int = 0
65
+ ratio_unicidade: float = 0.0
66
+ str_len_media: float | None = None
67
+ comprimento_fixo: bool = False
68
+ assimetria: float | None = None
69
+ minimo: float | None = None
70
+ monotonica_crescente: bool = False
71
+ casas_decimais_fixas: int | None = None
72
+
73
+
74
+ def _peso_posicional(indice: int) -> float:
75
+ return max(1.0 - _DECAIMENTO_POSICIONAL * indice, 0.5)
76
+
77
+
78
+ # ── 1. Conteúdo: padrão estruturado ─────────────────────────────────────────
79
+
80
+ def por_padrao_conteudo(detectado_padrao: str) -> list[Evidencia]:
81
+ """CPF/CNPJ/e-mail validados no conteúdo. É a evidência mais forte que
82
+ existe: uma coluna chamada `campo1` que só contém CPF é um identificador,
83
+ independentemente de como alguém a batizou."""
84
+ entrada = _MAPA_PADRAO_SEMANTICA.get(detectado_padrao)
85
+ if entrada is None:
86
+ return []
87
+ categoria, eixo = entrada
88
+ return [Evidencia(categoria, eixo, 0.98, f"conteúdo validado como {detectado_padrao}")]
89
+
90
+
91
+ # ── 2. Conteúdo: gazetteer de valores ───────────────────────────────────────
92
+
93
+ def por_gazetteer(perfil: PerfilConteudo) -> list[Evidencia]:
94
+ """Compara os valores da coluna com conjuntos fechados conhecidos.
95
+
96
+ É o detector que resolve o nome ilegível: `f27` cujos valores são as 27
97
+ siglas de UF é uma coluna de localização, e nenhuma análise do nome
98
+ chegaria lá.
99
+ """
100
+ if not perfil.valores_distintos or perfil.n_unicos <= 0:
101
+ return []
102
+
103
+ normalizados = [normalizar(v) for v in perfil.valores_distintos]
104
+ normalizados = [v for v in normalizados if v]
105
+ if not normalizados:
106
+ return []
107
+
108
+ achados: list[Evidencia] = []
109
+ for gazetteer in GAZETTEERS:
110
+ if perfil.n_unicos > gazetteer["max_distintos"]:
111
+ continue
112
+ contidos = sum(1 for v in normalizados if v in gazetteer["valores"])
113
+ cobertura = contidos / len(normalizados)
114
+ if cobertura < gazetteer["cobertura_minima"]:
115
+ continue
116
+ achados.append(Evidencia(
117
+ gazetteer["categoria"], gazetteer["eixo"],
118
+ round(gazetteer["peso"] * cobertura, 4),
119
+ f"valores correspondem a {gazetteer['nome']} ({cobertura:.0%} da coluna)",
120
+ ))
121
+ return achados
122
+
123
+
124
+ def _qualificador_de_borda(token: str, posicao: str) -> Evidencia | None:
125
+ """Evidência de papel vinda do token na borda do nome da coluna.
126
+
127
+ A expansão da abreviatura conta: `vl_saque` só é reconhecido como valor
128
+ financeiro porque `vl` vira `valor`. Quando a expansão é ambígua, a posição
129
+ resolve — `des` em `REFUND_TYPE_DES` pode ser `desc`, `despesa` ou
130
+ `demissao`, e na ponta do nome só `desc` faz sentido como qualificador.
131
+ """
132
+ candidatos: list[tuple[str, float]] = [(token, 1.0)]
133
+ expansoes = expandir_abreviatura(token)
134
+ qualificadoras = [e for e in expansoes if e[0] in config.TOKENS_QUALIFICADORES]
135
+ if len(expansoes) == 1:
136
+ candidatos.append(expansoes[0])
137
+ elif len(qualificadoras) == 1:
138
+ candidatos.append(qualificadoras[0])
139
+
140
+ for palavra, confianca in candidatos:
141
+ if palavra not in config.TOKENS_QUALIFICADORES:
142
+ continue
143
+ categorias = _INDICE_TOKEN_FORTE.get(palavra, ())
144
+ if len(categorias) != 1:
145
+ continue
146
+ origem = (
147
+ f"qualificador {posicao} '{palavra}'" if palavra == token
148
+ else f"qualificador {posicao} '{token}' → '{palavra}'"
149
+ )
150
+ return Evidencia(categorias[0], EIXO_PAPEL, round(0.9 * confianca, 4), origem)
151
+ return None
152
+
153
+
154
+ # ── 3. Nome: token forte (com abreviaturas expandidas) ──────────────────────
155
+
156
+ def por_token_forte(tokens: list[str]) -> list[Evidencia]:
157
+ """Casa os tokens do nome — e as expansões das abreviaturas — contra o
158
+ dicionário curado.
159
+
160
+ A regra do qualificador posicional continua valendo: o token na *borda* do
161
+ nome define o papel. As duas convenções que aparecem em sistema corporativo
162
+ põem o qualificador em pontas opostas — `id_funcionario`, `dt_movimento`,
163
+ `nome_departamento` no português; `EMPLOYEE_ID`, `SUPPLIER_CONTACT_CODE`,
164
+ `DEPARTMENT_NAME` no inglês. Olhar só o primeiro token classificava
165
+ `SUPPLIER_CONTACT_CODE` como valor financeiro, e alguém acabaria somando um
166
+ centro de custo.
167
+ """
168
+ if not tokens:
169
+ return []
170
+
171
+ evidencias: list[Evidencia] = []
172
+
173
+ bordas = [(tokens[0], "inicial")]
174
+ if len(tokens) > 1:
175
+ bordas.append((tokens[-1], "final"))
176
+ for token, posicao in bordas:
177
+ evidencia = _qualificador_de_borda(token, posicao)
178
+ if evidencia is not None:
179
+ evidencias.append(evidencia)
180
+
181
+ for indice, (palavra, confianca_expansao, original) in enumerate(tokens_expandidos(tokens)):
182
+ for categoria in _INDICE_TOKEN_FORTE.get(palavra, ()):
183
+ peso_token = (
184
+ config.PESO_TOKEN_QUALIFICADOR
185
+ if palavra in config.TOKENS_QUALIFICADORES
186
+ else config.PESO_TOKEN_ENTIDADE
187
+ )
188
+ peso = 0.85 * peso_token * confianca_expansao * _peso_posicional(indice)
189
+ origem = (
190
+ f"token '{palavra}'" if palavra == original
191
+ else f"abreviatura '{original}' → '{palavra}'"
192
+ )
193
+ evidencias.append(Evidencia(categoria, EIXO_PAPEL, round(peso, 4), origem))
194
+
195
+ return evidencias
196
+
197
+
198
+ def _fator_truncagem(candidato: str, palavra: str) -> float:
199
+ """Desconto para o match fuzzy que é só um prefixo da palavra-alvo.
200
+
201
+ Jaro-Winkler bonifica prefixo comum de propósito, então `work` casa com
202
+ `workshop` a 0,9 — foi assim que `WORK_EMAIL_ADDRESS` ganhou o domínio
203
+ "Curso / Treinamento". Quando o candidato é prefixo estrito e cobre pouco
204
+ da palavra, a evidência vale o que ela cobre, exatamente como já acontece
205
+ na reconstrução de abreviatura por subsequência.
206
+ """
207
+ if len(candidato) >= len(palavra) or not palavra.startswith(candidato):
208
+ return 1.0
209
+ cobertura = len(candidato) / len(palavra)
210
+ return 1.0 if cobertura > _COBERTURA_MINIMA_PREFIXO else cobertura
211
+
212
+
213
+ # ── 4. Nome: fuzzy contra as categorias de domínio ──────────────────────────
214
+
215
+ def por_fuzzy(nome_limpo: str, tokens: list[str]) -> list[Evidencia]:
216
+ """Jaro-Winkler contra as palavras-chave de domínio.
217
+
218
+ Roda sempre, inclusive quando um papel forte já foi encontrado: `nome` e
219
+ `cod` prefixam metade das colunas de um sistema corporativo, e condicionar
220
+ o fuzzy à ausência de token forte tornava as categorias de domínio
221
+ inalcançáveis.
222
+ """
223
+ melhores: dict[str, tuple[float, str]] = {}
224
+
225
+ # Token que já é palavra conhecida com papel definido não entra no fuzzy de
226
+ # domínio: a semelhança que sobra é homógrafo, não evidência. `time` é
227
+ # "equipe" em português e está no vocabulário de estrutura organizacional —
228
+ # por isso `RECORD_UPDATE_TIME` ganhava domínio "Estrutura Organizacional"
229
+ # tendo papel de data com 0,96 de confiança vindo do *mesmo* token.
230
+ candidatos_nome = [(nome_limpo, 1.0, nome_limpo)] + [
231
+ c for c in tokens_expandidos(tokens)
232
+ if not (c[0] == c[2] and c[0] in _INDICE_TOKEN_FORTE)
233
+ ]
234
+ for categoria, palavras_chave in config.CATEGORIAS_FUZZY.items():
235
+ for palavra in palavras_chave:
236
+ palavra_norm = normalizar(palavra)
237
+ threshold = (
238
+ config.THRESHOLD_FUZZY_CURTO if len(palavra_norm) <= 3
239
+ else config.THRESHOLD_FUZZY_PADRAO
240
+ )
241
+ for indice, (candidato, confianca, original) in enumerate(candidatos_nome):
242
+ candidato_norm = normalizar(candidato)
243
+ similaridade = JaroWinkler.similarity(candidato_norm, palavra_norm)
244
+ if similaridade < threshold:
245
+ continue
246
+ similaridade *= _fator_truncagem(candidato_norm, palavra_norm)
247
+ # Token que já é qualificador estrutural (`categoria`, `tipo`,
248
+ # `status`) pesa menos como evidência de domínio, do mesmo jeito
249
+ # que já pesa menos como evidência de papel: é genérico demais
250
+ # para decidir sozinho. Sem isso, `CATEGORIA_PRODUTO` empatava
251
+ # "Cargo / Função" (de `categoria`) com "Produto / Item" (de
252
+ # `produto`) e o desempate virava sorte de posição.
253
+ peso_qualificador = (
254
+ config.PESO_TOKEN_QUALIFICADOR if original in config.TOKENS_QUALIFICADORES
255
+ else 1.0
256
+ )
257
+ peso = (
258
+ 0.8 * similaridade * confianca * peso_qualificador
259
+ * _peso_posicional(max(indice - 1, 0))
260
+ )
261
+ atual = melhores.get(categoria)
262
+ if atual is None or peso > atual[0]:
263
+ origem = (
264
+ f"nome parecido com '{palavra}'" if candidato == original
265
+ else f"abreviatura '{original}' → '{candidato}' ~ '{palavra}'"
266
+ )
267
+ melhores[categoria] = (peso, origem)
268
+
269
+ return [
270
+ Evidencia(categoria, EIXO_DOMINIO, round(peso, 4), origem)
271
+ for categoria, (peso, origem) in melhores.items()
272
+ ]
273
+
274
+
275
+ # ── 5. Conteúdo: assinatura estrutural ──────────────────────────────────────
276
+
277
+ def por_assinatura_estrutural(perfil: PerfilConteudo) -> list[Evidencia]:
278
+ """Deduz o papel pela *forma* dos dados, não pelo nome.
279
+
280
+ Pistas fracas de propósito: sozinhas não decidem nada, mas somadas a um
281
+ nome ambíguo costumam ser o que desempata.
282
+ """
283
+ evidencias: list[Evidencia] = []
284
+ tipo = perfil.tipo_dados
285
+
286
+ if tipo == "Booleano":
287
+ evidencias.append(Evidencia(
288
+ "Status / Indicador / Flag", EIXO_PAPEL, 0.7, "coluna booleana"
289
+ ))
290
+
291
+ if tipo == "Número Inteiro" and perfil.monotonica_crescente and perfil.ratio_unicidade >= 0.99:
292
+ evidencias.append(Evidencia(
293
+ config.SEMANTICA_CHAVE_ID, EIXO_PAPEL, 0.6,
294
+ "inteiro único e crescente (cara de chave sequencial)",
295
+ ))
296
+
297
+ if (tipo == "Número Decimal" and perfil.casas_decimais_fixas == 2
298
+ and perfil.minimo is not None and perfil.minimo >= 0
299
+ and perfil.assimetria is not None and perfil.assimetria > 0.5):
300
+ evidencias.append(Evidencia(
301
+ "Valor Financeiro", EIXO_PAPEL, 0.45,
302
+ "decimal de 2 casas, não negativo e assimétrico à direita (perfil monetário)",
303
+ ))
304
+
305
+ if tipo.startswith("Texto") and perfil.str_len_media is not None:
306
+ if perfil.str_len_media > 40 and perfil.ratio_unicidade > 0.5:
307
+ evidencias.append(Evidencia(
308
+ "Texto Descritivo Livre", EIXO_PAPEL, 0.55,
309
+ f"texto longo (média de {perfil.str_len_media:.0f} caracteres) e pouco repetido",
310
+ ))
311
+ elif perfil.comprimento_fixo and perfil.ratio_unicidade > 0.9:
312
+ evidencias.append(Evidencia(
313
+ config.SEMANTICA_CHAVE_ID, EIXO_PAPEL, 0.5,
314
+ "texto de comprimento fixo e quase único (cara de código)",
315
+ ))
316
+
317
+ return evidencias
318
+
319
+
320
+ # ── 6. Contexto da tabela ───────────────────────────────────────────────────
321
+
322
+ def por_contexto_da_tabela(
323
+ tokens: list[str], dominios_da_tabela: dict[str, float]
324
+ ) -> list[Evidencia]:
325
+ """Desempata abreviaturas ambíguas usando o assunto da tabela.
326
+
327
+ `dep` pode ser departamento, dependente ou depósito. Sozinho é insolúvel —
328
+ nenhum modelo acerta olhando só a coluna. Mas se as outras colunas da
329
+ tabela já estabeleceram "Estrutura Organizacional" com confiança, a
330
+ expansão `departamento` passa a ser a leitura provável.
331
+ """
332
+ if not dominios_da_tabela:
333
+ return []
334
+
335
+ evidencias: list[Evidencia] = []
336
+ vistos: set[str] = set()
337
+ for palavra, confianca, original in tokens_expandidos(tokens):
338
+ if palavra == original or confianca >= 0.85:
339
+ continue # expansão única já é forte o bastante sem contexto
340
+ for categoria in _INDICE_TOKEN_FORTE.get(palavra, ()):
341
+ chave = f"{categoria}|{palavra}"
342
+ if chave in vistos or categoria not in dominios_da_tabela:
343
+ continue
344
+ vistos.add(chave)
345
+ evidencias.append(Evidencia(
346
+ categoria, EIXO_PAPEL,
347
+ round(0.4 * dominios_da_tabela[categoria], 4),
348
+ f"contexto da tabela favorece '{original}' → '{palavra}'",
349
+ ))
350
+ for categoria, forca in dominios_da_tabela.items():
351
+ if categoria not in config.CATEGORIAS_FUZZY:
352
+ continue
353
+ if palavra in config.CATEGORIAS_FUZZY[categoria]:
354
+ chave = f"{categoria}|{palavra}"
355
+ if chave in vistos:
356
+ continue
357
+ vistos.add(chave)
358
+ evidencias.append(Evidencia(
359
+ categoria, EIXO_DOMINIO, round(0.4 * forca, 4),
360
+ f"contexto da tabela favorece '{original}' → '{palavra}'",
361
+ ))
362
+ return evidencias
@@ -0,0 +1,82 @@
1
+ """Acúmulo e combinação de evidências semânticas.
2
+
3
+ O modelo antigo era "primeiro match vence": o primeiro detector que
4
+ respondesse definia a categoria e os demais nem rodavam. Isso descarta
5
+ informação — o nome pode sugerir uma coisa fracamente e o conteúdo confirmar
6
+ outra, e a resposta certa costuma ser a que várias fontes fracas apontam
7
+ juntas.
8
+
9
+ Aqui cada detector emite `Evidencia` e a combinação é feita por **noisy-OR**:
10
+ `1 - Π(1 - peso)`. Duas pistas de 0,5 valem 0,75; três valem 0,875. Evidências
11
+ independentes se reforçam sem nunca estourar 1,0, e uma pista forte sozinha
12
+ continua bastando.
13
+ """
14
+ from dataclasses import dataclass
15
+ from typing import Any
16
+
17
+ EIXO_PAPEL = "papel"
18
+ EIXO_DOMINIO = "dominio"
19
+
20
+ # Diferença mínima entre a 1ª e a 2ª hipótese para a escolha ser considerada
21
+ # conclusiva. Abaixo disso o relatório mostra as alternativas em vez de
22
+ # fingir certeza.
23
+ _MARGEM_CONCLUSIVA = 0.15
24
+
25
+
26
+ @dataclass(frozen=True)
27
+ class Evidencia:
28
+ """Uma pista sobre o significado de uma coluna.
29
+
30
+ `peso` é a confiança *desta* pista isoladamente (0-1). `origem` é o texto
31
+ que aparece no relatório — precisa explicar por que a pista existe, não só
32
+ nomeá-la.
33
+ """
34
+ categoria: str
35
+ eixo: str
36
+ peso: float
37
+ origem: str
38
+
39
+
40
+ def _noisy_or(pesos: list[float]) -> float:
41
+ resultado = 1.0
42
+ for peso in pesos:
43
+ resultado *= 1.0 - max(0.0, min(1.0, peso))
44
+ return 1.0 - resultado
45
+
46
+
47
+ def ranquear(evidencias: list[Evidencia], eixo: str) -> list[dict[str, Any]]:
48
+ """Ranqueia as categorias candidatas de um eixo pelo peso combinado."""
49
+ por_categoria: dict[str, list[Evidencia]] = {}
50
+ for evidencia in evidencias:
51
+ if evidencia.eixo == eixo:
52
+ por_categoria.setdefault(evidencia.categoria, []).append(evidencia)
53
+
54
+ ranking: list[dict[str, Any]] = [
55
+ {
56
+ "categoria": categoria,
57
+ "confianca": round(_noisy_or([e.peso for e in itens]), 4),
58
+ "origens": [e.origem for e in sorted(itens, key=lambda e: -e.peso)],
59
+ }
60
+ for categoria, itens in por_categoria.items()
61
+ ]
62
+ ranking.sort(key=lambda r: -float(r["confianca"]))
63
+ return ranking
64
+
65
+
66
+ def escolher(ranking: list[dict[str, Any]]) -> tuple[str | None, float, str, bool]:
67
+ """Escolhe a categoria vencedora de um ranking já ordenado.
68
+
69
+ Devolve `(categoria, confiança, origem, conclusiva)`. `conclusiva` é falso
70
+ quando a segunda hipótese está perto demais — sinal de que o nome é
71
+ ambíguo e o leitor deveria olhar as alternativas.
72
+ """
73
+ if not ranking:
74
+ return None, 0.0, "Sem evidência", False
75
+ melhor = ranking[0]
76
+ margem = melhor["confianca"] - (ranking[1]["confianca"] if len(ranking) > 1 else 0.0)
77
+ return (
78
+ melhor["categoria"],
79
+ float(melhor["confianca"]),
80
+ " + ".join(melhor["origens"][:3]),
81
+ bool(margem >= _MARGEM_CONCLUSIVA),
82
+ )
colsemantics/py.typed ADDED
File without changes
colsemantics/tokens.py ADDED
@@ -0,0 +1,131 @@
1
+ """Normalização, tokenização e expansão de abreviaturas de nomes de coluna."""
2
+ import re
3
+ from functools import lru_cache
4
+
5
+ from unidecode import unidecode
6
+
7
+ from . import _taxonomy as config
8
+ from .vocabulary import ABREVIATURAS
9
+
10
+ _RE_CAMEL = re.compile(r"([a-z0-9])([A-Z])")
11
+ _RE_SEPARADORES = re.compile(r"[_\s\-\.]+")
12
+ _RE_LETRA_NUMERO = re.compile(r"([a-z])(\d)")
13
+
14
+ # Comprimento máximo da expansão em relação à abreviatura. `dp` expandindo para
15
+ # uma palavra de 20 letras não é abreviatura, é coincidência de subsequência.
16
+ _RAZAO_MAX_EXPANSAO = 4.0
17
+ _MIN_LEN_ABREVIATURA = 2
18
+ # Abaixo disso, só o dicionário curado expande (`nm`, `sg`, `dt`...). Palpite
19
+ # por subsequência com 2 letras casa contra quase qualquer palavra do
20
+ # vocabulário — `ue` ⊂ `user` não quer dizer nada.
21
+ _MIN_LEN_ABREVIATURA_ESPECULATIVA = 3
22
+
23
+
24
+ def normalizar(texto: str) -> str:
25
+ return unidecode(str(texto)).lower().strip()
26
+
27
+
28
+ def tokenizar(nome_col: str) -> list[str]:
29
+ """Quebra o nome da coluna em tokens normalizados.
30
+
31
+ Separa camelCase, separadores explícitos e a fronteira letra→número
32
+ (`col1` → `col`, `1`), que é comum em nome gerado por sistema.
33
+ """
34
+ nome = _RE_CAMEL.sub(r"\1_\2", str(nome_col))
35
+ nome = normalizar(nome)
36
+ nome = _RE_LETRA_NUMERO.sub(r"\1_\2", nome)
37
+ return [p for p in _RE_SEPARADORES.split(nome) if p]
38
+
39
+
40
+ @lru_cache(maxsize=1)
41
+ def _vocabulario_expansao() -> tuple[str, ...]:
42
+ """Todas as palavras que valem como alvo de expansão: as palavras-chave da
43
+ taxonomia mais as expansões conhecidas do dicionário de abreviaturas."""
44
+ palavras: set[str] = set()
45
+ for grupo in (config.CATEGORIAS_FORTES, config.CATEGORIAS_FUZZY):
46
+ for lista in grupo.values():
47
+ palavras.update(lista)
48
+ for expansoes in ABREVIATURAS.values():
49
+ palavras.update(expansoes)
50
+ return tuple(sorted(palavras))
51
+
52
+
53
+ def _e_subsequencia(abreviatura: str, palavra: str) -> bool:
54
+ """`dpto` é subsequência de `departamento` (d-e-p-a-r-t-a-m-e-n-t-o).
55
+
56
+ Abreviatura corporativa é quase sempre a palavra com letras removidas na
57
+ ordem — não uma troca de letras. Distância de edição erra esse caso;
58
+ subsequência acerta.
59
+ """
60
+ iterador = iter(palavra)
61
+ return all(letra in iterador for letra in abreviatura)
62
+
63
+
64
+ @lru_cache(maxsize=4096)
65
+ def expandir_abreviatura(token: str) -> tuple[tuple[str, float], ...]:
66
+ """Devolve as expansões possíveis de um token, com a confiança de cada uma.
67
+
68
+ Duas fontes, nessa ordem: o dicionário curado (alta confiança, e é onde
69
+ moram as abreviaturas ambíguas como `dep`) e a reconstrução por
70
+ subsequência (confiança proporcional a quanto da palavra a abreviatura
71
+ preserva).
72
+
73
+ Retorna tupla de tuplas para poder ser cacheada.
74
+ """
75
+ if len(token) < _MIN_LEN_ABREVIATURA or not token.isalpha():
76
+ return ()
77
+
78
+ # Token que já é uma palavra conhecida do vocabulário não é abreviatura de
79
+ # nada. Sem esta guarda, `name` — que está na taxonomia como nome de
80
+ # pessoa — era expandido para `nascimento` (do qual é subsequência:
81
+ # n-a-s-c-i-M-E-n-t-o) e a coluna `FULL_NAME` virava "Data / Calendário".
82
+ # Um palpite não pode competir com a evidência literal do mesmo token.
83
+ if token in _vocabulario_expansao():
84
+ return ()
85
+
86
+ curadas = ABREVIATURAS.get(token)
87
+ if curadas:
88
+ # Quando há várias expansões, nenhuma é certa — a confiança cai e o
89
+ # desempate fica por conta do contexto da tabela.
90
+ confianca = 0.85 if len(curadas) == 1 else 0.55
91
+ return tuple((palavra, confianca) for palavra in curadas)
92
+
93
+ # Token de 2 letras casa por subsequência com quase qualquer palavra
94
+ # longa o suficiente — `ue` ⊂ `user`, sem nenhuma relação real entre os
95
+ # dois. Abaixo desse tamanho só o dicionário curado (checado acima) vale;
96
+ # o palpite por subsequência precisa de pelo menos 3 letras pra a posição
97
+ # relativa das letras significar alguma coisa.
98
+ if len(token) < _MIN_LEN_ABREVIATURA_ESPECULATIVA:
99
+ return ()
100
+
101
+ candidatos: list[tuple[str, float]] = []
102
+ for palavra in _vocabulario_expansao():
103
+ if palavra == token or len(palavra) <= len(token):
104
+ continue
105
+ if len(palavra) > len(token) * _RAZAO_MAX_EXPANSAO:
106
+ continue
107
+ if palavra[0] != token[0]:
108
+ continue
109
+ if not _e_subsequencia(token, palavra):
110
+ continue
111
+ # Quanto mais da palavra a abreviatura preserva, mais confiável.
112
+ cobertura = len(token) / len(palavra)
113
+ candidatos.append((palavra, round(0.35 + 0.35 * cobertura, 4)))
114
+
115
+ candidatos.sort(key=lambda c: -c[1])
116
+ return tuple(candidatos[:3])
117
+
118
+
119
+ def tokens_expandidos(tokens: list[str]) -> list[tuple[str, float, str]]:
120
+ """Expande cada token, mantendo o original como candidato de peso máximo.
121
+
122
+ Devolve `(palavra, confianca, token_original)` — o token original vai
123
+ junto para a origem do achado poder dizer de onde a palavra veio.
124
+ """
125
+ resultado: list[tuple[str, float, str]] = []
126
+ for token in tokens:
127
+ resultado.append((token, 1.0, token))
128
+ for palavra, confianca in expandir_abreviatura(token):
129
+ if palavra != token:
130
+ resultado.append((palavra, confianca, token))
131
+ return resultado