62 lines
2.7 KiB
Markdown
62 lines
2.7 KiB
Markdown
# Prompt Input Internals
|
|
|
|
`internal/promptinput` converts report metadata, an ordered module snapshot,
|
|
Recent Changes, and source warnings into the YAML `data_package` consumed by
|
|
Promptkit. It owns this package's schema, grouping, serialization, loading,
|
|
and validation—not weather collection, module construction, path choice, or
|
|
provider execution.
|
|
|
|
## Package construction
|
|
|
|
`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.
|
|
|
|
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).
|
|
|
|
## YAML ordering and grouping
|
|
|
|
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:
|
|
|
|
| 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 |
|
|
|
|
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.
|
|
|
|
## Validation and persistence
|
|
|
|
`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.
|
|
|
|
`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 package is narrower than a template render context and never infers changes
|
|
from report prose.
|