diff --git a/docs/internal/generatedtext.md b/docs/internal/generatedtext.md index d78cabb..b122f19 100644 --- a/docs/internal/generatedtext.md +++ b/docs/internal/generatedtext.md @@ -9,8 +9,7 @@ This document describes structured generated-text handling in generated-text-template reports and builds curated render contexts for templates. It also owns the generated-text catalog that connects report definitions to validators, render-context builders, schema assets, and template -assets. The implemented contracts are Daily render context, Today Report, -Tomorrow Report, and Hourly Report. +assets. ## Inputs And Outputs @@ -35,9 +34,9 @@ Outputs: - generated-text catalog handlers for report definitions that use `generated_text_template` -The Daily generated text JSON accepts the same public fields and validation -rules as Tomorrow. Its catalog entry is selected through schema ID `daily` and -template ID `daily`, with prompt ID `weather.daily_generated_text`. +## JSON Contracts + +Daily, Today, and Tomorrow use the same day-style generated-text JSON shape: ```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 { @@ -59,39 +72,35 @@ The hourly generated text JSON accepts: } ``` -`summary` and `forecast_discussion` are required after trimming whitespace. -`precipitation_timing` and `confidence` are optional and omitted from normalized -JSON when blank. +Hourly `summary` and `forecast_discussion` are required after trimming +whitespace. `precipitation_timing` and `confidence` are optional and omitted +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 -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`: +## Render Contexts -```json -{ - "summary": "string", - "forecast_discussion": ["string"], - "precipitation_timing": "string", - "confidence": "string" -} -``` +Daily, Today, Tomorrow, and Hourly render contexts all include: -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 -{ - "summary": "string", - "forecast_discussion": ["string"], - "precipitation_timing": "string", - "confidence": "string" -} -``` +Daily, Today, and Tomorrow share common civil-day render-context fields such as +forecast date labels, valid period, generated-at labels, current conditions, +hourly forecast, precipitation timing, alert digest, SPC outlooks, AFD, SPC +discussion, weather story, daily summary, and ordered daypart summaries. -`summary` is required 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. +Each civil-day report keeps its report-specific planning module: + +- Daily exposes `DailyPlanning`. +- 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 diff --git a/docs/internal/module.md b/docs/internal/module.md index ab11f88..51d483b 100644 --- a/docs/internal/module.md +++ b/docs/internal/module.md @@ -44,8 +44,8 @@ render-context reconstruction keep the full deterministic template surface. The `internal/briefing` module registry attaches prompt export values when it builds module outputs. Modules without a custom exporter use default 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 -builder. Current custom prompt exports are: +Modules with custom prompt export policy own typed prompt export structs near +the module builder. Custom prompt exports are: - `current_conditions` - `hourly_forecast` diff --git a/docs/templates.md b/docs/templates.md index 677a8e4..a92a806 100644 --- a/docs/templates.md +++ b/docs/templates.md @@ -6,7 +6,8 @@ This guide describes the implemented Markdown report template surface for `weatherreporter`. It is for maintainers editing embedded report templates, 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/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 templates. - 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 render context (`.`) unless the partial is intentionally designed for a narrower value. @@ -112,6 +113,9 @@ Tomorrow generated text uses the same `.GeneratedText.Summary`, Hourly. `.GeneratedText.ForecastDiscussion` is a slice of paragraphs and should be rendered with `range`. +Tomorrow uses the shared `daypart_forecast` and `precipitation_timing` +partials. + Tomorrow modules include the Hourly module fields plus: | Variable | Type | Description |