120 lines
5.4 KiB
Markdown
120 lines
5.4 KiB
Markdown
# Weatherreporter Operations
|
|
|
|
This guide covers normal output handling, Distributor notification, secure
|
|
prompt diagnostics, and cleanup of legacy application state. See the [CLI
|
|
reference](cli.md) for 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
|
|
```
|
|
|
|
The command writes `today.md` in the current directory. Choose a different
|
|
operator-owned file with `--out`; a relative path is resolved from the current
|
|
directory and an absolute path is used directly. Weatherreporter renders in
|
|
memory and atomically replaces the selected destination only after generation
|
|
and rendering succeed. It does not create a default workspace, metadata,
|
|
receipts, or intermediate output files.
|
|
|
|
Before a destination is published, provider, validation, rendering, write, and
|
|
cancellation failures leave an existing report unchanged. A notification
|
|
failure happens after publication, so retain and use the completed Markdown
|
|
file while resolving the delivery error. The JSON result identifies the
|
|
absolute output path and active profile, backend, model, warnings, validation,
|
|
debug, and notification information; see the [CLI reference](cli.md) for its
|
|
exact fields.
|
|
|
|
## Batch Outputs And Distributor Notification
|
|
|
|
Run a scheduled batch with an explicit output directory when appropriate:
|
|
|
|
```sh
|
|
weatherreporter run morning --out-dir ./reports
|
|
```
|
|
|
|
Without `--out-dir`, batch reports are written beneath the current directory.
|
|
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 local civil day.
|
|
A batch collects once, processes each selected report independently, and keeps
|
|
successful outputs if another report fails.
|
|
|
|
When `notify.distributor.enabled` and batch notification are enabled,
|
|
Weatherreporter sends one Distributor upload only after every selected output
|
|
exists. If an item fails, the batch notification is skipped and successful
|
|
files remain at their selected destinations. A batch notification failure also
|
|
leaves all successfully published report files in place. Distributor source
|
|
files are those operator-owned Markdown outputs; rendered bundle paths and
|
|
delivery status appear in the result, not in a local notification receipt.
|
|
|
|
For a single report, Distributor notification follows the atomic output write.
|
|
See the [configuration reference](config.md) for pipeline, bundle,
|
|
idempotency-key, and per-report path templates.
|
|
|
|
## 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.
|
|
|
|
Prompt and profile validation 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.
|
|
|
|
## 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. Requested captures are written with restrictive
|
|
permissions beneath the supplied directory, organized by report and run. They
|
|
can contain rendered prompts and generated output, so limit access to trusted
|
|
operators and remove the captures when they are no longer needed. Normal output,
|
|
summaries, and routine logs omit that sensitive content. Debug capture is never
|
|
created for an ordinary command without `--llm-debug-dir`.
|
|
|
|
If capture creation or writing fails, the affected run fails rather than
|
|
silently continuing without the requested diagnostics.
|
|
|
|
## Diagnosing Failures
|
|
|
|
Start with the command error and JSON summary. For a report generation failure,
|
|
the selected destination was not replaced; for a notification failure, inspect
|
|
the completed destination and the notification result. For a batch failure,
|
|
use the per-report statuses and retain successful output files. Enable explicit
|
|
debug capture only when content-rich Promptkit diagnostics are necessary.
|
|
|
|
Weatherreporter does not retain runs for later inspection, resume failed work,
|
|
or provide automatic cleanup, archival, remote state, daemon operation, or
|
|
automatic storm monitoring.
|
|
|
|
## Manual Cleanup Of Legacy Workspaces
|
|
|
|
Older installations may have a directory named `workspace` containing reports,
|
|
snapshots, prompt inputs, or notification records from previous versions.
|
|
Current commands neither read nor update it. After confirming that no separate
|
|
retention requirement applies, remove that specific legacy directory manually;
|
|
do not use a broad cleanup command that could remove current operator outputs.
|
|
|
|
For example, from the directory that contains the old directory:
|
|
|
|
```sh
|
|
rm -rf ./workspace
|
|
```
|
|
|
|
This removal cannot be recovered by Weatherreporter. Keep or archive any
|
|
historical files that are still needed before deleting them.
|