212 lines
9.8 KiB
Markdown
212 lines
9.8 KiB
Markdown
# Weatherreporter Operations
|
|
|
|
This guide covers normal operation, managed workspace state, inspection,
|
|
recovery, and operational caveats. See the [CLI reference](cli.md) for complete
|
|
command syntax and the [configuration reference](config.md) for fields,
|
|
defaults, and notification templates.
|
|
|
|
## Normal Operation
|
|
|
|
After configuring a Weather API endpoint, generate one report:
|
|
|
|
```sh
|
|
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](../examples/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:
|
|
|
|
```yaml
|
|
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](config.md) 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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](cli.md) 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:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
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.
|