Refresh report and template internals documentation
This commit is contained in:
@@ -1,177 +1,61 @@
|
||||
# Prompt Input Internals
|
||||
|
||||
This document describes YAML prompt data package construction in
|
||||
`internal/promptinput`.
|
||||
`internal/promptinput` converts report metadata, an ordered module snapshot,
|
||||
Recent Changes, and source warnings into the YAML `data_package` consumed by
|
||||
Scriptorium. It owns this package's schema, grouping, serialization, loading,
|
||||
and validation—not weather collection, module construction, path choice, or
|
||||
subprocess execution.
|
||||
|
||||
## Purpose
|
||||
## Package construction
|
||||
|
||||
`internal/promptinput` converts report metadata, ordered module outputs, Recent
|
||||
Changes, and source warnings into the `data_package` file passed to
|
||||
Scriptorium.
|
||||
`Build` produces `weatherreporter.data_package.v3`. It copies the run ID;
|
||||
report ID, variant, prompt ID, generation time, timezone, local current date,
|
||||
and valid period; ordered briefing stanzas; Recent Changes; and source
|
||||
warnings. A nil Recent Changes slice becomes an empty `items` list.
|
||||
|
||||
The persisted data package is YAML with schema version
|
||||
`weatherreporter.data_package.v3`. It is separate from the JSON module snapshot
|
||||
used for inspection and comparison. Data packages serialize each module
|
||||
output's prompt export value, not necessarily the full rich module value saved
|
||||
in the module snapshot.
|
||||
Briefing starts as a flat snapshot order and stanza-value map. `Build` uses
|
||||
each output's `DataPackageValue`, so runtime prompt exports take precedence and
|
||||
rich values are used only as a fallback. Prompt exports are selected by the
|
||||
[briefing registry](briefing.md), while the rich-versus-prompt contract is in
|
||||
[module internals](module.md).
|
||||
|
||||
## Inputs And Outputs
|
||||
## YAML ordering and grouping
|
||||
|
||||
Inputs:
|
||||
Serialization keeps `metadata` directly under `briefing`. Every other known
|
||||
stanza is placed in exactly one category, emitted in category order and in its
|
||||
original snapshot order within that category:
|
||||
|
||||
- report metadata from app/state orchestration
|
||||
- `module.Snapshot`
|
||||
- optional `[]changes.Change`
|
||||
| Category | Current stanzas |
|
||||
| --- | --- |
|
||||
| `applicable_risk_products` | alert digest, SPC convective outlooks |
|
||||
| `derived_summaries` | deterministic summaries, precipitation timing, outdoor windows, and planning values |
|
||||
| `narrative_products` | narrative forecast, discussions, and weather story |
|
||||
| `raw_data` | current conditions and hourly forecast |
|
||||
|
||||
Outputs:
|
||||
This YAML presentation does not alter the flat snapshot model. `LoadYAML`
|
||||
accepts the same category layout and reconstructs flat `Order` and `Values`,
|
||||
rejecting misplaced, duplicate, unknown, or uncategorized stanzas.
|
||||
|
||||
- `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`
|
||||
## Validation and persistence
|
||||
|
||||
The YAML shape includes:
|
||||
`Validate` requires the current schema version, run and report identifiers,
|
||||
prompt ID, generation timestamp, timezone, current local date, valid period,
|
||||
and at least one ordered briefing stanza. It rejects duplicate stanza names,
|
||||
missing values, and a missing category for every non-metadata stanza.
|
||||
|
||||
```yaml
|
||||
schema_version: weatherreporter.data_package.v3
|
||||
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: []
|
||||
`MarshalYAML` and `LoadYAML` validate their result. `Save` writes the serialized
|
||||
YAML atomically; managed workspace paths are owned by [state internals](state.md).
|
||||
Generated-text artifacts and template render contexts are later workflow
|
||||
artifacts, not members of this package.
|
||||
|
||||
## Verification and invariants
|
||||
|
||||
Focused tests cover construction, curated exports, category ordering, YAML
|
||||
round trips, invalid layout, validation, and atomic saves:
|
||||
|
||||
```sh
|
||||
go test ./internal/promptinput
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## Module Export Boundary
|
||||
|
||||
Data packages are curated prompt inputs. They are not full template render
|
||||
contexts and should not be treated as a dump of every field available to Go
|
||||
templates.
|
||||
|
||||
When module outputs are built by `internal/briefing`, the registry attaches a
|
||||
runtime prompt export value. `internal/promptinput` serializes
|
||||
`output.DataPackageValue()` for each stanza. That helper prefers the runtime
|
||||
prompt export and falls back to the rich `Value` when no prompt export is set,
|
||||
which keeps loaded snapshots and hand-built tests usable.
|
||||
|
||||
Modules without custom export policy use pass-through behavior. Modules with
|
||||
custom exports currently include:
|
||||
|
||||
- `current_conditions`: omits lower-case condition text and duplicate
|
||||
wind-direction text.
|
||||
- `hourly_forecast`: omits hour labels, lower-case description text, and the
|
||||
template precipitation-mention helper while keeping forecast facts.
|
||||
- `derived_daypart_summaries`: omits deterministic sentence-construction
|
||||
helpers while keeping daypart period, condition, temperature trend,
|
||||
precipitation, wind, notable-condition, hazard, and alert-relevance facts.
|
||||
|
||||
The rich module snapshot and generated-template render context still contain
|
||||
the helper fields used by deterministic Markdown templates.
|
||||
|
||||
Daily Report, 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 Daily, 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. Daily uses
|
||||
`daily_planning`, Today uses `today_planning`, and 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 collect weather data, derive forecast summaries, execute modules,
|
||||
choose module prompt export shapes, 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.
|
||||
- Data-package stanzas use curated module prompt exports when present and rich
|
||||
values only as pass-through or fallback values.
|
||||
- Data packages are narrower than generated-template render contexts.
|
||||
- Recent Changes are provided by `internal/changes`; this package does not
|
||||
infer changes from rendered report text.
|
||||
The package is narrower than a template render context and never infers changes
|
||||
from report prose.
|
||||
|
||||
Reference in New Issue
Block a user