DOCS — TRUST · AUDIT TRAIL

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 captured or 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 raw run is committed as JSON under `runs/YYYY/MM/DD/`, with one root Agent Trace Viewer-compatible `*.jsonl` file per session.
`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 --dataset "<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": "payload",
  "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.
`preview`	Fingerprints plus short best-effort redacted previews. Long values are intentionally clipped.
`payload`	Full raw input/output payloads. This is the default once audit is enabled.

The default payload mode is intended for complete private audit trails. Use preview for short redacted snippets, fingerprint when you only need non-reversible proof that the same payload was used later, or none for metadata-only traces.

openmed audit set-phi-payload preview
# Restore full private transcripts and tool payloads:
openmed audit set-phi-payload payload

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: syncing ..., audit: ✓ ..., audit: ⚠ local-only, or audit: ⚠ paused. TUI audit uploads run in the background so slow Hugging Face writes do not block the interactive run-completion path.

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
Session transcript messages captured during the run, including user messages, assistant messages, plans/cards, and tool messages when available
Tool-call actions with input/output fingerprints, status, latency, and error fingerprints
Full tool output payloads in payload mode, including large outputs expanded from persisted local tool-result files when available
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. HF dataset repos also get root *.jsonl trace files tagged as agent-traces, matching the layout used by public Agent Trace Viewer datasets. Those root JSONL files are stable per session and are updated as the session grows, so the Dataset Viewer row represents one session. The exact immutable OpenMed audit JSON for each run remains in runs/.

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