eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Align documentation with cleanup results

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-16 15:52:55 +00:00
parent 4f755704d9
commit d9ab1e47ec
3 changed files with 51 additions and 38 deletions
Download Patch File Download Diff File Expand all files Collapse all files

77
docs/internal/generatedtext.md
View File

@@ -9,8 +9,7 @@ This document describes structured generated-text handling in
generated-text-template reports and builds curated render contexts for generated-text-template reports and builds curated render contexts for
templates. It also owns the generated-text catalog that connects report templates. It also owns the generated-text catalog that connects report
definitions to validators, render-context builders, schema assets, and template definitions to validators, render-context builders, schema assets, and template
assets. The implemented contracts are Daily render context, Today Report, assets.
Tomorrow Report, and Hourly Report.
## Inputs And Outputs ## Inputs And Outputs
@@ -35,9 +34,9 @@ Outputs:
- generated-text catalog handlers for report definitions that use - generated-text catalog handlers for report definitions that use
`generated_text_template` `generated_text_template`
The Daily generated text JSON accepts the same public fields and validation ## JSON Contracts
rules as Tomorrow. Its catalog entry is selected through schema ID `daily` and
template ID `daily`, with prompt ID `weather.daily_generated_text`. Daily, Today, and Tomorrow use the same day-style generated-text JSON shape:
```json ```json
{ {
@@ -48,7 +47,21 @@ template ID `daily`, with prompt ID `weather.daily_generated_text`.
} }
``` ```
The hourly generated text JSON accepts: The day-style contract requires `summary` after trimming whitespace.
`forecast_discussion` must contain at least one nonblank paragraph after
trimming blank items. `precipitation_timing` and `confidence` are optional and
omitted from normalized JSON when blank. Unknown fields are rejected.
The report-specific Go API is:
| Report | Type | Validator | Schema ID | Template ID | Prompt ID |
| --- | --- | --- | --- | --- | --- |
| Daily Report | `Daily` | `ValidateDaily` | `daily` | `daily` | `weather.daily_generated_text` |
| Today Report | `Today` | `ValidateToday` | `today` | `today` | `weather.today_generated_text` |
| Tomorrow Report | `Tomorrow` | `ValidateTomorrow` | `tomorrow` | `tomorrow` | `weather.tomorrow_generated_text` |
Hourly generated text uses the same top-level field names, but
`forecast_discussion` is a single string:
```json ```json
{ {
@@ -59,39 +72,35 @@ The hourly generated text JSON accepts:
} }
``` ```
`summary` and `forecast_discussion` are required after trimming whitespace. Hourly `summary` and `forecast_discussion` are required after trimming
`precipitation_timing` and `confidence` are optional and omitted from normalized whitespace. `precipitation_timing` and `confidence` are optional and omitted
JSON when blank. from normalized JSON when blank. Unknown fields are rejected. The Hourly catalog
entry uses type `Hourly`, validator `ValidateHourly`, schema ID `hourly`,
template ID `hourly`, and prompt ID `weather.hourly_generated_text`.
The Today generated text JSON accepts the same public fields and validation ## Render Contexts
rules as Tomorrow. It is selected by the active Today report definition through
schema ID `today`, template ID `today`, and prompt ID
`weather.today_generated_text`:
```json Daily, Today, Tomorrow, and Hourly render contexts all include:
{
"summary": "string",
"forecast_discussion": ["string"],
"precipitation_timing": "string",
"confidence": "string"
}
```
The Tomorrow generated text JSON accepts: - display metadata derived from report metadata;
- validated generated text;
- typed module outputs decoded from the module snapshot;
- collected facts;
- derived facts.
```json Daily, Today, and Tomorrow share common civil-day render-context fields such as
{ forecast date labels, valid period, generated-at labels, current conditions,
"summary": "string", hourly forecast, precipitation timing, alert digest, SPC outlooks, AFD, SPC
"forecast_discussion": ["string"], discussion, weather story, daily summary, and ordered daypart summaries.
"precipitation_timing": "string",
"confidence": "string"
}
```
`summary` is required after trimming whitespace. `forecast_discussion` must Each civil-day report keeps its report-specific planning module:
contain at least one nonblank paragraph after trimming blank items.
`precipitation_timing` and `confidence` are optional and omitted from normalized - Daily exposes `DailyPlanning`.
JSON when blank. - Today exposes `TodayPlanning`.
- Tomorrow exposes `TomorrowPlanning`.
Today's ordered daypart context omits unavailable or elapsed dayparts according
to Today report rules. Daily and Tomorrow use fallback daypart behavior.
## Boundaries ## Boundaries

4
docs/internal/module.md
View File

@@ -44,8 +44,8 @@ render-context reconstruction keep the full deterministic template surface.
The `internal/briefing` module registry attaches prompt export values when it The `internal/briefing` module registry attaches prompt export values when it
builds module outputs. Modules without a custom exporter use default builds module outputs. Modules without a custom exporter use default
pass-through behavior, so their prompt value is the same as their rich value. pass-through behavior, so their prompt value is the same as their rich value.
Modules that need cleanup own typed prompt export structs near the module Modules with custom prompt export policy own typed prompt export structs near
builder. Current custom prompt exports are: the module builder. Custom prompt exports are:
- `current_conditions` - `current_conditions`
- `hourly_forecast` - `hourly_forecast`

8
docs/templates.md
View File

@@ -6,7 +6,8 @@ This guide describes the implemented Markdown report template surface for
`weatherreporter`. It is for maintainers editing embedded report templates, `weatherreporter`. It is for maintainers editing embedded report templates,
especially generated-text-template reports. especially generated-text-template reports.
Templates are Go `text/template` files. The current implemented templates are: Templates are Go `text/template` files. The implemented top-level templates
are:
- `internal/reporttemplate/templates/daily.md.tmpl` - `internal/reporttemplate/templates/daily.md.tmpl`
- `internal/reporttemplate/templates/today.md.tmpl` - `internal/reporttemplate/templates/today.md.tmpl`
@@ -32,7 +33,7 @@ validation, and artifact paths are handled before template rendering.
- Do not put weather derivation, source selection, or path construction logic in - Do not put weather derivation, source selection, or path construction logic in
templates. templates.
- Missing template keys are errors. A misspelled variable will fail rendering. - Missing template keys are errors. A misspelled variable will fail rendering.
- No custom template functions are currently registered. - No custom template functions are registered.
- Named partials are invoked with `{{ template "name" . }}`. Pass the current - Named partials are invoked with `{{ template "name" . }}`. Pass the current
render context (`.`) unless the partial is intentionally designed for a render context (`.`) unless the partial is intentionally designed for a
narrower value. narrower value.
@@ -112,6 +113,9 @@ Tomorrow generated text uses the same `.GeneratedText.Summary`,
Hourly. `.GeneratedText.ForecastDiscussion` is a slice of paragraphs and should Hourly. `.GeneratedText.ForecastDiscussion` is a slice of paragraphs and should
be rendered with `range`. be rendered with `range`.
Tomorrow uses the shared `daypart_forecast` and `precipitation_timing`
partials.
Tomorrow modules include the Hourly module fields plus: Tomorrow modules include the Hourly module fields plus:
| Variable | Type | Description | | Variable | Type | Description |