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.
- colsemantics/__init__.py +248 -0
- colsemantics/_taxonomy.py +177 -0
- colsemantics/detectors.py +362 -0
- colsemantics/evidence.py +82 -0
- colsemantics/py.typed +0 -0
- colsemantics/tokens.py +131 -0
- colsemantics/vocabulary.py +171 -0
- colsemantics-0.1.0.dist-info/METADATA +162 -0
- colsemantics-0.1.0.dist-info/RECORD +12 -0
- colsemantics-0.1.0.dist-info/WHEEL +5 -0
- colsemantics-0.1.0.dist-info/licenses/LICENSE +21 -0
- colsemantics-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -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
|
colsemantics/evidence.py
ADDED
|
@@ -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
|