Clarify module package documentation
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# App Orchestration Internals
|
||||
|
||||
This document describes the implemented workflow coordinator in `internal/app`.
|
||||
This document describes the workflow coordinator in `internal/app`.
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -26,9 +26,9 @@ Inputs:
|
||||
|
||||
Outputs:
|
||||
|
||||
- generated report results with module snapshot, data package, preflight, report,
|
||||
metadata, prior snapshot, Recent Changes, Scriptorium result details, and
|
||||
notification result when attempted
|
||||
- generated report results with JSON module snapshot, YAML data package,
|
||||
preflight, report, metadata, prior snapshot, Recent Changes, Scriptorium
|
||||
result details, and notification result when attempted
|
||||
- batch summaries with per-report status, artifact paths, error text, and
|
||||
notification outcome when attempted
|
||||
- saved Weather API bundle JSON for fetch workflows
|
||||
|
||||
@@ -1,49 +1,60 @@
|
||||
# Module Builder Internals
|
||||
|
||||
This document describes the implemented module builder boundary in
|
||||
`internal/briefing`.
|
||||
This document describes module builder behavior 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.
|
||||
`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
|
||||
- `weatherdata.Bundle` with source provenance and warnings
|
||||
- derived daily, period, or storm-window facts where required
|
||||
- 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:
|
||||
|
||||
- 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
|
||||
- `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`, `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`
|
||||
|
||||
The registry also contains accepted composition entries for modules that do not
|
||||
emit stanzas until a builder exists. App orchestration skips those entries when
|
||||
constructing snapshots.
|
||||
|
||||
## 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.
|
||||
- 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 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
|
||||
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.
|
||||
Current conditions are copied from the normalized `/conditions/current` bundle
|
||||
source only; observation station and timestamp fields remain provenance.
|
||||
|
||||
`area_forecast_discussion` uses optional `sections` configuration to include a
|
||||
subset of discussion fields.
|
||||
|
||||
## External Adapters Used
|
||||
|
||||
@@ -51,13 +62,13 @@ None directly.
|
||||
|
||||
## State Or Manifest Behavior
|
||||
|
||||
None. Module snapshots and prompt input data packages are persisted by
|
||||
`internal/state` and composed by `internal/app`.
|
||||
None. `internal/app` collects module outputs into a `module.Snapshot`, and
|
||||
`internal/state` persists that snapshot.
|
||||
|
||||
## Skip And Resume Behavior
|
||||
|
||||
None. Builders either return a module output, omit optional unavailable data,
|
||||
or return an error for invalid required inputs.
|
||||
None. Builders either emit a module output, omit optional unavailable data, or
|
||||
return an error for invalid required inputs.
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
@@ -65,8 +76,9 @@ or return an error for invalid required inputs.
|
||||
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.
|
||||
- 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
|
||||
@@ -86,5 +98,4 @@ Inspect:
|
||||
- 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.
|
||||
- Prompt input packaging and Scriptorium execution remain outside this package.
|
||||
|
||||
@@ -56,8 +56,7 @@ empty Recent Changes list without calling a comparison function.
|
||||
`precip_timing` when present.
|
||||
- 3-Day comparison requires `derived_daypart_summaries`.
|
||||
- Weekend comparison requires `derived_daypart_summaries`.
|
||||
- Storm Report currently has no comparison implementation, so the app leaves
|
||||
Recent Changes empty for Storm reports.
|
||||
- Storm Report comparison returns no changes.
|
||||
|
||||
## Tests
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Fact Contracts Internals
|
||||
|
||||
This document describes the implemented fact contract boundary.
|
||||
This document describes the fact contract boundary.
|
||||
|
||||
## Purpose
|
||||
|
||||
|
||||
@@ -1,46 +1,90 @@
|
||||
# Module Contract Internals
|
||||
|
||||
This document describes the implemented module contract boundary.
|
||||
This document describes the module contract in `internal/module`.
|
||||
|
||||
## Purpose
|
||||
|
||||
`internal/module` defines stable module IDs, typed configuration items, module
|
||||
outputs, and module snapshots. It is a shared contract imported by report
|
||||
definitions and module registry code.
|
||||
`internal/module` defines the shared identifiers and data envelopes used for
|
||||
prompt-facing modules. Report definitions use module IDs for composition,
|
||||
module builders produce outputs with stanza names, prompt input packages consume
|
||||
snapshots, and Recent Changes compares snapshot stanzas.
|
||||
|
||||
## Inputs And Outputs
|
||||
|
||||
Inputs:
|
||||
|
||||
- ordered `module.ConfigItem` values from report definitions
|
||||
- `module.Output` values assembled by callers
|
||||
- ordered `module.ConfigItem` values from report definitions or config
|
||||
overrides
|
||||
- `module.Output` values produced by module builders
|
||||
|
||||
Outputs:
|
||||
|
||||
- stable `module.ID` constants
|
||||
- typed option structs for known modules
|
||||
- `module.Snapshot` with ordered outputs and schema version
|
||||
- typed option structs for registered modules
|
||||
- `module.Snapshot` with schema version `weatherreporter.modules.v1`
|
||||
- ordered snapshot outputs with module ID, stanza name, and typed value
|
||||
- typed stanza lookup through `module.StanzaValue`
|
||||
|
||||
## Registered Module IDs
|
||||
|
||||
The registry recognizes these IDs:
|
||||
|
||||
- `metadata`
|
||||
- `current_conditions`
|
||||
- `derived_daily_summary`
|
||||
- `derived_daypart_summaries`
|
||||
- `hourly_table`
|
||||
- `precip_timing`
|
||||
- `alert_digest`
|
||||
- `area_forecast_discussion`
|
||||
- `weather_story`
|
||||
- `forecast_delta`
|
||||
- `outdoor_windows`
|
||||
- `tomorrow_planning`
|
||||
- `weekend_planning`
|
||||
- `storm_window_summary`
|
||||
|
||||
Modules with builders emit stanzas into module snapshots. Registered modules
|
||||
without builders are valid composition entries but do not emit snapshot stanzas.
|
||||
That keeps report composition declarations centralized while limiting prompt
|
||||
packages to data the application builds.
|
||||
|
||||
## Options
|
||||
|
||||
Most modules use an empty options struct. `area_forecast_discussion` accepts:
|
||||
|
||||
```yaml
|
||||
sections:
|
||||
- product
|
||||
- key_messages
|
||||
- short_term
|
||||
- long_term
|
||||
```
|
||||
|
||||
An omitted or empty `sections` list includes all available discussion sections.
|
||||
Invalid option shapes fail during config normalization or composition
|
||||
validation.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- This package owns shared module identifiers and output envelope contracts.
|
||||
- It does not define report IDs, build prompt stanzas, fetch weather data,
|
||||
derive facts, write state, or invoke Scriptorium.
|
||||
- This package owns module identifiers, config item envelopes, output
|
||||
envelopes, snapshot validation, and typed stanza lookup.
|
||||
- It does not define report IDs, execute builders, fetch weather data, derive
|
||||
forecast facts, write state, or invoke Scriptorium.
|
||||
|
||||
## State Or Manifest Behavior
|
||||
|
||||
`module.Snapshot` uses schema version `weatherreporter.modules.v1`. Snapshot
|
||||
validation rejects duplicate module outputs and duplicate stanza names while
|
||||
preserving output order.
|
||||
`module.Snapshot` values are persisted by `internal/state` as JSON. Snapshot
|
||||
validation rejects missing schema version, missing module IDs, missing stanza
|
||||
names, duplicate module outputs, and duplicate stanza names while preserving
|
||||
output order.
|
||||
|
||||
## Failure Behavior
|
||||
|
||||
- Snapshot validation fails when schema version, module ID, or stanza name is
|
||||
missing.
|
||||
- Snapshot validation fails on duplicate module IDs or duplicate stanza names.
|
||||
- Typed stanza lookup returns `found=false` for missing stanzas and wraps JSON
|
||||
marshal/decode failures with stanza context.
|
||||
- Snapshot construction fails for duplicate module outputs or duplicate stanza
|
||||
names.
|
||||
- Typed stanza lookup returns `found=false` for missing stanzas.
|
||||
- Typed stanza lookup wraps JSON marshal/decode failures with stanza context.
|
||||
|
||||
## Tests
|
||||
|
||||
@@ -54,5 +98,5 @@ Inspect:
|
||||
|
||||
- `internal/module` does not import `internal/report`.
|
||||
- Module IDs are stable strings.
|
||||
- Each module output has exactly one stanza name and one typed value.
|
||||
- Each emitted module output has exactly one stanza name and one typed value.
|
||||
- Snapshot output order is caller-owned and preserved.
|
||||
|
||||
@@ -1,38 +1,63 @@
|
||||
# Prompt Input Internals
|
||||
|
||||
This document describes prompt input data package construction.
|
||||
This document describes YAML prompt data package construction in
|
||||
`internal/promptinput`.
|
||||
|
||||
## Purpose
|
||||
|
||||
`internal/promptinput` converts report metadata, module snapshots, and optional
|
||||
Recent Changes into the YAML `data_package` passed to Scriptorium prompts.
|
||||
`internal/promptinput` converts report metadata, an ordered module snapshot,
|
||||
Recent Changes, and source warnings into the `data_package` file passed to
|
||||
Scriptorium.
|
||||
|
||||
The persisted data package is YAML with schema version
|
||||
`weatherreporter.data_package.v2`. It is separate from the JSON module snapshot
|
||||
used for inspection and comparison.
|
||||
|
||||
## Inputs And Outputs
|
||||
|
||||
Inputs:
|
||||
|
||||
- report metadata
|
||||
- report metadata from app/state orchestration
|
||||
- `module.Snapshot`
|
||||
- optional `[]changes.Change`
|
||||
|
||||
Outputs:
|
||||
|
||||
- `promptinput.Package` containing schema version, RunID, report metadata,
|
||||
named module stanzas under `briefing`, Recent Changes, and source warnings.
|
||||
- report metadata includes `currentLocalDate`, the generation date formatted as
|
||||
`YYYY-MM-DD` in the effective report timezone.
|
||||
- optional YAML file written by `promptinput.Save`
|
||||
- `promptinput.Package` with schema version, RunID, report metadata, named
|
||||
module stanzas, Recent Changes, and source warnings
|
||||
- YAML bytes from `promptinput.MarshalYAML`
|
||||
- YAML file written atomically by `promptinput.Save`
|
||||
|
||||
The YAML shape includes:
|
||||
|
||||
```yaml
|
||||
schema_version: weatherreporter.data_package.v2
|
||||
run_id: <run_id>
|
||||
report:
|
||||
id: <report_id>
|
||||
prompt_id: <prompt_id>
|
||||
briefing:
|
||||
metadata: {}
|
||||
current_conditions: {}
|
||||
recent_changes:
|
||||
items: []
|
||||
```
|
||||
|
||||
The `briefing` mapping contains named module stanzas. Stanza order follows the
|
||||
module snapshot output order.
|
||||
|
||||
## Boundaries
|
||||
|
||||
- This package owns the prompt input schema and validation.
|
||||
- It does not fetch weather data, derive forecast summaries, find prior
|
||||
snapshots, compare changes, or invoke Scriptorium.
|
||||
- This package owns prompt package schema, YAML marshaling, YAML loading, and
|
||||
validation.
|
||||
- It does not fetch weather data, derive forecast summaries, execute modules,
|
||||
find prior snapshots, compare changes, choose artifact paths, or invoke
|
||||
Scriptorium.
|
||||
|
||||
## Config Fields Used
|
||||
|
||||
None directly. Config-derived values, including timezone and prompt location
|
||||
context, are already present in report metadata and module stanzas before this
|
||||
None directly. Config-derived values such as timezone, units, and prompt
|
||||
location are already present in report metadata and module stanzas before this
|
||||
package runs.
|
||||
|
||||
## External Adapters Used
|
||||
@@ -51,8 +76,9 @@ None. Recent Changes is always present as an `items` list and may be empty.
|
||||
## Failure Behavior
|
||||
|
||||
Validation fails before render preflight when required top-level fields are
|
||||
missing or inconsistent, or when no named module stanzas are present. Save
|
||||
failures include filesystem operation and path context.
|
||||
missing or inconsistent, when the valid period is invalid, or when no module
|
||||
stanzas are present. Save failures include filesystem operation and path
|
||||
context.
|
||||
|
||||
## Tests
|
||||
|
||||
@@ -63,6 +89,7 @@ Inspect:
|
||||
|
||||
## Invariants
|
||||
|
||||
- Scriptorium receives structured `data_package` YAML.
|
||||
- Scriptorium receives structured YAML through `--input data_package=<path>`.
|
||||
- Module stanza order is deterministic for generated snapshots.
|
||||
- Recent Changes are not inferred from rendered report text.
|
||||
- Recent Changes are provided by `internal/changes`; this package does not
|
||||
infer changes from rendered report text.
|
||||
|
||||
@@ -7,8 +7,8 @@ membership, output naming, artifact grouping, and comparison declarations in
|
||||
## Purpose
|
||||
|
||||
`internal/report` is the canonical source for report definitions. App, state,
|
||||
module building, and CLI wiring consume resolved definitions instead of owning report
|
||||
identity policy themselves.
|
||||
module building, and CLI wiring consume resolved definitions instead of owning
|
||||
report identity policy themselves.
|
||||
|
||||
## Definition Fields
|
||||
|
||||
@@ -25,7 +25,7 @@ Each report definition declares:
|
||||
- morning or evening batch membership
|
||||
- default ordered module composition
|
||||
|
||||
## Implemented Reports
|
||||
## Reports
|
||||
|
||||
| Report | ID | Prompt | Artifact group | Batch copy | Prior compatibility |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
@@ -35,7 +35,7 @@ Each report definition declares:
|
||||
| Weekend Outlook | `weekend` | `weather.weekend_outlook` | `weekend` | `weekend.md` | Weekend Outlook |
|
||||
| Storm Report | `storm` | `weather.storm_report` | `storm` | `storm.md` | Storm Report |
|
||||
|
||||
All implemented report definitions are eligible for generation.
|
||||
All report definitions are eligible for generation.
|
||||
|
||||
## Valid Periods
|
||||
|
||||
@@ -55,8 +55,8 @@ must be after start time.
|
||||
## Boundaries
|
||||
|
||||
`internal/report` defines report metadata and time coverage. It does not fetch
|
||||
weather data, build module values, compare snapshot contents, write state, parse CLI
|
||||
flags, or invoke Scriptorium.
|
||||
weather data, build module values, compare snapshot contents, write state,
|
||||
parse CLI flags, or invoke Scriptorium.
|
||||
|
||||
The CLI owns public command names. The app maps those command names to report
|
||||
IDs, then uses the registry for report policy.
|
||||
|
||||
@@ -84,8 +84,8 @@ current report definition.
|
||||
date.
|
||||
- Weekend Outlook compares with prior Weekend snapshots for the same weekend
|
||||
window.
|
||||
- Storm Report currently has no prior lookup because explicit event-window
|
||||
comparison is not searched by the filesystem store.
|
||||
- Storm Report has no prior lookup because explicit event-window comparison is
|
||||
not searched by the filesystem store.
|
||||
|
||||
## Writes And Inspection
|
||||
|
||||
|
||||
Reference in New Issue
Block a user