Clinical guidelines, as code.
Turn a clinical practice guideline PDF into a deterministic, queryable decision engine with source citations.
Herald uses an LLM once during the parse step to extract decision logic from guideline text. After that, queries are deterministic: no LLM in the loop, no hallucinated answers at query time, and no API key required to run queries against an already parsed guideline.
herald convert guideline.pdf # PDF -> structured markdown
herald parse guideline.md # markdown -> decision tree JSON
herald query guideline.json # deterministic recommendations with citationsNo API key required for the demo. The repo ships synthetic guidelines that are safe to run locally.
pip install herald-cpg
herald query examples/synthetic_meningitis_guideline.json \
--ask "68F, suspected meningitis"Example output:
Recommendation [critical]: Start ceftriaxone plus vancomycin immediately and add ampicillin for Listeria coverage.
Evidence grade: A (strong)
Source: Section 2.2, p.14
"In adults aged 50 years or older, or in patients who are immunocompromised, add ampicillin to the empiric regimen to cover Listeria."
Clinical practice guidelines are some of the highest-value documents in healthcare. They encode treatment logic, evidence grading, and contraindications, but most of that logic is trapped in PDFs.
Herald turns those PDFs into infrastructure:
- queryable
- auditable
- versionable
- exportable
- usable without an LLM at runtime
| Herald | Generic clinical chatbot |
|---|---|
| LLM used only during parse | LLM used at query time |
| Deterministic query engine | Non-deterministic generation |
| Structured JSON decision tree | Mostly unstructured answers |
| Citation metadata stored on recommendations | Citation quality varies |
| Local querying after parse | Ongoing service/API dependency |
| Diffable and exportable artifacts | Mostly chat transcripts |
- Querying is deterministic once the guideline is parsed.
- Recommendations retain
source_section,source_page, andsource_text. herald validatechecks extracted recommendations against the source markdown and reports a fidelity score.herald diffcompares old and new guideline versions in text, JSON, or markdown.herald exportemits FHIRPlanDefinitionfor downstream CDS pipelines.
Herald is not a bedside autopilot. It is tooling for turning guidelines into inspectable, reviewable clinical logic.
- Clinical informaticists building computable guideline logic
- Digital health teams distributing protocol logic offline
- Health services researchers measuring guideline adherence
- Guideline authors who want recommendations to be implementable
- Health-tech teams that need auditable CDS infrastructure
| Capability | Status | Notes |
|---|---|---|
| PDF -> markdown conversion | Shipped | Uses markitdown |
| Markdown -> decision tree parse | Shipped | Anthropic or OpenAI |
| Deterministic query engine | Shipped | No LLM required to query |
| Source-text validation | Shipped | Fidelity scoring included |
| Guideline diffing | Shipped | Text, JSON, or markdown |
FHIR PlanDefinition export |
Shipped | For downstream CDS workflows |
| Batch querying from CSV | Shipped | herald query --batch |
| Multi-guideline query support | Shipped | Includes conflict detection |
| Audit logging | Shipped | JSONL query/result log |
README.md- product overview and quick startdocs/adding_your_own.md- run Herald on your own guidelinedocs/supported_guidelines.md- what converts cleanly and what does notSCHEMA.md- full decision-tree schemaCONTRIBUTING.md- contribution workflow and standardsSUPPORT.md- where to ask questions, report bugs, and discuss ideas
pip install herald-cpgFrom source:
git clone https://github.com/myceldigital/herald.git
cd herald
pip install -e ".[dev]"herald query examples/synthetic_meningitis_guideline.jsonOr ask a single question:
herald query examples/synthetic_meningitis_guideline.json \
--ask "68F, suspected meningitis"Other shipped examples:
herald query examples/synthetic_adhd_guideline.json \
--ask "Adult male, tried methylphenidate with partial response and insomnia"herald convert path/to/guideline.pdf -o guideline.mdAnthropic:
export ANTHROPIC_API_KEY=sk-ant-...
herald parse guideline.md -o guideline.jsonOpenAI:
export OPENAI_API_KEY=sk-...
herald parse guideline.md -o guideline.json --provider openaiherald validate guideline.json --source guideline.mdThis checks whether source_text from each recommendation is actually present in the source markdown and reports a fidelity score.
herald diff old_guideline.json new_guideline.json --format markdownherald export guideline.json -o guideline.fhir.json- Herald is strongest when the source PDF has clean structure and selectable text.
- The parse step is probabilistic because it uses an LLM.
- The query step is deterministic because it traverses the saved decision tree.
- Parsed guidelines should be reviewed and validated before real clinical use.
- This repo ships the engine, not real clinical content. The examples in
examples/are synthetic.
Parsed guidelines conform to the Herald decision-tree schema in SCHEMA.md.
Every recommendation can retain:
- recommendation text
- evidence grade and strength
- source section
- source page
- exact supporting quote
- branching logic
- structured dosing and workflow fields
Minimal example:
{
"guideline": {
"title": "Synthetic Acute Bacterial Meningitis Guideline",
"source": "Synthetic Example Guideline Consortium (SEGC)",
"version": "1.0",
"last_updated": "2026-03-25"
},
"decisions": [
{
"id": "adult_empiric_therapy",
"entry_point": true,
"conditions": [
{ "field": "diagnosis", "operator": "eq", "value": "meningitis" }
],
"recommendation": {
"action": "Start ceftriaxone plus vancomycin immediately.",
"source_section": "2.1",
"source_page": 13,
"source_text": "Administer ceftriaxone plus vancomycin immediately when acute bacterial meningitis is suspected in adults."
}
}
]
}See docs/supported_guidelines.md for current conversion guidance.
Short version:
- best: text-based PDFs with numbered sections and explicit recommendations
- okay with caveats: two-column layouts, complex tables
- weak: scanned PDFs without OCR, image-heavy flowcharts, slide decks
If you want to test Herald on real public guidelines, start with structured, text-based documents from major publishers:
Prefer guideline landing pages over random mirrored PDFs. Herald works best on documents with selectable text, numbered sections, and explicit recommendation statements.
Clinical practice guidelines are usually copyrighted by their publishers. Herald is designed to let users convert and query guidelines locally, but you still need to respect each publisher's reuse policy.
To use Herald with a real guideline:
- Obtain the PDF through legitimate channels.
- Check the publisher's licence and reuse policy.
- Convert, parse, validate, and query locally.
- deterministic query engine
- validation with fidelity scoring
- diffing for guideline updates
- FHIR export
- batch and multi-guideline query support
- MCP server for editor and desktop integrations
- richer export targets beyond FHIR
PlanDefinition - community registry of openly shareable synthetic/example guidelines
- broader multilingual and publisher-format support
See CONTRIBUTING.md.
- Use GitHub Discussions for questions, design ideas, and early-stage workflow discussion.
- Use GitHub Issues for concrete bugs, feature requests, and guideline-compatibility requests.
- Use private vulnerability reporting for security-sensitive issues. See SECURITY.md.
MIT