77 lines
4.1 KiB
Markdown
77 lines
4.1 KiB
Markdown
# Generated Text Internals
|
|
|
|
`internal/generatedtext` validates the structured prose produced for generated-
|
|
text reports and turns validated prose plus rich module values into typed render
|
|
contexts. It owns the catalog that pairs a generated-text report definition
|
|
with its validator, schema ID, template ID, and context builder. The complete
|
|
maintainer-facing context fields belong to [report templates](../templates.md).
|
|
|
|
## Catalog and validation
|
|
|
|
The Daily, Today, Tomorrow, and Hourly report definitions each use structured
|
|
generated text. `LookupDefinition` requires the exact report, schema, and
|
|
template triple and rejects unknown IDs, unsupported pairs, and a pair that
|
|
belongs to another report before the run begins. A handler validates raw JSON,
|
|
returns a typed value and canonical normalized JSON, loads its canonical schema through
|
|
`internal/promptassets`, builds a render context, and renders through
|
|
`internal/reporttemplate`.
|
|
|
|
Daily, Today, and Tomorrow use a day-style value with required trimmed summary
|
|
and one or more nonblank discussion paragraphs. Hourly requires trimmed summary
|
|
and a single trimmed discussion string. Every form also requires the
|
|
`precipitation_timing` field; an empty string means there is no supported timing
|
|
prose to render. Typed decoding requires the exact lowercase JSON field names,
|
|
rejects missing, duplicate, case-variant, and unknown fields, and checks field
|
|
shapes; no general-purpose JSON Schema engine is used at runtime.
|
|
|
|
The validator accepts at most 64 KiB of raw JSON before it allocates typed
|
|
values. Its JSON Schemas and typed checks limit `summary` and
|
|
`precipitation_timing` to 4,000 characters each. Hourly
|
|
`forecast_discussion` is limited to 12,000 characters. Day-style discussion
|
|
accepts at most 12 paragraphs of at most 4,000 characters each. Across all
|
|
prose fields, one report may contain at most 20,000 characters. These bounds
|
|
apply before trimming, filtering, normalization, and template rendering.
|
|
|
|
Malformed JSON and field values return short, content-safe errors. They name
|
|
only canonical fields where useful and never echo provider values or unknown
|
|
field names. The Promptkit adapter also drops an oversized provider result
|
|
before copying it into execution or debug state; direct executor implementations
|
|
receive the same enforcement in this package.
|
|
|
|
## Render contexts
|
|
|
|
The catalog's report-specific builders receive the prepared report identity, a
|
|
rich module snapshot, derived facts needed to order dayparts, and the matching
|
|
validated generated text. They require the identity's report ID to match the
|
|
selected builder. When the optional metadata stanza is present, every shared
|
|
identity field must agree with that prepared authority before context
|
|
construction continues. Builders then decode the module stanzas needed by the
|
|
template and build typed Daily, Today, Tomorrow, or Hourly contexts. Contexts
|
|
expose only display-ready report values, generated prose, and module values;
|
|
they do not expose complete collected or derived fact bundles. Ordered slices
|
|
remain the template iteration surface rather than maps.
|
|
|
|
Optional source stanzas become nil or fallback context fields. Today also
|
|
computes whether its ordered dayparts contain a displayable condition so the
|
|
template can render either rows or its explicit no-details fallback. Missing
|
|
required stanzas, type-decoding failures, conflicting identity values, invalid
|
|
metadata, or a generated-text type that does not match the chosen handler fail
|
|
before template execution. Prompt packages, raw Promptkit output handling, and
|
|
template asset lookup remain outside this package.
|
|
|
|
## Verification and invariants
|
|
|
|
Focused tests cover the catalog, each report-specific validator, normalization,
|
|
schema/template mismatches, context construction, optional modules, and typed
|
|
stanza errors:
|
|
|
|
```sh
|
|
go test ./internal/generatedtext
|
|
```
|
|
|
|
Generated text supplies prose slots only; deterministic weather facts remain in
|
|
module and fact values. The renderer applies its plain-text policy to every
|
|
generated prose insertion, preserving ordinary text and paragraph breaks while
|
|
preventing provider text from creating Markdown or HTML structure. Every report
|
|
definition must resolve to exactly one supported catalog pair.
|