# Cledon · Demonstrador da rede federada (dados fictícios)

> **DEMONSTRAÇÃO COM DADOS FICTÍCIOS.** Nenhum paciente real. Os números testam o software; não são evidência clínica.

Protótipo da arquitetura descrita na proposta (`../cledon-proposta.md`, seções 5, 10 e 11). Três hospitais simulados
guardam seus registros; um coordenador envia uma análise aprovada; cada hospital executa localmente e devolve só
agregados. O piloto simulado é o da proposta: prever a resposta patológica completa após quimiorradioterapia
neoadjuvante no carcinoma epidermoide de esôfago, com desenvolvimento nos hospitais A e B e teste externo no C.

## Como rodar

Requer Python 3 com `numpy` e `scipy` (o ambiente de `../analise/.venv` serve).

```bash
python gerar_dados_ficticios.py   # cria hospitais/A, B e C com pacientes fictícios e a aprovação local do protocolo
python coordenador.py             # executa o estudo e gera saida/relatorio.html
python testes.py                  # confere bloqueios, supressão, validação de entradas e federado = bases juntas
# para repetir o coordenador, rode antes gerar_dados_ficticios.py (o teste externo só aceita uma avaliação por modelo)
```

## O que cada parte faz

| Arquivo | Papel |
|---|---|
| `protocolo/protocolo-piloto-esofago.json` | Pergunta, desfecho, variáveis aprovadas, modelos, operações permitidas e controles de saída |
| `hospitais/X/pacientes_ficticios.csv` | Base local de cada hospital (fictícia). Inclui identificadores locais que nunca saem do hospital |
| `hospitais/X/aprovacoes.json` | Protocolos aprovados pelo hospital, pela impressão digital SHA-256 |
| `hospitais/X/auditoria_local.jsonl` | Registro de cada pedido recebido e da decisão (executado ou recusado) |
| `no.py` | Nó local: confere aprovação, operação e variáveis; executa; suprime células pequenas; bloqueia saídas em nível individual |
| `aprovacao_local.py` | Simula o passo institucional do hospital de teste: registrar um modelo congelado (num piloto real, feito pelo hospital, não pelo coordenador) |
| `saida/modelos_congelados/` | Modelos congelados antes do teste externo (coeficientes e impressão digital do protocolo) |
| `coordenador.py` | Envia pedidos aos nós (processos separados), nunca lê as bases, ajusta o modelo federado e gera o relatório |
| `testes.py` | Testes. Só aqui as bases fictícias são juntadas, para provar que o modelo federado é idêntico ao agrupado |
| `saida/relatorio.html` | As quatro telas da proposta: rede, protocolo, execução controlada e resultado |

## Controles demonstrados

- Protocolo identificado por SHA-256; versão alterada sem nova aprovação é recusada.
- Só operações e variáveis previstas no protocolo; pedido de CEP ou de exportação de linhas é recusado.
- Papel de cada hospital imposto pelo próprio nó: o hospital de teste externo recusa treino e só avalia um modelo
  congelado e registrado localmente, uma única vez.
- O protocolo 0.2 fixa também os casos usados na comparação, a semente e as reamostragens. A aprovação local não permite
  trocar a versão de um modelo já registrado sob o mesmo protocolo.
- Células com menos de 5 pessoas suprimidas, com supressão complementar; faltantes e observados de cada variável são
  suprimidos em conjunto em todas as operações, para que uma consulta não desfaça a supressão de outra.
- Campos categóricos vazios ou fora das categorias válidas, e números inválidos ou fora de faixas plausíveis, viram
  ausência (nunca a categoria de referência) e ficam fora dos modelos.
- Coeficientes com dimensão incorreta ou não finitos são recusados; grupos com menos de 5 respostas ou não respostas
  não liberam estatísticas do modelo. As faixas de validação são exemplos do demonstrador, a revisar no protocolo clínico.
- Modelo só roda com pelo menos 50 casos completos no hospital; limite de rodadas por protocolo.
- Verificação final bloqueia respostas com listas longas (possíveis dados individuais).
- Auditoria local em cada hospital e auditoria do coordenador.

## Limites

- Dados fictícios demonstram o funcionamento do software, não eficácia clínica, distribuição real de pacientes ou
  segurança definitiva. Os efeitos foram inventados em `gerar_dados_ficticios.py`.
- Gradientes e hessianas podem vazar informação com poucos casos ou muitas rodadas; o mínimo de casos e o limite de
  rodadas reduzem o risco, mas não são garantia formal. Num piloto real, o modelo de ameaças e controles como agregação
  segura e privacidade diferencial seriam avaliados com os hospitais.
- A supressão conjunta cobre faltantes e observados por variável; outras margens (como o número de casos completos de
  cada modelo) ainda podem ser combinadas entre consultas. Num piloto real, todas as saídas seriam registradas e checadas
  em conjunto antes da liberação.
- Os "hospitais" rodam no mesmo computador como processos separados. Num piloto real, cada nó ficaria na infraestrutura
  do hospital, com autenticação, criptografia, rede restrita e aprovação local de cada versão do código.
- O protocolo é um exemplo para o software, não um protocolo clínico: pergunta, desfecho, variáveis e tamanho de amostra
  seriam definidos com oncologistas, patologistas e bioestatísticos.

## PDFs de revisão

Na raiz do projeto, `gerar_pdfs_revisao.py` gera novamente os dois PDFs de `revisao-proposta-1.2/` e as cópias
publicadas em `documentos/` (cledon.org/documentos), a partir de `cledon-proposta.md` e
`demonstrador/saida/relatorio.html`. Requer `reportlab` (incluído em `../analise/requirements.txt`) e as fontes Arial
do macOS: `../analise/.venv/bin/python gerar_pdfs_revisao.py`.
As tabelas de discriminação e calibração são separadas e o aviso de dados fictícios se repete em todas as páginas.