84 lines
3.7 KiB
Markdown
84 lines
3.7 KiB
Markdown
# 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.
|