182 lines
7.2 KiB
Markdown
182 lines
7.2 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 implemented 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 fetch 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 fetch 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 briefing 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 notification after successful report
|
|
generation. It is disabled by default and does not add CLI flags. When enabled,
|
|
weatherreporter uploads one distributor bundle per generated report after
|
|
`scriptorium run` succeeds and final metadata is saved.
|
|
|
|
- `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`.
|
|
- `bundle_id_template`: template for distributor bundle IDs. Default:
|
|
`weatherreporter.{location_id}.{report_id}.{run_id}`.
|
|
- `idempotency_key_template`: template for distributor idempotency keys.
|
|
Default: `{bundle_id}`.
|
|
- `report_path_template`: template for the Markdown report path inside the
|
|
distributor bundle. Default: `{batch_output_name}`.
|
|
|
|
Supported template variables are `location_id`, `report_id`, `run_id`,
|
|
`artifact_group`, and `batch_output_name`. `idempotency_key_template` may also
|
|
use `bundle_id`.
|
|
|
|
Rendered report paths must be relative paths with `/` separators. They must not
|
|
contain backslashes, empty path segments, `.`, `..`, `manifest.json`, or
|
|
`.distributor.json`.
|
|
|
|
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 and
|
|
stub source slots use the missing-source policy.
|
|
|
|
### `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`: briefing 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 briefing
|
|
snapshot exists and a threshold is crossed.
|
|
|
|
## 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 implemented fields.
|
|
|
|
Both example files are loaded by the config test suite.
|