161 lines
6.9 KiB
Markdown
161 lines
6.9 KiB
Markdown
# Module Builder Internals
|
|
|
|
This document describes module builder behavior in `internal/briefing`.
|
|
|
|
## Purpose
|
|
|
|
`internal/briefing` turns report metadata, collected weather data, and derived
|
|
forecast facts into prompt-facing module outputs. The package also owns the
|
|
module registry used to validate report composition and config overrides.
|
|
|
|
Module outputs are structured prompt inputs. They are not rendered report prose
|
|
and they are not persisted by this package.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- resolved report definition, generation time, timezone, and valid period
|
|
- collected facts built from `weatherdata.Bundle`
|
|
- derived daily, daypart, precipitation, alert, and storm-window facts where
|
|
required
|
|
- configured units, timezone, and descriptive location context
|
|
- typed module options from report defaults or config overrides
|
|
|
|
Outputs:
|
|
|
|
- `ModuleDefinition` values with module ID, stanza name, option type,
|
|
supported reports, fact requirements, missing-data behavior, and builder
|
|
- `module.Output` values for source-oriented stanzas:
|
|
`metadata`, `current_conditions`, `narrative_forecast`, `hourly_forecast`,
|
|
`alert_digest`, `spc_convective_outlooks`,
|
|
`area_forecast_discussion`, `spc_convective_discussion`, and
|
|
`weather_story`
|
|
- `module.Output` values for derived stanzas:
|
|
`derived_daily_summary`, `derived_daypart_summaries`, `precip_timing`,
|
|
`outdoor_windows`, `today_planning`, `tomorrow_planning`, and
|
|
`daily_planning`
|
|
|
|
Every registered composition entry has a builder. Unknown or unimplemented
|
|
module IDs fail validation instead of being skipped.
|
|
|
|
Daily Report supports the Daily-style civil-day modules plus `daily_planning`
|
|
and `hourly_forecast`; those outputs feed the dated Daily GeneratedText prompt
|
|
package and embedded Markdown template.
|
|
|
|
Tomorrow Report supports the Daily-style civil-day modules plus
|
|
`tomorrow_planning` and `hourly_forecast`; those outputs feed the Tomorrow
|
|
GeneratedText prompt package and embedded Markdown template.
|
|
|
|
Today Report supports the Daily-style civil-day modules plus `today_planning`
|
|
and `hourly_forecast`; those outputs feed the Today GeneratedText prompt
|
|
package and embedded Markdown template.
|
|
|
|
`today_planning` is a Today-specific deterministic planning stanza with
|
|
morning readiness, commute/school/workday concerns, outdoor planning, and
|
|
late-day change-watch fields. It is compatible with `report.Today` only.
|
|
|
|
`daily_planning` is a dated Daily deterministic planning stanza with morning
|
|
readiness, commute/school/workday concerns, and overnight change-watch fields.
|
|
It is compatible only with the `daily` report ID value. The default Daily
|
|
Report composition includes it.
|
|
|
|
Hourly Report supports source and valid-period modules that operate over its
|
|
rolling six-hour period: `metadata`, `current_conditions`, `hourly_forecast`,
|
|
`precip_timing`, `alert_digest`, `spc_convective_outlooks`,
|
|
`area_forecast_discussion`, `spc_convective_discussion`, and `weather_story`.
|
|
It does not support daily/daypart-only modules such as
|
|
`derived_daily_summary`, `derived_daypart_summaries`, `outdoor_windows`,
|
|
`today_planning`, `tomorrow_planning`, or `daily_planning`.
|
|
|
|
Prompt-facing module values use local, human-readable date and time labels
|
|
where the LLM is expected to reason about report content. Canonical timestamps
|
|
remain in report metadata, source provenance, and integration artifacts.
|
|
|
|
## Boundaries
|
|
|
|
- This package selects and shapes already-collected weather facts for prompts.
|
|
- It validates module composition against report compatibility and option
|
|
types.
|
|
- It does not fetch weather data, compare prior snapshots, write module
|
|
snapshots, build YAML data packages, invoke Scriptorium, or write workflow
|
|
metadata.
|
|
|
|
## Config Fields Used
|
|
|
|
The app layer passes effective units, timezone, and location context into the
|
|
module context. `internal/facts` consumes daypart configuration before module
|
|
builders run. Configured `location` values are prompt context only; Weather API
|
|
`sourceLocationId` and `sourceLocation` remain source provenance.
|
|
|
|
`area_forecast_discussion` uses optional `sections` configuration to include a
|
|
subset of discussion fields. Hourly Report defaults this module to
|
|
`key_messages` and `short_term`.
|
|
|
|
`spc_convective_outlooks` uses collected SPC run metadata and derived
|
|
report-period outlooks. It emits `checked: true` for a successfully fetched
|
|
empty run, reports `outlook_count`, and includes prompt-facing outlook fields
|
|
such as risk label, `period_begins`, `period_ends`, image URL, and whether the
|
|
outlook contains the configured location. It also emits a curated `risk_digest`
|
|
for categorical outlooks that overlap the report period, contain the location,
|
|
and meet the configured-in-code minimum severity for report rendering. It does
|
|
not emit GeoJSON geometry, source URL, expiration time, or severity rank.
|
|
|
|
Prompt-facing module intervals use friendly local `period_begins` and
|
|
`period_ends` labels. Canonical report metadata, source provenance,
|
|
`issued_at`, `updated_at`, and point-in-time fields remain separate.
|
|
|
|
`spc_convective_discussion` uses the same derived report-period outlooks and
|
|
discussion records. It is omitted unless at least one retained categorical
|
|
outlook for the same SPC day has severity rank `3` or higher and matching
|
|
discussion text exists.
|
|
|
|
## External Adapters Used
|
|
|
|
None directly.
|
|
|
|
## State Or Manifest Behavior
|
|
|
|
None. `internal/app` collects module outputs into a `module.Snapshot`, and
|
|
`internal/state` persists that snapshot.
|
|
|
|
## Skip And Resume Behavior
|
|
|
|
None. Builders either emit a module output, omit optional unavailable data, or
|
|
return an error for invalid required inputs.
|
|
|
|
## Failure Behavior
|
|
|
|
- Required derived modules return errors when their dependent facts are not
|
|
available.
|
|
- Module registry construction rejects duplicate module IDs and duplicate
|
|
stanza names.
|
|
- Composition validation rejects unknown modules, duplicate modules,
|
|
incompatible report/module combinations, duplicate stanza names, and invalid
|
|
option shapes.
|
|
- Source-oriented module builders omit missing optional current conditions,
|
|
forecast discussion, and weather story stanzas.
|
|
- Alert digest output distinguishes checked empty alert data from missing alert
|
|
source data.
|
|
- SPC convective outlook output distinguishes checked empty outlook data from
|
|
missing outlook source data and omits GeoJSON geometry from prompt-facing
|
|
fields.
|
|
- SPC convective discussion output is omitted unless a retained outlook has
|
|
severity rank `3` or higher and matching discussion text is available.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/briefing/base_modules_test.go`
|
|
- `internal/briefing/derived_modules_test.go`
|
|
- `internal/briefing/modules_test.go`
|
|
- `internal/app/app_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Module outputs contain structured weather facts and source context.
|
|
- Common metadata includes RunID, report ID, prompt ID, valid period, source
|
|
provenance, source hashes, source warnings, and configured prompt location.
|
|
- Prompt input packaging and Scriptorium execution remain outside this package.
|