colsemantics 0.1.0__tar.gz

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,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Caio (https://github.com/Caio-Analytics)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,162 @@
1
+ Metadata-Version: 2.4
2
+ Name: colsemantics
3
+ Version: 0.1.0
4
+ Summary: Inferência semântica de colunas: descobre o papel (o que a coluna é) e o domínio (do que ela fala) a partir do nome, de abreviações corporativas e do conteúdo.
5
+ Author: Caio
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Caio-Analytics/colsemantics
8
+ Keywords: semantic,data-profiling,column-inference,pii,etl,pandas
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Developers
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
16
+ Classifier: Typing :: Typed
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: rapidfuzz>=3.0
21
+ Requires-Dist: unidecode>=1.3
22
+ Provides-Extra: dev
23
+ Requires-Dist: pytest>=8; extra == "dev"
24
+ Requires-Dist: mypy>=1.10; extra == "dev"
25
+ Requires-Dist: ruff>=0.6; extra == "dev"
26
+ Dynamic: license-file
27
+
28
+ # colsemantics
29
+
30
+ **Descobre o que uma coluna *é* e do que ela *fala* — a partir do nome, de
31
+ abreviações corporativas e do conteúdo.**
32
+
33
+ `cd_dpto_lot` não está em nenhum dicionário. Mas a abreviatura reconstrói
34
+ `codigo` / `departamento` / `lotacao`, o conteúdo confirma baixa
35
+ cardinalidade, e o resultado é uma coluna com **papel** "Chave Identificadora"
36
+ e **domínio** "Estrutura Organizacional" — com a confiança e a evidência que
37
+ levaram a essa conclusão.
38
+
39
+ ```python
40
+ from colsemantics import inferir_semantica
41
+
42
+ inferir_semantica("cd_dpto_lot")
43
+ # {
44
+ # "semantica": "Chave Identificadora (ID)",
45
+ # "papel": "Chave Identificadora (ID)",
46
+ # "dominio": "Estrutura Organizacional",
47
+ # "confianca_score": 0.87,
48
+ # "origem": "abreviatura 'cd' → 'codigo' + abreviatura 'lot' → 'lotacao'",
49
+ # "conclusiva": True,
50
+ # "hipoteses": [...],
51
+ # }
52
+ ```
53
+
54
+ ## Por que isso é diferente de inferir `dtype`
55
+
56
+ Toda ferramenta de profiling te diz que uma coluna é `int64` ou `object`.
57
+ Nenhuma te diz que `f27` é geografia porque os valores são siglas de UF, ou
58
+ que `DEPARTMENT_NAME` não é dado pessoal mesmo terminando em `_NAME`. É essa
59
+ segunda pergunta — **papel** (o que a coluna é: chave, data, valor
60
+ financeiro...) e **domínio** (do que ela fala: estrutura organizacional,
61
+ cargo, localidade...) — que `colsemantics` responde.
62
+
63
+ ## Como funciona
64
+
65
+ A inferência é uma **cascata de detectores independentes**, não um
66
+ `if/elif` em que o primeiro match vence:
67
+
68
+ 1. **Padrão de conteúdo validado** (CPF, CNPJ, e-mail...) — a pista mais forte que existe.
69
+ 2. **Token forte** — match exato contra um dicionário curado, com abreviações expandidas (`vl` → `valor`).
70
+ 3. **Fuzzy (Jaro-Winkler)** — nome parecido com uma palavra-chave de domínio, tolera erro de digitação.
71
+ 4. **Gazetteer de conteúdo** — os valores da coluna batem com um conjunto fechado conhecido (UFs, meses, sexo/gênero...), independente do nome.
72
+ 5. **Assinatura estrutural** — a *forma* dos dados (inteiro crescente e único, decimal de 2 casas assimétrico à direita...) sugere o papel.
73
+ 6. **Contexto da tabela** — colunas vizinhas já resolvidas desambiguam abreviaturas ambíguas (`dep` é departamento, dependente ou depósito — sozinho é insolúvel, trivial se a tabela já fala de RH).
74
+
75
+ Cada detector emite evidência com peso; a combinação é **noisy-OR**
76
+ (`1 - Π(1 - peso)`), não "o primeiro que responder". Pistas fracas se somam.
77
+
78
+ ## Instalação
79
+
80
+ ```bash
81
+ pip install colsemantics
82
+ ```
83
+
84
+ ## Uso
85
+
86
+ ### Uma coluna isolada
87
+
88
+ ```python
89
+ from colsemantics import inferir_semantica
90
+
91
+ inferir_semantica("nome_departamento")
92
+ # semântica = "Estrutura Organizacional" (domínio vence: "nome" é só a forma)
93
+
94
+ inferir_semantica("uf")
95
+ # semântica = "Localização Geográfica"
96
+ ```
97
+
98
+ ### Com o conteúdo da coluna (resolve nomes opacos)
99
+
100
+ ```python
101
+ from colsemantics import PerfilConteudo, inferir_semantica
102
+
103
+ perfil = PerfilConteudo(
104
+ tipo_dados="Texto",
105
+ valores_distintos=["SP", "RJ", "MG", "BA"],
106
+ n_unicos=4,
107
+ ratio_unicidade=4 / 40,
108
+ )
109
+ inferir_semantica("f27", perfil=perfil)["semantica"]
110
+ # "Localização Geográfica" — nenhuma análise do nome chegaria lá
111
+ ```
112
+
113
+ `PerfilConteudo` é um dataclass simples — todos os campos são opcionais além
114
+ dos primeiros, então passe só o que você já sabe sobre a coluna:
115
+
116
+ | campo | o que é |
117
+ |---|---|
118
+ | `tipo_dados` | `"Texto"`, `"Número Inteiro"`, `"Número Decimal"`, `"Booleano"`... |
119
+ | `valores_distintos` | amostra de valores únicos (usada pelo gazetteer) |
120
+ | `n_unicos`, `ratio_unicidade` | cardinalidade |
121
+ | `str_len_media`, `comprimento_fixo` | forma do texto |
122
+ | `assimetria`, `minimo`, `casas_decimais_fixas` | forma do número |
123
+ | `monotonica_crescente` | sinal de chave sequencial |
124
+
125
+ ### Uma tabela inteira (desambiguação por contexto)
126
+
127
+ ```python
128
+ from colsemantics import inferir_semanticas_da_tabela
129
+
130
+ resultados = inferir_semanticas_da_tabela([
131
+ {"nome": "matricula", "padrao": "Nenhum", "perfil": None},
132
+ {"nome": "nome_func", "padrao": "Nenhum", "perfil": None},
133
+ {"nome": "cod_dep", "padrao": "Nenhum", "perfil": None},
134
+ {"nome": "diretoria", "padrao": "Nenhum", "perfil": None},
135
+ ])
136
+ # "cod_dep" sozinho é ambíguo (departamento? dependente? depósito?).
137
+ # Com "diretoria" na mesma tabela, o contexto resolve para "Estrutura Organizacional".
138
+ ```
139
+
140
+ `padrao` é o que seu próprio detector de padrão estruturado encontrou no
141
+ conteúdo (`"CPF"`, `"CNPJ"`, `"UUID"`, `"E-mail"`, `"Telefone"`, `"CEP"` ou
142
+ `"Nenhum"`) — `colsemantics` não faz essa detecção, só consome o resultado.
143
+
144
+ ## O que a saída traz
145
+
146
+ ```python
147
+ {
148
+ "semantica": str, # papel estrutural, ou domínio quando o papel é só formal
149
+ "papel": str | None,
150
+ "dominio": str | None,
151
+ "confianca_score": float, # 0-1, noisy-OR das evidências
152
+ "origem": str, # por que — as evidências que decidiram
153
+ "conclusiva": bool, # False = havia ambiguidade, olhe "hipoteses"
154
+ "hipoteses": list[dict], # até 4 alternativas ranqueadas, com evidência cada
155
+ }
156
+ ```
157
+
158
+ ## Licença
159
+
160
+ MIT. Extraído do módulo de inferência semântica do
161
+ [Recon](https://github.com/Caio-Analytics/Recon), ferramenta de profiling de
162
+ dados desconhecidos.
@@ -0,0 +1,135 @@
1
+ # colsemantics
2
+
3
+ **Descobre o que uma coluna *é* e do que ela *fala* — a partir do nome, de
4
+ abreviações corporativas e do conteúdo.**
5
+
6
+ `cd_dpto_lot` não está em nenhum dicionário. Mas a abreviatura reconstrói
7
+ `codigo` / `departamento` / `lotacao`, o conteúdo confirma baixa
8
+ cardinalidade, e o resultado é uma coluna com **papel** "Chave Identificadora"
9
+ e **domínio** "Estrutura Organizacional" — com a confiança e a evidência que
10
+ levaram a essa conclusão.
11
+
12
+ ```python
13
+ from colsemantics import inferir_semantica
14
+
15
+ inferir_semantica("cd_dpto_lot")
16
+ # {
17
+ # "semantica": "Chave Identificadora (ID)",
18
+ # "papel": "Chave Identificadora (ID)",
19
+ # "dominio": "Estrutura Organizacional",
20
+ # "confianca_score": 0.87,
21
+ # "origem": "abreviatura 'cd' → 'codigo' + abreviatura 'lot' → 'lotacao'",
22
+ # "conclusiva": True,
23
+ # "hipoteses": [...],
24
+ # }
25
+ ```
26
+
27
+ ## Por que isso é diferente de inferir `dtype`
28
+
29
+ Toda ferramenta de profiling te diz que uma coluna é `int64` ou `object`.
30
+ Nenhuma te diz que `f27` é geografia porque os valores são siglas de UF, ou
31
+ que `DEPARTMENT_NAME` não é dado pessoal mesmo terminando em `_NAME`. É essa
32
+ segunda pergunta — **papel** (o que a coluna é: chave, data, valor
33
+ financeiro...) e **domínio** (do que ela fala: estrutura organizacional,
34
+ cargo, localidade...) — que `colsemantics` responde.
35
+
36
+ ## Como funciona
37
+
38
+ A inferência é uma **cascata de detectores independentes**, não um
39
+ `if/elif` em que o primeiro match vence:
40
+
41
+ 1. **Padrão de conteúdo validado** (CPF, CNPJ, e-mail...) — a pista mais forte que existe.
42
+ 2. **Token forte** — match exato contra um dicionário curado, com abreviações expandidas (`vl` → `valor`).
43
+ 3. **Fuzzy (Jaro-Winkler)** — nome parecido com uma palavra-chave de domínio, tolera erro de digitação.
44
+ 4. **Gazetteer de conteúdo** — os valores da coluna batem com um conjunto fechado conhecido (UFs, meses, sexo/gênero...), independente do nome.
45
+ 5. **Assinatura estrutural** — a *forma* dos dados (inteiro crescente e único, decimal de 2 casas assimétrico à direita...) sugere o papel.
46
+ 6. **Contexto da tabela** — colunas vizinhas já resolvidas desambiguam abreviaturas ambíguas (`dep` é departamento, dependente ou depósito — sozinho é insolúvel, trivial se a tabela já fala de RH).
47
+
48
+ Cada detector emite evidência com peso; a combinação é **noisy-OR**
49
+ (`1 - Π(1 - peso)`), não "o primeiro que responder". Pistas fracas se somam.
50
+
51
+ ## Instalação
52
+
53
+ ```bash
54
+ pip install colsemantics
55
+ ```
56
+
57
+ ## Uso
58
+
59
+ ### Uma coluna isolada
60
+
61
+ ```python
62
+ from colsemantics import inferir_semantica
63
+
64
+ inferir_semantica("nome_departamento")
65
+ # semântica = "Estrutura Organizacional" (domínio vence: "nome" é só a forma)
66
+
67
+ inferir_semantica("uf")
68
+ # semântica = "Localização Geográfica"
69
+ ```
70
+
71
+ ### Com o conteúdo da coluna (resolve nomes opacos)
72
+
73
+ ```python
74
+ from colsemantics import PerfilConteudo, inferir_semantica
75
+
76
+ perfil = PerfilConteudo(
77
+ tipo_dados="Texto",
78
+ valores_distintos=["SP", "RJ", "MG", "BA"],
79
+ n_unicos=4,
80
+ ratio_unicidade=4 / 40,
81
+ )
82
+ inferir_semantica("f27", perfil=perfil)["semantica"]
83
+ # "Localização Geográfica" — nenhuma análise do nome chegaria lá
84
+ ```
85
+
86
+ `PerfilConteudo` é um dataclass simples — todos os campos são opcionais além
87
+ dos primeiros, então passe só o que você já sabe sobre a coluna:
88
+
89
+ | campo | o que é |
90
+ |---|---|
91
+ | `tipo_dados` | `"Texto"`, `"Número Inteiro"`, `"Número Decimal"`, `"Booleano"`... |
92
+ | `valores_distintos` | amostra de valores únicos (usada pelo gazetteer) |
93
+ | `n_unicos`, `ratio_unicidade` | cardinalidade |
94
+ | `str_len_media`, `comprimento_fixo` | forma do texto |
95
+ | `assimetria`, `minimo`, `casas_decimais_fixas` | forma do número |
96
+ | `monotonica_crescente` | sinal de chave sequencial |
97
+
98
+ ### Uma tabela inteira (desambiguação por contexto)
99
+
100
+ ```python
101
+ from colsemantics import inferir_semanticas_da_tabela
102
+
103
+ resultados = inferir_semanticas_da_tabela([
104
+ {"nome": "matricula", "padrao": "Nenhum", "perfil": None},
105
+ {"nome": "nome_func", "padrao": "Nenhum", "perfil": None},
106
+ {"nome": "cod_dep", "padrao": "Nenhum", "perfil": None},
107
+ {"nome": "diretoria", "padrao": "Nenhum", "perfil": None},
108
+ ])
109
+ # "cod_dep" sozinho é ambíguo (departamento? dependente? depósito?).
110
+ # Com "diretoria" na mesma tabela, o contexto resolve para "Estrutura Organizacional".
111
+ ```
112
+
113
+ `padrao` é o que seu próprio detector de padrão estruturado encontrou no
114
+ conteúdo (`"CPF"`, `"CNPJ"`, `"UUID"`, `"E-mail"`, `"Telefone"`, `"CEP"` ou
115
+ `"Nenhum"`) — `colsemantics` não faz essa detecção, só consome o resultado.
116
+
117
+ ## O que a saída traz
118
+
119
+ ```python
120
+ {
121
+ "semantica": str, # papel estrutural, ou domínio quando o papel é só formal
122
+ "papel": str | None,
123
+ "dominio": str | None,
124
+ "confianca_score": float, # 0-1, noisy-OR das evidências
125
+ "origem": str, # por que — as evidências que decidiram
126
+ "conclusiva": bool, # False = havia ambiguidade, olhe "hipoteses"
127
+ "hipoteses": list[dict], # até 4 alternativas ranqueadas, com evidência cada
128
+ }
129
+ ```
130
+
131
+ ## Licença
132
+
133
+ MIT. Extraído do módulo de inferência semântica do
134
+ [Recon](https://github.com/Caio-Analytics/Recon), ferramenta de profiling de
135
+ dados desconhecidos.
@@ -0,0 +1,61 @@
1
+ [project]
2
+ name = "colsemantics"
3
+ version = "0.1.0"
4
+ description = "Inferência semântica de colunas: descobre o papel (o que a coluna é) e o domínio (do que ela fala) a partir do nome, de abreviações corporativas e do conteúdo."
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ authors = [{ name = "Caio" }]
8
+ requires-python = ">=3.10"
9
+ keywords = ["semantic", "data-profiling", "column-inference", "pii", "etl", "pandas"]
10
+ classifiers = [
11
+ "Development Status :: 3 - Alpha",
12
+ "Intended Audience :: Developers",
13
+ "Programming Language :: Python :: 3",
14
+ "Programming Language :: Python :: 3.10",
15
+ "Programming Language :: Python :: 3.11",
16
+ "Programming Language :: Python :: 3.12",
17
+ "Topic :: Software Development :: Libraries :: Python Modules",
18
+ "Typing :: Typed",
19
+ ]
20
+ dependencies = [
21
+ "rapidfuzz>=3.0",
22
+ "unidecode>=1.3",
23
+ ]
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/Caio-Analytics/colsemantics"
27
+
28
+ [project.optional-dependencies]
29
+ dev = ["pytest>=8", "mypy>=1.10", "ruff>=0.6"]
30
+
31
+ [build-system]
32
+ requires = ["setuptools>=68"]
33
+ build-backend = "setuptools.build_meta"
34
+
35
+ [tool.setuptools.packages.find]
36
+ where = ["src"]
37
+
38
+ [tool.setuptools.package-data]
39
+ colsemantics = ["py.typed"]
40
+
41
+ [tool.pytest.ini_options]
42
+ testpaths = ["tests"]
43
+ python_files = ["test_*.py"]
44
+ python_classes = ["Test*"]
45
+ python_functions = ["test_*"]
46
+
47
+ [tool.ruff]
48
+ line-length = 100
49
+ src = ["src", "tests"]
50
+
51
+ [tool.ruff.lint]
52
+ select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
53
+ ignore = [
54
+ "E501", # comprimento de linha é responsabilidade do formatter
55
+ ]
56
+
57
+ [tool.mypy]
58
+ python_version = "3.10"
59
+ files = ["src/colsemantics"]
60
+ ignore_missing_imports = true
61
+ warn_unused_ignores = true
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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
+ ]