Skip to content

protocol_authoring_guide.md

Latest commit

 

History

History
82 lines (61 loc) · 2.5 KB

protocol_authoring_guide.md

File metadata and controls

82 lines (61 loc) · 2.5 KB
Raw

Protocol Authoring Guide

Overview

County protocols are stored as structured JSON files in content/protocols/. Each county has its own folder containing an index file and individual topic files.

Why Local Protocol Files?

Protocol knowledge NEVER relies on LLM model memory. Protocols are:

  • Loaded from structured JSON at runtime
  • Resolved by county, certification level, and tags
  • Injected into LLM prompts when needed
  • Versioned and auditable

Folder Structure

content/protocols/<county_id>/
├── index.json              # Required: pack metadata and topic file list
├── chest_pain.json         # Topic file
├── respiratory_distress.json
├── hemorrhage.json
└── ...

index.json

Must validate against content/schemas/protocol_index.schema.json.

{
  "county_id": "demo_county",
  "county_name": "Demo County EMS",
  "version": "2025.1",
  "cert_levels": ["EMR", "EMT-B", "AEMT", "Paramedic"],
  "topic_files": ["chest_pain.json", "hemorrhage.json"],
  "destination_policy": "...",
  "general_standing_orders": ["..."]
}

Topic Files

Each topic file covers one clinical complaint/category.

Required Fields

Field Type Description
id string Unique topic ID
title string Human-readable title
tags string[] Tags that scenarios use for matching

Optional Fields

Field Type Description
scope_of_practice object cert_level → list of permitted interventions
assessment_steps string[] Ordered assessment steps
treatment_steps string[] Ordered treatment steps
medications array Medication permissions
contraindication_snippets array Contraindication rules
destination_policy string Transport destination guidance

Protocol Resolution

The ProtocolResolver service matches protocols by:

  1. County ID — the session's county setting
  2. Certification level — the learner's cert level
  3. Tags — matched against county_protocol_tags from the scenario

Only relevant protocol snippets are loaded, minimizing token usage when injected into LLM prompts.

Adding a New County Protocol Pack

  1. Create a new folder: content/protocols/<county_id>/
  2. Create index.json with pack metadata
  3. Create topic files for each clinical area
  4. Add tags that match your scenario county_protocol_tags
  5. Validate against schemas
  6. Test: cd apps/api && pytest tests/test_protocol_resolver.py