Refresh report and template internals documentation
This commit is contained in:
@@ -1,128 +1,51 @@
|
||||
# Report Template Internals
|
||||
|
||||
This document describes embedded Markdown templates and GeneratedText schemas
|
||||
in `internal/reporttemplate`.
|
||||
`internal/reporttemplate` embeds and renders the repository's native Markdown
|
||||
templates and exposes their companion generated-text schemas. The current asset
|
||||
IDs are `daily`, `today`, `tomorrow`, and `hourly`. The template files, partials,
|
||||
and complete render-context field reference are maintained in
|
||||
[report templates](../templates.md).
|
||||
|
||||
## Purpose
|
||||
## Assets and lookup
|
||||
|
||||
`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 top-level templates, shared partials, and JSON schemas from
|
||||
its asset directories. `Template` and `Schema` return the requested embedded
|
||||
asset and fail with the requested ID when it is unknown or unreadable.
|
||||
|
||||
The package embeds assets from:
|
||||
Generated-text catalog handlers obtain schema bytes and template source through
|
||||
these APIs. Prompt source files are repository assets for prompt registration;
|
||||
they are not reporttemplate lookup assets. Report definitions select IDs, while
|
||||
[generated-text internals](generatedtext.md) verifies the supported
|
||||
schema/template pairing.
|
||||
|
||||
- `internal/reporttemplate/templates/*.md.tmpl`
|
||||
- `internal/reporttemplate/templates/partials/*.md.tmpl`
|
||||
- `internal/reporttemplate/schemas/*.schema.json`
|
||||
## Rendering
|
||||
|
||||
Generated-text prompt source files live under
|
||||
`internal/reporttemplate/prompts/`. They are repository assets for prompt
|
||||
registration, not embedded lookup APIs.
|
||||
`Render` loads the top-level template, creates a `text/template` with helper
|
||||
functions and `missingkey=error`, parses the template, parses every shared
|
||||
partial, and executes the result against the typed render context. This makes
|
||||
missing context fields, bad template syntax, unreadable partials, and execution
|
||||
failures actionable with template or partial context.
|
||||
|
||||
## Inputs And Outputs
|
||||
Top-level templates decide which shared partials they invoke. The current
|
||||
partials cover daypart forecast variants, alert digest, and precipitation
|
||||
timing. Template code receives curated typed contexts rather than raw data
|
||||
packages, and it must not reimplement weather selection or generated-text
|
||||
validation.
|
||||
|
||||
Inputs:
|
||||
## Boundaries and verification
|
||||
|
||||
- template ID from a report definition
|
||||
- typed render context built by `internal/generatedtext`
|
||||
This package does not collect weather data, build modules, validate generated
|
||||
text, construct contexts, resolve report definitions, write state, execute
|
||||
Scriptorium, or upload reports. It produces Markdown bytes for application
|
||||
orchestration to persist.
|
||||
|
||||
Outputs:
|
||||
Focused tests cover asset lookup, schema availability, rendering, partial
|
||||
behavior, missing keys, and malformed context:
|
||||
|
||||
- template source for inspection and tests
|
||||
- GeneratedText schema bytes for prompt/schema configuration
|
||||
- rendered Markdown bytes for app orchestration to persist
|
||||
```sh
|
||||
go test ./internal/reporttemplate
|
||||
```
|
||||
|
||||
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.
|
||||
Embedded assets stay as separate files, shared fragments stay under the partial
|
||||
directory, and generated-text schemas describe prose slots rather than
|
||||
deterministic weather facts.
|
||||
|
||||
Reference in New Issue
Block a user