schemas.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://peas.local/schemas/v0/tools.json",
  "title": "PEAS schemas — PH2 tool chain + T5 mesh-pod messages",
  "description": "Two schema families coexist here. (1) PEAS PH2 tool-call chain: five tools (detect_pileup_signature → compose_ops_brief → request_approval → issue_vms_update → notify_driver) each with input + output schemas, every output carrying a `reasoning` block to satisfy §6.8 + Safety & Trust. Hop routing per phase-2-spike.md §2 E6: tool-call hops default to Ollama /api/chat tools (Mac + Jetson); pure language-generation hops default to LiteRT on Jetson. (2) T5 wildfire mesh-pod messages (added 2026-05-12, per docs/research/t5-wildfire-mesh-pod-requirements-2026-05-12.md): three message types (PEAS-MESH-ADVISORY-v1 / PEAS-MESH-AGGREGATION-v1 / PEAS-MESH-BROADCAST-v1) carried over a pluggable mesh transport (loopback in v1, real LoRA / RFD900 / ATAK in T5-FW-3). All schemas use JSON Schema 2020-12; cross-family refs go through #/$defs. Validator: scripts/tools/validate_schemas.py (PH2 tools today); T5 fixture validation is a pilot follow-up.",
  "$defs": {
    "iso_timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 UTC timestamp, e.g. 2026-04-19T15:30:00Z"
    },
    "uuid_v4": {
      "type": "string",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$",
      "description": "RFC 4122 UUID v4"
    },
    "sensor_readings": {
      "type": "object",
      "description": "Structured deterministic sensor input. Per technical invariant §6.8, detection is threshold-based on these fields; Gemma 4 does not itself classify raw sensor data.",
      "additionalProperties": false,
      "required": [
        "crash_density_per_min",
        "visibility_ft",
        "ambient_temp_f",
        "traffic_speed_mph"
      ],
      "properties": {
        "crash_density_per_min": {
          "type": "number",
          "minimum": 0,
          "description": "Running crash reports per minute in the corridor. Threshold for signature candidate: > 0.5."
        },
        "visibility_ft": {
          "type": "integer",
          "minimum": 0,
          "maximum": 52800,
          "description": "RWIS / nearby-sensor visibility in feet. Threshold: < 500 ft is concerning."
        },
        "ambient_temp_f": {
          "type": "number",
          "minimum": -60,
          "maximum": 140,
          "description": "Air temperature in Fahrenheit. Freeze risk ≤ 34 F."
        },
        "precipitation_type": {
          "type": "string",
          "enum": ["none", "rain", "snow", "sleet", "freezing_rain", "fog"],
          "description": "Current precipitation classification from RWIS or operator input."
        },
        "traffic_speed_mph": {
          "type": "number",
          "minimum": 0,
          "maximum": 120,
          "description": "Median corridor traffic speed, mph."
        },
        "wind_mph": {
          "type": "number",
          "minimum": 0,
          "maximum": 200,
          "description": "Sustained wind speed, mph. Optional — not always present."
        }
      }
    },
    "signature": {
      "type": "object",
      "description": "Shared pile-up signature object produced by detect_pileup_signature and consumed by compose_ops_brief.",
      "additionalProperties": false,
      "required": [
        "signature_id",
        "location_id",
        "detected_at",
        "severity",
        "confidence",
        "contributing_factors"
      ],
      "properties": {
        "signature_id": { "$ref": "#/$defs/uuid_v4" },
        "location_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "description": "Stable identifier for a corridor + milepost pair, e.g. 'I-94:MM88-EB'."
        },
        "detected_at": { "$ref": "#/$defs/iso_timestamp" },
        "severity": {
          "type": "string",
          "enum": ["watch", "warn", "critical"],
          "description": "watch: early indicators; warn: multi-factor crossing; critical: active pile-up signature."
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Deterministic detector confidence [0,1]. Gemma 4 does not compute this."
        },
        "contributing_factors": {
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": {
            "type": "string",
            "minLength": 2,
            "maxLength": 80
          },
          "description": "Short human-readable factors, e.g. 'visibility < 500 ft', 'crash density rising', 'near-freezing + snow'."
        },
        "sensor_snapshot": {
          "$ref": "#/$defs/sensor_readings"
        }
      }
    },
    "reasoning_block": {
      "type": "string",
      "minLength": 20,
      "maxLength": 1200,
      "description": "Plain-language explanation of why this output was produced. Required on every tool output (Safety & Trust invariant, §7 story invariant §5, §6.8 technical invariant). Rule: reasoning MUST cite the specific input fields or prior-tool outputs that justified the response. Hallucination-risk mitigation per phase-2-spike.md §7 risk #4."
    },
    "tier_enum": {
      "type": "string",
      "enum": ["info", "warning", "critical", "emergency"],
      "description": "T5 mesh-pod hazard alert tier per docs/science/hazard-observability-v1.md §3.3. Shared by detector_state, aggregation severity, and broadcast severity."
    },
    "mgrs_position": {
      "type": "object",
      "additionalProperties": false,
      "required": ["mgrs"],
      "description": "T5 forward-node position. v1 (per OQ-T5.2 resolution 2026-05-12) uses fixture-supplied plausible-looking strings; real MGRS conversion is future-work T5-FW-4.",
      "properties": {
        "mgrs": {
          "type": "string",
          "minLength": 4,
          "maxLength": 32,
          "description": "Military Grid Reference System coordinate string. v1: hardcoded plausible-looking value per node."
        },
        "lat": { "type": "number", "minimum": -90, "maximum": 90 },
        "lon": { "type": "number", "minimum": -180, "maximum": 180 },
        "uncertainty_m": {
          "type": "number",
          "minimum": 0,
          "description": "Position uncertainty in meters."
        }
      }
    },
    "mesh_sensor_reading": {
      "type": "object",
      "additionalProperties": false,
      "description": "Structured deterministic sensor input from a T5 forward mesh-pod node. Mirrors the §6.8 discipline of sensor_readings (PH2) — detection is threshold-based on these fields; Gemma 4 composes over them rather than classifying them.",
      "properties": {
        "thermal_max_c": {
          "type": "number",
          "description": "Peak radiometric temperature in °C from the thermal sensor frame."
        },
        "thermal_area_m2": {
          "type": "number",
          "minimum": 0,
          "description": "Area (m²) above the deterministic thermal threshold."
        },
        "thermal_anomaly_pixels": { "type": "integer", "minimum": 0 },
        "ambient_c": { "type": "number" },
        "humidity_pct": { "type": "number", "minimum": 0, "maximum": 100 },
        "wind_speed_ms": { "type": "number", "minimum": 0 },
        "wind_gust_ms": { "type": "number", "minimum": 0 },
        "wind_dir_deg": { "type": "number", "minimum": 0, "maximum": 360 }
      }
    },
    "mesh_detector_state": {
      "type": "object",
      "additionalProperties": false,
      "required": ["tier", "rule_signature"],
      "description": "Output of the deterministic fire-weather rule + WFIGS perimeter-proximity escalator. Reused at every T5 forward node (FR-T5.F.3). Detector remains deterministic per §6.8.",
      "properties": {
        "tier": { "$ref": "#/$defs/tier_enum" },
        "rule_signature": {
          "type": "string",
          "minLength": 4,
          "maxLength": 64,
          "description": "Stable identifier for the deterministic rule version that produced this state, e.g. 'fwra-v1-2026-04-22'."
        },
        "wfigs_proximity_km": { "type": "number", "minimum": 0 },
        "rfw_active": {
          "type": "boolean",
          "description": "Whether a Red Flag Warning is active at the node's position."
        }
      }
    },
    "mesh_composer_signature": {
      "type": "object",
      "additionalProperties": false,
      "required": ["model"],
      "description": "Identifies which Gemma 4 model + optional adapter composed an advisory or aggregation. Adapter is null in stock mode and a path/identifier in adapter mode (per T5 §8 stock-vs-adapter modes).",
      "properties": {
        "model": {
          "type": "string",
          "minLength": 1,
          "maxLength": 96,
          "description": "Model identifier, e.g. 'gemma-4-E2B-it' or 'gemma-4-E4B-it'."
        },
        "adapter": {
          "type": ["string", "null"],
          "maxLength": 256,
          "description": "Adapter path or identifier when adapter mode is in use; null in stock mode."
        },
        "wall_s": {
          "type": "number",
          "minimum": 0,
          "description": "Composer wall time in seconds."
        }
      }
    },
    "peas_mesh_advisory_v1": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema_version",
        "node_id",
        "position",
        "observation_ts",
        "sensor_reading",
        "detector_state",
        "advisory_text",
        "composer_signature"
      ],
      "description": "T5 mesh-pod forward advisory. Emitted by each forward Jetson per cycle (30–60 s default) over the mesh transport. Size-bounded ≤ 2 KB (NFR-T5.2). Composed by Gemma 4 over deterministic detector output; preserves §6.8 composer-not-classifier. R4 discipline test: when detector_state.tier='info' (clear), advisory_text MUST NOT fabricate fire.",
      "properties": {
        "schema_version": { "const": "PEAS-MESH-ADVISORY-v1" },
        "node_id": {
          "type": "string",
          "pattern": "^forward-[A-Za-z0-9-]+$",
          "minLength": 9,
          "maxLength": 64,
          "description": "Stable forward-node identifier. Pattern enforces the 'forward-' prefix per T5 §1.1 topology."
        },
        "position": { "$ref": "#/$defs/mgrs_position" },
        "observation_ts": { "$ref": "#/$defs/iso_timestamp" },
        "sensor_reading": { "$ref": "#/$defs/mesh_sensor_reading" },
        "detector_state": { "$ref": "#/$defs/mesh_detector_state" },
        "advisory_text": {
          "type": "string",
          "minLength": 20,
          "maxLength": 800,
          "description": "Plain-language §6.8-disciplined advisory composed by Gemma 4. MUST NOT contradict the deterministic detector_state.tier."
        },
        "composer_signature": { "$ref": "#/$defs/mesh_composer_signature" }
      }
    },
    "peas_mesh_aggregation_v1": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema_version",
        "aggregation_ts",
        "input_advisory_node_ids",
        "aggregation_text",
        "severity_tier",
        "approval_request_id"
      ],
      "description": "T5 Mac-side aggregation across N forward advisories. Produced on hybrid cadence (60 s minimum + event-triggered on new critical/emergency, per OQ-T5.1 resolution 2026-05-12). Size-bounded ≤ 2 KB (NFR-T5.3). Has its own §6.8 discipline test (OQ-T5.3 resolution): MUST NOT escalate when ALL input nodes report info/clear.",
      "properties": {
        "schema_version": { "const": "PEAS-MESH-AGGREGATION-v1" },
        "aggregation_ts": { "$ref": "#/$defs/iso_timestamp" },
        "input_advisory_node_ids": {
          "type": "array",
          "minItems": 1,
          "maxItems": 32,
          "items": {
            "type": "string",
            "pattern": "^forward-[A-Za-z0-9-]+$"
          },
          "description": "Node IDs of the forward advisories synthesized in this aggregation. Cross-references PEAS-MESH-ADVISORY-v1.node_id."
        },
        "aggregation_text": {
          "type": "string",
          "minLength": 40,
          "maxLength": 1200,
          "description": "Plain-language wide-area synthesis. MUST cite which node said what (anti-hallucination guard for cross-node correlation per T5 §11)."
        },
        "severity_tier": { "$ref": "#/$defs/tier_enum" },
        "spatial_extent_bbox": {
          "type": "array",
          "minItems": 4,
          "maxItems": 4,
          "items": { "type": "number" },
          "description": "[min_lat, min_lon, max_lat, max_lon] bounding box of the contributing nodes. Optional in v1 (OQ-T5.2 fixture-position mode)."
        },
        "stale_node_ids": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Nodes silent > 3× polling period. Their last-known severity is downgraded to 'warning' max in the aggregation (FR-T5.A.5 fail-safe-on-stale)."
        },
        "approval_request_id": { "$ref": "#/$defs/uuid_v4" },
        "composer_signature": { "$ref": "#/$defs/mesh_composer_signature" }
      }
    },
    "peas_mesh_broadcast_v1": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema_version",
        "broadcast_ts",
        "approval_request_id",
        "operator_id",
        "broadcast_text",
        "severity_tier",
        "target_audience"
      ],
      "description": "T5 approved wide-area broadcast emitted by the Mac after operator form-(a) approval of an aggregation. Per §6.7, operator approval is the gate; this message is the chain-of-custody record of the approved actuation. Target audiences are named text labels in v1 (OQ-T5.4 default 2026-05-12); GPS-routed targeting is T5-FW-7.",
      "properties": {
        "schema_version": { "const": "PEAS-MESH-BROADCAST-v1" },
        "broadcast_ts": { "$ref": "#/$defs/iso_timestamp" },
        "approval_request_id": {
          "$ref": "#/$defs/uuid_v4",
          "description": "Threads back to the PEAS-MESH-AGGREGATION-v1 that the operator approved. Single approval_request_id appears in the aggregation + broadcast + the audit-trail JSONL ledger (§6.9 chain-of-custody)."
        },
        "operator_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "description": "Identifier of the human operator who approved the broadcast (form-(a) §6.2)."
        },
        "broadcast_text": {
          "type": "string",
          "minLength": 20,
          "maxLength": 1200,
          "description": "Plain-language wide-area broadcast. MAY repeat content from the aggregation_text; MUST NOT introduce new claims the operator did not approve."
        },
        "severity_tier": {
          "type": "string",
          "enum": ["warning", "critical", "emergency"],
          "description": "Broadcasts are never tier=info (only warning or higher reach this gate)."
        },
        "target_audience": {
          "type": "array",
          "minItems": 1,
          "maxItems": 16,
          "items": {
            "type": "string",
            "enum": [
              "ground_crew_alpha",
              "ground_crew_bravo",
              "ground_crew_charlie",
              "ops_center",
              "evacuation_route_signage"
            ]
          },
          "description": "Named audiences in v1. GPS-routed delivery is T5-FW-7 (post-v1)."
        }
      }
    }
  },
  "tools": [
    {
      "name": "detect_pileup_signature",
      "description": "Evaluate a window of sensor readings and return a structured pile-up signature when deterministic thresholds cross. Gemma 4's role is orchestration only — the numeric thresholds are computed externally; the LLM decides whether to call this tool based on conversational context. If called with sub-threshold readings, the tool returns severity='watch' with confidence < 0.5 and the caller SHOULD NOT advance to compose_ops_brief.",
      "hop_routing": "ollama",
      "input": {
        "type": "object",
        "additionalProperties": false,
        "required": ["location_id", "sensor_readings"],
        "properties": {
          "location_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Stable corridor+milepost id."
          },
          "sensor_window_s": {
            "type": "integer",
            "minimum": 30,
            "maximum": 3600,
            "default": 300,
            "description": "Aggregation window in seconds."
          },
          "sensor_readings": { "$ref": "#/$defs/sensor_readings" }
        }
      },
      "output": {
        "type": "object",
        "additionalProperties": false,
        "required": ["signature", "reasoning"],
        "properties": {
          "signature": { "$ref": "#/$defs/signature" },
          "reasoning": { "$ref": "#/$defs/reasoning_block" }
        }
      }
    },
    {
      "name": "compose_ops_brief",
      "description": "Turn a pile-up signature into a plain-language ops brief for the human approver. MUST cite the Galesburg 2015 historical comparison when severity ≥ warn. MUST NOT invent fields beyond those present in the signature or historical_comparisons arguments (anti-hallucination guard per phase-2-spike.md §7 risk #4). Output text target: ≤ 200 words, readable at a glance on a mobile PWA. Hop routing: language-generation only — prefer LiteRT on Jetson for the edge-local case, fall back to Mac Ollama gemma4:latest for the ops-console case per the 26B/31B weight allocation.",
      "hop_routing": "litert_preferred",
      "input": {
        "type": "object",
        "additionalProperties": false,
        "required": ["signature"],
        "properties": {
          "signature": { "$ref": "#/$defs/signature" },
          "historical_comparisons": {
            "type": "array",
            "maxItems": 4,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["label", "summary"],
              "properties": {
                "label": {
                  "type": "string",
                  "minLength": 4,
                  "maxLength": 96,
                  "description": "Short human-readable identifier, e.g. 'I-94 Galesburg 2015-01-09 whiteout pile-up (~193 vehicles, 1 fatality)'."
                },
                "summary": {
                  "type": "string",
                  "minLength": 20,
                  "maxLength": 400
                },
                "source_url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "output": {
        "type": "object",
        "additionalProperties": false,
        "required": ["brief_id", "ops_brief_text", "recommended_action", "urgency", "reasoning"],
        "properties": {
          "brief_id": { "$ref": "#/$defs/uuid_v4" },
          "ops_brief_text": {
            "type": "string",
            "minLength": 40,
            "maxLength": 1400,
            "description": "≤ ~200 words, plain-language brief aimed at a human ops operator."
          },
          "recommended_action": {
            "type": "string",
            "minLength": 4,
            "maxLength": 200,
            "description": "One-sentence action for the operator to approve or decline."
          },
          "urgency": {
            "type": "string",
            "enum": ["low", "medium", "high", "critical"]
          },
          "historical_citation_included": {
            "type": "boolean",
            "description": "True iff the brief cited at least one element from historical_comparisons."
          },
          "reasoning": { "$ref": "#/$defs/reasoning_block" },
          "prediction_trace_id": {
            "type": ["string", "null"],
            "pattern": "^[0-9a-f]{32}$",
            "description": "PEAS-PRED-5: OTel trace_id (32-hex-char) of the prediction root span. Null when OTel is disabled or the composer wasn't run inside a prediction context. Consumed by B3.4 PWA for deep-linking into Tempo."
          },
          "prediction_span_id": {
            "type": ["string", "null"],
            "pattern": "^[0-9a-f]{16}$",
            "description": "PEAS-PRED-5: OTel span_id (16-hex-char) of the current hop's span. Pairs with prediction_trace_id."
          }
        }
      }
    },
    {
      "name": "request_approval",
      "description": "Dispatch an approval request to the on-duty ops operator via their preferred channel. This tool does NOT issue any public-facing action; it only pages a human. The human approves via the mobile PWA (§7.4 chain-of-custody). Story invariant §7.5: the ops operator is always the approver — no autonomous driver pushes (§6.7).",
      "hop_routing": "ollama",
      "input": {
        "type": "object",
        "additionalProperties": false,
        "required": ["brief_id", "target_operator_id"],
        "properties": {
          "brief_id": { "$ref": "#/$defs/uuid_v4" },
          "target_operator_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "On-duty operator identifier, e.g. 'mdot-ops-A-2026W16'."
          },
          "preferred_channel": {
            "type": "string",
            "enum": ["pwa", "pager", "sms"],
            "default": "pwa"
          },
          "expires_in_s": {
            "type": "integer",
            "minimum": 30,
            "maximum": 1800,
            "default": 300,
            "description": "Request lifetime before escalation."
          }
        }
      },
      "output": {
        "type": "object",
        "additionalProperties": false,
        "required": ["approval_request_id", "dispatched_at", "expires_at", "channel_used", "reasoning"],
        "properties": {
          "approval_request_id": { "$ref": "#/$defs/uuid_v4" },
          "dispatched_at": { "$ref": "#/$defs/iso_timestamp" },
          "expires_at": { "$ref": "#/$defs/iso_timestamp" },
          "channel_used": {
            "type": "string",
            "enum": ["pwa", "pager", "sms"]
          },
          "reasoning": { "$ref": "#/$defs/reasoning_block" }
        }
      }
    },
    {
      "name": "issue_vms_update",
      "description": "Post a message to a variable message sign (VMS) billboard. MUST ONLY be invoked after request_approval has returned approval_status='approved' on the referenced approval_request_id. The orchestrator is responsible for enforcing that gate; this tool returns an error if the referenced approval is missing or not 'approved'. Message content MUST fit VMS display constraints: ≤ 80 chars, uppercase ASCII + .,!- punctuation only (no emoji, no lowercase).",
      "hop_routing": "ollama",
      "input": {
        "type": "object",
        "additionalProperties": false,
        "required": ["approval_request_id", "billboard_id", "message"],
        "properties": {
          "approval_request_id": { "$ref": "#/$defs/uuid_v4" },
          "billboard_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Stable VMS id, e.g. 'I-94:VMS:MM85-EB'."
          },
          "message": {
            "type": "string",
            "minLength": 4,
            "maxLength": 80,
            "pattern": "^[A-Z0-9 .,!\\-]+$",
            "description": "VMS-safe uppercase message."
          },
          "duration_s": {
            "type": "integer",
            "minimum": 60,
            "maximum": 7200,
            "default": 900
          }
        }
      },
      "output": {
        "type": "object",
        "additionalProperties": false,
        "required": ["vms_update_id", "posted_at", "message_shown", "expires_at", "reasoning"],
        "properties": {
          "vms_update_id": { "$ref": "#/$defs/uuid_v4" },
          "posted_at": { "$ref": "#/$defs/iso_timestamp" },
          "message_shown": {
            "type": "string",
            "minLength": 4,
            "maxLength": 80,
            "pattern": "^[A-Z0-9 .,!\\-]+$"
          },
          "expires_at": { "$ref": "#/$defs/iso_timestamp" },
          "reasoning": { "$ref": "#/$defs/reasoning_block" }
        }
      }
    },
    {
      "name": "notify_driver",
      "description": "Deliver a soft warning to an in-vehicle PEAS device. This is the last hop in the chain-of-custody (roadside → ops → approval → VMS → in-car). §6.7 forbids autonomous pushes: the orchestrator MUST NOT call this tool without a prior approved vms_update_id, and the tool returns an error if that linkage is absent. Warning text is short and TTS-friendly.",
      "hop_routing": "ollama",
      "input": {
        "type": "object",
        "additionalProperties": false,
        "required": ["vehicle_id", "vms_update_id", "warning_text"],
        "properties": {
          "vehicle_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64,
            "description": "Stable in-car device id."
          },
          "vms_update_id": {
            "$ref": "#/$defs/uuid_v4",
            "description": "The already-issued VMS update this warning piggybacks on (chain-of-custody link)."
          },
          "warning_text": {
            "type": "string",
            "minLength": 8,
            "maxLength": 140,
            "description": "Short TTS-friendly warning. Avoid numbers spelled as digits where word-form reads better."
          },
          "tts_voice_style": {
            "type": "string",
            "enum": ["calm", "urgent"],
            "default": "calm",
            "description": "Calm preferred; urgent only when severity=critical and per operator override."
          }
        }
      },
      "output": {
        "type": "object",
        "additionalProperties": false,
        "required": ["notification_id", "delivered_at", "warning_text_shown", "reasoning"],
        "properties": {
          "notification_id": { "$ref": "#/$defs/uuid_v4" },
          "delivered_at": { "$ref": "#/$defs/iso_timestamp" },
          "warning_text_shown": {
            "type": "string",
            "minLength": 8,
            "maxLength": 140
          },
          "audio_uri": {
            "type": ["string", "null"],
            "format": "uri",
            "description": "Optional URI of the pre-rendered TTS clip; null if device-local TTS used."
          },
          "reasoning": { "$ref": "#/$defs/reasoning_block" }
        }
      }
    }
  ]
}