146 lines
4.8 KiB
Markdown
146 lines
4.8 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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.
|