94 lines
3.0 KiB
Markdown
94 lines
3.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 first implemented template contract is the
|
|
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 ID is `hourly`. The implemented schema ID is also
|
|
`hourly`, backed by `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 decides which template and schema IDs apply to a report through
|
|
`internal/report` definitions.
|
|
|
|
## Template Contract
|
|
|
|
Hourly rendering uses a typed render context with:
|
|
|
|
- report metadata labels such as title, location, valid period, and generation
|
|
time
|
|
- validated hourly 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
|
|
|
|
Templates use `text/template` with `missingkey=error`, so missing context fields
|
|
fail rendering instead of producing incomplete Markdown.
|
|
|
|
## Schema Contract
|
|
|
|
The hourly GeneratedText schema describes the structured prose Scriptorium is
|
|
expected to write for the prompt. It requires:
|
|
|
|
- `summary`
|
|
- `forecast_discussion`
|
|
|
|
It allows optional `precipitation_timing` and `confidence`, and rejects
|
|
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.
|