Skip to main content

K12 Safety Documentation

K12 Safety Platform Overview​

The K12 Safety platform provides AI-powered tools and workflows for managing Emergency Operation Plans (EOPs) and Quick Reference Guides (QRGs) for K12 educational institutions. The system helps schools and districts create, edit, and maintain critical safety documentation through intelligent automation and structured workflows.

What Is Currently Implemented​

1. Emergency Operation Plan (EOP) Editing​

Purpose: AI-assisted editing of EOP functional annexes (emergency response procedures).

What It Does:

  • Accepts edit requests for specific EOP annex sections
  • Uses AI agents to generate or modify safety procedure content
  • Maintains contextual awareness through EOP snapshot integration with MOEOP (Missouri EOP) system
  • Provides version tracking and audit logging of all changes
  • Ensures role-based access for authorized personnel

Use Cases:

  • Safety coordinators editing emergency response procedures
  • Principals updating facility-specific safety protocols
  • District administrators standardizing safety documentation

Output: Edited EOP content ready for review and incorporation into official plans

Current Status: Production-ready. Processes edit requests with full database logging and status tracking.

2. Quick Reference Guide (QRG) Generation​

Purpose: Automated creation of action-oriented safety guides from EOP annexes.

What It Does:

  • Generates category-specific QRGs from existing EOP annexes
  • Classifies annex categories (functionality-based vs. emergency-type)
  • Resolves exact General User Tag Categories from the compiled EOP
  • Creates one recommendation target per annex/category pair
  • Creates structured content blocks organized by phases (BEFORE, DURING, AFTER)
  • Supports batch processing for multiple QRG creation

Use Cases:

  • Generating category-specific quick reference cards from comprehensive EOPs
  • Creating emergency response checklists for different scenarios
  • Producing actionable guides for specific audiences

Output: Category-specific QRG documents with phase-structured action items

Current Status: Production-ready. Generates multiple QRGs per EOP with customizable roles and formats.

3. QRG Editing Workflow​

Purpose: AI-assisted modification of existing Quick Reference Guides.

What It Does:

  • Accepts edit requests for existing QRG content
  • Uses specialized QRG editor agent to modify specific sections
  • Maintains structural integrity (BEFORE/DURING/AFTER phases)
  • Preserves the QRG's exact General User Tag Category targeting
  • Logs all modifications for audit trail

Current Status: Production-ready. Edits existing QRGs with full version control.

Architecture Components​

Agents​

K12 Safety uses specialized AI agents for different tasks:

  • K12 Safety Agent (Eddy) - Main agent for EOP editing and content generation
  • Scenario-specific EOP agents - District, facility, functional-annex, hazard-annex, and missing-role behaviors with stable profile/registry IDs
  • QRG Category Guide Generator - Recommends and generates one guide for an exact annex/category target
  • QRG Category Guide Editor - Edits one category-specific guide section
  • Turn-based Evaluator Agent - Scores annex/QRG scenario conversations
  • Optional Browser EOP Agent - Loaded only when browser evaluation artifacts are enabled

The older QRG classification, group-extraction, role-mapping, content-generation, and generic editor profiles are retired and are not registered at runtime.

See K12 Agents for detailed agent documentation.

Workflows​

Production workflows and evaluation workflows orchestrate the K12 domain:

  1. EOP Workflow (packages/domain-k12/src/k12-annex.workflow.ts)

    • Handles EOP editing requests
    • Manages task logging and status tracking
    • Integrates with MOEOP (Missouri EOP) system for snapshots

  2. QRG Workflows

    • Generation (packages/domain-k12/src/qrg-generation.workflow.ts) - Creates new QRGs from EOPs
    • Editing (packages/domain-k12/src/qrg-editing.workflow.ts) - Modifies existing QRGs

  3. Turn-based evaluation workflows (packages/domain-k12/src/k12-turn-based/)

    • Replays annex and QRG conversations
    • Runs checked-in scenarios and batch scenario suites
    • Mines draft scenarios from historical interactions

See K12 Workflows for workflow details.

Tools​

28 registered K12 tools handle specific operations:

  • Task Management: Insert, update, lookup task requests and status
  • Workflow Orchestration: EOP kickoff, scenario-specific kickoff, status polling, result retrieval
  • Data Collection: EOP snapshots and role universe lookups
  • QRG Operations: Generation, editing, status tracking, cancellation

See K12 Tools (Detailed) for complete tool catalog.

Database​

K12 Safety uses the K12SAFETY schema in Azure SQL for operational data:

EOP Tables:

  • log_EOP_TaskRequests - Full request payloads and responses
  • log_EOP_TaskStatus - Status timeline for monitoring
  • log_Jobs - General job tracking

QRG Tables:

  • qrg_requests - QRG generation/editing requests
  • qrg_generations - Generation metadata and results
  • qrg_generated_items - Individual generated QRGs
  • qrg_generation_annexes - Per-annex processing tracking
  • qrg_ai_calls - Individual AI call logs (tokens, duration, status)
  • qrg_execution_errors - Workflow-level error tracking
  • qrg_edits - Edit requests and results
  • qrg_edit_context - Edit context snapshots
  • qrg_request_prompts - Custom prompts per request
  • qrg_request_roles - Role associations

See K12 Database for schema details and ER diagrams.

How It Works​

EOP Editing Flow​

  1. Request Submission: User submits edit request via API or UI
  2. Task Logging: Request logged to log_EOP_TaskRequests
  3. Workflow Kickoff: k12-annex-editing-kickoff starts Mastra workflow
  4. EOP Snapshot: Fetches current plan state from MOEOP
  5. AI Processing: K12 Safety Agent generates/edits content
  6. Result Storage: Response saved to database
  7. Status Updates: Client polls status via k12-annex-editing-status
  8. Result Retrieval: Final payload fetched via k12-annex-editing-result

QRG Generation Flow​

  1. Request Submission: Submit EOP ID and generation parameters
  2. Request Creation: Record created in qrg_requests (type: GENERATION)
  3. Workflow Kickoff: k12-qrg-generation-kickoff starts workflow
  4. Category Resolution: Resolves exact General User Tag Categories from the compiled EOP or an explicit category-ID filter
  5. Target Construction: Creates each annex × category pair and deterministically classifies the annex name
  6. Recommendation And Generation: One category guide agent recommends or skips each target and generates BEFORE/DURING/AFTER blocks when recommended
  7. Result Storage: Target decisions and generated QRGs are saved to the QRG audit tables; external K12 writes are recorded per guide
  8. Status Polling: Client checks status via k12-qrg-generation-status
  9. Result Retrieval: Fetch complete results via k12-qrg-generation-result

Key Features​

Profile-Based Agent Management​

Agents use database-managed prompts from Core.AgentProfiles:

  • Prompts editable via Admin UI
  • Version tracking with ProfileHash
  • Per-profile LLM model overrides
  • Automatic agent rebuilding on profile changes

Idempotent Workflow Execution​

Workflows support safe retries and status checking:

  • Duplicate request detection via requestId
  • Status tracking for in-flight operations
  • Cancellation support via k12-qrg-cancel

Audit Trail​

Complete audit logging for compliance:

  • Full request/response payloads in RawRequestJson/RawResponseJson
  • Status timeline in log_EOP_TaskStatus
  • Timestamp tracking (CreatedAt, ModifiedAt)
  • User and role tracking

Integration Points​

  • MOEOP Integration: EOP snapshot tool for contextual data
  • Mastra Workflows: Native Mastra workflow orchestration
  • Azure SQL: Durable state and audit logging
  • Azure OpenAI: LLM-powered content generation

Development & Testing​

Local Development​

# Run dev server
npm run dev

# Run all K12 tests
npm run test:k12

Testing​

  • Tool unit tests: packages/domain-k12/tests/tools/ (annex editing, EOP snapshot, QRG tools, task management)
  • Agent tests: packages/domain-k12/tests/agents/k12-agents.test.ts
  • E2E tests: tests/e2e/k12/annex-editing.e2e.test.ts
  • Bruno collections: npm run bruno:test:k12

See K12 Testing for full details.

Environment Variables​

Key environment variables:

  • AZURE_SQL_CONNECTION_STRING - Database connection
  • AZURE_INFERENCE_ENDPOINT - Azure AI Inference endpoint
  • MOEOP_INTERNAL_BASE_URL - MOEOP integration endpoint
  • QRG_GENERATION_CONCURRENCY - Category-target model concurrency (1-6, default 4)
  • QRG_SAVE_TO_K12 - Enable/disable external K12 guide saves
  • K12_DEBUG_AGENT_OVERRIDES - Enable agent debugging

Code Locations​

  • Agents: packages/domain-k12/src/agents/
  • Workflows: packages/domain-k12/src/ (k12-annex.workflow.ts, qrg-*.workflow.ts) and packages/domain-k12/src/k12-turn-based/
  • Tools: packages/domain-k12/src/
  • Database: db/sqlproj/Mastra.Platform.K12SafetyDb/
  • Tests: packages/domain-k12/tests/, tests/integration/k12/, tests/e2e/k12/, tests/shared/integration/workflows/k12-annex-schemas.test.ts

Next Steps​

Implementation Guide

End-to-end deployment guide: Azure template, K12 config, MOEOP integration, and debugging

K12 Agents

Explore K12 Safety and QRG agents

K12 Workflows

Learn about EOP and QRG workflows

K12 Tools

Complete catalog of K12 tools

K12 Database

Database schema and ER diagrams