# Omit Unset Optional Request Parameters

Status: Complete.

## 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.