129 lines
5.0 KiB
Markdown
129 lines
5.0 KiB
Markdown
# Report Template Internals
|
|
|
|
This document describes embedded Markdown templates and GeneratedText schemas
|
|
in `internal/reporttemplate`.
|
|
|
|
## Purpose
|
|
|
|
`internal/reporttemplate` owns repository-native report templates and companion
|
|
GeneratedText JSON schemas. The implemented template assets are Daily, Today,
|
|
Tomorrow, and Hourly.
|
|
|
|
The package embeds assets from:
|
|
|
|
- `internal/reporttemplate/templates/*.md.tmpl`
|
|
- `internal/reporttemplate/templates/partials/*.md.tmpl`
|
|
- `internal/reporttemplate/schemas/*.schema.json`
|
|
|
|
Generated-text prompt source files live under
|
|
`internal/reporttemplate/prompts/`. They are repository assets for prompt
|
|
registration, not embedded lookup APIs.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- template ID from a report definition
|
|
- typed render context built by `internal/generatedtext`
|
|
|
|
Outputs:
|
|
|
|
- template source for inspection and tests
|
|
- GeneratedText schema bytes for prompt/schema configuration
|
|
- rendered Markdown bytes for app orchestration to persist
|
|
|
|
The implemented template IDs are `daily`, `today`, `tomorrow`, and `hourly`.
|
|
The implemented schema IDs are also `daily`, `today`, `tomorrow`, and
|
|
`hourly`, backed by matching `*.generated_text.schema.json` files.
|
|
|
|
Generated-text prompt sources are maintained under
|
|
`internal/reporttemplate/prompts/`, including Daily's
|
|
`daily.generated_text.md` source for prompt ID `weather.daily_generated_text`.
|
|
|
|
## Boundaries
|
|
|
|
This package owns embedded asset lookup, Go template parsing, and Markdown
|
|
template execution. It does not collect weather data, build module outputs,
|
|
validate GeneratedText, construct render contexts, choose report definitions,
|
|
write artifacts, invoke Scriptorium, or notify distributor.
|
|
|
|
GeneratedText validation is owned by `internal/generatedtext`. App
|
|
orchestration uses `internal/generatedtext` catalog lookup to connect
|
|
`internal/report` definition schema/template IDs to the matching validator,
|
|
render-context builder, and embedded assets.
|
|
|
|
## Template Contracts
|
|
|
|
Daily, Today, Tomorrow, and Hourly rendering use typed render contexts with:
|
|
|
|
- report metadata labels such as title, location, valid period, and generation
|
|
time
|
|
- validated GeneratedText prose slots
|
|
- deterministic labels derived from module outputs, including current
|
|
conditions, hourly forecast rows, precipitation timing, alerts, SPC outlooks,
|
|
forecast discussion, SPC discussion, and weather story
|
|
|
|
Daily, Today, and Tomorrow additionally expose forecast-date labels, ordered
|
|
daypart forecast rows, daily/daypart summaries, planning facts, and a
|
|
multi-paragraph forecast discussion generated-text slot. The ordered daypart
|
|
slice is built in Go so templates do not range over maps.
|
|
|
|
The Daily template asset uses the same Markdown structure as Tomorrow's
|
|
template and renders from `generatedtext.DailyRenderContext`.
|
|
|
|
Templates use `text/template` with `missingkey=error`, so missing context fields
|
|
fail rendering instead of producing incomplete Markdown.
|
|
|
|
Daily and Tomorrow call the shared `daypart_forecast` partial. Today calls
|
|
`today_daypart_forecast` so it can omit elapsed or missing dayparts. Daily,
|
|
Today, Tomorrow, and Hourly call the shared `alert_digest` and
|
|
`precipitation_timing` partials. Partial files are parsed with each top-level
|
|
template at render time and receive the same typed render context as the
|
|
caller. The `alert_digest` partial renders the combined Alerts and Risk
|
|
Products section from relevant NWS alerts and curated SPC outlook digest
|
|
records. Rendered NWS alert bullets include alert identity and timing but omit
|
|
instruction and description text. Rendered SPC outlook bullets start at
|
|
Enhanced Risk; lower-risk SPC entries may still exist in module snapshots and
|
|
data packages.
|
|
|
|
## Schema Contract
|
|
|
|
The GeneratedText schemas describe the structured prose Scriptorium is expected
|
|
to write for each generated-text prompt. Hourly requires:
|
|
|
|
- `summary`
|
|
- `forecast_discussion`
|
|
|
|
Daily, Today, and Tomorrow require `summary` and a nonempty
|
|
`forecast_discussion` array. All generated-text schemas allow optional
|
|
`precipitation_timing` and `confidence`, and reject additional properties.
|
|
Weather truth remains in module outputs; GeneratedText is limited to prose
|
|
slots consumed by the template.
|
|
|
|
## Failure Behavior
|
|
|
|
- Unknown template IDs return actionable lookup errors.
|
|
- Unknown schema IDs return actionable lookup errors.
|
|
- Template parse errors include the template ID.
|
|
- Partial read or parse errors include the partial path.
|
|
- Template execution errors include the template ID and usually identify the
|
|
missing context field.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/reporttemplate/reporttemplate_test.go`
|
|
- `internal/generatedtext/render_context_test.go`
|
|
- `internal/app/app_test.go`
|
|
- `internal/cli/root_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Embedded templates and schemas live as separate files, not inline Go strings.
|
|
- Shared Markdown partials live under `templates/partials/`.
|
|
- Report definitions select templates by ID.
|
|
- Templates render from curated render contexts, not raw data packages.
|
|
- GeneratedText schemas describe LLM prose slots, not deterministic weather
|
|
facts.
|