DOCS — INTEGRATIONS · CLINICAL NLP

Clinical NLP

Turn a clinical note into a redaction draft you can inspect, process a collection of records, or extract clinical entities into files for further review. OpenMed Agent 0.4.0 adds language and redaction controls, document previews, resumable batches, and more reliable extraction exports.

Clinical tools use your configured NLP service. With the hosted preview, source content is processed remotely even when your chat model runs locally. Start with synthetic examples and review every result before sharing it.

Start with a note

Open /privacy to select a source file and a new output path. Choose the language, redaction method, identifier categories, and whether to redact patient details, clinician details, or both. The review screen requires FULL PHI mode; use /phi to select it. The screen does not change this setting for you.

Select the review-draft checkbox when you want to inspect preview results, then request a preview. For text output, Save shown output saves the preview you reviewed. Changing a control clears the old preview. You can cancel a request before saving, and the source file is preserved.

You can also describe the task in chat. Replace the example paths with your own:

Deidentify /path/cardiology.txt into /path/cardiology.masked.txt.
Use German and mask patient and clinician names, identifiers, phones,
email addresses, addresses and dates of birth. Preserve clinical terms,
diagnoses, medications and negation. I want a draft to review before saving.

For dedicated file redaction, provide the path directly. Reading or pasting the source into chat first can disclose it to the chat model. The dedicated file tools process the source through the NLP service and report a summary and output path; the review preview is displayed separately from the conversation.

Language and clinical preservation

Use automatic language selection or specify a language/locale such as en, de, DE or de-DE. In a prompt, “language German” is sufficient to request the language control. Text is not translated.

The clinical redaction profile is designed to preserve medical terms, diagnoses, medications, doses, units and negation while transforming selected identifiers. It distinguishes dates of birth from other dates: when birth dates are selected for redaction, the full birth date is removed rather than retaining its year.

Language controls do not establish accuracy for every language or national identifier. Availability depends on the configured service and model. English and German workflows remain previews requiring review; do not assume that accepting a locale means every local identifier is covered. A higher detection threshold can leave more identifiers visible.

Choose what to redact and preserve

Select patient details, clinician details, or both. For example, request patient-only redaction when the clinician's attribution needs to remain visible.

Available categories are person names, identifiers, phones, email addresses, addresses, dates of birth, other dates, URLs and organizations. Review the chosen categories before processing; keeping a category can leave identifying data.

For finer control in chat, request exact terms to preserve or label exceptions. The de-identification tool supports keep_terms and keep_labels. These advanced options are supplied through the prompt; the /privacy screen offers role and category controls, not a term-list editor.

Mask patient and clinician identifiers in /path/note.txt and write a review
draft to /path/note.masked.txt. Use language de. Keep the exact clinical
terms "Sozialanamnese" and "Kurznarkose". Show me the result before saving.

Term and label exceptions narrow redaction and require review. A term that also appears as an identifier can conflict with the requested policy. Inspect both what was removed and what remains.

Five redaction methods

Method	What to request	What to expect
mask	Replace selected identifiers with labels	Placeholders such as [TYPE]
remove	Delete selected identifiers	Text with those spans removed
replace	Substitute fictional details	Localized replacements where supported
hash	Use consistent pseudonyms within a named scope	Repeatable replacements for the same identifier and scope; requires service support
shift_dates	Move dates by a specified number of days	Shifted dates while preserving their intervals; selected birth dates are fully redacted

For hashing, choose a stable, non-identifying scope such as synthetic-study-a. Consistent pseudonyms allow records to remain linkable; they are not a guarantee of anonymity. Do not use a patient identifier as the scope.

For date shifting, supply a nonzero offset, for example:

Deidentify /path/note.txt into /path/note.shifted.txt using shift_dates.
Shift encounter dates by 30 days and fully redact dates of birth.
I want a draft for review.

The configured service determines which methods are available. PDF and image mask exports require mask; the other methods apply to text output.

PDF and image redaction

The document preview supports PDF, PNG and JPEG input when enabled by your NLP service. In /privacy, choose OCR languages separately from the redaction language. The preview currently provides English, German, or both OCR packs.

Input	Available output
PDF	OCR text draft, or a PDF mask draft
PNG or JPEG	OCR text draft, or a PNG mask draft

The on-screen preview shows OCR text. For PDF or PNG output, choose the matching output format, save the draft, and open the saved file to inspect the actual masked pages alongside the source. PDF mask drafts are image-only documents; they do not retain the original searchable text layer.

The preview accepts up to eight pages and 8 MB per document, with additional image and recognized-text limits. OCR can miss or alter text. Check every page, including regions where OCR found nothing, before sharing an export.

Long notes and resumable batches

Single-text redaction accepts up to 100,000 characters. Larger collections can use /privacy-batch for UTF-8 text, CSV or JSONL. Choose the source, output, checkpoint and selected text field, then set the redaction controls and review option. The batch screen also requires FULL PHI mode.

For example:

Deidentify the clinical_text column of /path/notes.csv into
/path/notes.masked.csv. Save the checkpoint at /path/notes.batch.json.
Use German, mask patient and clinician identifiers, and create drafts
for my review.

Follow progress and per-record status, cancel when needed, and resume with the same source, output, checkpoint and controls. Completed rows are retained. Keep these files together and unchanged between runs. Resume checks for changes so a different input is not silently treated as the original batch.

Current limits are 1,000 records, 20 MB per source and 100,000 characters per selected field. Only the selected field is transformed. Other columns are preserved and may still contain identifiers. Failed or pending selected fields are blank; inspect row status before using the output.

Clinical extraction and exports

Ask for disease, medication, anatomy, oncology, genomic or chemical entities from a note using the existing extraction tools. You can process one file or a collection and save structured results as JSONL.

In 0.4.0, exports can select a particular extraction result. This improves work with several notes or entity types: the saved file can refer to the intended extraction instead of relying only on whichever result ran last. A failed extraction no longer leaves an earlier result looking like its output.

Extract diseases and medications from /path/note.txt. Save each extraction
to its own JSONL file and read both files back to confirm what was written.

This uses the existing entity extractors; it does not establish new multilingual accuracy for those models. Extracted mentions are candidates for review, not confirmed diagnoses or prescribing instructions. Check doses, units, negation and whose history a mention describes against the source.

File privacy controls

File privacy is off by default. Choose a mode explicitly:

Command	Behavior
/privacy-chat off	Use the usual tools permitted by the session's other settings
/privacy-chat on	Restrict subsequent file work to the dedicated privacy tools
/privacy-chat auto	Wait for a recognized file-redaction request, then activate the restriction

The selected mode survives session resume. Once auto activates, it stays active until you select off or reset it to auto. Automatic recognition does not cover every language or phrasing; use on when you want the restriction immediately. Stop or finish an active turn before changing modes.

These controls do not scrub text already pasted into chat or make hosted NLP processing local. PHI mode is a separate setting. See Privacy & Security for detailed behavior.

Updating and compatibility

Existing preview users can update with openmed --update, then check openmed --version for the installed version (these controls require 0.4.0 or later). For installation and provider setup, see Getting Started and Providers.

Older agents retain their established NLP service interfaces. The new language, policy, document and batch controls are available through the updated Agent; they do not silently change an older agent's extraction behavior or model.