Refresh report and template internals documentation
This commit is contained in:
@@ -1,164 +1,69 @@
|
||||
# Module Builder Internals
|
||||
|
||||
This document describes module builder behavior in `internal/briefing`.
|
||||
`internal/briefing` builds typed module outputs from resolved report context,
|
||||
collected facts, and derived facts. It owns the module registry, including
|
||||
module support, fact requirements, option types, missing-data policy, builders,
|
||||
and prompt-export hooks. It does not collect data, derive periods, write a
|
||||
snapshot, construct YAML, invoke Scriptorium, or render a report.
|
||||
|
||||
## Purpose
|
||||
## Registry and construction
|
||||
|
||||
`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.
|
||||
Every `ModuleDefinition` declares an ID, stanza name, default option value,
|
||||
required collected and derived facts, supported report IDs, missing-data
|
||||
behavior, duplicate policy, builder, and optional prompt exporter.
|
||||
|
||||
Module outputs are structured prompt inputs. They are not rendered report prose
|
||||
and they are not persisted by this package.
|
||||
`BuildModule` first verifies the requested module, report compatibility, and
|
||||
option shape. It then applies the declared missing-data behavior:
|
||||
|
||||
## Inputs And Outputs
|
||||
- `omit` returns no output for unavailable optional facts;
|
||||
- `error` returns the missing fact requirements; and
|
||||
- `empty` allows the builder to emit an explicit checked-empty value.
|
||||
|
||||
Inputs:
|
||||
Unsupported `warn` behavior, missing builders, duplicate registry IDs or
|
||||
stanza names, output ID or stanza mismatches, and exporter failures all return
|
||||
errors with module context. A successful builder gets a pass-through prompt
|
||||
value unless its definition supplies an exporter.
|
||||
|
||||
- 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
|
||||
## Built value families
|
||||
|
||||
Outputs:
|
||||
Source-oriented builders shape report metadata, current conditions, narrative
|
||||
and hourly forecasts, alert digest, SPC outlooks and discussion, area forecast
|
||||
discussion, and weather story. Derived builders shape daily and daypart
|
||||
summaries, precipitation timing, outdoor windows, and the report-specific
|
||||
Daily, Today, and Tomorrow planning values.
|
||||
|
||||
- `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`
|
||||
The module registry preserves rich values for templates and snapshots while
|
||||
curating prompt exports where needed. In particular, source warnings are a
|
||||
metadata summary, checked-empty alerts and SPC outlooks remain distinct from
|
||||
missing sources, and prompt-safe SPC values omit geometry and other
|
||||
template-only or source details. The complete module composition is in
|
||||
[module internals](module.md); fact derivation is in [fact contracts](facts.md).
|
||||
|
||||
Every registered composition entry has a builder. Unknown or unimplemented
|
||||
module IDs fail validation instead of being skipped.
|
||||
`area_forecast_discussion` accepts an optional typed section filter. Planning
|
||||
modules are report-specific: `daily_planning` supports Daily,
|
||||
`today_planning` supports Today, and `tomorrow_planning` supports Tomorrow.
|
||||
|
||||
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.
|
||||
## Missing data and boundaries
|
||||
|
||||
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.
|
||||
Optional current conditions, narrative products, discussions, and weather
|
||||
stories may be omitted. Required derived modules fail when their declared facts
|
||||
are unavailable. Empty alert and outlook runs can still produce checked-empty
|
||||
modules. SPC discussion is omitted unless a retained categorical outlook meets
|
||||
the package's severity criterion and matching discussion text exists.
|
||||
|
||||
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.
|
||||
Effective units, timezone, and location context arrive in `ModuleContext` from
|
||||
configuration and resolved report metadata. Field defaults are owned by
|
||||
[configuration](../config.md), and prompt-package layout is owned by
|
||||
[prompt input](prompt-input.md).
|
||||
|
||||
`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.
|
||||
## Verification and invariants
|
||||
|
||||
`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.
|
||||
Focused tests cover source and derived values, registry validation, option
|
||||
handling, prompt exporters, support rules, and missing-data behavior:
|
||||
|
||||
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`.
|
||||
```sh
|
||||
go test ./internal/briefing
|
||||
```
|
||||
|
||||
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 collect 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.
|
||||
The `metadata` module carries report context and source warnings only; alert
|
||||
status and relevant alert details belong in the `alert_digest` module.
|
||||
|
||||
`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`; Daily Report defaults it to `long_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 enriches matching outlooks with
|
||||
embedded background definitions owned by this package. 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.
|
||||
Builders emit structured facts, never report prose. The app collects their
|
||||
outputs into a module snapshot, and state persists that snapshot.
|
||||
|
||||
Reference in New Issue
Block a user