91 lines
3.3 KiB
Markdown
91 lines
3.3 KiB
Markdown
# Module Builder Internals
|
|
|
|
This document describes the implemented module builder boundary in
|
|
`internal/briefing`.
|
|
|
|
## Purpose
|
|
|
|
`internal/briefing` builds prompt-facing module values from resolved report
|
|
metadata, collected weather data, and derived forecast facts. These values are
|
|
curated prompt inputs, not rendered report prose or durable report snapshots.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- resolved report definition, generation time, timezone, and valid period
|
|
- `weatherdata.Bundle` with source provenance and warnings
|
|
- derived daily, period, or storm-window facts where required
|
|
- configured units, timezone, and descriptive location context
|
|
|
|
Outputs:
|
|
|
|
- module registry definitions for known module IDs, stanza names, option
|
|
shapes, fact requirements, report compatibility, and missing-data behavior
|
|
- source-oriented module outputs for `metadata`, `current_conditions`,
|
|
`alert_digest`, `area_forecast_discussion`, and `weather_story`
|
|
- derived module outputs such as daily summaries, daypart summaries,
|
|
precipitation timing, outdoor windows, and tomorrow planning
|
|
- optional current conditions and weather story module outputs when those
|
|
Weather API sources are available
|
|
|
|
## Boundaries
|
|
|
|
- This package selects and shapes weather facts for prompts.
|
|
- It owns module registry validation and module builder behavior.
|
|
- It does not fetch weather data, compare prior snapshots, build
|
|
`data_package` files, invoke Scriptorium, or write workflow metadata.
|
|
|
|
## Config Fields Used
|
|
|
|
The package receives configured units and timezone from the app layer. Daypart
|
|
configuration is consumed by `internal/facts` before module builders run.
|
|
Configured `location` values are prompt context only; Weather API
|
|
`sourceLocationId` and `sourceLocation` remain source provenance.
|
|
Current conditions are copied from the normalized `/conditions/current` bundle
|
|
source only; observation station and timestamp fields remain provenance.
|
|
|
|
## External Adapters Used
|
|
|
|
None directly.
|
|
|
|
## State Or Manifest Behavior
|
|
|
|
None. Module snapshots and prompt input data packages are persisted by
|
|
`internal/state` and composed by `internal/app`.
|
|
|
|
## Skip And Resume Behavior
|
|
|
|
None. Builders either return 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.
|
|
- Module composition validation rejects unknown modules, duplicate modules,
|
|
incompatible report/module combinations, and invalid typed options.
|
|
- 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.
|
|
|
|
## 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.
|
|
- LLM prompt input packaging and Scriptorium execution remain outside this
|
|
boundary.
|