base-layer/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Document resource inspection and source migrations

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-06 15:31:16 +00:00
parent ea31e71280
commit 19a0604874
8 changed files with 148 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/formats.md
View File

@@ -110,8 +110,8 @@ and static template syntax at construction. It does not reread configuration or
message files on ordinary runs; construct a new engine to observe edits.
Schema and request artifact reads still happen during preparation. Use
`InspectConfiguration` for an explicit effective-configuration or provenance
report, `InspectProfile` for backend-completed profile settings, and preparation
for request-specific rendered details. For identity discovery before inspection,
report, resource inspection for resolved prompt, profile, and backend fields,
and preparation for completed request-specific details. For identity discovery before inspection,
see the consumer guide's [resource and collection listing](consumers/pkg-promptkit.md#discover-available-resources-and-collections).
## Prompt Definitions
@@ -315,17 +315,33 @@ only a model or backend does not clear unrelated explicitly inherited fields.
| Profile field | Absent | Explicit value | Explicit null |
| --- | --- | --- | --- |
| `backend` | No backend | Exact backend ID; blank means none | No backend |
| `endpoint` | Selected backend endpoint | Valid nonblank URL; empty clears | Clear, without backend fallback |
| `endpoint` | Selected backend endpoint | Valid nonblank URL; empty clears | Selected backend endpoint |
| `model` | Unspecified | Nonblank model; empty clears | Unspecified |
| `temperature`, `top_p`, `max_tokens` | Unspecified | Valid value, including outbound zero | Suppress outbound control |
| `service_tier`, `reasoning_effort` | Unspecified | Normalized value; blank suppresses | Suppress outbound control |
| `timeout_seconds` | 600 seconds | Nonnegative; zero disables generation deadline | Reset to 600 seconds |
| `api_key_env` | Backend lookup name, if any | Trimmed name; blank disables | Disable backend lookup |
| `api_key_env` | Backend lookup name, if any | Trimmed name; blank disables | Backend lookup name, if any |
| `api_key_required` | False | Boolean, including false | False |
| `extra_params` | Backend defaults | Recursively overlay profile map on backend map | Suppress configured provider map |
| `extra_params` | Backend defaults | Recursively overlay profile map on backend map | Backend defaults |
An empty profile mapping does not clear backend map entries. After ConfigKit
composition and inheritance, a whole-map null and omission both permit backend
defaults. Nested maps merge recursively, while scalar and array values replace;
nulls within provider maps or arrays remain literal data.
When `api_key_required` is true and the profile source is absent or null,
execution suppresses the backend credential source; an explicitly configured
profile source remains in use.
For example, if the backend provides an endpoint, API-key environment name,
and provider map, a profile containing `endpoint: null`, `api_key_env: null`,
and `extra_params: null` now inherits those backend values after handoff (unless
the required-key rule suppresses the credential source). Earlier versions used
those nulls to suppress the corresponding fallback. Use `endpoint: ""` or
`api_key_env: ""` to clear those individual strings. There is no profile-level
whole-map suppression replacement; change the backend map through ordinary
ConfigKit composition when different provider defaults are needed. ConfigKit's
retained configuration and provenance continue to show the nulls.
An empty mapping does not clear inherited map entries; null clears the whole
map. Nested maps merge recursively, while scalar and array values replace.
Runtime nonempty `ExtraParams` overrides replace the entire configured map.
Request overrides otherwise follow the [public value GoDoc](../types.go).
For example, a runtime `extra_params["extends"]` key is ordinary provider