Referência do SDK

diagnos #

diagnos — SDK zero-knowledge do cofre diagnos. Tudo que uma aplicação precisa é alcançável a partir deste pacote de primeiro nível: `Diagnos` é o ponto de entrada, `Settings` o configura, os tipos de registro/modelo dão forma ao que `patients`/`exams` leem e escrevem, e as exceções são o que quem chama captura. Qualquer coisa não exportada aqui — `diagnos.resources`, `diagnos.session`, `diagnos.transport`, `diagnos.crypto` — é encanamento interno que `cli`/`api` e código de aplicação não devem importar direto (`CONTRIBUTING.md`): se algo lá dentro está faltando nesta lista, é uma lacuna na superfície pública do SDK, não um sinal para alcançar por cima dela.

• exception AuthenticationError 401 — token, sessão ou assinatura recusados; em geral, refaça o enrollment.
• exception ConfigError Configuração ausente ou malformada (variáveis de ambiente, token).
• exception ConflictError 409 — o estado discorda (versão pendente, replay).
• exception CryptoError Um envelope não abriu ou um formato não bateu com o protocolo. Uma classe só, de propósito: distinguir "chave errada" de "ciphertext adulterado" daria um oráculo a quem estiver sondando.
• class Diagnos O ponto de entrada do SDK: a conexão viva de uma service account com um workspace.
• exception DiagnosError Base de todo erro do SDK.
• exception DiagnosPermissionError 403 — a service account não pode fazer isto aqui.
• class DocumentDraft A cabeça mutável de rascunho de um fluxo: o autosave do editor web, sobrescrito no lugar, nunca uma versão.
• class DocumentIndex O que o cofre sabe sobre um paciente/exame/modelo (`docs/PROTOCOL.md §8`): chaves, fluxos, metadado em claro. Todo campo aqui é algo que o próprio cofre lê para rotear e autorizar. O conteúdo clínico nunca aparece neste modelo: ele vive no objeto selado de cada versão, e um resumo selado curto (nome, título) vive em `encrypted_index`, que só quem tem a DEK abre. Exatamente um `security_group_id` por documento: compartilhar um paciente com outra equipe é copiá-lo, nunca compartilhar a chave.
• class DocumentListItem Uma linha de lista: o índice mais o resumo decifrado — nenhuma versão baixada. `summary` é `None` quando o documento é anterior ao `encrypted_index` ou pertence a um security group para o qual esta sessão não tem chave.
• class DocumentStream Uma linha independente de versões dentro de um documento (`docs/PROTOCOL.md §8`). Exames e modelos têm um fluxo só, `data`. Pacientes têm dois: `data` (o registro estruturado que este SDK lê e grava) e `file` (o documento rico do editor web, ainda não exposto pelo SDK).
• class DocumentVersion Uma versão confirmada de um fluxo (`docs/PROTOCOL.md §8`) — só metadado, nunca conteúdo.
• class Drive Os arquivos de um security group — o "drive" do app web: listar, subir, pastas, baixar.
• class DriveNode Um arquivo ou pasta de um workspace (`docs/PROTOCOL.md §9`) — o índice que o cofre tem dele, nunca o conteúdo. Todo nó tem a própria DEK, embrulhada para o security group em `encrypted_keys`; o nome fica selado em `encrypted_name` até `name_of` abri-lo sob demanda (fazer isso para uma página inteira significaria um AES-GCM por linha que ninguém pediu). Uma pasta não tem conteúdo nem campos de upload; o `size` de um arquivo é o que o cofre mediu, nunca só o declarado.
• class Drives `vault.drives` — os arquivos do workspace entre grupos, e `drive(grupo)` para os de um grupo.
• exception EnrollmentDeniedError Uma pessoa negou esta sessão de SDK no app web.
• exception EnrollmentExpiredError Ninguém aprovou dentro do prazo; comece de novo.
• class EnrollmentPrompt O que uma pessoa precisa ver: o link para abrir e o código para digitar.
• class Exam Um exame do jeito que uma aplicação quer: o índice, o registro decifrado e o resumo.
• class ExamListItem Uma linha de `vault.exams.list()`: o índice mais o `ExamSummary` decifrado (título, modalidade, data).
• class Exams `vault.exams` — listar, ler, criar, atualizar, arquivar/desarquivar, apagar/restaurar.
• class ExamRecord O conteúdo de uma versão de exame (`ExamContent` no app web) — o laudo e o contexto clínico. `report_lexical` é o estado do editor web (JSON do Lexical, como string) e é a fonte da verdade; `report_html` é derivado dele para leitores que nunca abrem o editor. Grave os dois ao produzir um laudo, senão o editor web abre um documento vazio.
• class ExamSummary O texto claro do `encrypted_index` de um exame: título, modalidade e data, derivados do registro.
• exception GroupKeyUnavailable O SDK nunca recebeu a DEK deste security group. Acontece quando um admin aprova um enrollment para um conjunto de grupos mais estreito do que o documento que está sendo aberto precisa — uma lacuna de permissão, não uma falha de cripto, por isso é exceção própria em vez de `CryptoError`.
• exception MemoryLockWarning Emitido uma vez quando o SO recusou travar pelo menos um segredo na RAM. O segredo ainda tem guard pages, sem dump e zero-ao-descartar; o que perdeu foi a garantia de nunca ir ao swap. A correção é operacional, não de código: aumente `ulimit -l`, conceda `CAP_IPC_LOCK`, ou defina `DIAGNOS_MEMORY_LOCK=require` para se recusar a rodar assim.
• exception NotFoundError 404.
• class Page Uma página de uma lista paginada por cursor (`docs/PROTOCOL.md §8`/`§9`): `items` mais o cursor para a próxima chamada. `__iter__` entrega `items` direto (não a iteração padrão do pydantic sobre pares campo-valor) para `for item in vault.patients.list(): ...` ler como qualquer sequência Python — o comportamento de tupla de campos que ninguém quer aqui ainda seria alcançável via `dict(page)` se um dia precisasse.
• class Patient Um paciente do jeito que uma aplicação quer: o índice, o registro decifrado e o resumo.
• class PatientAddress O endereço de um paciente; todo campo opcional (um cadastro de emergência pode não ter nenhum).
• class PatientListItem Uma linha de `vault.patients.list()`: o índice mais o `PatientSummary` decifrado (nomes, tags).
• class PatientRecord O fluxo `data` de um paciente (`PatientData` no app web) — tudo aqui é selado antes do upload. `birth_date` aceita `date` ou `datetime` com fuso e é gravado do jeito que o app web grava, como um instante ISO 8601 em UTC. Defina `Settings.time_precision` para truncá-lo à precisão de anonimização do workspace antes de selar, como o app web faz.
• class PatientSummary O texto claro do `encrypted_index` de um paciente: o que uma lista mostra sem abrir nenhuma versão. O SDK o deriva do registro a cada gravação (mais `tags`, que não são campo do registro); ele nunca carrega documento de identidade, porque abrir o resumo não é auditado.
• class Patients `vault.patients` — listar, ler, criar, atualizar, arquivar/desarquivar, apagar/restaurar.
• class PersonalIdentifier Um documento de identidade (CPF, RG, passaporte…) cujo `value` é selado pelo cofre, não por este SDK. Abrir um é auditado no servidor, por isso o valor é material selado `secret:v1:…` e não texto claro. A API externa ainda não tem rota para selar um novo: registros lidos do cofre os carregam intactos, e um registro montado por quem chama já precisa trazer valores selados. Para um id simples de outro sistema, use `PatientRecord.external_id`.
• exception ProtocolError O cofre respondeu algo que o protocolo não permite (ex.: assinou um tamanho que não é o do corpo). Não é culpa de quem chama e não adianta retentar: reporte com a versão do SDK, ou atualize se o cofre evoluiu.
• exception QuotaError 402 — o workspace não tem crédito para isto; nada foi feito.
• exception RateLimitError 429 — devagar; o SDK já tentou de novo com backoff.
• exception SessionExpiredError As chaves de sessão passaram de `expires_at`; refaça o enrollment.
• class Settings Configuração imutável do SDK, normalmente construída por `from_env`.
• attribute TimePrecision A precisão de anonimização de um workspace: toda data é truncada nela antes de selar (`Settings.time_precision`).
• class UploadSource Um arquivo para `upload_many`: o conteúdo mais o nome e o tipo MIME. `name` é, por padrão, o nome de arquivo de um path (ou de um arquivo aberto); `bytes` ou um stream anônimo precisam de um explícito — todo nó leva um nome selado. `mime_type` é, por padrão, um palpite pelo nome, o que deixa o cofre classificar DICOM, imagem e vídeo.
• exception ValidationError 400/413 — a requisição está errada; corrija a entrada.
• exception VaultError O cofre respondeu com um envelope de erro.
• function memory_status O que o enclave garante agora (política de travamento, alocações sem trava, limites).
• function to_iso_instant A string do app web para `value`, sem truncamento.
• function truncate_timestamp O `truncateTimestamp` do app web: zera tudo que é mais fino que `precision`, em UTC. `month` põe o dia em 1 (mantém o mês, não o zera).