75 lines
2.3 KiB
Markdown
75 lines
2.3 KiB
Markdown
# Generated Text Internals
|
|
|
|
This document describes structured generated-text handling in
|
|
`internal/generatedtext`.
|
|
|
|
## Purpose
|
|
|
|
`internal/generatedtext` validates structured text returned for
|
|
generated-text-template reports and builds curated render contexts for
|
|
templates. The first implemented contract is the Hourly Report.
|
|
|
|
## Inputs And Outputs
|
|
|
|
Inputs:
|
|
|
|
- raw Hourly Report GeneratedText JSON
|
|
- report metadata from `internal/briefing`
|
|
- a module snapshot from `internal/module`
|
|
- validated hourly generated text
|
|
|
|
Outputs:
|
|
|
|
- typed `Hourly` generated text
|
|
- normalized stable JSON for validated hourly generated text
|
|
- typed `HourlyRenderContext` values for `internal/reporttemplate`
|
|
|
|
The hourly generated text JSON accepts:
|
|
|
|
```json
|
|
{
|
|
"summary": "string",
|
|
"forecast_discussion": "string",
|
|
"precipitation_timing": "string",
|
|
"confidence": "string"
|
|
}
|
|
```
|
|
|
|
`summary` and `forecast_discussion` are required after trimming whitespace.
|
|
`precipitation_timing` and `confidence` are optional and omitted from normalized
|
|
JSON when blank.
|
|
|
|
## Boundaries
|
|
|
|
- This package owns typed generated-text validation and render-context shaping.
|
|
- It uses typed module snapshot decoding through `module.StanzaValue`.
|
|
- It does not invoke Scriptorium, write state artifacts, choose report
|
|
definitions, compare snapshots, or render templates directly in production
|
|
workflows.
|
|
- It does not use a Go JSON Schema dependency; schema enforcement in Go is
|
|
limited to typed JSON decoding, unknown-field rejection, and required-field
|
|
checks.
|
|
|
|
## Failure Behavior
|
|
|
|
- Malformed generated-text JSON fails with decode context.
|
|
- Unknown generated-text JSON fields fail during decoding.
|
|
- Empty required hourly fields fail after trimming whitespace.
|
|
- Missing optional render-context stanzas become nil module pointers.
|
|
- Invalid render metadata, including missing timezone, missing generated time,
|
|
or invalid valid period, fails before template rendering.
|
|
|
|
## Tests
|
|
|
|
Inspect:
|
|
|
|
- `internal/generatedtext/hourly_test.go`
|
|
- `internal/generatedtext/render_context_test.go`
|
|
|
|
## Invariants
|
|
|
|
- Render contexts are curated structs, not raw prompt-input packages.
|
|
- Required generated text is normalized before downstream artifact storage.
|
|
- Missing optional weather narrative stanzas produce empty or fallback render
|
|
context fields rather than forcing raw module data into templates.
|