Skip to main content

K12 Tools (EOP & QRG)

K12 Tools — Emergency Operation Plans (EOP)​

This section documents the K12 EOP (formerly Annex) tools. Each entry includes a short summary, how it works, key input/output shapes, where to find the code, and common troubleshooting tips.

k12-insert-task-request-log​

  • Summary: Insert a full workflow request into K12SAFETY.log_EOP_TaskRequests.
  • How it works: Validates the request via Zod schema, normalizes optional fields, serializes the full request as RawRequestJson, and performs a parameterized INSERT that outputs the inserted row. Returns the persisted row id and core fields used for downstream correlation.
  • Code: packages/domain-k12/src/insert-task-request-tool.ts (input/output schemas defined near top)
  • DB: Writes to K12SAFETY.log_EOP_TaskRequests.
  • When to use: Called at workflow kickoff to record original request payload (useful for auditing and debugging).
  • Troubleshooting: If inserts fail, check SQL connectivity (load-sql-client), duplicate RequestID errors, and confirm caller supplied requestId/sessionId as expected.

k12-insert-task-in-monitoring-table​

  • Summary: Insert a status/monitoring row into K12SAFETY.log_EOP_TaskStatus.
  • How it works: Normalizes status values, validates allowed status (accepted|processing|success|error|cancelled), then INSERTs a monitoring row used by dashboards and polling endpoints.
  • Code: packages/domain-k12/src/insert-task-monitoring-tool.ts
  • DB: Writes to K12SAFETY.log_EOP_TaskStatus (indexed on CreatedAt, Status).
  • When to use: Workflow components and external systems use this to report intermediate and terminal statuses.
  • Troubleshooting: Status validation errors surface as schema validation errors (see tests). If monitoring rows missing, confirm createdAt timezone handling and SQL defaults.

k12-update-task-status​

  • Summary: Update an existing monitoring row's status and message for a request.
  • How it works: Validates input (requestId/sessionId/status), then performs an UPDATE to append status or message; used for progress updates.
  • Code: packages/domain-k12/src/update-task-status-tool.ts
  • DB: Updates K12SAFETY.log_EOP_TaskStatus rows.
  • Troubleshooting: If status won't change, inspect uniqueness constraints and ensure correct requestId/sessionId pairing.

k12-update-task-request-response​

  • Summary: Record the workflow's final response payload and optional isEdit flag into the request log.
  • How it works: Validates response payload, stores structured response JSON fields into log_EOP_TaskRequests for later retrieval and audit.
  • Code: packages/domain-k12/src/update-task-request-response-tool.ts
  • DB: Updates K12SAFETY.log_EOP_TaskRequests.
  • Troubleshooting: Use rawResponseJson and ResponsePayloadJson fields to debug serialization mismatches.

k12-lkp-task-status-by-session-or-request​

  • Summary: Query monitoring rows by sessionId or requestId to show status history.
  • How it works: Runs a parameterized SELECT that returns recent monitoring rows and status history to inform polling clients.
  • Code: packages/domain-k12/src/log-task-status-tool.ts
  • DB: Reads K12SAFETY.log_EOP_TaskStatus.
  • When to use: Poll status endpoints, tooling that monitors long-running workflows.

k12-lkp-task-request-result​

  • Summary: Fetch the persisted request row (and attached response fields) for a given request id.
  • How it works: SELECT from log_EOP_TaskRequests and returns parsed fields like response payload, history used, and raw JSON.
  • Code: packages/domain-k12/src/lookup-task-request-result-tool.ts

k12-cancel-task-request​

  • Summary: Request cancellation for an in-flight workflow run and update DB to cancelled where appropriate.
  • How it works: Validates requestId, then updates relevant log_Jobs / log_EOP_TaskStatus rows to reflect cancellation and returns a success/error response.
  • Code: packages/domain-k12/src/cancel-task-request-tool.ts

k12-get-emergency-operation-plan-snapshot​

  • Summary: Get a snapshot of the EOP (document) for contextual prompts and verification.
  • How it works: Calls the MOEOP internal client to fetch a plan snapshot and returns normalized document sections.
  • Code: packages/domain-k12/src/emergency-operation-plan-snapshot-tool.ts and moeop-internal-client.ts.
  • When to use: Used by kickoff tools to include canonical plan text in prompts.

k12-annex-editing-kickoff​

  • Summary: Compatibility entry point for the EOP/Annex editing workflow. Prefer the scenario-specific kickoff tools for new integrations: k12-district-planning-kickoff, k12-facility-planning-kickoff, k12-functional-annex-kickoff, k12-hazard-annex-kickoff, k12-functional-annex-suggest-roles-kickoff, and k12-hazard-annex-suggest-roles-kickoff.
  • How it works: Each kickoff delegates to runAnnexWorkflowKickoff which ensures idempotency, creates a job row in K12SAFETY.log_Jobs, starts a Mastra workflow run, and optionally waits for results. The selected tool ID determines the agent profile and execution mode. k12-functional-annex-kickoff and k12-hazard-annex-kickoff also auto-route to the suggest-role execution mode when the prompt normalizes to Suggest Roles and Responsibilities.
  • Code: packages/domain-k12/src/annex-editing-kickoff.ts, annex-editing-scenario-kickoffs.ts, annex-editing-workflow-runner.ts (packages/domain-k12/src/annex-editing-workflow-runner.ts)
  • DB: K12SAFETY.log_Jobs, log_EOP_TaskRequests, log_EOP_TaskStatus.
  • Inputs: Exactly one identity source must be provided: emergencyOperationPlanId or emergencyOperationPlan (persisted-plan flow), emergencyOperationPlanConfigurationId or emergencyOperationPlanConfiguration (pre-EOP configuration-stage flow), or eopMasterCopyId/emergencyOperationPlanMasterCopy (Master Copy flow). The selected request object should send organizationId; the workflow uses that organization ID directly for district/organization details and does not derive it through EOP, configuration, or Master Copy lookups. roleId is optional traceability metadata; frontend-provided roles, userTags, or generalUserTags override backend-resolved role tags for prompt context. userTagIds is accepted as an alias for selected role/tag IDs and may be empty while frontend tag filling is pending.
  • Example (HTTP - Kickoff using emergencyOperationPlan object):
curl -X POST "$BASE_URL/ai/api/tools/k12-annex-editing-kickoff/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"emergencyOperationPlan": {"id": "plan-sample", "organizationId": "org-sample"}, "userId": "principal@example.edu", "roleId": "safety-coordinator", "form": {"field": {"content": "<p>...</p>"}}}}'
  • Example (HTTP - Kickoff using emergencyOperationPlan object and frontend roles):
curl -X POST "$BASE_URL/ai/api/tools/k12-annex-editing-kickoff/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"emergencyOperationPlan": {"id": "plan-sample", "organizationId": "org-1", "organization": {"id": "org-1", "name": "District One"}}, "userId": "principal@example.edu", "userTagIds": [], "roles": [{"id": "tag-1", "name": "Principal"}], "form": {"field": {"content": "<p>...</p>"}}}}'
  • Example (HTTP - Kickoff using emergencyOperationPlanConfiguration object):
curl -X POST "$BASE_URL/ai/api/tools/k12-annex-editing-kickoff/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"emergencyOperationPlanConfiguration": {"id": "config-sample", "organizationId": "org-sample"}, "userId": "principal@example.edu", "roleId": "safety-coordinator", "form": {"field": {"content": "<p>...</p>"}}}}'

k12-annex-editing-status​

  • Summary: Poll the status of a running or completed Annex editing workflow.
  • How it works: Queries job tables for status rows matching the provided requestId.
  • Code: packages/domain-k12/src/annex-editing-tools.ts
  • Example (HTTP - Status):
curl -X POST "$BASE_URL/ai/api/tools/k12-annex-editing-status/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"requestId": "req-123"}}'

k12-annex-editing-result​

  • Summary: Fetch the final result payload from a completed Annex editing workflow.
  • How it works: Retrieves the stored result from K12SAFETY.log_EOP_TaskRequests.ResponsePayloadJson.
  • Code: packages/domain-k12/src/annex-editing-tools.ts

K12 Tools — QRG (Quick Reference Guide)​

This section documents the QRG toolchain for generation and editing of Quick Reference Guides.

k12-qrg-generation-kickoff​

  • Summary: Main entry point to kick off QRG (Quick Reference Guide) generation from an Emergency Operation Plan. Creates QRGs for each annex form in the plan.
  • How it works: Validates input schema, creates a qrg_requests record with type GENERATION, starts the QRG generation workflow via Mastra, and optionally waits for completion. Returns request ID and status.
  • Code: packages/domain-k12/src/qrg/qrg-generation-kickoff.ts, qrg-generation-workflow-runner.ts (packages/domain-k12/src/qrg/qrg-generation-workflow-runner.ts)
  • DB: Creates records in K12SAFETY.qrg_requests, qrg_generations, workflow populates qrg_generated_items.
  • Example (HTTP):
curl -X POST "$BASE_URL/ai/api/tools/k12-qrg-generation-kickoff/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"emergencyOperationPlanId": "plan-sample", "userId": "admin@district.edu"}}'

k12-qrg-generation-status​

  • Summary: Poll the status of a QRG generation workflow.
  • How it works: Queries K12SAFETY.qrg_requests for the current status by requestId. QRG generation uses UPPERCASE status values: accepted (initial), PROCESSING, SUCCESS, ERROR, CANCELLED.
  • Code: packages/domain-k12/src/qrg/qrg-status-tools.ts (qrgGenerationStatusTool)
  • DB: Reads K12SAFETY.qrg_requests.
note

QRG generation uses UPPERCASE status values (SUCCESS, ERROR, PROCESSING, CANCELLED). QRG editing and EOP editing use lowercase (success, error, processing, cancelled). The initial accepted status is always lowercase across all workflows.

k12-qrg-generation-result​

  • Summary: Fetch the final result payload from a completed QRG generation workflow (list of generated QRGs).
  • How it works: Queries K12SAFETY.qrg_generations and qrg_generated_items to return the full structured result including annex count, QRG count, and generated items. Returns error status with detailed error messages when AI calls fail - no fallback content is generated.
  • Code: packages/domain-k12/src/qrg/qrg-status-tools.ts (qrgGenerationResultTool)
  • DB: Reads K12SAFETY.qrg_generations, qrg_generated_items.

k12-qrg-editing-kickoff​

  • Summary: Main entry point to kick off QRG editing workflow (edit existing QRGs based on user instructions).
  • How it works: Validates editing input schema (includes qrgId, editInstructions), creates a qrg_requests record with type EDITING, starts the editing workflow via Mastra, and optionally waits for completion.
  • Code: packages/domain-k12/src/qrg/qrg-editing-kickoff.ts, qrg-editing-workflow-runner.ts (packages/domain-k12/src/qrg/qrg-editing-workflow-runner.ts)
  • DB: Creates records in K12SAFETY.qrg_requests, workflow updates qrg_edits.

k12-qrg-editing-status​

  • Summary: Poll the status of a QRG editing workflow.
  • How it works: Queries K12SAFETY.qrg_requests for the current status by requestId.
  • Code: packages/domain-k12/src/qrg/qrg-status-tools.ts (qrgEditingStatusTool)
  • DB: Reads K12SAFETY.qrg_requests.

k12-qrg-editing-result​

  • Summary: Fetch the final result payload from a completed QRG editing workflow.
  • How it works: Queries K12SAFETY.qrg_edits to return the edited QRG content and metadata.
  • Code: packages/domain-k12/src/qrg/qrg-status-tools.ts (qrgEditingResultTool)
  • DB: Reads K12SAFETY.qrg_edits.

k12-qrg-cancel​

  • Summary: Cancel a pending QRG generation or editing job by RequestId.
  • How it works: Checks current job status and updates K12SAFETY.qrg_requests status to cancelled if allowed; returns success/error.
  • Code: packages/domain-k12/src/qrg/qrg-status-tools.ts (qrgCancelTool).
  • DB: Updates K12SAFETY.qrg_requests.

Tool Registry​

All K12 tools are exported from packages/domain-k12/src/index.ts. QRG-specific tools are in packages/domain-k12/src/qrg/index.ts.

Tool IDs follow the pattern: k12-{operation}-{entity} (e.g., k12-insert-task-request-log, k12-qrg-generation-kickoff).

Implementation notes & where to look​

  • Schemas & validation: All tools use Zod schemas for input/output located near each tool (e.g., annex-editing-kickoff-schemas.ts (packages/domain-k12/src/annex-editing-kickoff-schemas.ts), qrg/qrg-schemas.ts (packages/domain-k12/src/qrg/qrg-schemas.ts)).
  • SQL access: Tools use loadSqlClient() and executeSql() helpers for parameterized SQL against the Azure SQL DB.
  • Tests: Unit tests for tools live under packages/domain-k12/tests/tools/ and API checks are in bruno/.
  • Workflows: See packages/domain-k12/src/k12-annex.workflow.ts, qrg-generation.workflow.ts (packages/domain-k12/src/qrg-generation.workflow.ts), qrg-editing.workflow.ts (packages/domain-k12/src/qrg-editing.workflow.ts) for orchestration logic.

Next steps​