promptkit/docs/roadmap/optional-request-parameters.md

Omit Unset Optional Request Parameters

Status: Selected for implementation.

Purpose

Promptkit will stop turning an unset optional provider control into an explicit outbound value. Required protocol fields and settings needed to enforce Promptkit's own contracts will retain defined behavior, while provider tuning choices will be sent only when a supported configuration layer selects them.

This keeps profiles intentional, avoids overriding model- or backend-specific defaults, and improves compatibility across OpenAI-compatible endpoints with different supported parameter sets.

Scope

The framework-level top_p default of 1 will become unspecified. When no profile or runtime override supplies top_p, the built-in OpenAI-compatible client will omit it from the request body rather than serialize 1.

This establishes the general outbound policy for currently supported optional controls:

• temperature, max_tokens, and top_p are omitted when unspecified and included when selected by a profile or runtime override;
• an explicit numeric zero supplied through a runtime override remains present on the wire through the existing numeric-presence contract;
• service_tier and reasoning_effort remain omitted when their resolved values are empty;
• backend, profile, or runtime extra_params remain explicit configuration and are sent when present; and
• session_id remains conditional on a supplied nonempty value, while response_format remains conditional on the effective output contract.

The request body will continue to require model and messages. Endpoint and credential resolution remain transport concerns rather than body defaults. The positive framework timeout_seconds default also remains in place because it enforces a Promptkit-owned generation deadline and is not serialized as a provider request field.

Effective Settings And Compatibility

An unspecified numeric provider control continues to use its zero Go value in resolved public metadata. For a GenerateRequest delivered to an injected client, the existing ExecutionTargetPresence value distinguishes an explicit runtime zero from an inherited unspecified zero. Prepared and inspection metadata will continue to report the resolved numeric value without adding source-provenance fields.

The behavior change is intentional and belongs in a minor release. Consumers that require stable sampling behavior should declare the desired values in their profiles or runtime overrides instead of relying on Promptkit to repeat a provider's conventional default.

Built-in profile parameters remain explicit profile policy and will continue to be sent. An explicit built-in setting will not be removed merely because the framework default becomes unspecified.

Non-Goals

This change does not add:

• pointer-valued numeric fields to file or in-memory profiles;
• a general provenance model for effective settings;
• automatic discovery of provider defaults or supported parameters;
• backend- or model-specific request-shape negotiation;
• changes to required request fields, structured-output behavior, credentials, or timeout enforcement; or
• removal of deliberately configured settings from consumer or built-in profiles.

Target End State

An otherwise unset optional provider tuning parameter is absent from the OpenAI-compatible request body. Explicit profile values and runtime overrides, including explicit runtime zero values, retain their current precedence and wire effect. Promptkit continues to supply only the required protocol fields and the settings necessary to honor its own execution and output contracts.

GoDoc, the framework format reference, and the OpenAI-compatible integration contract will own the implemented omission and metadata semantics once the feature lands.