Ir para o conteúdo

Dados Locais dos Clientes

Esta pasta contém os dados ingeridos via MQTT de cada cliente federado, usados para execução local e em Docker dos experimentos. Nada aqui é escrito manualmente pelo pesquisador — todo o conteúdo é gerado por DataComponent/MqttTimeSeriesIngestor a partir de dados recebidos via MQTT (ver docs/componentes/07-data-component.md para a API completa e docs/componentes/16-simulacao-dataset-generico.md para como os dados chegam até o MQTT a partir de um dataset).

BL-091: a partir desta versão, timeseries.db é a única fonte de leitura de DataComponent.loadLocalCdmRepository(...) (o caminho de treino). A estrutura antiga data/{client_id}/{experiment_id}/dataset.csv não é mais necessária nem lida por esse caminho — deixou de existir a obrigação de materializar um snapshot por cliente antes de treinar.

Estrutura atual

data/
  timeseries.db                    # SQLite único, compartilhado por todos os clientes/experimentos
                                    # (tabelas mqtt_observations, mqtt_events, mqtt_entities;
                                    #  store padrão — TIMESERIES_STORE=sqlite)
  {client_id}/
    {experiment_id}/
      dataset.csv                  # OPCIONAL — snapshot legado, só existe se alguém chamar
      metadata.json                # DataComponent.materializeDatasetFromStore(...)/dataset(...)
                                    # diretamente (loaders legados fora do pipeline MQTT genérico;
                                    # loadLocalCdmRepository() nunca lê esses dois arquivos)
      observations_ts.csv          # somente se TIMESERIES_STORE=csv (store legado por arquivo)
      events_ts.csv                # idem
      entities_ts.csv              # idem

timeseries.db é a fonte de verdade e o único caminho de leitura para treino. dataset.csv/ metadata.json continuam existindo como um recurso opcional de depuração/exportação manual (via DataComponent.dataset(...)/materializeDatasetFromStore(...), preservados para os loaders legados Ecg5000DatasetLoader/HarDatasetLoader) — mas loadLocalCdmRepository(), usado por todo o pipeline de treino, nunca consulta esses dois arquivos.

Isolamento físico em Docker (BL-091)

FederatedDockerClientExecutor não monta mais data/{client_id}/{experiment_id} no container. Em vez disso, a cada lançamento de container ele exporta — via ClientTimeSeriesExporter, a partir do timeseries.db compartilhado desta pasta — um timeseries.db filtrado, contendo só as linhas do cliente/experimento daquele container, e monta esse arquivo filtrado (não o diretório) em /app/data/timeseries.db:ro. O container nunca tem acesso ao timeseries.db compartilhado inteiro, preservando a invariante "não permitir dados brutos fora do cliente" mesmo sem a estrutura de diretório por cliente.

metadata.json — exemplo real (quando gerado manualmente)

{
  "client_id": "1",
  "experiment_id": "exp-mnist-digits-001",
  "dataset_file": "dataset.csv",
  "records": 7860,
  "created_at": "2026-07-14T18:38:16.402797Z",
  "notes": ["source=mqtt", "observations=7850", "events=10"]
}

dataset.csv — cabeçalho fixo

record_type,record_id,entity_id,property_or_event,value_numeric,value_text,unit,timestamp

Uma linha por observação (record_type=observation) ou evento (record_type=event) do CDM local do cliente — nunca o formato bruto do dataset de origem (ex.: não são as colunas pixel_0..pixel_783 do MNIST; essas viram uma linha cada, identificadas por property_or_event).

Como os dados chegam até aqui (pipeline obrigatório)

Fonte do dataset (CSV real ou fallback sintético)
    │
    │ CsvDatasetSimulationSource / {Dataset}MqttSimulationAdapter
    │ (ver docs/componentes/16-simulacao-dataset-generico.md)
    ▼
MqttDatasetReplaySimulator.replayRepository(...)   → publica MqttEnvelope assinado via MQTT
    ▼
DataComponent.subscribeToMqttSource(...)            → assina ANTES da publicação
    │
    ▼
MqttTimeSeriesIngestor  → verifica assinatura → grava em timeseries.db
    │
    │ DataComponent.loadLocalCdmRepository(...)  ← lê direto daqui (BL-091)
    ▼
InMemoryLocalCdmRepository

Proveniência MQTT é garantida estruturalmente, não por arquivo (BL-091): o único escritor de produção de timeseries.db (appendObservation/appendEvent) é MqttTimeSeriesIngestor, que só grava depois de envelope.verify(signatureService) ter sucesso — logo, a simples presença de dados na store para (clientId, experimentId) já comprova que passaram pela verificação de assinatura MQTT. DataComponent.loadLocalCdmRepository(...) lança IllegalStateException apenas quando não há dado nenhum na store para o par consultado; não existe mais checagem de metadata.json. Não existe caminho de "carregar CSV bruto do dataset diretamente" — todo experimento novo deve seguir o pipeline acima.

Regras

  • client_id deve ser um inteiro positivo (validado por ClientExperimentDataStore, ainda usado pelo caminho legado de dataset()/materializeDatasetFromStore()).
  • Todo dado de treino trafega por timeseries.db — loadLocalCdmRepository() lança IllegalStateException se não houver observações/eventos/entidades na store para o par (clientId, experimentId).
  • Código de treinamento (TrainingLocalModel) nunca acessa esta pasta diretamente — recebe context.authorizedDataView(), filtrado por AuthorizedTrainingViewBuilder a partir do repositório carregado por DataComponent.
  • Nenhum loader de dataset deve escrever diretamente em timeseries.db — sempre passar pelo pipeline MQTT ({Dataset}MqttSimulationAdapter + MqttDatasetReplaySimulator ou o motor genérico CsvDatasetSimulationSource, nunca escrita direta em disco).
  • Datasets de teste definidos no contrato não devem ser colocados nesta árvore, pois não pertencem a nenhum cliente (ver seção abaixo).

Dataset de teste contratual

Se o pesquisador definir um dataset de teste em EvaluationDatasetSpec, ele deve ficar sob controle do pesquisador/agregador, por exemplo em research/datasets/{dataset_id} ou em um Artifact Experiment Service com URI e hash registrados no contrato.

Esse dataset:

  • nunca é enviado aos clientes;
  • nunca é montado nos containers dos clientes;
  • nunca é usado para construir a visão autorizada de treinamento;
  • pode ser usado para avaliar modelos locais submetidos e modelo global candidato.

Não confundir com a segmentação train/test/validation do motor genérico de simulação (BL-088, ver docs/componentes/16-simulacao-dataset-generico.md): aquela decide quais linhas de um dataset simulado são publicadas aos clientes via MQTT (train+test) versus retidas como holdout central (validation) — ainda assim, tudo o que é publicado aos clientes passa pelo pipeline acima e termina materializado nesta pasta.

Variáveis de ambiente

Variável Padrão Descrição
HDT_AF_DATA_ROOT (alias DATA_ROOT) data Raiz desta árvore de dados
TIMESERIES_STORE sqlite sqlite (padrão, timeseries.db) ou csv (legado, *_ts.csv por cliente/experimento)

Execução Docker (BL-091)

Em containers, HDT_AF_DATA_ROOT=/app/data continua sendo a variável usada por ExperimentRuntimePaths.dataRoot()/DataComponent. O que muda é o que é montado nesse caminho:

{export filtrado por cliente}/timeseries.db -> /app/data/timeseries.db:ro

FederatedDockerClientExecutor gera esse arquivo automaticamente a cada lançamento de container — não é este data/timeseries.db compartilhado que é montado diretamente. O fluxo, por cliente:

  1. ClientTimeSeriesExporter.export(sourceDataRoot=data/, destinationDataRoot=target/docker-client-data/{experimentId}/round-{roundId}/{clientId}, clientId, experimentId) lê o timeseries.db compartilhado desta pasta e grava um timeseries.db novo contendo só as linhas de mqtt_observations/mqtt_events/mqtt_entities daquele (clientId, experimentId).
  2. O arquivo exportado é montado somente-leitura em /app/data/timeseries.db:ro.
  3. Dentro do container, DataComponent(ExperimentRuntimePaths.dataRoot()) resolve /app/data/timeseries.db normalmente — o código do cliente (DockerEcgClientApp, DockerHarClientApp) não muda nada, só passa a enxergar um banco pré-filtrado.

Assim o container de um cliente continua sem receber dados de outros clientes, sem depender da estrutura data/{client_id}/{experiment_id} — que deixou de ser criada/exigida para este fluxo.