Prompt Input Internals

This document describes YAML prompt data package construction in internal/promptinput.

Purpose

internal/promptinput converts report metadata, an ordered module snapshot, Recent Changes, and source warnings into the data_package file passed to Scriptorium.

The persisted data package is YAML with schema version weatherreporter.data_package.v2. It is separate from the JSON module snapshot used for inspection and comparison.

Inputs And Outputs

Inputs:

report metadata from app/state orchestration
module.Snapshot
optional []changes.Change

Outputs:

promptinput.Package with schema version, RunID, report metadata, named module stanzas grouped for prompt presentation, Recent Changes, and source warnings
YAML bytes from promptinput.MarshalYAML
YAML file written atomically by promptinput.Save

The YAML shape includes:

schema_version: weatherreporter.data_package.v2
run_id: <run_id>
report:
  id: <report_id>
  prompt_id: <prompt_id>
briefing:
  metadata: {}
  applicable_risk_products:
    alert_digest: {}
    spc_convective_outlooks: {}
  derived_summaries:
    derived_daily_summary: {}
    derived_daypart_summaries: {}
    precip_timing: {}
    outdoor_windows: {}
  narrative_products:
    narrative_forecast: {}
    area_forecast_discussion: {}
    spc_convective_discussion: {}
    weather_story: {}
  raw_data:
    current_conditions: {}
    hourly_forecast: {}
recent_changes:
  items: []

The briefing mapping keeps metadata directly under briefing and groups weather module stanzas under prompt-facing categories. This grouping is a YAML presentation concern only: module snapshots remain flat, and loaded promptinput.Package values expose flat stanza names in Briefing.Values. Within each category, stanza order follows the module snapshot output order. Prompt-facing module intervals use local period_begins and period_ends labels; canonical report metadata and source timestamps remain structured timestamps where applicable.

Today Report, Tomorrow Report, and Hourly Report module snapshots use the same package schema and categories when converted into prompt input. The default hourly module list places precip_timing under derived_summaries, alert and SPC outlooks under applicable_risk_products, AFD/SPC discussion/weather story under narrative_products, and current/hourly data under raw_data. It does not include civil-day summary stanzas. Generated-text and render context artifacts are produced later in app orchestration and are not part of the YAML data package.

The default Today and Tomorrow module lists include civil-day summary stanzas, planning stanzas, and hourly_forecast in the data package before structured GeneratedText is requested from Scriptorium. Today uses today_planning; Tomorrow uses tomorrow_planning.

Current categories are:

applicable_risk_products: location-applicable alerts, warnings, outlooks, and similar risk products. Current stanzas include alert_digest and spc_convective_outlooks.
derived_summaries: deterministic summaries and calculated report facts.
narrative_products: official narrative text products and forecast stories. Current stanzas include narrative_forecast, area_forecast_discussion, spc_convective_discussion, and weather_story.
raw_data: minimally transformed underlying weather data.

Boundaries

This package owns prompt package schema, YAML marshaling, YAML loading, and validation.
It does not fetch weather data, derive forecast summaries, execute modules, find prior snapshots, compare changes, choose artifact paths, or invoke Scriptorium.

Config Fields Used

None directly. Config-derived values such as timezone, units, and prompt location are already present in report metadata and module stanzas before this package runs.

External Adapters Used

None.

State Or Manifest Behavior

promptinput.Save writes YAML atomically. Managed workspace paths are owned by internal/state.

Skip And Resume Behavior

None. Recent Changes is always present as an items list and may be empty.

Failure Behavior

Validation fails before render preflight when required top-level fields are missing or inconsistent, when the valid period is invalid, or when no module stanzas are present. Save failures include filesystem operation and path context.

Tests

Inspect:

internal/promptinput/package_test.go
internal/app/app_test.go

Invariants

Scriptorium receives structured YAML through --input data_package=<path>.
Module stanza order is deterministic within each prompt-facing category.
Every non-metadata module stanza has exactly one prompt-input category.
Recent Changes are provided by internal/changes; this package does not infer changes from rendered report text.

4.8 KiB Raw Blame History