weatherreporter/docs/integrations/promptkit.md

Promptkit Integration

Weatherreporter uses Promptkit for all generated-text reports. The four logical prompts are weather.daily_generated_text, weather.today_generated_text, weather.tomorrow_generated_text, and weather.hourly_generated_text, each at version 1.1.0. Their prompt assets, generated-text JSON Schemas, and Weatherreporter profile catalog are embedded by internal/promptassets.

Logical profile catalog

Prompt definitions select a stable Weatherreporter profile ID. The embedded definitions currently use Promptkit's openrouter backend:

Profile ID	Model	Reasoning effort	Timeout	Service tier	Default reports
weather-light	deepseek/deepseek-v4-flash	Provider default	180 seconds	flex	Hourly
weather-balanced	~google/gemini-flash-latest	high	240 seconds	flex	Daily, Today, Tomorrow
weather-deep	~anthropic/claude-sonnet-latest	high	240 seconds	flex	None

The ~ prefix is part of each OpenRouter rolling-alias model ID. The embedded profiles intentionally omit endpoints, credentials, temperature, top_p, and output-token limits.

Selection, lookup, and active execution

Before collection, Weatherreporter inspects the exact prompt version and output contract. A nonblank promptkit.profile selects one profile ID for every report in the command; otherwise the prompt's declared default selects it. Promptkit resolves the selected definition in this order:

1. explicit in-memory profiles used by an embedding consumer or test;
2. the configured profile_file or profile_dir;
3. Weatherreporter's embedded fallback profiles; and
4. Promptkit's built-in catalog.

A source falls through only when the selected ID is absent. Each source supplies a complete definition, so profile fields are not merged. A malformed matching operator definition is an error and does not fall back.

Profiles that require a direct API key are unsupported; a profile that reports APIKeyEnv requires a nonblank value in that environment variable. Inspection, preparation, and execution retain the selected logical profile ID and resolved backend and model through Weatherreporter's project-owned contract. Ordinary errors, summaries, logs, and workspace state exclude endpoints, credentials, rendered messages, schemas, request bodies, response bodies, and complete parameter maps.

Execution receives the already-persisted YAML package, prepares it once, and returns structured JSON that Weatherreporter validates before rendering its own Markdown template. Preparation and execution receipts are project-owned, safe provenance records. Content-rich diagnostics are opt-in through --llm-debug-dir; see operations for retention and permissions.

The generated-text schemas require summary, forecast_discussion, and precipitation_timing, and reject additional properties. Prompts return an empty string for precipitation_timing when the deterministic package contains no precipitation windows.

Prompt/profile configuration and the maintained local override example are owned by the configuration reference. Adapter construction and mapping are documented in the Promptkit adapter internals. Durable metadata compatibility is described in state internals.