K12 Workflows

Workflow Summary

The K12 domain now exposes two workflow layers:

• 3 production document workflows used by standard integrations
• 6 evaluation and testing workflows used for multi-turn scenario replay, scoring, and scenario mining

That means the current K12 workflow surface is larger than the older “three async workflows” model.

Workflow Family	Count	Typical Use
Production workflows	3	Annex editing, QRG generation, and QRG editing
Evaluation workflows	6	Multi-turn annex/QRG replay, named scenario execution, batch testing, and scenario mining

---

Production Workflows

These are the workflows external integrators normally care about first.

Workflow	Purpose	Kickoff Endpoint	Status Endpoint	Result Endpoint	Cancel Endpoint
EOP Editing	Edit district planning, facility planning, hazard annexes, functional annexes, and role-suggestion variants	Use the scenario-specific EOP kickoff tools	k12-annex-editing-status	k12-annex-editing-result	k12-cancel-task-request
QRG Generation	Generate QRGs from an EOP	k12-qrg-generation-kickoff	k12-qrg-generation-status	k12-qrg-generation-result	k12-qrg-cancel
QRG Editing	Edit a section of an existing QRG	k12-qrg-editing-kickoff	k12-qrg-editing-status	k12-qrg-editing-result	k12-qrg-cancel

Production flow at a glance

These workflows are independent. You can have EOP edits, QRG generation jobs, and QRG edit jobs in flight at the same time.

---

EOP Editing Workflow

Kickoff routes

The EOP editing workflow now has dedicated kickoff endpoints for each major editing mode:

• k12-district-planning-kickoff
• k12-facility-planning-kickoff
• k12-functional-annex-kickoff
• k12-hazard-annex-kickoff
• k12-functional-annex-suggest-roles-kickoff
• k12-hazard-annex-suggest-roles-kickoff

The older k12-annex-editing-kickoff route still exists for compatibility, but new integrations should prefer the dedicated kickoff endpoint that matches the editing intent.

Standard sequence

1. Call the scenario-specific kickoff tool that matches the editing task.
2. Receive a requestId with status accepted.
3. Poll k12-annex-editing-status with the requestId until the status reaches success or error.
4. Call k12-annex-editing-result to retrieve the edited content.

Cancellation:

• use k12-cancel-task-request with the requestId

What this workflow covers

This single production workflow is the async execution layer underneath:

• district planning edits
• facility planning edits
• functional annex edits
• hazard annex edits
• functional annex role suggestion
• hazard annex role suggestion
• the legacy annex route

So the kickoff surface has become more specialized, even though the underlying async tracking pattern is still unified.

---

QRG Generation Workflow

Standard sequence

1. Call k12-qrg-generation-kickoff with the EOP ID, user, role, and optional generation configuration.
2. Receive a requestId with status accepted.
3. Poll k12-qrg-generation-status until the status reaches SUCCESS or ERROR.
4. Call k12-qrg-generation-result to retrieve the generated QRGs.

Cancellation:

• use k12-qrg-cancel with jobType: "generation"

What it does internally

This workflow orchestrates the QRG pipeline:

• category classification
• audience/group extraction
• role mapping
• content generation

The caller still interacts with it as a single async workflow.

---

QRG Editing Workflow

Standard sequence

1. Call k12-qrg-editing-kickoff with the QRG metadata, target phase, current content, and editing instruction.
2. Receive a requestId with status accepted.
3. Poll k12-qrg-editing-status until the status reaches success or error.
4. Call k12-qrg-editing-result to retrieve the updated section.

Cancellation:

• use k12-qrg-cancel with jobType: "editing"

---

Evaluation And Testing Workflows

In addition to the production workflows, the K12 domain now registers six evaluation-oriented workflows:

Workflow	Purpose
Annex turn-based conversation	Run an explicit multi-turn annex conversation payload
QRG turn-based conversation	Run an explicit multi-turn QRG conversation payload
Annex turn-based named scenario	Run a checked-in annex scenario by scenarioId
QRG turn-based named scenario	Run a checked-in QRG scenario by scenarioId
Annex turn-based scenario batch	Run a selected list of annex scenarios and aggregate results
Annex scenario mining	Mine draft annex scenarios from historical interaction data

These are primarily used for:

• QA
• regression testing
• implementation validation
• operator-driven testing through the internal K12 harness

They are not the normal document-editing integration path for end-user applications.

Current turn-based routes

Workflow Path	Purpose
/k12/workflows/annex-turn-based-conversation	Run an explicit multi-turn annex conversation and return the completed evaluation payload
/k12/workflows/qrg-turn-based-conversation	Run an explicit multi-turn QRG conversation and return the completed evaluation payload
/k12/workflows/annex-turn-based-scenario	Run a named checked-in annex scenario by scenarioId
/k12/workflows/qrg-turn-based-scenario	Run a named checked-in QRG scenario by scenarioId
/k12/workflows/annex-turn-based-scenario-batch	Run a selected list of annex scenarios and aggregate pass/fail counts
/k12/workflows/annex-turn-based-scenario-mining	Mine draft annex scenarios from historical interaction data

Evaluation flow at a glance

---

Async vs Synchronous Behavior

The production workflows and the evaluation workflows do not all behave the same way.

Async workflows

These are kickoff/status/result workflows:

• EOP Editing
• QRG Generation
• QRG Editing

They return quickly with a tracking identifier, then require polling.

Synchronous workflows

These execute the full request before returning:

• annex-turn-based-conversation
• qrg-turn-based-conversation
• annex-turn-based-scenario
• qrg-turn-based-scenario
• annex-turn-based-scenario-batch
• annex-turn-based-scenario-mining

Implications:

• turn-based routes can take much longer than kickoff/status/result routes
• long multi-turn scenarios are expected to feel slower
• scenario batch runs should use an explicit scenarioIds subset instead of an unbounded catalog run

Optional synchronous annex editing

The production annex editing workflow also supports a synchronous shortcut:

• pass waitForResult: true in the kickoff payload

When you do that, the kickoff call waits for the job to complete and returns the full result instead of only the tracking fields.

---

Status Lifecycle

Production workflow statuses

Status	EOP Editing	QRG Generation	QRG Editing
Job accepted	accepted	accepted	accepted
Work in progress	processing	PROCESSING	processing
Completed	success	SUCCESS	success
Failed	error	ERROR	error
Cancelled	cancelled	CANCELLED	cancelled

note

QRG Generation uses UPPERCASE status values. EOP Editing and QRG Editing use lowercase.

Evaluation workflow statuses

The turn-based routes do not use a separate status/result polling lifecycle. They return a completed response body directly, including:

• per-turn results
• aggregate pass/fail counts
• evaluation summaries
• mined draft scenarios, depending on the route

---

What Changed From The Older Model

The older external overview implied:

• only 3 K12 workflows existed
• only annex turn-based testing mattered
• the EOP workflow was a single generic kickoff surface

The current system is broader:

• the K12 domain registers 9 workflows
• the EOP kickoff surface now has dedicated planning, annex, and suggest-roles routes
• QRG turn-based evaluation workflows exist alongside annex turn-based workflows
• annex scenario mining is part of the registered workflow surface

---

Next Steps

EOP Workflow

Deep dive into EOP editing: dedicated kickoff routes, async behavior, and result handling

QRG Workflow

Deep dive into QRG generation and editing: pipeline stages, status handling, and output structure