109 lines
4.0 KiB
Markdown
109 lines
4.0 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`, and `weather_story`
|
|
- `module.Output` values for derived stanzas:
|
|
`derived_daily_summary`, `derived_daypart_summaries`, `precip_timing`,
|
|
`outdoor_windows`, and `tomorrow_planning`
|
|
|
|
Every registered composition entry has a builder. Unknown or unimplemented
|
|
module IDs fail validation instead of being skipped.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
## 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.
|