Título Completo

Fundamentos de TypedDict Aplicados à Saúde

Autoria

Ricardo Costa Val do Rosário

1 Conceito

- O TypedDict, introduzido no módulo typing do Python a partir da versão 3.8, 
possibilita a definição de dicionários com chaves previamente estabelecidas e
tipagem explícita. 

- Ao contrário dos dicionários dinâmicos, essa abordagem estabelece um contrato
estrutural que potencializa a identificação de erros por ferramentas como MyPy e 
Pyright antes da execução do código. 

- O TypedDict harmoniza a flexibilidade dos dicionários tradicionais com a robustez 
da tipagem forte das classes, destacando-se em aplicações que envolvem estruturas 
similares a JSON, integração entre APIs, sistemas clínicos e promoção da reutilização 
de código, contribuindo também para a governança da informação em saúde.

- O TypedDict configura-se como uma solução estratégica para a padronização 
estrutural de dados clínicos, elevando expressivamente a confiabilidade de sistemas
hospitalares, sobretudo quando aplicado em:

1. Ambientes integrados
2. Plataformas de inteligência artificial
3. Sistemas de Tecnovigilância
4. Auditorias digitais
5. Governança da informação em saúde

- Ao adotar tipagem explícita e estruturação fixa, o TypedDict minimiza variações indesejadas, 
aprimora a previsibilidade computacional e reforça os fundamentos da segurança assistencial 
contemporânea.

2 Importância da Tipagem Estrutural em Sistemas de Saúde

- No ambiente hospitalar, TypedDict organiza dados clínicos com segurança, padronização e
rastreabilidade, sem perder agilidade no desenvolvimento. 

- A ausência de tipagem padronizada pode causar erros de processamento e riscos à segurança 
do paciente. 

- TypedDict antecipa a verificação da estrutura dos dados, previne falhas de tipagem e reforça 
a confiabilidade dos sistemas clínicos.

3 Estrutura Básica de um TypedDict

- A construção fundamental de um TypedDict segue o padrão:

from typing import TypedDict

class Exemplo(TypedDict):
    campo_1: str
    campo_2: int
    campo_3: bool

- Esse modelo estabelece:
1. Nomes de chaves obrigatórios
2. Tipos de dados esperados
3. Consistência estrutural válida por ferramentas estáticas

4 Exemplo Clínico 1 – Registro Estruturado de Paciente

# 4.1 Definição do Modelo de Paciente

from typing import TypedDict, List

class RegistroPaciente(TypedDict):
    patient_id: int
    nome: str
    idade: int
    diagnostico_principal: str
    alergias: List[str]
    medicamentos_em_uso: List[str]

# 4.2 Instância de Registro

paciente_01: RegistroPaciente = {
    "patient_id": 1001,
    "nome": "Maria Oliveira",
    "idade": 58,
    "diagnostico_principal": "Hipertensão Arterial Sistêmica",
    "alergias": ["Penicilina"],
    "medicamentos_em_uso": ["Losartana", "Hidroclorotiazida"]
}

# 4.3 Validação Estrutural
- Ferramentas como MyPy garantem que:
•	Todas as chaves exigidas estejam presentes
•	Nenhum tipo incompatível seja atribuído
•	Nenhuma chave inexistente seja introduzida

-  Impacto direto:
•	Redução de erros de integração
•	Melhora da interoperabilidade
•	Segurança assistencial ampliada

5 Exemplo Clínico 2 – Evento Adverso e Tecnovigilância

# 5.1 Definição do Evento Adverso

class EventoAdverso(TypedDict):
    evento_id: int
    dispositivo: str
    tipo_falha: str
    gravidade: str
    data_evento: str  # formato ISO: YYYY-MM-DD
    paciente_id: int
    notificado_anvisa: bool

# 5.2 Registro do Evento

evento_tecno_01: EventoAdverso = {
    "evento_id": 3001,
    "dispositivo": "Bomba de Infusão",
    "tipo_falha": "Interrupção inesperada",
    "gravidade": "Alta",
    "data_evento": "2025-12-01",
    "paciente_id": 1001,
    "notificado_anvisa": True
}

 - Aplicação direta:
•	Padronização da Tecnovigilância
•	Rastreabilidade institucional
•	Base estruturada para auditorias
•	Integração com sistemas externos

6 Exemplo Clínico 3 – Dados para Inteligência Artificial e Monitoramento

# 6.1 Modelo de Sinais Vitais

class SinaisVitais(TypedDict):
    paciente_id: int
    frequencia_cardiaca: int
    pressao_arterial: str
    saturacao_oxigenio: float
    temperatura: float
    data_hora: str

# 6.2 Uso em Monitoramento Automatizado

monitoramento_01: SinaisVitais = {
    "paciente_id": 1001,
    "frequencia_cardiaca": 118,
    "pressao_arterial": "170/100",
    "saturacao_oxigenio": 92.5,
    "temperatura": 38.4,
    "data_hora": "2025-12-02 14:32"
}

-  Esses dados podem alimentar:
•	Dashboards clínicos
•	Sistemas de alerta automatizado
•	Modelos de Machine Learning
•	Sistemas de apoio à decisão clínica