102 lines
3.5 KiB
Markdown
102 lines
3.5 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 contracts are Tomorrow
|
|
Report and Hourly Report.
|
|
|
|
The package embeds assets from:
|
|
|
|
- `internal/reporttemplate/templates/*.md.tmpl`
|
|
- `internal/reporttemplate/schemas/*.schema.json`
|
|
|
|
## 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 `tomorrow` and `hourly`. The implemented
|
|
schema IDs are also `tomorrow` and `hourly`, backed by
|
|
`tomorrow.generated_text.schema.json` and `hourly.generated_text.schema.json`.
|
|
|
|
## Boundaries
|
|
|
|
This package owns embedded asset lookup, Go template parsing, and Markdown
|
|
template execution. It does not fetch 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
|
|
|
|
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
|
|
|
|
Tomorrow additionally exposes forecast-date labels, ordered daypart forecast
|
|
rows, daily/daypart summaries, tomorrow 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.
|
|
|
|
Templates use `text/template` with `missingkey=error`, so missing context fields
|
|
fail rendering instead of producing incomplete Markdown.
|
|
|
|
## Schema Contract
|
|
|
|
The GeneratedText schemas describe the structured prose Scriptorium is expected
|
|
to write for each generated-text prompt. Hourly requires:
|
|
|
|
- `summary`
|
|
- `forecast_discussion`
|
|
|
|
Tomorrow requires `summary` and a nonempty `forecast_discussion` array. Both
|
|
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.
|
|
- 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.
|
|
- 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.
|