Triage v4 — orchestrator + MSK pathway library

Last updated 2026-05-21 · live at triage-rn.dev.hiolly.com/demo/chat · MSK viewer /msk/ · coverage vs NHS /msk/coverage.html · v5 narrower →

TL;DR

v4 is a single endpoint that orchestrates three sequential layers and two parallel "Ver-Stacks". The BFF makes one POST; v4 picks a pathway via the narrower (Layer 1), walks it through the agent (Layer 2), and renders a disposition (Layer 3). The RF observer and tone formatter run in parallel on every turn.

End-to-end flow

flowchart TD
  user([Patient])
  bff["BFF /api/chat
(triage-rn)"]
  v4["/v4/chat/completions"]

  subgraph L1["Layer 1 — Pathway narrowing"]
    direction TB
    v3["v3 narrower
narrow_step(state, user, messages)"]
    v3a{"action"}
  end

  subgraph L2["Layer 2 — Pathway walk"]
    direction TB
    pin["pin_and_handoff
start_session(pw_code) + seed history"]
    v1["v1 agent.run
advance(option) per turn"]
  end

  subgraph L3["Layer 3 — Disposition"]
    direction TB
    map["disposition_map.map_to_olly
Olly-styled terminal"]
  end

  subgraph VS["Ver-Stacks (parallel)"]
    direction LR
    rf["Ver-Stack 1: RF sidecar
async observe_turn"]
    tone["Ver-Stack 2: tone_filter
Olly voice spec applied"]
  end

  user --> bff --> v4
  v4 --> v3
  v3 --> v3a
  v3a -.->|ask| user
  v3a -->|pathway| pin
  v3a -.->|escape / out_of_scope| user
  pin --> v1
  v1 -->|"is_terminal=false"| v1
  v1 -->|"is_terminal=true"| map
  map --> tone
  v1 --> tone
  v4 -.-> rf
  tone --> bff --> user

  classDef layer fill:#eef2ff,stroke:#4338ca,color:#312e81
  classDef vs fill:#fff8eb,stroke:#b45309,color:#78350f
  classDef ep fill:#dbeafe,stroke:#2563eb,color:#1e40af
  classDef user fill:#f5f5f4,stroke:#475569,color:#1a1a1a
  class L1,L2,L3 layer
  class VS vs
  class v4,bff ep
  class user user

The three layers

Layer 1 — pathway narrowing (v3 narrower)

narrow_step() looks at the patient's free-text complaint, shortlists candidate pathways from the enabled pool in dev-2 nhs111.pathways, and either commits to one or asks a 2-3 turn differential. Returns one of:

Narrower mechanics — how it decides per turn

State is kept in Valkey keyed on chat_id, so each turn the narrower sees the full accumulated free-text plus a turn counter. The flow per turn:

1. Shortlist — query list_pathways for the demographic-filtered enabled pool. Trim to candidates whose label/pick_hint keyword-overlaps the accumulated user text.
2. LLM rank — gemini-3.5-flash ranks the shortlist with confidence scores. If the top candidate is ≥ 0.85 confidence with a clear margin over runner-up, commit (action="pathway").
3. Differential — otherwise, ask an LLM-generated differential question with 2-4 options. Each option binds to a candidate pw_code (or is a "I'm not sure" / "(asks again)" continuation).
4. option_index short-circuit — when the next turn carries an option_index matching a previously-offered option, v3 commits directly to that option's bound pw_code without re-running the LLM rank.
5. Hard cap — after V3_MAX_TURNS (3) ask turns, emit action="escape" with a declared fallback pw_code.

Worked example — narrowing from vague to specific

Three real traces captured against the live /v3/narrow endpoint (Male / 35 persona). Each row is one HTTP round-trip.

Case A — confident commit on turn 1

Clear single-pathway match — the LLM ranker finds olly_msk_001 "Low back pain (non-specific)" above threshold on the first read. No narrowing needed. Layer 2 takes over immediately.

Case B — two-step narrowing (1 ask, then commit)

"Painful, stiff joints" is anatomically ambiguous — could be hand OA, foot OA, rheumatoid arthritis, polymyalgia, or gout. v3 asks one differential keyed on body region. Each option is pre-bound to a pw_code; the user's pick short-circuits straight to olly_msk_024.

Case C — three-step narrowing

The accumulated free-text drives the ranker on every turn. "I have pain" alone is too vague — v3 asks for location. "Upper body" narrows but is still imprecise, so v3 makes its best soft-commit guess. Once the patient adds "shoulder when I lift my arm" on turn 3, the ranker reweights with the new signal and commits to olly_msk_012 (Shoulder impingement). The full accumulated context — three user messages — is what wins.

Layer 2 — pathway walk (v1 agent on the picked pathway)

Once Layer 1 commits, pin_and_handoff() writes the pw_code onto the session and seeds the pydantic-ai message history with a synthetic start_session tool call+return. Every subsequent user reply forwards to v1's chat_completions handler, which runs the agent's advance() tool to step the FSM. Gateway rules block the agent from re-picking the pathway (so v3's choice stands).

The agent walks the canonical state machine defined in nhs111.pathway_states / pathway_options. Each gate is a single question with a list of patient-language signs; user picks an option; advance() returns the next state. When the next state is a terminal, the agent's TriageOutput.is_terminal=True and Layer 3 fires.

Layer 3 — disposition (Olly-styled terminal)

For NHS pathways (PW*), disposition_map.map_to_olly() rewrites the NHS title and care_type into Olly's UX ("Book an Olly physiotherapist", "Speak to an Olly GP"). For Olly pathways (olly_*), the disposition is already Olly-styled at source — the map early-returns the input verbatim.

The terminal disposition is what the patient ultimately sees, with three structured signals attached to the response:

X-Triage-Is-Terminal:       true
X-Triage-Care-Type:         physio | gp | emergency | nurse | mental_health | pharmacy | self_care | specialist
X-Triage-Disposition-Title: Book an Olly physiotherapist | Call 999 | Go to A&E now | …

The two Ver-Stacks (parallel)

MSK pathway library

39 enabled pathways in dev-2 nhs111.pathways:

Each MSK pack has: 5 red-flag gates (each with a patient_question + patient_signs[] routing to an emergency/urgent terminal) → default terminal (typically physio booking). The original auto-compile also produced a history-question chain (HQ1…HQ10), but every HQ Y/N routed to the next HQ regardless of answer — pure dead weight from a patient-experience POV. All 332 HQs are now patient_skip: true, so the runtime tree is RF gates + terminals only. Patient walks dropped from ~15 turns to ~5.

Full viewer at arch.dev.hiolly.com/msk/ with one decision-tree page per pathway. NHS-vs-Olly coverage matrix at /msk/coverage.html.

Booking prompt — terminal UX

When v4 reaches a non-emergency terminal, the chat client (per the X-Triage-Care-Type header) replaces the verbose canonical disposition with a single Olly-tone prompt. The patient sees who they'd be booking with and what to expect:

Chips: "Yes, please" / "Not right now". Yes navigates to /demo/chat/booking + appends the AppointmentPill. No closes softly.

What changed since v2

Agent functions & tools

v4 reuses v1's pydantic-ai agent and tool registry. The key tools (defined in src/triage/tools.py + invoked by the agent loop):

Tests & observability

Try it

Direct API smoke (no UI)

BEARER="olly_triage_grant_35_0UkEemrBIVaZPnQ0-JKvLQ"
curl -X POST https://triage-rn.dev.hiolly.com/api/chat?json=true \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"'$(uuidgen)'","messages":[{"role":"user","content":"I have lower back pain"}]}'

Returns:

{
  "text":              "Two weeks of …",
  "session_id":        "",
  "is_terminal":       false,
  "care_type":         null,
  "disposition_title": null,
  "pathway_id":        "olly_msk_001"
}

Branches & commits