Audit Trail¶

OpenMed can write an opt-in audit trail for agent runs. It is off by default.

The audit trail is for operators who need durable evidence of what happened across runs: which model path was used, which tools ran, whether they succeeded, how long they took, and which prompts/results were fingerprinted. It is not telemetry. OpenMed does not send audit data to OpenMed infrastructure.

Storage options¶

OpenMed supports three audit destinations:

Destination	Use when	Notes
`hf_dataset`	You want versioned private audit history on Hugging Face Hub	Recommended default. Each run is committed as JSON under `runs/YYYY/MM/DD/`.
`hf_bucket`	You want private mutable object storage on Hugging Face	Requires a newer `huggingface_hub` release with bucket APIs. If unsupported locally, OpenMed falls back to local traces.
`local`	You want offline-only audit traces	Writes under `~/.openmed/traces` by default.

HF datasets are useful for audit because they are private, access-controlled, versioned, and easy to inspect in the Hub UI. HF buckets are useful when you prefer object-storage semantics over dataset history.

Enable audit¶

For a private Hugging Face dataset:

export OPENMED_AUDIT_HF_TOKEN=hf_...
openmed audit enable --destination hf_dataset --repo "<user-or-org>/openmed-traces"
openmed audit status

For a local-only trace store:

openmed audit enable --destination local

For a private Hugging Face bucket:

export OPENMED_AUDIT_HF_TOKEN=hf_...
openmed audit enable --destination hf_bucket --bucket "<bucket-name>"

If the HF write fails during an agent run, the trace is saved locally instead. Audit failures never stop the agent run.

Configuration file¶

OpenMed stores audit config in ~/.openmed/audit.json:

{
  "enabled": true,
  "schema_version": "1.0",
  "destination": "hf_dataset",
  "phi_payload": "fingerprint",
  "flush_mode": "per_run",
  "hf": {
    "repo": "my-org/openmed-traces",
    "token_env": "OPENMED_AUDIT_HF_TOKEN"
  },
  "local": {
    "path": "~/.openmed/traces",
    "fallback_on_hf_failure": true
  }
}

Use token_env instead of a literal token whenever possible.

PHI payload modes¶

Audit capture is independent of PHI mode. PHI mode describes the operator posture for the run. phi_payload controls what the audit trace stores.

Mode	What the trace stores
`none`	Metadata only. No input/output fingerprints.
`fingerprint`	Metadata plus SHA-256 fingerprints. This is the default.
`preview`	Fingerprints plus short best-effort redacted previews.
`payload`	Full raw input/output payloads. Use only for synthetic or explicitly de-identified data.

The default fingerprint mode is intentionally conservative: it can prove that the same payload was used later without storing the raw payload in the audit destination.

Runtime commands¶

openmed audit status
openmed audit verify
openmed audit show --last 10
openmed audit show <run_id>
openmed audit export <run_id> --out trace.json
openmed audit local-list
openmed audit local-sync
openmed audit disable

Inside the TUI, /audit shows the active status, destination, PHI payload mode, fallback path, and relevant CLI commands. The status line shows audit: off, audit: ✓ ..., audit: ⚠ local-only, or audit: ⚠ paused.

Trace contents¶

Each run trace includes:

OpenMed version, run ID, timestamps, duration, and host fingerprint
Agent mode, access mode, PHI mode, model provider, model name, and reasoning effort
Prompt fingerprint, and optionally preview or payload depending on phi_payload
Tool-call actions with input/output fingerprints, status, latency, and error fingerprints
Provider usage actions when the SDK reports token accounting
Summary counts for actions, tools, model calls, and errors

OpenMed writes schema.json to new HF dataset destinations so teams can validate trace shape outside the app.

Environment variables¶

Variable	Purpose
`OPENMED_AUDIT_ENABLED`	Runtime override for audit on/off
`OPENMED_AUDIT_DESTINATION`	`hf_dataset`, `hf_bucket`, `local`, or `none`
`OPENMED_AUDIT_HF_TOKEN`	HF token used for private dataset or bucket writes
`OPENMED_AUDIT_HF_REPO`	Private HF dataset repo
`OPENMED_AUDIT_HF_BUCKET`	Private HF bucket name
`OPENMED_AUDIT_PHI_PAYLOAD`	`none`, `fingerprint`, `preview`, or `payload`
`OPENMED_AUDIT_FLUSH_MODE`	`per_run` or `manual`
`OPENMED_AUDIT_LOCAL_FALLBACK`	`1` or `0`
`OPENMED_AUDIT_LOCAL_PATH`	Local fallback trace path

The audit HF token is separate from native medical-service tokens such as OPENMED_INFERENCE_HF_TOKEN and OPENMED_MED_CODES_HF_TOKEN.