SDK reference

diagnos #

diagnos — zero-knowledge SDK for the diagnos vault. Everything an application needs is reachable from this top-level package: `Diagnos` is the entry point, `Settings` configures it, the record/model types shape what `patients`/`exams` read and write, and the exceptions are what a caller catches. Anything not exported here — `diagnos.resources`, `diagnos.session`, `diagnos.transport`, `diagnos.crypto` — is internal plumbing `cli`/`api` and application code are not meant to import directly (`CONTRIBUTING.md`): if something in there is missing from this list, that is a gap in the SDK's public surface, not a signal to reach past it.

• exception AuthenticationError 401 — token, session or signature rejected; usually re-enroll.
• exception ConfigError Missing or malformed configuration (env vars, token).
• exception ConflictError 409 — state disagrees (pending version, replay).
• exception CryptoError An envelope did not open or a format did not match the protocol. Deliberately one class: distinguishing "wrong key" from "tampered ciphertext" would hand an oracle to whoever is probing.
• class Diagnos The SDK's entry point: one service account's live connection to one workspace.
• exception DiagnosError Base of every SDK error.
• exception DiagnosPermissionError 403 — the service account may not do this here.
• class DocumentDraft A stream's mutable draft head: the web editor's autosave, overwritten in place, never a version.
• class DocumentIndex What the vault knows about a patient/exam/template (`docs/PROTOCOL.md §8`): keys, streams, clear metadata. Every field here is something the vault itself reads to route and authorize. The clinical content never appears on this model: it lives in the sealed object of each version, and a short sealed summary (name, title) lives in `encrypted_index`, which only a DEK holder opens. Exactly one `security_group_id` per document: sharing a patient with another team means copying it, never sharing its key.
• class DocumentListItem One row of a list: the index plus its decrypted summary — no version downloaded. `summary` is `None` when the document predates `encrypted_index` or belongs to a security group this session holds no key for.
• class DocumentStream One independent line of versions inside a document (`docs/PROTOCOL.md §8`). Exams and templates have a single stream, `data`. Patients have two: `data` (the structured record this SDK reads and writes) and `file` (the web editor's rich document, not exposed by the SDK yet).
• class DocumentVersion One committed version of a stream (`docs/PROTOCOL.md §8`) — metadata only, never content.
• class Drive One security group's files — the web app's "drive": list, upload, folders, download.
• class DriveNode One file or folder of a workspace (`docs/PROTOCOL.md §9`) — the vault's index of it, never its content. Every node has its own DEK, wrapped for its security group in `encrypted_keys`; the name stays sealed in `encrypted_name` until `name_of` opens it on demand (doing it eagerly for a whole page would mean an AES-GCM per row nobody asked for). A folder has no content and no upload fields; a file's `size` is what the vault measured, never just what was declared.
• class Drives `vault.drives` — the workspace's files across groups, and `drive(group)` for one group's.
• exception EnrollmentDeniedError A person denied this SDK session in the web app.
• exception EnrollmentExpiredError Nobody approved within the window; start again.
• class EnrollmentPrompt What a human needs to see: the link to open and the code to type.
• class Exam An exam as an application wants it: the index, the decrypted record and its summary.
• class ExamListItem One row of `vault.exams.list()`: the index plus the decrypted `ExamSummary` (title, modality, date).
• class Exams `vault.exams` — list, read, create, update, archive/unarchive, delete/restore.
• class ExamRecord The content of an exam version (`ExamContent` in the web app) — the report and its clinical context. `report_lexical` is the web editor's state (Lexical JSON, as a string) and is the source of truth; `report_html` is derived from it for readers that never open the editor. Write both when you produce a report, or the web editor opens an empty document.
• class ExamSummary The plaintext of an exam's `encrypted_index`: title, modality and date, derived from the record.
• exception GroupKeyUnavailable The SDK was never handed the DEK of this security group. This happens when an admin approves an enrollment for a narrower set of groups than the document being opened needs — a permissions gap, not a crypto failure, so it is its own exception rather than `CryptoError`.
• exception MemoryLockWarning Emitted once when the OS refused to lock at least one secret in RAM. The secret still has guard pages, no-dump and zero-on-drop; what it lost is the guarantee of never reaching swap. The fix is operational, not in code: raise `ulimit -l`, grant `CAP_IPC_LOCK`, or set `DIAGNOS_MEMORY_LOCK=require` to refuse to run this way.
• exception NotFoundError 404.
• class Page One page of a cursor-paginated list (`docs/PROTOCOL.md §8`/`§9`): `items` plus the cursor for the next call. `__iter__` yields `items` directly (not pydantic's default field-tuple iteration) so `for item in vault.patients.list(): ...` reads the way any Python sequence does — the field-tuple behaviour nobody wants here is still reachable through `dict(page)` if it were ever needed.
• class Patient A patient as an application wants it: the index, the decrypted record and its summary.
• class PatientAddress A patient's address; every field optional (an emergency registration may have none).
• class PatientListItem One row of `vault.patients.list()`: the index plus the decrypted `PatientSummary` (names, tags).
• class PatientRecord The `data` stream of a patient (`PatientData` in the web app) — everything here is sealed before upload. `birth_date` accepts a `date` or an aware `datetime` and is stored the way the web app stores it, as a UTC ISO 8601 instant. Set `Settings.time_precision` to truncate it to the workspace's anonymization precision before sealing, like the web app does.
• class PatientSummary The plaintext of a patient's `encrypted_index`: what a list shows without opening any version. The SDK derives it from the record on every write (plus `tags`, which are not a record field); it never carries identity documents, because opening the summary is not audited.
• class Patients `vault.patients` — list, read, create, update, archive/unarchive, delete/restore.
• class PersonalIdentifier An identity document (CPF, RG, passport…) whose `value` is sealed by the vault, not by this SDK. Opening one is audited server-side, which is why the value is `secret:v1:…` sealed material rather than plain text. The external API has no route to seal a new one yet: records read from the vault carry them through untouched, and a caller-built record must already hold sealed values. For a plain id from another system, use `PatientRecord.external_id`.
• exception ProtocolError The vault answered something the protocol does not allow (e.g. signed a size that is not the body's). Not the caller's fault and not retryable: report it with the SDK version, or upgrade if the vault moved on.
• exception QuotaError 402 — the workspace has no credit for this; nothing was done.
• exception RateLimitError 429 — slow down; the SDK already retried with backoff.
• exception SessionExpiredError The session keys are past `expires_at`; enroll again.
• class Settings Immutable SDK configuration, usually built by `from_env`.
• attribute TimePrecision A workspace's anonymization precision: every date is truncated to it before sealing (`Settings.time_precision`).
• class UploadSource One file for `upload_many`: the content plus its name and MIME type. `name` defaults to the file name of a path (or of an open file); a `bytes` or anonymous stream needs one explicitly — every node carries a sealed name. `mime_type` defaults to a guess from the name, which is what lets the vault classify DICOM, images and video.
• exception ValidationError 400/413 — the request itself is wrong; fix the input.
• exception VaultError The vault answered with an error envelope.
• function memory_status What the enclave guarantees right now (lock policy, unlocked allocations, limits).
• function to_iso_instant The web app's string for `value`, with no truncation. >>> to_iso_instant(date(1984, 3, 2)) '1984-03-02T00:00:00.000Z'
• function truncate_timestamp `truncateTimestamp` from the web app: zero everything finer than `precision`, in UTC. `month` sets the day to 1 (it keeps the month, it does not zero it). >>> truncate_timestamp("1984-03-17T15:42:10Z", "month") '1984-03-01T00:00:00.000Z'