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, 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.

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.

3.8 KiB Raw Blame History