Clinical Context

SauBit's Clinical Context keeps or processes the clinical information essential for the medication-safety analysis. It does not replace the hospital's official electronic medical record — the hospital system remains the source of truth.

Copia um prompt pronto com fluxo de integração, payload e exemplos.

What it is · What it isn't

• It is: a minimal, optional longitudinal profile (medications, allergies, conditions, key labs, renal/hepatic function, pregnancy) that improves future analyses.
• It isn't: an EMR/HIS, multidisciplinary notes, e-prescribing, inpatient, hospital billing or a complete legal record.

Two operating modes

SauBit runs in two modes, set per request in processing_options.context_mode (within the organization policy limits):

Mode	Behavior
stateless	Receives, normalizes and analyzes the payload; does not load or update the longitudinal profile. Maximum minimization — ideal for hospitals with their own EMR.
persistent_context	Loads the existing profile, optionally updates it (update_clinical_context) and uses the consolidated context for the analysis.

Audit snapshot (independent option)

create_audit_snapshot: true records, immutably, the exact context used for that analysis (with a hash and engine/rules/database versions). Works in either mode. The snapshot is not editable or overwritten; later context changes do not affect it.

GET /api/v1/clinical-context/snapshots/{snapshot_id}
GET /api/v1/clinical-context/analyses/{analysis_id}/snapshot

Per-organization policy (authority)

The organization defines the policy (default mode, whether persistent context/snapshots are allowed, per-domain persistence, retention, zero_retention). The request never widens permissions — it can only narrow. With zero_retention: no persistent context, no snapshots, only minimal technical metadata.

The policy is configured via admin routes (Admin Swagger): GET/PUT/DELETE /api/v1/admin/organizations/{org_id}/clinical-context-policy. Client view of the effective policy: GET /api/v1/clinical-context/policies/current.

data_handling in the analysis response

Every analysis reports how data was handled:

"data_handling": {
  "requested_mode": "persistent_context",
  "effective_mode": "stateless",
  "clinical_context_updated": false,
  "audit_snapshot_created": true,
  "policy_restrictions_applied": ["organization_disallows_persistent_context"]
}

Endpoints (client)

GET    /api/v1/clinical-context/patients/{patient_reference}
PUT    /api/v1/clinical-context/patients/{patient_reference}
PATCH  /api/v1/clinical-context/patients/{patient_reference}
DELETE /api/v1/clinical-context/patients/{patient_reference}   # ?purge=true = hard delete (LGPD)
GET    /api/v1/clinical-context/policies/current
GET    /api/v1/clinical-context/snapshots/{snapshot_id}
GET    /api/v1/clinical-context/analyses/{analysis_id}/snapshot

Scopes: clinical_context:read / clinical_context:write (interchangeable with the legacy prontuario:*).

Examples in the analysis

// stateless, no snapshot
{ "medications": [], "patient_reference": "patient-token-123",
  "processing_options": { "context_mode": "stateless", "create_audit_snapshot": false } }

// persistent context + snapshot + partial update
{ "medications": [], "patient_reference": "patient-token-123", "encounter_reference": "encounter-123",
  "clinical_context": {}, "processing_options": {
    "context_mode": "persistent_context", "update_clinical_context": true, "create_audit_snapshot": true,
    "persistence_overrides": { "medications": true, "observations": false } } }

Pseudonymization and LGPD

patient_reference is usually a pseudonym (re-linkable by the controller) — not anonymization. Health data is still sensitive personal data. See LGPD.

Migrating the legacy routes (/prontuario)

The /api/v1/prontuario/* routes keep working but are deprecated (they return Deprecation: true + Sunset + Link to /clinical-context). Migrate to /clinical-context.

FHIR compatibility

Clinical Context maps to Patient, Encounter, MedicationRequest/Statement, AllergyIntolerance, Condition, Observation, Provenance and Consent (see FHIR R4). FHIR identifiers/versions/provenance are preserved.

Policy errors

CLINICAL_CONTEXT_MODE_NOT_ALLOWED · PERSISTENT_CONTEXT_DISABLED · AUDIT_SNAPSHOT_DISABLED · ZERO_RETENTION_POLICY_ACTIVE (applied restrictions appear in data_handling.policy_restrictions_applied).