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.
- colsemantics-0.1.0/LICENSE +21 -0
- colsemantics-0.1.0/PKG-INFO +162 -0
- colsemantics-0.1.0/README.md +135 -0
- colsemantics-0.1.0/pyproject.toml +61 -0
- colsemantics-0.1.0/setup.cfg +4 -0
- colsemantics-0.1.0/src/colsemantics/__init__.py +248 -0
- colsemantics-0.1.0/src/colsemantics/_taxonomy.py +177 -0
- colsemantics-0.1.0/src/colsemantics/detectors.py +362 -0
- colsemantics-0.1.0/src/colsemantics/evidence.py +82 -0
- colsemantics-0.1.0/src/colsemantics/py.typed +0 -0
- colsemantics-0.1.0/src/colsemantics/tokens.py +131 -0
- colsemantics-0.1.0/src/colsemantics/vocabulary.py +171 -0
- colsemantics-0.1.0/src/colsemantics.egg-info/PKG-INFO +162 -0
- colsemantics-0.1.0/src/colsemantics.egg-info/SOURCES.txt +16 -0
- colsemantics-0.1.0/src/colsemantics.egg-info/dependency_links.txt +1 -0
- colsemantics-0.1.0/src/colsemantics.egg-info/requires.txt +7 -0
- colsemantics-0.1.0/src/colsemantics.egg-info/top_level.txt +1 -0
- colsemantics-0.1.0/tests/test_colsemantics.py +384 -0
|
@@ -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,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
|
+
]
|