Weatherreporter Operations

This guide covers normal operation, managed workspace state, inspection, recovery, and operational caveats. See the CLI reference for complete command syntax and the configuration reference for fields, defaults, and notification templates.

Normal Operation

After configuring a Weather API endpoint, generate one report:

weatherreporter generate today --out ./today.md

A generation collects weather data, resolves the report period, builds and persists the module snapshot and prompt data package, records Promptkit preparation provenance before provider execution, then persists raw output and execution provenance, validates the structured generated text, and renders the managed Markdown report from the validated text and deterministic values. These receipts describe the current workspace implementation; they are not a cross-version profile-provenance contract.

The managed report and its final metadata are saved before single-report Distributor notification is attempted. --out writes an extra operator copy; it never changes the managed report or upload source. A successful generate command prints its summary to stdout unless --quiet is used.

Local Prompt Profile Override

Hourly normally selects the embedded weather-light profile. To use a local OpenAI-compatible model without changing prompts or application code, copy weather-light-local-profile.yml, set its endpoint and model for the local server, and configure the copy as promptkit.profile_file. The profile file's weather-light definition completely replaces the embedded definition; it does not affect a report that selects another profile ID.

For example, install the profile file at a known absolute path and set:

promptkit:
  profile_file: /etc/weatherreporter/weather-light-local-profile.yml

Prompt inspection occurs before weather collection. A malformed profile file, missing required credential, or unsupported selected backend stops the command before collection. A reachable profile can still fail later if its local model endpoint is unavailable; Weatherreporter does not switch to a remote profile. See the configuration reference for field definitions. For a provider failure, start with the command error and enable secure prompt debug capture when content-rich diagnostics are required.

Optional Prompt Debug Capture

Use --llm-debug-dir only when content-rich prompt diagnostics are required:

weatherreporter generate today --llm-debug-dir /var/tmp/weatherreporter-debug

The directory must be absolute and is initialized before prompt inspection or weather collection. Capture files are stored outside the managed workspace, with restrictive permissions, under the report ID, valid date, and RunID. They can contain rendered prompts and generated output, so the normal metadata, CLI summary, and routine logs contain only the optional directory path—not their content. A capture-write failure stops that run before later work can continue.

Run a scheduled batch with the same configured collection:

weatherreporter run morning --out-dir ./reports --llm-debug-dir /var/tmp/weatherreporter-debug

Each batch validates its configured prompt/profile candidates, then collects once before it plans reports. Morning runs Today, Tomorrow, and every eligible dated Daily Report; evening runs Tomorrow and the same eligible Daily Reports. Eligible Daily dates begin after tomorrow and require complete hourly coverage for their entire local civil day. A batch continues after an individual report fails and returns an aggregate failure when any report or batch notification fails.

--out-dir writes extra copies such as today.md, tomorrow.md, and daily-YYYY-MM-DD.md. These copies are never upload sources. Batch report copies and notification behavior are summarized in the CLI result; use the CLI reference for its exact JSON and stderr contract.

Managed Workspace

The default workspace root is workspace. Artifact paths use the report definition's artifact group, the valid-period start date in the effective timezone, and the RunID:

workspace/
  reports/<artifact_group>/<YYYY-MM-DD>/report.<run_id>.md

  snapshots/<artifact_group>/<YYYY-MM-DD>/modules.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/metadata.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text_raw.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/prompt_execution.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/generated_text.<run_id>.json
  snapshots/<artifact_group>/<YYYY-MM-DD>/render_context.<run_id>.json

  data-packages/<artifact_group>/<YYYY-MM-DD>/data_package.<run_id>.yaml
  preflight/<artifact_group>/<YYYY-MM-DD>/prompt_preparation.<run_id>.json

  notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json
  notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json

The generated-text and render-context artifacts are written for every completed single-report generation. A report's metadata links the module snapshot, data package, preparation and execution receipts, managed report, generated-text artifacts, and any available single-report notification artifact. These current-version receipts are implementation details rather than durable interfaces. Use the active command's error and explicit secure debug capture for prompt diagnosis. Batch notification artifacts are separate batch-level records under notifications/batches.

RunIDs begin with the UTC generation timestamp and report ID. A Daily RunID also contains its local valid date so multiple Daily reports in one batch have different managed paths. Batch notification RunIDs contain the UTC batch start timestamp and batch name.

Distributor Notification

When notify.distributor.enabled is enabled, a successful generate uploads only the managed Markdown report after final metadata has been saved. The extra copy from --out is never uploaded. A notification attempt writes a redacted debug artifact at notifications/<artifact_group>/<YYYY-MM-DD>/distributor.<run_id>.json; its path is then recorded in report metadata.

Batches suppress per-report notification. When both Distributor and its batch notification are enabled, Weatherreporter submits one multi-report upload after every planned report succeeds. If any report fails, it records a top-level skipped notification with reason one or more reports failed and does not call Distributor. If batch notification is disabled, a batch does not fall back to individual uploads.

A batch notification attempt writes notifications/batches/<batch>/<YYYY-MM-DD>/distributor.<batch_run_id>.json. A notification failure makes the batch fail but does not change successful individual report items into failed items. The debug artifacts contain rendered identifiers, managed source and bundle paths, upload and status results, and redacted errors; they do not contain tokens.

Inspecting Stored Runs

Inspection is read-only: it neither collects weather data nor invokes Promptkit or Distributor. Start by finding a RunID:

weatherreporter inspect reports --limit 10
weatherreporter inspect metadata RUN_ID

Command	Reads
`inspect reports`	Metadata files under the workspace snapshots tree.
`inspect metadata RUN_ID`	Metadata located by RunID.
`inspect modules RUN_ID`	The module snapshot path recorded in metadata.
`inspect data-package RUN_ID`	The data-package path recorded in metadata.
`inspect prior RUN_ID`	The run metadata, then compatible earlier metadata for its comparison policy.
`inspect sources RUN_ID`	Source provenance and warnings in the run metadata.

A missing snapshots directory produces no listed reports. An unknown or empty RunID is an error; use inspect reports to obtain a valid value.

New runs write weatherreporter.metadata.v2, including preparation and execution references once those receipts exist. inspect metadata also reads historic V1 records; their legacy preflight and generated-text-result fields remain visible for compatibility, but Weatherreporter does not write them for new runs.

Recovery

Keep the workspace when a run fails: artifacts reached before the failure remain available where they can be safely persisted.

A preparation failure can leave its classified receipt and metadata.
A report-generation failure can leave the managed report, module snapshot, data package, and metadata.
A completed prompt validation rejection leaves raw text, an execution receipt, and metadata. Later generated-text failures can also leave validated text and a render-context artifact, depending on where they stopped.
A single-report notification failure preserves the report and final metadata, including its notification artifact when it was written.
A batch notification failure preserves each report's artifacts and adds the top-level batch notification artifact.

Use the action summary and its error first. For prompt or provider diagnosis, prefer an explicitly enabled secure debug capture; current-version receipt paths may provide supplemental context when available. For a batch failure, inspect the summary first, then inspect the affected report RunIDs or the batch notification path. Do not remove the whole workspace as a first response; retain it until the failure is understood.

Operational Caveats

Workspace files and generated reports can contain sensitive operational context. Set appropriate filesystem permissions and do not publish them unintentionally.
Weatherreporter uses one configured Weather API endpoint and local workspace state.
Promptkit profile resolution does not discover local endpoints or fail over between local and remote profiles.
It does not provide automatic resume, cleanup, archival, remote state, daemon operation, or automatic storm monitoring.

9.8 KiB Raw Blame History