Machine-readable CLI contract¶
--json emits one document with stable command, exit-status, and error-code fields.
Contract fixtures¶
The offline gate covers the outcomes below. Fixtures omit inputs, paths, exceptions, and record values.
| Outcome | Command path | Exit code | Error code |
|---|---|---|---|
| Success | models list | 0 | — |
| Validation failure | risk discover | 2 | invalid_discovery_config |
| Offline failure | models pull | 1 | offline_unavailable |
| Privacy-policy failure | risk assess | 1 | release_policy_failed |
| Brief needs human review | brief | 0 | — |
| Brief refused | brief | 1 | — |
| Brief request/output failure | brief | 1 | brief_failed |
| Diagnostic check failed | doctor | 1 | — |
| FHIR validation check failed | fhir validate | 1 | — |
JSON shape¶
Successful commands use the following top-level keys:
Failures use the same command field and a stable error code/message pair:
{
"ok": false,
"command": "models pull",
"error": {
"code": "offline_unavailable",
"message": "The requested operation requires a local model cache."
}
}
message never echoes input, identifiers, paths, exceptions, or model responses. Change a fixture only for an intentional public-contract change.
Completed commands with negative results¶
brief, doctor, and fhir validate add a top-level outcome without changing the existing ok, command, data, or error keys. ok: true means a command produced its structured result, not that a clinical or validation gate passed. Consumers should check outcome and the exit code:
outcome | ok | Exit | Meaning |
|---|---|---|---|
completed | true | 0 | Command completed; a brief still requires human review |
refused | true | 1 | Brief safely refused; no summary was produced |
check_failed | true | 1 | Diagnostic or validation result includes failed checks |
failed | false | 1 or 2 | The command could not produce a normal result |
Successful envelopes for other commands remain unchanged. A refusal is not an exception or a clinical decision. Brief stdout contains only controlled status, reason, character count and digest, never the source or generated summary.
Exit codes¶
0means the command completed successfully.1means a runtime, offline, or privacy-policy gate failed.2means command validation or usage failed.
Run the deterministic offline gate with .venv/bin/python -m pytest tests/unit/cli/test_contract.py -q.
These fixtures are a scripting contract, not a compliance or clinical guarantee.
Guarded summary and NLI commands¶
summarize and nli verify use the same success/error envelopes above. Their fixed error message is Local clinical request could not complete.; it never includes clinical text, paths, backend names supplied by a caller or exception details. Use --json on the leaf command for stable error codes.
| Outcome | Exit | Stable codes |
|---|---|---|
| Successful summary files or all claims entailed | 0 | None |
| Valid NLI contradiction, neutral or abstention | 1 | No error; ok: true with per-claim evidence |
| Backend/cache/dependency unavailable | 1 | summary_backend_unavailable, nli_backend_unavailable |
| Privacy or ordering gate refusal | 1 | summary_leakage_rejected, summary_deidentification_rejected |
| Output reservation/write failure | 1 | summary_output_failed |
| Invalid backend result or processing failure | 1 | summary_result_invalid, summary_failed, nli_result_invalid, nli_failed |
| Invalid command arguments | 2 | summary_arguments_invalid, nli_arguments_invalid |
| Unsupported mode or local alias | 2 | summary_mode_unsupported, summary_model_invalid, nli_backend_invalid, nli_backend_factory_invalid |
| Invalid, unavailable, special or oversized local input | 2 | summary_input_invalid, summary_input_unavailable, summary_input_not_regular, summary_input_too_large; corresponding nli_input_* codes |
| Invalid claim array or per-claim bounds | 2 | nli_claims_invalid |
The summary console/file metadata contains only mode, backend_id, template_digest, leakage_check, summary_characters and human_review_required. The protected summary goes to its separate explicit new destination. NLI data contains only a claims array with each row's claim_index, label, score, backend_id, contradicted and review_required. Plain console output also omits clinical values.
Summary/source inputs are limited to 16 KiB, protected summary output to 8 KiB, and the claims file to 64 KiB with 1–128 claims of at most 4 KiB each. These commands use existing native APIs with local-only defaults and never download models. Their guards do not qualify a model artifact or validate a clinical workflow. See summarization and NLI verification for provisioning and trusted-code boundaries.
Offline clinical extraction¶
openmed clinical sdoh, openmed clinical relations and openmed clinical timeline consume existing analyzed spans. They run the local Python extractors without loading NER models or downloading artifacts:
openmed clinical sdoh --note note.txt --spans analyzed.json --json
openmed clinical relations --note note.txt --spans analyzed.json --json
openmed clinical timeline --note note.txt --spans analyzed.json \
--reference-time 2026-06-15 --json
--note is a UTF-8 regular local file limited to 16,384 bytes, the same note limit as the brief CLI. --spans accepts the success envelope from openmed analyze --json, or its unwrapped prediction-result data object. Both shapes contain an entities array. Supplied document text and entity surfaces must match the note exactly. Offsets are half-open Python character offsets, including for Unicode text. Each entity needs integer start and end, a registered NER label or supported clinical attribute label, and an optional finite confidence in [0, 1]. The CLI maps confidence to the Python extractor's score; the compatible score spelling is also accepted. Conflicting scores are invalid. Empty notes and entity arrays are valid. Existing model names, timestamps and arbitrary metadata are discarded. ASCII labels allow letters, digits, underscores, hyphens and spaces; arbitrary punctuation, controls and non-ASCII suffixes are refused before normalization.
Span and section JSON files are limited to 1 MiB. Inputs reject duplicate JSON keys, non-finite numbers, nesting deeper than 32 levels, more than 65,536 JSON values, more than 512 entities, and more than 256 sections. Symlinks and non-regular input files are refused. Every span, section, supplied context axis and explicit temporal link is validated before extraction. Malformed offsets fail rather than being silently skipped.
--sections sections.json accepts a JSON array of {start, end, label} records forming a complete contiguous partition of the note. Labels are canonical section names or unsectioned. SDOH extraction retains only Social History findings; English medication relations and timeline context use the same section inputs as their Python APIs. Supplied section headers and other metadata are omitted from output.
Languages are explicit: SDOH supports en; relations support the native en, hi and zh APIs; timeline normalization supports native en and de rules. The multilingual relation API does not accept sections. Unsupported languages and option combinations fail with typed codes, without translation or English fallback. Declaring a language does not validate the note's actual language.
The timeline command composes assert_context, normalize_temporal and the public build_timeline API. It preserves supplied axes under entity metadata.clinical_context (or compatible top-level or assertion fields), then groups events into historical, recent and hypothetical lanes. Conflicting supplied axes are invalid. certainty and uncertainty accept certain or uncertain; negation accepts affirmed or negated; experiencer accepts patient or family. Without supplied axes, native deterministic ConText cues and section priors provide advisory assertions.
Temporal entities have DATE, DATE_OF_BIRTH, TIME, TIMEX or DURATION labels, including registered aliases. --reference-time accepts an ASCII ISO calendar date or timezone-aware ISO datetime with seconds. It never reads the wall clock or analyzed result's timestamp. Relative expressions remain unanchored without a reference. Partial and ambiguous expressions retain the normalizer's offsets and granularity flags. Calendar values and reference dates stay in memory and are omitted from JSON.
Temporal entities can order their own timeline events. Another event receives a time only when its entity metadata contains an explicit clinical_time_span: [start, end] pointing to a supplied temporal entity. The CLI does not infer a nearest-date association. Only unambiguous normalized calendar-day dates anchor events; other events remain unanchored. This is an advisory span ordering, not a clinical chronology of record.
The shared {ok, command, data} envelope contains schema_version: 1, language, input span count, SHA-256 digests of the input file bytes, review_required: true, and the command's records:
- SDOH: trigger offsets, category, status, temporality, score and extent presence; trigger values, occupations and amounts are omitted.
- Relations: head/tail offsets and labels, canonical relation type, score, derived-tail flags and supported assertion status; source surfaces are omitted.
- Timeline: event offsets and supplied labels, kinds, assertions, time states, lane indices and temporal offsets/types/states/granularity flags; source surfaces, calendar values and raw identifiers are omitted.
All findings require review and do not authorize clinical action. Digests support input binding; they are not an anonymization guarantee.
--output result.json reserves a new file exclusively with mode 0600 and writes the same value-free envelope. Existing files and symlinks are refused; a failed write removes the partial file only while its device and inode still match the file reserved by this invocation. A replacement is preserved. The complete envelope must serialize as finite JSON within 1 MiB before any file creation or stdout emission; larger results fail without truncation. Stdout still contains the value-free result with output_written: true, and never the output path. Without --json, stdout contains the value-free data object. Errors use fixed messages without note text, span surfaces, private paths or exception details, including retained exception context. Projection codes and scores must be exact built-in scalar types; custom scalar subclasses are refused. Processor writes to Python stdout and stderr are discarded. Registered custom extractors execute as trusted local code; this is not an execution sandbox.
| Failure | Exit | Stable code |
|---|---|---|
| Invalid clinical command arguments | 2 | clinical_arguments_invalid |
| Unsupported language / options | 2 | clinical_language_unsupported / clinical_options_unsupported |
| Invalid reference | 2 | clinical_reference_invalid |
| Missing, unreadable or symlink input | 2 | clinical_input_unavailable |
| Non-regular or oversized input | 2 | clinical_input_not_regular / clinical_input_too_large |
| Invalid UTF-8 / JSON | 2 | clinical_input_encoding / clinical_json_invalid |
| Invalid span document / entity / count | 2 | clinical_spans_invalid / clinical_span_invalid / clinical_spans_too_many |
| Unknown label or mismatched text | 2 | clinical_label_unsupported / clinical_source_mismatch |
| Invalid section partition / temporal link | 2 | clinical_sections_invalid / clinical_time_link_invalid |
| Processing or output failure | 1 | clinical_processing_failed / clinical_output_unavailable |
Supported clinical attribute labels include DOSE, DOSAGE, DURATION, FREQUENCY, ROUTE, STRENGTH, FORM, STATUS, INDICATION, SEVERITY, TIMEX, DRUG, MED, MEDICINE, RX, DISEASE, SYMPTOM, DIAGNOSIS, EVENT, FINDING and OBSERVATION. Chinese CMeIE entity types are also accepted. Unknown labels are refused rather than copied into evidence. Custom SDOH extractors must emit built-in controlled categories, statuses and temporality states for this CLI projection; unknown output codes fail privately.
Validate parity and process behavior offline with .venv/bin/python -m pytest tests/unit/cli/test_clinical_cli.py tests/integration/test_clinical_cli_offline.py -q.