Document prepared message content hashes
This commit is contained in:
@@ -45,6 +45,9 @@ boundary and constraints that framework work must preserve.
|
||||
|
||||
## Release Guidance
|
||||
|
||||
The [v0.24.0 release notes](docs/releases/v0.24.0.md) describe the prepared
|
||||
message-content hash and its compatibility considerations.
|
||||
|
||||
The [v0.23.3 release notes](docs/releases/v0.23.3.md) cover HTTP operation-timeout
|
||||
attribution, custom caller cancellation causes, and response-read error identity.
|
||||
|
||||
|
||||
@@ -559,12 +559,17 @@ if err != nil {
|
||||
defer preparedExecution.Discard()
|
||||
|
||||
details := preparedExecution.Details()
|
||||
messageContentHash := details.MessageContentHash
|
||||
_ = messageContentHash // An opaque value available before model execution.
|
||||
// Inspect or persist an application-selected safe subset of details.
|
||||
|
||||
result, err := engine.RunPrepared(ctx, preparedExecution)
|
||||
```
|
||||
|
||||
Preparation does not call the model or reserve backend capacity.
|
||||
`MessageContentHash` compares the ordered message roles and text, whereas
|
||||
`RenderedPromptHash` also includes the session and cache-control hints. See
|
||||
the [`PreparedRun` GoDoc](../../types.go) for their contracts and compatibility.
|
||||
`RunPrepared` executes from the retained snapshot rather than reloading
|
||||
consumer sources. The handle is opaque in-process state, while `Details`
|
||||
contains rendered content and remains subject to the application's data
|
||||
|
||||
@@ -144,7 +144,7 @@ profile, or backend:
|
||||
3. render messages and the prompt-defined session;
|
||||
4. apply any direct session ID, then compose captured history, rendered
|
||||
definition messages, and already-normalized request messages in that order;
|
||||
5. hash the effective rendered prompt; and
|
||||
5. hash the effective rendered prompt and its ordered message content; and
|
||||
6. construct the prepared value and preparation timing.
|
||||
|
||||
`Prepare` runs both phases consecutively and never performs capacity admission.
|
||||
@@ -185,6 +185,12 @@ sequence. The rendered-prompt hash uses a versioned, length-framed SHA-256
|
||||
encoding of that session, every role and content value, and cache-control
|
||||
presence and values; its hexadecimal value is opaque.
|
||||
|
||||
The separate message-content hash is computed once after that same composition.
|
||||
It streams a versioned prefix, message count, and length-framed role and text
|
||||
bytes into SHA-256, excluding session and cache metadata. Fixed reference
|
||||
vectors protect the selected v1 scheme across refactors; the public
|
||||
[`PreparedRun` GoDoc](../../types.go) owns its compatibility contract.
|
||||
|
||||
The configuration snapshot is read-only after engine construction. Concurrent
|
||||
`Prepare` and `Run` calls use detached captured targets and keep invocation
|
||||
state local.
|
||||
|
||||
20
docs/releases/v0.24.0.md
Normal file
20
docs/releases/v0.24.0.md
Normal file
@@ -0,0 +1,20 @@
|
||||
# Promptkit v0.24.0
|
||||
|
||||
This feature release adds an opaque message-content hash to prepared results.
|
||||
It identifies the ordered prepared message roles and exact text independently
|
||||
of session identity, cache hints, and other metadata. The existing rendered
|
||||
prompt hash is unchanged. See the [prepared-result GoDoc](../../types.go) and
|
||||
[consumer guide](../consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later).
|
||||
|
||||
## Compatibility And Upgrade
|
||||
|
||||
Prepared-result JSON now includes `message_content_hash`; older JSON without it
|
||||
decodes with an empty value. The new Go struct field is additive, though callers
|
||||
using positional `PreparedRun` literals may need to adjust them. No configuration
|
||||
migration is required. The Go consumer minimum and dependencies are unchanged.
|
||||
|
||||
```sh
|
||||
go get go.maximumdirect.net/promptkit@v0.24.0
|
||||
```
|
||||
|
||||
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/oss/attribution.md)
|
||||
@@ -187,6 +187,8 @@ in the feature roadmap has proportionate coverage at its owning boundary.
|
||||
|
||||
## Stage 4 — Document, Demonstrate, And Validate The End State
|
||||
|
||||
Status: complete.
|
||||
|
||||
Update these existing documentation owners:
|
||||
|
||||
- `docs/consumers/pkg-promptkit.md`: explain the narrower hash versus
|
||||
|
||||
@@ -13,15 +13,16 @@ import (
|
||||
)
|
||||
|
||||
type summary struct {
|
||||
PromptID string `json:"prompt_id"`
|
||||
SelectedProfile string `json:"selected_profile"`
|
||||
Model string `json:"model"`
|
||||
MessageCount int `json:"message_count"`
|
||||
ProfileTimeout int `json:"profile_timeout_seconds"`
|
||||
Namespaces []string `json:"namespaces"`
|
||||
Collections []collectionSummary `json:"collections"`
|
||||
ScopedPrompts []string `json:"scoped_prompts"`
|
||||
ReviewPrompts []string `json:"review_prompts"`
|
||||
PromptID string `json:"prompt_id"`
|
||||
SelectedProfile string `json:"selected_profile"`
|
||||
Model string `json:"model"`
|
||||
MessageCount int `json:"message_count"`
|
||||
MessageContentHash string `json:"message_content_hash"`
|
||||
ProfileTimeout int `json:"profile_timeout_seconds"`
|
||||
Namespaces []string `json:"namespaces"`
|
||||
Collections []collectionSummary `json:"collections"`
|
||||
ScopedPrompts []string `json:"scoped_prompts"`
|
||||
ReviewPrompts []string `json:"review_prompts"`
|
||||
}
|
||||
|
||||
type collectionSummary struct {
|
||||
@@ -152,14 +153,15 @@ func run(ctx context.Context, exampleDir string, out io.Writer) error {
|
||||
encoder := json.NewEncoder(out)
|
||||
encoder.SetIndent("", " ")
|
||||
return encoder.Encode(summary{
|
||||
PromptID: prepared.PromptID,
|
||||
SelectedProfile: prepared.SelectedProfileID,
|
||||
Model: prepared.EffectiveModelParams.Model,
|
||||
MessageCount: len(prepared.Messages),
|
||||
ProfileTimeout: *profile.TimeoutSeconds,
|
||||
Namespaces: namespaces,
|
||||
Collections: collectionSummaries,
|
||||
ScopedPrompts: scopedPromptIDs,
|
||||
ReviewPrompts: reviewPromptIDs,
|
||||
PromptID: prepared.PromptID,
|
||||
SelectedProfile: prepared.SelectedProfileID,
|
||||
Model: prepared.EffectiveModelParams.Model,
|
||||
MessageCount: len(prepared.Messages),
|
||||
MessageContentHash: prepared.MessageContentHash,
|
||||
ProfileTimeout: *profile.TimeoutSeconds,
|
||||
Namespaces: namespaces,
|
||||
Collections: collectionSummaries,
|
||||
ScopedPrompts: scopedPromptIDs,
|
||||
ReviewPrompts: reviewPromptIDs,
|
||||
})
|
||||
}
|
||||
|
||||
@@ -13,21 +13,22 @@ func TestPrepareExample(t *testing.T) {
|
||||
t.Fatal(err)
|
||||
}
|
||||
var got struct {
|
||||
PromptID string `json:"prompt_id"`
|
||||
Profile string `json:"selected_profile"`
|
||||
Model string `json:"model"`
|
||||
MessageCount int `json:"message_count"`
|
||||
Timeout int `json:"profile_timeout_seconds"`
|
||||
Namespaces []string `json:"namespaces"`
|
||||
Collections []map[string]json.RawMessage `json:"collections"`
|
||||
ScopedPrompts []string `json:"scoped_prompts"`
|
||||
ReviewPrompts []string `json:"review_prompts"`
|
||||
PromptID string `json:"prompt_id"`
|
||||
Profile string `json:"selected_profile"`
|
||||
Model string `json:"model"`
|
||||
MessageCount int `json:"message_count"`
|
||||
MessageContentHash string `json:"message_content_hash"`
|
||||
Timeout int `json:"profile_timeout_seconds"`
|
||||
Namespaces []string `json:"namespaces"`
|
||||
Collections []map[string]json.RawMessage `json:"collections"`
|
||||
ScopedPrompts []string `json:"scoped_prompts"`
|
||||
ReviewPrompts []string `json:"review_prompts"`
|
||||
}
|
||||
if err := json.Unmarshal(output.Bytes(), &got); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got.PromptID != "support/prepare" || got.Profile != "support/fast" || got.Model != "offline-model" ||
|
||||
got.MessageCount <= 0 || got.Timeout != 30 || !reflect.DeepEqual(got.Namespaces, []string{"review", "support"}) ||
|
||||
got.MessageCount <= 0 || got.MessageContentHash == "" || got.Timeout != 30 || !reflect.DeepEqual(got.Namespaces, []string{"review", "support"}) ||
|
||||
!reflect.DeepEqual(got.ScopedPrompts, []string{"support/prepare"}) || !reflect.DeepEqual(got.ReviewPrompts, []string{"review/check"}) || len(got.Collections) != 2 {
|
||||
t.Fatalf("unexpected preparation summary: %+v", got)
|
||||
}
|
||||
|
||||
@@ -17,7 +17,7 @@ func contentHashEngine(t *testing.T, promptID, profileID, backendID, content str
|
||||
}
|
||||
config := promptkit.Config{Sources: promptkit.ConfigurationSources{Main: &configkit.Input{Source: configkit.Mapping("hash test", map[string]any{
|
||||
"backends": []any{map[string]any{"id": backendID, "endpoint": "https://example.test/v1"}},
|
||||
"profiles": []any{map[string]any{"id": profileID, "backend": backendID, "model": "model-" + profileID}},
|
||||
"profiles": []any{map[string]any{"id": profileID, "backend": backendID, "model": "model"}},
|
||||
"prompts": []any{map[string]any{"id": promptID, "default_profile": profileID, "inputs": []any{map[string]any{"name": "input", "required": false}}, "messages": []any{message}, "output": output}},
|
||||
})}}}
|
||||
engine, err := promptkit.NewEngine(config, opts...)
|
||||
@@ -44,15 +44,23 @@ func TestMessageContentHashIgnoresPreparationMetadata(t *testing.T) {
|
||||
baseEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, false)
|
||||
base := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
|
||||
repeated := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
|
||||
other := contentHashEngine(t, "second", "beta", "two", "same", textOutput, false)
|
||||
otherPrepared := prepareContentHash(t, other, promptkit.RunRequest{PromptID: "second", APIKey: "synthetic-key", Execution: &promptkit.ExecutionTargetOverride{Model: "other-model"}})
|
||||
otherPrompt := contentHashEngine(t, "second", "alpha", "one", "same", textOutput, false)
|
||||
otherProfile := contentHashEngine(t, "first", "beta", "one", "same", textOutput, false)
|
||||
otherBackend := contentHashEngine(t, "first", "alpha", "two", "same", textOutput, false)
|
||||
credential := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first", APIKey: "synthetic-key"})
|
||||
settings := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first", Execution: &promptkit.ExecutionTargetOverride{Model: "other-model"}})
|
||||
session := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first", SessionID: "other-session"})
|
||||
cacheEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, true)
|
||||
cached := prepareContentHash(t, cacheEngine, promptkit.RunRequest{PromptID: "first"})
|
||||
schemas := fstest.MapFS{"schema.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)}}
|
||||
schemaEngine := contentHashEngine(t, "first", "alpha", "one", "same", map[string]any{"format": "json", "validation_mode": "json_schema", "schema_path": "schema.json"}, false, promptkit.WithSchemaFS(schemas, "."))
|
||||
schema := prepareContentHash(t, schemaEngine, promptkit.RunRequest{PromptID: "first"})
|
||||
for name, prepared := range map[string]*promptkit.PreparedRun{"repeat": repeated, "identifiers and model": otherPrepared, "session": session, "cache": cached, "schema": schema} {
|
||||
for name, prepared := range map[string]*promptkit.PreparedRun{
|
||||
"repeat": repeated, "prompt": prepareContentHash(t, otherPrompt, promptkit.RunRequest{PromptID: "second"}),
|
||||
"profile": prepareContentHash(t, otherProfile, promptkit.RunRequest{PromptID: "first"}),
|
||||
"backend": prepareContentHash(t, otherBackend, promptkit.RunRequest{PromptID: "first"}),
|
||||
"credential": credential, "settings": settings, "session": session, "cache": cached, "schema": schema,
|
||||
} {
|
||||
if prepared.MessageContentHash != base.MessageContentHash {
|
||||
t.Errorf("%s changed content hash", name)
|
||||
}
|
||||
@@ -65,10 +73,10 @@ func TestMessageContentHashIgnoresPreparationMetadata(t *testing.T) {
|
||||
func TestMessageContentHashUsesRenderedInputBytes(t *testing.T) {
|
||||
reader := &mutablePreparedArtifactReader{body: "body", hash: "first-hash"}
|
||||
engine := contentHashEngine(t, "prompt", "profile", "backend", `{{input "input"}} {{.label}}`, map[string]any{"format": "text", "validation_mode": "none"}, false, promptkit.WithArtifactReader(reader))
|
||||
request := promptkit.RunRequest{PromptID: "prompt", Inputs: map[string]promptkit.ArtifactRef{"input": promptkit.Inline("first")}, Vars: map[string]string{"label": "label", "unused": "first"}}
|
||||
request := promptkit.RunRequest{PromptID: "prompt", Inputs: map[string]promptkit.ArtifactRef{"input": promptkit.File("first")}, Vars: map[string]string{"label": "label", "unused": "first"}}
|
||||
base := prepareContentHash(t, engine, request)
|
||||
reader.set("body", "other-hash")
|
||||
request.Inputs["input"] = promptkit.Inline("other")
|
||||
request.Inputs["input"] = promptkit.File("other")
|
||||
request.Vars["unused"] = "other"
|
||||
unchanged := prepareContentHash(t, engine, request)
|
||||
if unchanged.MessageContentHash != base.MessageContentHash {
|
||||
|
||||
Reference in New Issue
Block a user