110 lines
3.9 KiB
Markdown
110 lines
3.9 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 Today
|
|
Report, Tomorrow Report, and Hourly Report.
|
|
|
|
The package embeds assets from:
|
|
|
|
- `internal/reporttemplate/templates/*.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 `today`, `tomorrow`, and `hourly`. The
|
|
implemented schema IDs are also `today`, `tomorrow`, and `hourly`, backed by
|
|
matching `*.generated_text.schema.json` files.
|
|
|
|
The Today generated-text prompt source is
|
|
`internal/reporttemplate/prompts/today.generated_text.md`, selected by prompt
|
|
ID `weather.today_generated_text`.
|
|
|
|
## 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
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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`
|
|
|
|
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.
|
|
- 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.
|