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,248 @@
1
+ """colsemantics: inferência semântica de colunas por acúmulo de evidências.
2
+
3
+ O modelo tem dois eixos, não um:
4
+
5
+ - **papel** — o que a coluna *é*: identificador, data, valor financeiro,
6
+ quantidade, nome, descrição, contato, flag.
7
+ - **domínio** — sobre o que ela *fala*: estrutura organizacional, cargo,
8
+ curso, localidade, perfil do colaborador.
9
+
10
+ `nome_departamento` tem papel "Nome" e domínio "Estrutura Organizacional".
11
+
12
+ A inferência é uma **cascata de detectores independentes**, não uma sequência
13
+ de `if/elif` em que o primeiro a responder vence. Cada detector emite
14
+ evidências com peso, e a combinação por noisy-OR deixa pistas fracas se
15
+ somarem. É o que permite classificar `cd_dpto_lot`: o dicionário não conhece o
16
+ nome, mas a abreviatura reconstrói `codigo`/`departamento`/`lotacao`, o
17
+ conteúdo mostra baixa cardinalidade e o contexto da tabela confirma o assunto.
18
+
19
+ A inferência acontece em **duas passadas**. A primeira classifica o que dá
20
+ isoladamente; a segunda usa os domínios já estabelecidos com confiança para
21
+ desambiguar o que ficou em cima do muro — `dep` (departamento? dependente?
22
+ depósito?) é insolúvel na coluna e trivial na tabela.
23
+ """
24
+ from typing import Any
25
+
26
+ from . import _taxonomy as config
27
+ from .detectors import (
28
+ PAPEIS_ESTRUTURAIS,
29
+ PerfilConteudo,
30
+ por_assinatura_estrutural,
31
+ por_contexto_da_tabela,
32
+ por_fuzzy,
33
+ por_gazetteer,
34
+ por_padrao_conteudo,
35
+ por_token_forte,
36
+ )
37
+ from .evidence import EIXO_DOMINIO, EIXO_PAPEL, Evidencia, escolher, ranquear
38
+ from .tokens import expandir_abreviatura, normalizar, tokenizar
39
+
40
+ __version__ = "0.1.0"
41
+
42
+ __all__ = [
43
+ "Evidencia",
44
+ "PAPEIS_ESTRUTURAIS",
45
+ "PerfilConteudo",
46
+ "expandir_abreviatura",
47
+ "inferir_semantica",
48
+ "inferir_semanticas_da_tabela",
49
+ "normalizar",
50
+ "semanticas_para_gap_analysis",
51
+ "tokenizar",
52
+ ]
53
+
54
+ # Confiança mínima para um domínio da primeira passada entrar no contexto que
55
+ # desambigua as demais colunas. Baixo demais e o contexto propaga o próprio
56
+ # erro; alto demais e ele nunca ajuda.
57
+ _CONFIANCA_MINIMA_CONTEXTO = 0.7
58
+
59
+ # Piso para *afirmar* um domínio. Abaixo dele a categoria continua visível em
60
+ # `hipoteses`, mas o campo `dominio` fica vazio.
61
+ _CONFIANCA_MINIMA_DOMINIO = 0.5
62
+
63
+ _MAX_HIPOTESES = 4
64
+
65
+
66
+ def _coletar_evidencias(
67
+ nome_col: str,
68
+ detectado_padrao: str,
69
+ perfil: PerfilConteudo | None,
70
+ ) -> list[Evidencia]:
71
+ tokens = tokenizar(nome_col)
72
+ nome_limpo = normalizar(nome_col)
73
+
74
+ evidencias: list[Evidencia] = []
75
+ evidencias += por_padrao_conteudo(detectado_padrao)
76
+ evidencias += por_token_forte(tokens)
77
+ evidencias += por_fuzzy(nome_limpo, tokens)
78
+
79
+ if perfil is not None:
80
+ evidencias += por_gazetteer(perfil)
81
+ evidencias += por_assinatura_estrutural(perfil)
82
+
83
+ return evidencias
84
+
85
+
86
+ def _refinar_papel(papel: str | None, dominio: str | None, perfil: PerfilConteudo | None) -> str | None:
87
+ """Ajusta o papel com o que os outros dois sinais já sabem.
88
+
89
+ O eixo de domínio e a cardinalidade da coluna carregam informação que o
90
+ nome sozinho não dá, e são eles que separam dois pares que o motor
91
+ confundia:
92
+
93
+ - **nome de gente × nome de coisa** — `FULL_NAME` e `DEPARTMENT_NAME` têm o
94
+ mesmo qualificador. O que os separa é o domínio: departamento é estrutura
95
+ organizacional, e nome de departamento não é dado pessoal.
96
+ - **descrição × categoria** — `JOB_DESCRIPTION` (milhares de valores) é
97
+ texto livre; `SHIFT_TYPE_DESC` (poucos valores numa tabela grande) é uma
98
+ dimensão. Quem vai modelar precisa dessa diferença, e ela está no dado,
99
+ não no nome.
100
+ """
101
+ if papel == config.SEMANTICA_NOME_PESSOA:
102
+ if dominio is not None and dominio not in config.DOMINIOS_DE_PESSOA:
103
+ return config.SEMANTICA_ROTULO_ENTIDADE
104
+ elif papel == config.SEMANTICA_TEXTO_LIVRE and perfil is not None:
105
+ cardinalidade_de_dimensao = (
106
+ 1 < perfil.n_unicos <= config.CARDINALIDADE_MAX_CATEGORIA
107
+ and perfil.ratio_unicidade < 0.5
108
+ )
109
+ if cardinalidade_de_dimensao:
110
+ return config.SEMANTICA_CATEGORIA
111
+ return papel
112
+
113
+
114
+ def _montar_resultado(
115
+ evidencias: list[Evidencia], perfil: PerfilConteudo | None = None
116
+ ) -> dict[str, Any]:
117
+ ranking_papel = ranquear(evidencias, EIXO_PAPEL)
118
+ ranking_dominio = ranquear(evidencias, EIXO_DOMINIO)
119
+
120
+ papel, conf_papel, origem_papel, papel_conclusivo = escolher(ranking_papel)
121
+ dominio, conf_dominio, origem_dominio, _ = escolher(ranking_dominio)
122
+
123
+ # Domínio abaixo do piso não é afirmado: continua listado em `hipoteses`,
124
+ # mas não vira fato no relatório. `cod_dep` numa tabela sem nenhuma outra
125
+ # pista de estrutura organizacional é um palpite, não um achado — e é
126
+ # justamente esse caso que a segunda passada por contexto vai resolver (ou
127
+ # deixar em aberto, o que também é uma resposta honesta).
128
+ dominio_incerto = dominio is not None and conf_dominio < _CONFIANCA_MINIMA_DOMINIO
129
+ if dominio_incerto:
130
+ dominio, conf_dominio, origem_dominio = None, 0.0, "Sem evidência"
131
+
132
+ papel = _refinar_papel(papel, dominio, perfil)
133
+
134
+ # O papel estrutural manda porque é ele que decide o tratamento no
135
+ # pipeline. Papel "fraco" (Nome, Texto Descritivo) descreve a forma e não
136
+ # o assunto — aí o domínio é mais informativo.
137
+ if papel in PAPEIS_ESTRUTURAIS:
138
+ semantica, confianca, origem = papel, conf_papel, origem_papel
139
+ elif dominio is not None:
140
+ semantica, confianca, origem = dominio, conf_dominio, origem_dominio
141
+ elif papel is not None:
142
+ semantica, confianca, origem = papel, conf_papel, origem_papel
143
+ else:
144
+ semantica, confianca, origem = config.SEMANTICA_GENERICA, 0.0, "Unmatched"
145
+
146
+ hipoteses = sorted(
147
+ [{"semantica": r["categoria"], "eixo": eixo, "confianca": r["confianca"],
148
+ "evidencias": r["origens"][:3]}
149
+ for eixo, ranking in ((EIXO_PAPEL, ranking_papel), (EIXO_DOMINIO, ranking_dominio))
150
+ for r in ranking],
151
+ key=lambda h: -h["confianca"],
152
+ )[:_MAX_HIPOTESES]
153
+
154
+ return {
155
+ "semantica": semantica,
156
+ "papel": papel,
157
+ "dominio": dominio,
158
+ "confianca_score": round(confianca, 4),
159
+ "origem": origem,
160
+ # Conclusiva exige os *dois* eixos resolvidos — mas ambiguidade é ter
161
+ # candidatos empatados, não é não ter candidato nenhum. Uma coluna como
162
+ # `diretoria`, que só tem domínio e nenhum papel, está perfeitamente
163
+ # resolvida e precisa entrar no contexto que desambigua as vizinhas.
164
+ "conclusiva": not (bool(ranking_papel) and not papel_conclusivo) and not dominio_incerto,
165
+ "hipoteses": hipoteses,
166
+ }
167
+
168
+
169
+ def inferir_semantica(
170
+ nome_col: str,
171
+ detectado_padrao: str = "Nenhum",
172
+ perfil: PerfilConteudo | None = None,
173
+ ) -> dict[str, Any]:
174
+ """Infere papel, domínio e semântica primária de uma coluna isolada.
175
+
176
+ `perfil` habilita os detectores de conteúdo (gazetteer e assinatura
177
+ estrutural) — sem ele a inferência é só pelo nome.
178
+ """
179
+ return _montar_resultado(_coletar_evidencias(nome_col, detectado_padrao, perfil), perfil)
180
+
181
+
182
+ def inferir_semanticas_da_tabela(entradas: list[dict[str, Any]]) -> list[dict[str, Any]]:
183
+ """Infere a semântica de todas as colunas, com desambiguação por contexto.
184
+
185
+ Cada entrada é `{"nome": str, "padrao": str, "perfil": PerfilConteudo}`.
186
+
187
+ Passada 1 classifica cada coluna isoladamente. Passada 2 monta o perfil de
188
+ assunto da tabela a partir do que ficou confiante e reprocessa apenas as
189
+ colunas cuja escolha não foi conclusiva — é onde `cod_dep` numa tabela de
190
+ RH vira departamento em vez de dependente.
191
+ """
192
+ evidencias_por_coluna: list[list[Evidencia]] = []
193
+ resultados: list[dict[str, Any]] = []
194
+ for entrada in entradas:
195
+ evidencias = _coletar_evidencias(
196
+ str(entrada["nome"]), entrada.get("padrao", "Nenhum"), entrada.get("perfil")
197
+ )
198
+ evidencias_por_coluna.append(evidencias)
199
+ resultados.append(_montar_resultado(evidencias, entrada.get("perfil")))
200
+
201
+ contexto = _perfil_de_assunto(resultados)
202
+ if not contexto:
203
+ return resultados
204
+
205
+ for indice, (entrada, resultado) in enumerate(zip(entradas, resultados, strict=True)):
206
+ if resultado["conclusiva"]:
207
+ continue
208
+ extras = por_contexto_da_tabela(tokenizar(str(entrada["nome"])), contexto)
209
+ if not extras:
210
+ continue
211
+ resultados[indice] = _montar_resultado(
212
+ evidencias_por_coluna[indice] + extras, entrada.get("perfil")
213
+ )
214
+
215
+ return resultados
216
+
217
+
218
+ def _perfil_de_assunto(resultados: list[dict[str, Any]]) -> dict[str, float]:
219
+ """Resume de que a tabela trata, a partir das colunas já bem classificadas.
220
+
221
+ Só entram categorias estabelecidas com confiança: o contexto serve para
222
+ desempatar, e um contexto construído a partir de palpites propagaria o
223
+ erro para as colunas ambíguas em vez de resolvê-las.
224
+ """
225
+ forcas: dict[str, float] = {}
226
+ for resultado in resultados:
227
+ if not resultado["conclusiva"]:
228
+ continue
229
+ for categoria in (resultado["papel"], resultado["dominio"]):
230
+ if not categoria or categoria == config.SEMANTICA_GENERICA:
231
+ continue
232
+ if resultado["confianca_score"] < _CONFIANCA_MINIMA_CONTEXTO:
233
+ continue
234
+ forcas[categoria] = max(forcas.get(categoria, 0.0), resultado["confianca_score"])
235
+ return forcas
236
+
237
+
238
+ def semanticas_para_gap_analysis(registro: dict[str, Any]) -> list[str]:
239
+ """Todas as semânticas que uma coluna aporta a uma análise de cobertura.
240
+
241
+ Uma coluna `cod_departamento` habilita tanto requisitos de "Chave
242
+ Identificadora" quanto de "Estrutura Organizacional" — considerar só a
243
+ semântica primária deixaria esse tipo de requisito bloqueado por engano.
244
+ """
245
+ return [
246
+ v for v in (registro.get("semantica"), registro.get("papel"), registro.get("dominio"))
247
+ if v and v != config.SEMANTICA_GENERICA
248
+ ]
@@ -0,0 +1,177 @@
1
+ """Taxonomia e thresholds da inferência semântica.
2
+
3
+ Este módulo é só dado: categorias, regexes de vocabulário e limiares. Toda a
4
+ lógica que consome esses valores vive em `detectors.py`, `tokens.py` e
5
+ `vocabulary.py`.
6
+ """
7
+
8
+ # ── Nomes de categorias/papéis referenciados fora deste módulo ─────────────
9
+ SEMANTICA_GENERICA: str = "Genérico / Não mapeado"
10
+ SEMANTICA_DATA_CALENDARIO: str = "Data / Calendário"
11
+ SEMANTICA_CHAVE_ID: str = "Chave Identificadora (ID)"
12
+ SEMANTICA_TEXTO_LIVRE: str = "Texto Descritivo Livre"
13
+ SEMANTICA_NOME_PESSOA: str = "Nome / Identificação Pessoal"
14
+ # Nome *de coisa*: `DEPARTMENT_NAME`, `POSITION_NAME`. Sem este papel, tudo que
15
+ # terminava em `_NAME` virava nome de pessoa.
16
+ SEMANTICA_ROTULO_ENTIDADE: str = "Rótulo / Nome de Entidade"
17
+ # Coluna de descrição com poucos valores distintos é categoria, não texto: quem
18
+ # vai modelar precisa saber que aquilo vira dimensão, não campo livre.
19
+ SEMANTICA_CATEGORIA: str = "Categoria / Classificação"
20
+
21
+ # ── Thresholds gerais ────────────────────────────────────────────────────
22
+ THRESHOLD_FUZZY_PADRAO: float = 0.85
23
+ THRESHOLD_FUZZY_CURTO: float = 0.95
24
+
25
+ # ── Categorias fortes (match exato por token) ───────────────────────────────
26
+ CATEGORIAS_FORTES: dict[str, list[str]] = {
27
+ SEMANTICA_CHAVE_ID: [
28
+ "id", "cod", "codigo", "code", "key", "number", "matricula", "mat",
29
+ "cpf", "cnpj", "registro", "chave", "identifier", "iden", "nr", "num", "pk", "fk",
30
+ "sequencial",
31
+ ],
32
+ SEMANTICA_DATA_CALENDARIO: [
33
+ "date", "dt", "data", "time", "timestamp", "periodo", "competencia",
34
+ "admissao", "demissao", "nascimento", "vencimento", "inicio", "fim",
35
+ "prazo", "realizacao", "referencia", "vigencia", "expiracao",
36
+ # Sem "ano" cadastrado, o token não tinha vocabulário próprio e caía
37
+ # no palpite de abreviatura: "ano" é subsequência de "aluno"
38
+ # (a-n-o ⊂ al-u-n-o), e `ANO_BASE` saía marcada como dado pessoal
39
+ # (LGPD) com recomendação de mascarar — apagaria a série temporal
40
+ # inteira se aplicada sem checar.
41
+ "ano",
42
+ ],
43
+ "Status / Indicador / Flag": [
44
+ "status", "flg", "flag", "is", "has", "state", "situacao",
45
+ "enforced", "ativo", "inativo", "habilitado", "bloqueado",
46
+ ],
47
+ "Valor Financeiro": [
48
+ "salario", "salary", "wage", "remuneracao", "vlr", "valor",
49
+ "custo", "cost", "preco", "price", "receita", "revenue",
50
+ "despesa", "expense", "budget", "orcamento", "bonus",
51
+ "comissao", "honorario", "verba", "provisao", "encargo",
52
+ ],
53
+ "Quantidade / Métrica": [
54
+ "qtd", "quantidade", "count", "total", "volume", "horas", "dias", "carga",
55
+ "duracao", "frequencia", "score", "nota", "percentual", "pct",
56
+ "indice", "taxa", "ratio", "proporcao", "media",
57
+ ],
58
+ "Texto Descritivo Livre": [
59
+ "desc", "descricao", "description", "obs", "observacao", "comentario",
60
+ "justificativa", "detalhe", "motivo", "complemento", "historico",
61
+ "task", "function", "resumo", "anotacao", "mensagem",
62
+ ],
63
+ "Nome / Identificação Pessoal": [
64
+ "nome", "name", "colaborador", "funcionario", "empregado",
65
+ "pessoa", "participante", "aluno", "candidato", "usuario", "user",
66
+ ],
67
+ "Contato / Rede": [
68
+ "email", "mail", "telefone", "celular", "ramal",
69
+ "whatsapp", "contato", "fone", "phone",
70
+ ],
71
+ "Resultado de Avaliação": [
72
+ "resultado", "result", "aprovacao", "reprovacao", "conceito",
73
+ "avaliacao", "desempenho", "conclusao", "outcome", "performance",
74
+ "feedback", "rating", "classificacao",
75
+ ],
76
+ }
77
+
78
+ # ── Categorias fuzzy (Jaro-Winkler) ─────────────────────────────────────────
79
+ CATEGORIAS_FUZZY: dict[str, list[str]] = {
80
+ "Localização Geográfica": [
81
+ "country", "province", "city", "facility", "pais", "cidade",
82
+ "estado", "regiao", "municipio", "cep", "uf", "endereco", "local",
83
+ "latitude", "longitude", "bairro", "logradouro",
84
+ ],
85
+ "Estrutura Organizacional": [
86
+ "department", "company", "business", "hierarquia", "departamento",
87
+ "diretoria", "gerencia", "setor", "area", "divisao", "celula",
88
+ "squad", "lotacao", "unidade", "filial", "subsidiaria", "agencia",
89
+ "coordenacao", "superintendencia", "nucleo", "equipe", "time",
90
+ # Vocabulário de dado público brasileiro: sem "orgao"/"secretaria",
91
+ # `NOME_ORGAO_SUPERIOR` (nome do órgão do governo, não de pessoa)
92
+ # não tinha domínio nenhum pra competir com o default de nome
93
+ # pessoal do qualificador "nome".
94
+ "orgao", "secretaria", "ministerio", "autarquia",
95
+ ],
96
+ # Vocabulário de processo eleitoral (dados do TSE): sem domínio próprio,
97
+ # `NM_PARTIDO`/`NM_TIPO_ELEICAO` (nome do partido, tipo de eleição — não
98
+ # de pessoa) ficavam sem nada pra competir com o qualificador "nome" e
99
+ # saíam como dado pessoal. Não inclui "candidato" de propósito: um
100
+ # candidato é uma pessoa, e a coluna `NOME_CANDIDATO` precisa continuar
101
+ # sendo dado pessoal — misturar o termo aqui derrubaria isso.
102
+ "Processo Eleitoral": [
103
+ "eleicao", "partido", "pleito", "coligacao", "chapa", "urna",
104
+ "votacao", "sufragio", "candidatura",
105
+ ],
106
+ "Perfil do Colaborador": [
107
+ "gender", "nationality", "career", "workforce", "staff",
108
+ "genero", "nacionalidade", "idade", "raca", "escolaridade",
109
+ "deficiencia", "etnia",
110
+ ],
111
+ # Sem este domínio, `NOME_PRODUTO` não tinha nenhuma categoria de domínio
112
+ # para competir com "Perfil do Colaborador" vazio, e o papel "Nome" caía
113
+ # no default de nome de pessoa — mesmo bug de `DEPARTMENT_NAME`, só que
114
+ # sem um domínio já cadastrado para resolvê-lo. Qualquer "nome de coisa"
115
+ # que caia fora dos domínios já cadastrados ainda tem esse risco; este é o
116
+ # caso mais comum (produto/item/SKU), não uma cobertura exaustiva.
117
+ "Produto / Item": [
118
+ "product", "item", "sku", "merchandise", "produto", "mercadoria",
119
+ "insumo", "material", "ativo", "equipamento", "veiculo", "artigo",
120
+ "marca", "brand", "modelo", "model",
121
+ ],
122
+ "Cargo / Função": [
123
+ "cargo", "funcao", "nivel", "grade", "posicao", "categoria",
124
+ "classe", "faixa", "perfil", "role", "position", "job",
125
+ "title", "occupation",
126
+ ],
127
+ # Domínio financeiro separado do *papel* "Valor Financeiro": `cost_center_code`
128
+ # é uma chave (papel) que fala de custo (domínio). Sem esta categoria, a
129
+ # evidência de `cost` só tinha o eixo de papel para disputar, e a coluna
130
+ # saía como valor monetário — pronta para alguém somar um centro de custo.
131
+ "Financeiro / Custo": [
132
+ "custo", "cost", "centro de custo", "despesa", "orcamento", "budget",
133
+ "financeiro", "finance", "contabil", "fiscal", "conta", "rateio",
134
+ ],
135
+ "Curso / Treinamento": [
136
+ "curso", "treinamento", "capacitacao", "formacao", "modulo",
137
+ "trilha", "programa", "workshop", "disciplina", "tema",
138
+ "course", "training", "learning", "certificacao",
139
+ ],
140
+ }
141
+
142
+ # ── Qualificadores estruturais de nome de coluna ────────────────────────────
143
+ # Tokens que descrevem o *papel* da coluna, não a *entidade* de que ela trata.
144
+ # Em `nome_departamento` o `nome` é qualificador e `departamento` é a entidade:
145
+ # a coluna é sobre estrutura organizacional, não sobre uma pessoa. Sem essa
146
+ # distinção o desempate cai no comprimento da palavra e erra sistematicamente.
147
+ TOKENS_QUALIFICADORES: frozenset[str] = frozenset({
148
+ "id", "cod", "codigo", "code", "key", "chave", "pk", "fk", "nr", "num",
149
+ "number", "matricula", "mat", "iden", "identifier", "registro",
150
+ "nome", "name", "desc", "descricao", "description", "sigla", "abrev",
151
+ "tipo", "type", "categoria", "class", "flag", "flg", "status",
152
+ "qtd", "quantidade", "total", "vlr", "valor", "pct", "percentual",
153
+ "dt", "date", "data", "hora", "time", "timestamp",
154
+ # Unidade de duração: `PRAZO_ENTREGA_DIAS` tem `prazo` (que É data em outros
155
+ # contextos, como "data de prazo") competindo com `dias`, que qualifica a
156
+ # coluna como contagem, não data. Sem `dias` como borda, `prazo` vencia
157
+ # sozinho e uma coluna numérica de dias virava "Data / Calendário".
158
+ "dias",
159
+ # `SQ_CANDIDATO_FORNECEDOR` (dado real do TSE) é um número sequencial que
160
+ # referencia um candidato — não o nome dele. Sem `sequencial` como borda,
161
+ # `candidato` (palavra forte de nome de pessoa) vencia sozinho.
162
+ "sequencial",
163
+ })
164
+
165
+ # Peso do token qualificador no ranking semântico. Ele ainda conta (um
166
+ # `id_x` continua tendo cara de identificador) mas perde para a entidade
167
+ # quando as duas categorias competem.
168
+ PESO_TOKEN_QUALIFICADOR: float = 0.45
169
+ PESO_TOKEN_ENTIDADE: float = 1.0
170
+
171
+ # Domínios que falam de gente. Só neles um papel "Nome" é nome de pessoa: em
172
+ # `DEPARTMENT_NAME` (Estrutura Organizacional) o nome é de um departamento.
173
+ DOMINIOS_DE_PESSOA: frozenset[str] = frozenset({"Perfil do Colaborador"})
174
+
175
+ # Acima desta cardinalidade a coluna deixa de ser categoria e vira texto de
176
+ # verdade. 79 mil linhas com 4 valores distintos são uma dimensão.
177
+ CARDINALIDADE_MAX_CATEGORIA: int = 100