132 lines
5.9 KiB
Markdown
132 lines
5.9 KiB
Markdown
# Promptkit v0.6.0
|
|
|
|
This supplemental changelog and migration guide summarizes the consumer-facing
|
|
changes from `v0.5.0` to `v0.6.0`. The annotated `v0.6.0` tag is the
|
|
authoritative release record. Exact current contracts belong to the linked
|
|
GoDoc and durable documentation.
|
|
|
|
## Summary
|
|
|
|
`v0.6.0` is a broad correctness, safety, efficiency, and maintainability
|
|
release. It does not add or remove public declarations. The release:
|
|
|
|
- centralizes shared execution-setting, output-contract, endpoint, and
|
|
JSON-compatible-value rules;
|
|
- unifies prompt repository behavior and avoids unnecessary prompt and profile
|
|
decoding;
|
|
- bounds consumer-controlled JSON trees and successful provider responses;
|
|
- hardens prompt content paths, artifact files, provider URLs, JSON framing,
|
|
and error propagation;
|
|
- reuses compiled schema plans and rendered artifact text within an operation;
|
|
and
|
|
- improves cancellation behavior, prepared-value ownership, deterministic
|
|
transport testing, and maintainer validation.
|
|
|
|
## Compatibility
|
|
|
|
No public declaration was added, removed, or changed. Ordinary valid `v0.5.0`
|
|
configurations and requests should continue to compile and behave as before.
|
|
|
|
The release intentionally rejects or reports several inputs that were
|
|
previously accepted, altered, or misclassified:
|
|
|
|
- execution settings must be finite, within their documented ranges, and safe
|
|
to convert to Go durations;
|
|
- output formats, validation modes, repair counts, and JSON Schema dependencies
|
|
are validated consistently;
|
|
- file-backed prompt and profile identity comes from normalized YAML metadata,
|
|
not filenames;
|
|
- prompt `content_file` values must be exact relative paths contained by their
|
|
configured source root;
|
|
- built-in file artifacts must resolve to regular files;
|
|
- selected provider endpoints must be absolute HTTP or HTTPS URLs without user
|
|
information, query strings, or fragments;
|
|
- JSON documents and successful provider responses must contain exactly one
|
|
value, and successful provider bodies are limited to 16 MiB; and
|
|
- excessively deep or expansive JSON-compatible values fail with ordinary
|
|
validation errors.
|
|
|
|
These are compatibility corrections and safety boundaries rather than new
|
|
consumer configuration requirements. Consumers relying on an invalid or
|
|
ambiguous input should correct that input before upgrading.
|
|
|
|
## Upgrade
|
|
|
|
Update the module dependency with:
|
|
|
|
```sh
|
|
go get gitea.maximumdirect.net/eric/promptkit@v0.6.0
|
|
go mod tidy
|
|
```
|
|
|
|
Run the consuming project's ordinary and race-enabled tests after upgrading.
|
|
Applications with custom prompt/profile sources, local provider endpoints,
|
|
unusual artifact paths, or assertions over provider error identities should
|
|
pay particular attention to the compatibility notes below.
|
|
|
|
## Source Loading And Identity
|
|
|
|
Prompt definitions now share one source-neutral selection and normalization
|
|
flow across operating-system and `fs.FS` sources. YAML `id` and `version`
|
|
metadata are authoritative; filenames do not create a second identity system.
|
|
Only selected content bodies are loaded, malformed unrelated definitions do
|
|
not shadow valid exact matches, and per-file read failures are reported as
|
|
prompt-load failures rather than false absence.
|
|
|
|
File-backed profiles likewise use normalized YAML IDs, reuse their metadata
|
|
read for selected strict decoding, and avoid fully decoding unrelated files.
|
|
Selected malformed definitions remain authoritative and do not silently fall
|
|
through to a lower-precedence source.
|
|
|
|
Prompt `content_file` paths are opened exactly as declared after a separate
|
|
blank check. They must remain relative to and contained by the configured
|
|
prompt source root, including across operating-system symlinks.
|
|
|
|
See the [framework source and identity reference](../formats.md) and
|
|
[internal source overview](../internal/sources.md) for the current contracts.
|
|
|
|
## Validation, Cancellation, And Efficiency
|
|
|
|
JSON Schema documents preserve exact JSON-number representations. Schema
|
|
resource URLs safely escape legal filesystem names, and each operation loads
|
|
and compiles its schema graph once. `Run` and prepared execution reuse that
|
|
operation-local plan; Promptkit does not introduce a cross-operation cache.
|
|
|
|
Artifact reading, rendering, schema loading, compilation, and validation now
|
|
check cancellation at the synchronous boundaries Promptkit controls. Rendering
|
|
memoizes each artifact's text within one render operation, while plain JSON
|
|
validation avoids materializing an unnecessary generic tree.
|
|
|
|
The shared JSON-compatible-value owner now limits nesting and produced work so
|
|
unsafe consumer-controlled structures return errors instead of risking
|
|
unbounded recursion or allocation. See the
|
|
[architecture policy](../policy/architecture.md) for invariant ownership and
|
|
the [format reference](../formats.md) for validation behavior.
|
|
|
|
## Provider Transport Hardening
|
|
|
|
OpenAI-compatible endpoints are parsed and composed structurally, including
|
|
nested base paths. Underlying transport cancellation and deadline errors remain
|
|
discoverable with `errors.Is` through Promptkit's generation error category.
|
|
|
|
Successful provider bodies are read with a fixed 16 MiB bound and must contain
|
|
exactly one JSON response object followed only by whitespace. Oversized,
|
|
truncated, malformed, or multiply framed responses fail without returning a
|
|
partial result. See the
|
|
[OpenAI-compatible integration contract](../integrations/openai-compatible-chat.md)
|
|
for the canonical request, endpoint, error, and response behavior.
|
|
|
|
## Public API Changes
|
|
|
|
None.
|
|
|
|
## Consumer Action
|
|
|
|
- Correct any configuration or request that depends on the formerly permissive
|
|
cases described under Compatibility.
|
|
- Confirm custom local provider endpoints are absolute HTTP or HTTPS base URLs
|
|
without credentials, queries, or fragments.
|
|
- Confirm prompt content paths remain within their configured source root and
|
|
file artifacts resolve to regular files.
|
|
- Run ordinary and race-enabled consumer tests after updating the dependency.
|