Document curated data package exports
This commit is contained in:
@@ -5,9 +5,9 @@ This document describes the module contract in `internal/module`.
|
||||
## Purpose
|
||||
|
||||
`internal/module` defines the shared identifiers and data envelopes used for
|
||||
prompt-facing modules. Report definitions use module IDs for composition,
|
||||
module builders produce outputs with stanza names, prompt input packages consume
|
||||
snapshots, and Recent Changes compares snapshot stanzas.
|
||||
report modules. Report definitions use module IDs for composition, module
|
||||
builders produce rich outputs with stanza names, prompt input packages consume
|
||||
runtime prompt export values, and Recent Changes compares snapshot stanzas.
|
||||
|
||||
## Inputs And Outputs
|
||||
|
||||
@@ -23,8 +23,38 @@ Outputs:
|
||||
- typed option structs for registered modules
|
||||
- `module.Snapshot` with schema version `weatherreporter.modules.v1`
|
||||
- ordered snapshot outputs with module ID, stanza name, and typed value
|
||||
- runtime-only prompt export values on module outputs
|
||||
- `module.Output.DataPackageValue`, which selects the prompt export value and
|
||||
falls back to the rich value for hand-built or loaded snapshots
|
||||
- typed stanza lookup through `module.StanzaValue`
|
||||
|
||||
## Rich Values And Prompt Exports
|
||||
|
||||
Each `module.Output` has two value surfaces:
|
||||
|
||||
- `Value`: the rich module value used by templates, module snapshots,
|
||||
inspection, Recent Changes, and render contexts.
|
||||
- `PromptValue`: the runtime-only prompt export used when building Scriptorium
|
||||
data packages.
|
||||
|
||||
`PromptValue` is deliberately excluded from module snapshot JSON. Persisted
|
||||
module snapshots keep only the rich `value` field so inspection and
|
||||
render-context reconstruction keep the full deterministic template surface.
|
||||
|
||||
The `internal/briefing` module registry attaches prompt export values when it
|
||||
builds module outputs. Modules without a custom exporter use default
|
||||
pass-through behavior, so their prompt value is the same as their rich value.
|
||||
Modules that need cleanup own typed prompt export structs near the module
|
||||
builder. Current custom prompt exports are:
|
||||
|
||||
- `current_conditions`
|
||||
- `hourly_forecast`
|
||||
- `derived_daypart_summaries`
|
||||
|
||||
Custom exporters remove template-only helpers or confusing duplicates from the
|
||||
data package without shrinking the rich module structs used by templates.
|
||||
Exporter failures include module ID and stanza context.
|
||||
|
||||
## Registered Module IDs
|
||||
|
||||
The registry recognizes these IDs:
|
||||
@@ -186,7 +216,7 @@ validation.
|
||||
|
||||
## SPC Convective Module Outputs
|
||||
|
||||
`spc_convective_outlooks` emits a prompt-facing risk-product stanza with:
|
||||
`spc_convective_outlooks` emits a risk-product stanza with:
|
||||
|
||||
- `checked`
|
||||
- `as_of`
|
||||
@@ -221,7 +251,8 @@ meet the severity threshold.
|
||||
`module.Snapshot` values are persisted by `internal/state` as JSON. Snapshot
|
||||
validation rejects missing schema version, missing module IDs, missing stanza
|
||||
names, duplicate module outputs, and duplicate stanza names while preserving
|
||||
output order.
|
||||
output order. Snapshot JSON contains rich module values only; runtime prompt
|
||||
export values are not persisted.
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
@@ -242,5 +273,8 @@ Inspect:
|
||||
|
||||
- `internal/module` does not import `internal/report`.
|
||||
- Module IDs are stable strings.
|
||||
- Each emitted module output has exactly one stanza name and one typed value.
|
||||
- Each emitted module output has exactly one stanza name and one rich typed
|
||||
value.
|
||||
- Built module outputs have a data-package value, either from a custom prompt
|
||||
exporter or from default pass-through behavior.
|
||||
- Snapshot output order is caller-owned and preserved.
|
||||
|
||||
@@ -5,13 +5,15 @@ This document describes YAML prompt data package construction in
|
||||
|
||||
## Purpose
|
||||
|
||||
`internal/promptinput` converts report metadata, an ordered module snapshot,
|
||||
Recent Changes, and source warnings into the `data_package` file passed to
|
||||
`internal/promptinput` converts report metadata, ordered module outputs, 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.
|
||||
`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.
|
||||
|
||||
## Inputs And Outputs
|
||||
|
||||
@@ -32,7 +34,7 @@ Outputs:
|
||||
The YAML shape includes:
|
||||
|
||||
```yaml
|
||||
schema_version: weatherreporter.data_package.v2
|
||||
schema_version: weatherreporter.data_package.v3
|
||||
run_id: <run_id>
|
||||
report:
|
||||
id: <report_id>
|
||||
@@ -68,6 +70,32 @@ 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
|
||||
@@ -101,8 +129,8 @@ Current categories are:
|
||||
- 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.
|
||||
choose module prompt export shapes, find prior snapshots, compare changes,
|
||||
choose artifact paths, or invoke Scriptorium.
|
||||
|
||||
## Config Fields Used
|
||||
|
||||
@@ -142,5 +170,8 @@ Inspect:
|
||||
- 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.
|
||||
|
||||
@@ -19,7 +19,7 @@ weatherreporter generate storm --start 2026-05-29T18:00 --end 2026-05-30T06:00
|
||||
```
|
||||
|
||||
Generation commands resolve a report period, fetch a Weather API bundle, build
|
||||
a JSON module snapshot, build a YAML prompt input data package, run
|
||||
a rich JSON module snapshot, build a curated YAML prompt input data package, run
|
||||
`scriptorium render`, and write managed artifacts under the configured
|
||||
workspace. Markdown-path reports then run `scriptorium run` directly to the
|
||||
managed Markdown report path.
|
||||
@@ -287,11 +287,12 @@ weatherreporter inspect sources RUN_ID
|
||||
|
||||
Use `inspect reports` to find RunIDs and artifact paths. Use
|
||||
`inspect metadata` to see the artifact links recorded for a run. Use
|
||||
`inspect modules` to review the persisted ordered module snapshot, and
|
||||
`inspect data-package` to review the structured prompt package used for
|
||||
rendering. Use `inspect prior` to see the prior comparable snapshot selected for
|
||||
Recent Changes, or `null` when none exists. Use `inspect sources` to review
|
||||
source provenance and warnings without dumping full weather payloads.
|
||||
`inspect modules` to review the persisted ordered module snapshot with rich
|
||||
template-facing values, and `inspect data-package` to review the curated prompt
|
||||
package passed to Scriptorium. Use `inspect prior` to see the prior comparable
|
||||
snapshot selected for Recent Changes, or `null` when none exists. Use
|
||||
`inspect sources` to review source provenance and warnings without dumping full
|
||||
weather payloads.
|
||||
|
||||
## Recent Changes
|
||||
|
||||
|
||||
@@ -6,8 +6,9 @@ This roadmap defines the target state for cleaning up module fields exposed in
|
||||
YAML data packages. The goal is to keep report templates composable while making
|
||||
LLM prompt inputs concise, readable, and free of template-only helper fields.
|
||||
|
||||
This feature is not implemented yet. Current data-package behavior remains
|
||||
documented outside `docs/roadmap/`.
|
||||
This feature is implemented. Current data-package behavior is documented in
|
||||
`docs/internal/prompt-input.md`; the rich module and template boundary is
|
||||
documented in `docs/internal/module.md` and `docs/templates.md`.
|
||||
|
||||
## Problem
|
||||
|
||||
|
||||
@@ -184,6 +184,12 @@ falls back to sorted keys for any unmatched entries.
|
||||
prompt data package. Module fields are pointers because missing-data policy may
|
||||
omit a stanza.
|
||||
|
||||
Templates render from rich module values, not from the curated YAML data
|
||||
package. Some fields documented below are deterministic wording helpers for
|
||||
Markdown templates and are intentionally omitted from data packages passed to
|
||||
Scriptorium. The data package is a prompt input, while the render context is the
|
||||
template surface.
|
||||
|
||||
| Variable | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `.Modules.Metadata` | *briefing.MetadataModule | Report metadata module output, when present. |
|
||||
@@ -270,6 +276,40 @@ Common fields:
|
||||
| `.Modules.PrecipTiming.PrecipitationWindows[].MaxPopHourLabel` | string | Friendly hour label for the window maximum. |
|
||||
| `.Modules.PrecipTiming.ThunderMentioned` | bool | Whether thunder is mentioned in the forecast text. |
|
||||
|
||||
### Daypart Summaries
|
||||
|
||||
Daily, Today, and Tomorrow templates should use `.Modules.Dayparts` for
|
||||
ordered daypart rendering. Each item has `Key` and `Summary`; `Summary` is a
|
||||
rich `briefing.DerivedDaypartSummaryModule`.
|
||||
|
||||
Common rich daypart fields:
|
||||
|
||||
| Variable | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `.Modules.Dayparts[].Summary.DisplayName` | string | Human-readable daypart label. |
|
||||
| `.Modules.Dayparts[].Summary.PeriodBegins` | string | Friendly local daypart start. |
|
||||
| `.Modules.Dayparts[].Summary.PeriodEnds` | string | Friendly local daypart end. |
|
||||
| `.Modules.Dayparts[].Summary.TempRangeF` | string | Rounded temperature range or single temperature. |
|
||||
| `.Modules.Dayparts[].Summary.TemperaturePhraseF` | string | Temperature phrase used for steady template wording. |
|
||||
| `.Modules.Dayparts[].Summary.TemperatureTrend` | string | Trend category such as `rising`, `falling`, `peaking`, or `steady`. |
|
||||
| `.Modules.Dayparts[].Summary.TemperatureStartPhraseF` | string | Starting temperature phrase for rising/falling wording. |
|
||||
| `.Modules.Dayparts[].Summary.TemperatureEndPhraseF` | string | Ending temperature phrase for rising/falling wording. |
|
||||
| `.Modules.Dayparts[].Summary.TemperaturePeakPhraseF` | string | Peak temperature phrase for peaking wording. |
|
||||
| `.Modules.Dayparts[].Summary.TemperatureSteadyPhraseF` | string | Steady temperature phrase. |
|
||||
| `.Modules.Dayparts[].Summary.MaxPopPercent` | *int | Highest precipitation probability in the daypart. |
|
||||
| `.Modules.Dayparts[].Summary.MaxPopTime` | string | Friendly local time for the highest precipitation probability. |
|
||||
| `.Modules.Dayparts[].Summary.MaxPopTimeLabel` | string | Clock-style label for deterministic precipitation timing text. |
|
||||
| `.Modules.Dayparts[].Summary.MentionPrecipitation` | bool | True when precipitation probability should be mentioned by the template. |
|
||||
| `.Modules.Dayparts[].Summary.DominantCondition` | string | Dominant condition text. |
|
||||
| `.Modules.Dayparts[].Summary.DominantConditionLower` | string | Lower-case condition text for inline sentences. |
|
||||
| `.Modules.Dayparts[].Summary.DominantConditionDisplay` | string | Display-case condition text for bullet starts. |
|
||||
| `.Modules.Dayparts[].Summary.NotableConditions` | []string | Notable condition labels retained for the daypart. |
|
||||
|
||||
Template-only daypart helpers such as `TemperaturePhraseF`,
|
||||
`DominantConditionLower`, `DominantConditionDisplay`, and `MaxPopTimeLabel`
|
||||
remain available here even though they are not serialized into data-package
|
||||
YAML.
|
||||
|
||||
### Alert Digest
|
||||
|
||||
| Variable | Type | Description |
|
||||
|
||||
Reference in New Issue
Block a user