weatherreporter/docs/config.md

Weatherreporter Configuration

Weatherreporter reads YAML configuration. The default path is:

/usr/local/etc/weatherreporter/config.yml

If the default file is absent, Weatherreporter uses built-in defaults. An explicit --config PATH must exist. Values are applied in this order:

1. built-in defaults;
2. the configuration file, when present; and
3. the --units and --tz command-line overrides.

Environment variables do not override configuration fields. Output flags select operator-owned destinations for one command and do not change configuration.

Maintained Examples

• minimal-config.yml is the smallest useful collection and generation configuration.
• config.yml is a representative production-oriented configuration using synthetic endpoints and no credentials.
• weather-light-local-profile.yml is a complete endpoint-only override for the embedded weather-light profile.

The configuration examples are loaded by the configuration test suite. The profile example is inspected through the Promptkit adapter test suite.

Minimal Configuration

weather_api:
  base_url: https://weather.api.example.com/

weather_api.base_url is required for workflows that collect weather data. All omitted fields use their built-in defaults.

Field Reference

weather_api

Field	Default	Rules
base_url	empty	Absolute HTTP(S) Weather API URL. Required for collection and generation.
timeout	10s	Must be greater than zero.
precision	0	Must be zero or greater. Sent as the Weather API precision query value.
units	us	Required Weather API units query value; --units overrides it for one command.
timezone	America/Chicago	Required report and Weather API timezone; --tz overrides it for one command.
format	json	Required and must be json.

Timezone values may be IANA names, configured aliases such as Chicago and Stl, US timezone abbreviations, or signed UTC offsets such as -5, +0930, and +09:30. Numeric offsets require a sign, one or two hour digits, and an optional two-digit minute component with or without a colon. Hours must be from 00 through 23, minutes from 00 through 59, so the largest accepted offset magnitude is 23:59.

location

location supplies descriptive prompt context; it does not choose a Weather API endpoint or configure multiple forecast locations.

Field	Default
id	home
name	Brentwood
region	St. Louis Metro

The prompt-facing location timezone is derived from the effective weather_api.timezone after command-line overrides.

secrets

secrets.directory defaults to empty, which disables secret loading. When it is set, every regular file directly in that directory is staged after the file and command-line overrides, then applied only after the complete configuration has validated successfully. A rejected load leaves the existing environment unchanged. A file basename must match [A-Za-z_][A-Za-z0-9_]*; it becomes an environment variable name, and the file contents replace any existing value. One trailing LF or CRLF is removed.

Missing directories, unreadable files, subdirectories, symlinks, non-regular files, and invalid names fail configuration loading. Put only secret values in this directory, never in the YAML file.

output

output.directory selects the ordinary operator-owned publication directory for individual reports, batches, and the default parent of comparison bundles.

Field	Default	Rules
directory	empty	An omitted or empty value uses the invocation working directory. A nonempty value must contain at least one non-whitespace character.

The configured value is preserved while configuration loads: it is not cleaned, made absolute, inspected, created, or expanded through environment variables or a home-directory shortcut. At execution, an absolute directory is used as given; a relative directory resolves from the invocation working directory, not from the configuration file's location. A missing directory is created when a report is successfully published. An existing non-directory or an uninspectable path fails output preflight before prompt inspection, weather collection, or publication.

For one generate command, --out is a complete file destination and takes precedence over output.directory. For run, --out-dir takes precedence. For compare, --out-dir selects its exact bundle directory; without it, the comparison's report-derived directory is placed beneath output.directory. Those explicit flags do not inspect or rebase beneath the configured directory. See the CLI reference for command selection and the operations guide for publication and failure handling.

notify.distributor

Distributor notification is disabled by default. Its fields are:

Field	Default	Rules when notification is enabled
enabled	false	Activates Distributor notification validation.
endpoint	https://distributor.example.com	Must be an absolute HTTP(S) base URL with a host and no userinfo, query, or fragment. A path prefix is allowed.
token_env	DISTRIBUTOR_UPLOAD_TOKEN	Must name a valid environment variable.
timeout	30s	Must be greater than zero.
failure_policy	error	Must be error.
pipeline_id_template	empty	Required single-report pipeline ID template.
bundle_id_template	weatherreporter.{location_id}.{report_id}	Required single-report bundle ID template.
idempotency_key_template	{bundle_id}.{run_id}	Required single-report idempotency-key template.
batch.enabled	true	Activates batch notification validation when Distributor notification is enabled.
batch.pipeline_id_template	weatherreporter	Required when batch notification is enabled.
batch.bundle_id_template	weatherreporter.{location_id}.{batch}	Required when batch notification is enabled.
batch.idempotency_key_template	{bundle_id}.{batch_run_id}	Required when batch notification is enabled.

The upload token is read from the environment variable named by token_env. Use secrets.directory when a file-backed secret is appropriate.

When notification is enabled, Weatherreporter validates the Distributor endpoint before prompt inspection, weather collection, or output publication. Use an HTTP(S) base URL such as https://distributor.example.com/archive; do not put credentials, a query string, or a fragment in the endpoint.

When notification is enabled, each rendered single-report pipeline ID, bundle ID, and idempotency key must contain at least one non-whitespace character.

Single-report bundle templates accept 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, Pipeline and idempotency-key templates may also use bundle_id. Dates use YYYY-MM-DD; times use HHMM; and stamps use YYYY-MM-DDTHHMM in the effective report timezone.

Batch bundle and pipeline templates accept location_id, batch, batch_run_id, and batch_started_date; batch idempotency-key templates may also use bundle_id. batch_started_date is the batch start date in the effective report timezone.

reports.<report>.distributor.path_templates overrides the default ordered Distributor paths for that report. Each rendered path must be a unique relative path with / separators. Backslashes, empty segments, . and .. segments, manifest.json, and the reserved Distributor sidecar basename are rejected. The default paths are:

Report	Paths
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

See the operations guide for notification timing, uploaded output selection, and failure handling.

missing_source

missing_source.default defaults to warn and accepts error, warn, or none. missing_source.sources optionally overrides that policy by source. Hourly forecast data is required for generated reports and cannot have a source-specific policy. Supported optional source keys are observations, current, narrative, alerts, discussion, weather_story, and spc_convective_outlooks; any other key is rejected.

promptkit

Promptkit configuration selects the executor and prompt/profile checks for every generate, run, and compare command. A top-level scriptorium: configuration key is rejected with a migration error; it is not translated or ignored.

Prompt debug capture has no YAML setting. Use --llm-debug-dir PATH on an individual generate, run, or compare command when explicitly needed.

Field	Default	Rules
profile	empty	Optional global profile selection for every report in one command. When empty, each exact prompt version selects its declared default.
profile_file	empty	Optional external Promptkit profile file. It cannot be combined with profile_dir. A same-ID profile completely replaces Weatherreporter's embedded definition.
profile_dir	empty	Optional external Promptkit profile directory. It cannot be combined with profile_file. A same-ID profile completely replaces Weatherreporter's embedded definition.
timeout	2m	Must be greater than zero.
local.endpoint	empty	Optional absolute URL for the conventional local backend. A blank endpoint leaves it unregistered.
local.concurrency_limit	1	Maximum local backend concurrency. 0 is unlimited; negative values are invalid.

profile selects an ID; profile_file and profile_dir supply definitions. They are separate decisions. An explicit profile applies to every selected report. Otherwise Hourly selects weather-light, while Daily, Today, and Tomorrow select weather-balanced through their exact 2.0.0 prompt definitions.

Promptkit resolves a selected profile definition from a test or embedding consumer's explicit in-memory profile, then the configured profile_file or profile_dir, then Weatherreporter's embedded catalog, and finally Promptkit's built-in catalog. Sources provide complete definitions; fields are never merged. A matching malformed external profile fails rather than using the embedded definition. The Promptkit integration guide owns the catalog and precedence details.

To replace the default Hourly definition with a local OpenAI-compatible endpoint, set profile_file to a copy of weather-light-local-profile.yml. The example has no credential and should be edited for the local endpoint and model before use. An alternative profile may use backend: local; in that case promptkit.local.endpoint supplies the conventional local backend endpoint.

dayparts

dayparts is a non-empty list of named local-time windows used in forecast derivation. Every item needs name, start, and end; start and end use HH:MM. Defaults are overnight (00:00–06:00), morning (06:00–10:00), midday (10:00–15:00), afternoon (15:00–17:00), and evening (17:00–24:00).

Names remain display text, but each name must have a distinct canonical identity. Canonicalization trims whitespace, lowercases letters, and collapses punctuation and whitespace to underscores; for example, Morning, morning!, and morning conflict. Planning recognizes the canonical identities morning, afternoon, evening, and overnight regardless of their display capitalization or punctuation.

reports

reports optionally overrides a report's ordered deterministic modules and Distributor path templates. Omit a report entry to retain its defaults.

Supported report keys are daily, today, tomorrow, and hourly. Keys are trimmed, case-folded to lowercase, and normalize hyphens to underscores before lookup.

Each report entry can contain:

• deterministic_modules: an ordered list of module IDs, or objects with id and optional options.
• distributor.path_templates: an optional, non-empty ordered list of Distributor paths for that report.

Unknown reports and modules, duplicate modules, incompatible report-module combinations, duplicate stanza names, invalid path templates, and invalid module options fail configuration loading. The accepted module IDs and module option contracts are documented in the module contract internals.