316 lines
13 KiB
Markdown
316 lines
13 KiB
Markdown
# Weatherreporter Configuration
|
|
|
|
Configuration is YAML. By default, `weatherreporter` reads:
|
|
|
|
```text
|
|
/usr/local/etc/weatherreporter/config.yml
|
|
```
|
|
|
|
Use `--config PATH` to load a different file. If the default file is absent,
|
|
built-in defaults are used. If `--config PATH` points to a missing file, loading
|
|
fails.
|
|
|
|
Precedence is:
|
|
|
|
1. CLI flags
|
|
2. configuration file
|
|
3. built-in defaults
|
|
|
|
The CLI configuration overrides are `--units` and `--tz`. Output flags control
|
|
report copies for the current command but do not change configuration files.
|
|
Environment variables do not override configuration fields.
|
|
|
|
## Minimal Config
|
|
|
|
See [examples/minimal-config.yml](../examples/minimal-config.yml).
|
|
|
|
```yaml
|
|
weather_api:
|
|
base_url: https://weather.api.example.com/
|
|
```
|
|
|
|
`weather_api.base_url` is required for commands that collect weather data.
|
|
Other fields fall back to defaults.
|
|
|
|
## Production-Oriented Config
|
|
|
|
See [examples/config.yml](../examples/config.yml). The example is loaded by the
|
|
config test suite.
|
|
|
|
## Field Reference
|
|
|
|
### `weather_api`
|
|
|
|
- `base_url`: absolute base URL for the Weather API. Required for generation and collection workflows.
|
|
- `timeout`: HTTP timeout duration. Default: `10s`.
|
|
- `precision`: numeric precision query value. Default: `1`.
|
|
- `units`: Weather API units query value. Default: `us`.
|
|
- `timezone`: report timezone and Weather API timezone query value where supported. Default: `America/Chicago`.
|
|
- `format`: Weather API response format. Must be `json`. Default: `json`.
|
|
|
|
Timezone values may be IANA names, configured aliases such as `Chicago` and
|
|
`Stl`, US timezone abbreviations, or UTC offsets such as `-5` and `+09:30`.
|
|
|
|
### `location`
|
|
|
|
`location` is descriptive prompt context included in module metadata and
|
|
Scriptorium data packages. It does not select a Weather API endpoint or enable
|
|
multiple configured forecast locations.
|
|
|
|
- `id`: short local identifier. Default: `home`.
|
|
- `name`: human-readable location name. Default: `Brentwood`.
|
|
- `region`: broader forecast area context. Default: `St. Louis Metro`.
|
|
|
|
The prompt-facing location object also includes `timezone`, derived from the
|
|
effective `weather_api.timezone` after CLI overrides such as `--tz`.
|
|
|
|
### `secrets`
|
|
|
|
- `directory`: optional directory of file-backed environment secrets. Default:
|
|
empty, which disables secret loading.
|
|
|
|
When configured, each regular file directly under `secrets.directory` is loaded
|
|
after config file parsing and CLI overrides. The file basename must be a valid
|
|
environment variable name matching `[A-Za-z_][A-Za-z0-9_]*`; the file contents
|
|
become the environment variable value and overwrite any existing value. One
|
|
trailing LF or CRLF is stripped. Subdirectories, symlinks, invalid filenames,
|
|
missing directories, and unreadable files fail config loading.
|
|
|
|
### `notify`
|
|
|
|
`notify.distributor` controls distributor uploads after successful report
|
|
rendering. It is disabled by default and does not add CLI flags. When enabled,
|
|
`generate <report>` uploads one distributor bundle for the generated report
|
|
after final metadata is saved. `run morning` and `run evening` use
|
|
`notify.distributor.batch`: when batch notification is enabled and every
|
|
planned report succeeds, weatherreporter uploads one distributor bundle that
|
|
contains all managed Markdown reports from that batch.
|
|
|
|
- `enabled`: whether distributor notification config is active. Default:
|
|
`false`.
|
|
- `endpoint`: absolute distributor endpoint URL. Required when enabled.
|
|
Default: `https://distributor.example.com`.
|
|
- `token_env`: environment variable name that will contain the distributor
|
|
upload token. Required when enabled. Default: `DISTRIBUTOR_UPLOAD_TOKEN`.
|
|
- `timeout`: distributor operation timeout. Must be greater than zero when
|
|
enabled. Default: `30s`.
|
|
- `failure_policy`: must be `error` when enabled. Default: `error`.
|
|
- `pipeline_id_template`: template for single-report distributor pipeline IDs.
|
|
Required when enabled. Default: empty.
|
|
- `bundle_id_template`: template for single-report distributor bundle IDs.
|
|
Default: `weatherreporter.{location_id}.{report_id}`.
|
|
- `idempotency_key_template`: template for single-report distributor
|
|
idempotency keys. Default: `{bundle_id}.{run_id}`.
|
|
- `batch.enabled`: whether batch distributor notification config is active
|
|
when distributor notification is enabled. Default: `true`.
|
|
- `batch.pipeline_id_template`: template for batch distributor pipeline IDs.
|
|
Required when distributor notification and batch notification are enabled.
|
|
Default: `weatherreporter`.
|
|
- `batch.bundle_id_template`: template for batch distributor bundle IDs.
|
|
Required when distributor notification and batch notification are enabled.
|
|
Default: `weatherreporter.{location_id}.{batch}`.
|
|
- `batch.idempotency_key_template`: template for batch distributor idempotency
|
|
keys. Required when distributor notification and batch notification are
|
|
enabled. Default: `{bundle_id}.{batch_run_id}`.
|
|
|
|
Single-report templates support `location_id`, `report_id`, `run_id`,
|
|
`artifact_group`, `batch_output_name`, `valid_start_date`, `valid_end_date`,
|
|
`valid_start_time`, `valid_end_time`, `valid_start_stamp`, `valid_end_stamp`,
|
|
and `storm_id`. Date values use `YYYY-MM-DD`, time values use `HHMM`, and
|
|
stamp values use `YYYY-MM-DDTHHMM` in the effective report timezone.
|
|
`storm_id` is derived from the storm report valid period as
|
|
`{valid_start_stamp}-{valid_end_stamp}`; it renders empty for non-storm
|
|
reports. `pipeline_id_template` and `idempotency_key_template` may also use
|
|
`bundle_id`.
|
|
|
|
The rendered pipeline ID selects the configured distributor `http_upload`
|
|
workflow. The rendered bundle ID is the stable logical source identity for the
|
|
report stream. The rendered idempotency key is the per-run retry identity.
|
|
|
|
Batch templates support `location_id`, `batch`, `batch_run_id`, and
|
|
`batch_started_date`. Batch idempotency templates may also use `bundle_id`.
|
|
`batch_started_date` is the batch start date in the effective report timezone.
|
|
Batch bundle IDs identify a logical batch stream; batch idempotency keys
|
|
identify a specific retryable batch attempt.
|
|
|
|
Rendered report paths must be unique relative paths with `/` separators. They
|
|
must not contain backslashes, empty path segments, `.`, `..`, `manifest.json`,
|
|
or `.distributor.json`. In a batch upload, uniqueness is checked across every
|
|
rendered bundle path for every included report before distributor is called.
|
|
Managed Markdown report paths are the only upload source files; copies written
|
|
with `--out` or `--out-dir` are never uploaded.
|
|
|
|
Distributor bundle paths are report-specific. Weatherreporter uses
|
|
`reports.<report>.distributor.path_templates` when that override is configured;
|
|
otherwise it uses the report definition defaults:
|
|
|
|
- `hourly`: `hourly/index.md`
|
|
- `daily`: `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`
|
|
- `today`: `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `today/index.md`
|
|
- `tomorrow`: `daily/{valid_start_date}/{run_id}.md`, `daily/{valid_start_date}/index.md`, `tomorrow/index.md`
|
|
- `three_day`: `three-day/{valid_start_date}/{run_id}.md`, `three-day/{valid_start_date}/index.md`
|
|
- `weekend`: `weekend/{valid_start_date}/{run_id}.md`, `weekend/{valid_start_date}/index.md`
|
|
- `storm`: `storm/{storm_id}/{run_id}.md`, `storm/{storm_id}/index.md`
|
|
|
|
The upload token is read from the environment variable named by `token_env`
|
|
after config loading and `secrets.directory` processing. Config files should
|
|
name the variable only; they should not contain the token value.
|
|
|
|
### `missing_source`
|
|
|
|
- `default`: missing-source behavior for optional sources. One of `error`, `warn`, or `none`. Default: `warn`.
|
|
- `sources`: optional map of source-specific overrides, using the same policy values.
|
|
|
|
Hourly forecast data is required for generated reports. Optional sources use
|
|
the missing-source policy. Source override keys include `observations`,
|
|
`current`, `narrative`, `alerts`, `discussion`, `weather_story`, and
|
|
`spc_convective_outlooks`.
|
|
|
|
### `scriptorium`
|
|
|
|
- `binary`: `scriptorium` executable name or path. Default: `scriptorium`.
|
|
- `config_path`: optional Scriptorium config path passed to the adapter.
|
|
- `profile`: optional Scriptorium profile passed to the adapter.
|
|
- `timeout`: subprocess timeout. Default: `2m`.
|
|
- `extra_args`: optional additional arguments passed to Scriptorium commands.
|
|
|
|
### `workspace`
|
|
|
|
- `root`: workspace root for managed artifacts. Default: `workspace`.
|
|
- `snapshots_dir`: module snapshot and metadata directory under `workspace.root`. Default: `snapshots`.
|
|
- `reports_dir`: managed Markdown report directory under `workspace.root`. Default: `reports`.
|
|
- `data_packages_dir`: prompt input package directory under `workspace.root`. Default: `data-packages`.
|
|
- `preflight_dir`: Scriptorium render output directory under `workspace.root`. Default: `preflight`.
|
|
- `notifications_dir`: distributor notification debug artifact directory under `workspace.root`. Default: `notifications`.
|
|
|
|
Workspace subdirectories must be relative paths that stay inside
|
|
`workspace.root`.
|
|
|
|
### `dayparts`
|
|
|
|
`dayparts` is a list of named local-time windows used by forecast derivation.
|
|
Each entry has:
|
|
|
|
- `name`
|
|
- `start`
|
|
- `end`
|
|
|
|
`start` and `end` use `HH:MM`. The default entries are overnight, morning,
|
|
midday, afternoon, and evening.
|
|
|
|
### `recent_change`
|
|
|
|
- `temperature_degrees`: temperature change threshold. Default: `5`.
|
|
- `precip_probability_points`: precipitation probability threshold. Default: `20`.
|
|
- `wind_gust_miles_per_hour`: wind gust change threshold. Default: `10`.
|
|
- `precip_timing_shift_minutes`: precipitation timing shift threshold. Default: `120`.
|
|
|
|
Recent Changes are added to prompt input when a prior comparable module
|
|
snapshot exists and a threshold is crossed.
|
|
|
|
### `reports`
|
|
|
|
`reports` optionally overrides the ordered deterministic modules declared by
|
|
report definitions. Omit a report entry to use its default module order.
|
|
|
|
Supported report keys are `daily`, `today`, `tomorrow`, `hourly`,
|
|
`three_day`, `weekend`, and `storm`. Canonical report IDs and accepted aliases
|
|
are also valid, including `three_day_outlook`, `weekend_outlook`, and
|
|
`storm_report`. Hyphens and underscores are treated equivalently in report
|
|
keys. Retired report keys are not supported.
|
|
|
|
`reports.today` applies only to the Today Report. `reports.daily` applies only
|
|
to the dated Daily Report.
|
|
|
|
Each report entry supports:
|
|
|
|
- `deterministic_modules`: ordered module list. Entries may be string module
|
|
IDs or objects with `id` and optional `options`.
|
|
- `distributor.path_templates`: optional ordered distributor bundle path
|
|
templates for this report. If omitted, the report definition defaults are
|
|
used. If present, the list must contain at least one template.
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
reports:
|
|
daily:
|
|
distributor:
|
|
path_templates:
|
|
- "daily/{valid_start_date}/{run_id}.md"
|
|
- "daily/{valid_start_date}/index.md"
|
|
deterministic_modules:
|
|
- metadata
|
|
- current_conditions
|
|
- narrative_forecast
|
|
- alert_digest
|
|
- spc_convective_outlooks
|
|
- id: area_forecast_discussion
|
|
options:
|
|
sections:
|
|
- short_term
|
|
- spc_convective_discussion
|
|
- daily_planning
|
|
- hourly_forecast
|
|
today:
|
|
deterministic_modules:
|
|
- metadata
|
|
- current_conditions
|
|
- narrative_forecast
|
|
- derived_daily_summary
|
|
- derived_daypart_summaries
|
|
- precip_timing
|
|
- alert_digest
|
|
- spc_convective_outlooks
|
|
- area_forecast_discussion
|
|
- spc_convective_discussion
|
|
- weather_story
|
|
- outdoor_windows
|
|
- hourly_forecast
|
|
- today_planning
|
|
hourly:
|
|
deterministic_modules:
|
|
- metadata
|
|
- current_conditions
|
|
- hourly_forecast
|
|
- precip_timing
|
|
- alert_digest
|
|
- spc_convective_outlooks
|
|
- id: area_forecast_discussion
|
|
options:
|
|
sections:
|
|
- key_messages
|
|
- short_term
|
|
- spc_convective_discussion
|
|
- weather_story
|
|
```
|
|
|
|
Unknown reports, unknown modules, duplicate modules, incompatible report/module
|
|
combinations, duplicate stanza names, and invalid options fail config loading.
|
|
`area_forecast_discussion.options.sections` may contain `product`,
|
|
`key_messages`, `short_term`, and `long_term`. Empty or omitted `sections`
|
|
includes all available AFD sections.
|
|
|
|
The module registry accepts all module IDs documented in
|
|
[Module Contract Internals](internal/module.md). Unknown or unimplemented
|
|
module IDs fail validation instead of being skipped.
|
|
|
|
## Secrets
|
|
|
|
Configuration files should not contain raw secrets. Use `secrets.directory` to
|
|
load secret values from files into environment variables for integrations that
|
|
read credentials from the environment. Secret file names become environment
|
|
variable names, and secret file contents become values. For distributor
|
|
notification, this allows a file such as
|
|
`<secrets.directory>/DISTRIBUTOR_UPLOAD_TOKEN` to supply the token referenced by
|
|
`notify.distributor.token_env`.
|
|
|
|
## Maintained Examples
|
|
|
|
- [examples/minimal-config.yml](../examples/minimal-config.yml): smallest
|
|
useful config for generation and fetching.
|
|
- [examples/config.yml](../examples/config.yml): production-oriented config
|
|
covering maintained fields.
|
|
|
|
Both example files are loaded by the config test suite.
|