quantilica-core¶
Biblioteca de utilitários domain-neutral que serve como base para todos os coletores e pipelines Quantilica. Centraliza rede resiliente, armazenamento atômico, proveniência criptográfica e logging estruturado — permitindo que cada pacote de domínio foque exclusivamente na lógica da sua fonte.
A regra de ouro é a neutralidade de domínio. O
quantilica-corenão sabe o que é SIDRA, DATASUS ou Tesouro Nacional. Ele lida exclusivamente com abstrações técnicas (HTTP, FTP, storage, manifestos, logging).
Instalação¶
uv add quantilica-core
Anatomia de um download Quantilica¶
Os três blocos de construção que todo coletor do ecossistema usa:
from quantilica.core.http import HttpClient
from quantilica.core.storage import LocalStorage
from quantilica.core.manifests import DownloadManifest, write_manifest_sidecar
# 1. HTTP resiliente — retry com backoff exponencial
client = HttpClient(attempts=3)
response = client.get("https://servicodados.ibge.gov.br/api/v3/agregados/1705/metadados")
# 2. Storage atômico — escrita sem deixar arquivo corrompido em caso de falha
storage = LocalStorage("dados/raw")
stat = storage.write_bytes("sidra/agregado-1705.json", response.content)
# 3. Manifesto SHA-256 — proveniência criptográfica do artefato
manifest = DownloadManifest.from_file(
source_id="ibge",
dataset_id="sidra-1705",
url="https://servicodados.ibge.gov.br/...",
file_path=stat.path,
producer="ibge-sidra-fetcher",
)
write_manifest_sidecar(stat.path, manifest)
Resultado em disco:
dados/raw/sidra/
├── agregado-1705.json
└── agregado-1705.json.manifest.json ← schema v2: SHA-256, URL, timestamp, producer, source_meta
Módulos¶
| Módulo | Responsabilidade |
|---|---|
http |
HttpClient e AsyncHttpClient com retentativas, backoff exponencial e download_with_manifest |
ftp |
Cliente FTP resiliente para fontes legadas (DATASUS, PDET) com download_with_manifest |
retry |
Lógica configurável para falhas de rede e erros transientes |
storage |
LocalStorage e BaseDataRepository para artefatos brutos e processados |
files |
Escrita atômica, cálculo incremental de SHA-256, descompactação (decompress_archive) e validação de payload (check_payload) |
manifests |
DownloadManifest (schema v2, MANIFEST_VERSION = 2), DatasetManifest, RunManifest e helpers de sidecar .manifest.json |
sync |
Probes de frescor (HttpFreshnessProbe, FtpFreshnessProbe), políticas de skip (should_skip) e validação estrita (is_manifest_valid) |
lake |
Contrato do Lake Hive (lake_root, file_key, DatasetDescriptor, select_current, materialize_view) |
logging |
get_logger, log_step — logging estruturado padronizado |
exceptions |
Hierarquia comum: FetchError, ParseError, StorageError, CorruptPayloadError |
Manifestos de proveniência (manifests — Schema v2)¶
O módulo quantilica.core.manifests define o contrato de proveniência criptográfica na versão MANIFEST_VERSION = 2:
DownloadManifest: manifesto individual por arquivo baixado (<arquivo>.manifest.json). Registra a identidade do recurso (source_id,dataset_id,resource_id,url,path), integridade (sha256,size_bytes,fetched_at), autoria (producer,producer_version),manifest_version = 2e 5 grupos opcionais de enriquecimento:source_meta(SourceMetadata):etag,last_modified,published_at,expected_cadencefingerprint(ContentFingerprint):content_type,schema_hash,row_count,column_count,temporal_extent,geographic_extentlineage(Lineage):derived_from,pipeline_idquality(QualitySignals):validation_status,null_ratio,diff_from_previousexecution(ExecutionInfo):duration_ms,retry_count,environment,data_license- Helpers de sidecar:
write_manifest_sidecar(target, manifest),read_manifest_sidecar(target),manifest_sidecar_path(target)eis_manifest_valid(manifest_path)(emquantilica.core.sync). - Lotes e execuções:
DatasetManifest(snapshot de múltiplosDownloadManifest) eRunManifest/ExecutionManifest(rastreamento de início, fim e status de uma execução).
Para a anatomia completa do .manifest.json v2, tabelas de campos e exemplos de leitura, enriquecimento e injeção em Parquet, veja Proveniência & Manifestos.
Por que isso importa¶
Sem quantilica-core, cada fetcher precisaria:
- Escrever seu próprio retry com backoff.
- Lidar com falhas parciais de download (arquivo truncado no disco).
- Inventar um formato de proveniência (e raramente fazer SHA-256).
- Decidir um padrão de logging que ninguém mais segue.
Com o core, esses são problemas resolvidos uma vez para sempre. O fetcher fica enxuto e foca no que é específico da fonte — parsear o XML do Siscomex, navegar o FTP do DATASUS, traduzir o JSON do IBGE.
Princípios¶
- Neutralidade de domínio — o core nunca sabe que existe IBGE, DATASUS, INMET.
- Leveza — dependências mínimas no núcleo; integrações pesadas ficam em
quantilica-analytics. - Estabilidade — testes automatizados para HTTP, storage, manifestos, FTP, retry e sync.
- DX — APIs tipadas e tratamento de erro consistente em toda a organização.
Veja também os Princípios de Design do ecossistema como um todo.