Document prepared message content hashes
This commit is contained in:
@@ -45,6 +45,9 @@ boundary and constraints that framework work must preserve.
|
|||||||
|
|
||||||
## Release Guidance
|
## 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
|
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.
|
attribution, custom caller cancellation causes, and response-read error identity.
|
||||||
|
|
||||||
|
|||||||
@@ -559,12 +559,17 @@ if err != nil {
|
|||||||
defer preparedExecution.Discard()
|
defer preparedExecution.Discard()
|
||||||
|
|
||||||
details := preparedExecution.Details()
|
details := preparedExecution.Details()
|
||||||
|
messageContentHash := details.MessageContentHash
|
||||||
|
_ = messageContentHash // An opaque value available before model execution.
|
||||||
// Inspect or persist an application-selected safe subset of details.
|
// Inspect or persist an application-selected safe subset of details.
|
||||||
|
|
||||||
result, err := engine.RunPrepared(ctx, preparedExecution)
|
result, err := engine.RunPrepared(ctx, preparedExecution)
|
||||||
```
|
```
|
||||||
|
|
||||||
Preparation does not call the model or reserve backend capacity.
|
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
|
`RunPrepared` executes from the retained snapshot rather than reloading
|
||||||
consumer sources. The handle is opaque in-process state, while `Details`
|
consumer sources. The handle is opaque in-process state, while `Details`
|
||||||
contains rendered content and remains subject to the application's data
|
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;
|
3. render messages and the prompt-defined session;
|
||||||
4. apply any direct session ID, then compose captured history, rendered
|
4. apply any direct session ID, then compose captured history, rendered
|
||||||
definition messages, and already-normalized request messages in that order;
|
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.
|
6. construct the prepared value and preparation timing.
|
||||||
|
|
||||||
`Prepare` runs both phases consecutively and never performs capacity admission.
|
`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
|
encoding of that session, every role and content value, and cache-control
|
||||||
presence and values; its hexadecimal value is opaque.
|
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
|
The configuration snapshot is read-only after engine construction. Concurrent
|
||||||
`Prepare` and `Run` calls use detached captured targets and keep invocation
|
`Prepare` and `Run` calls use detached captured targets and keep invocation
|
||||||
state local.
|
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
|
## Stage 4 — Document, Demonstrate, And Validate The End State
|
||||||
|
|
||||||
|
Status: complete.
|
||||||
|
|
||||||
Update these existing documentation owners:
|
Update these existing documentation owners:
|
||||||
|
|
||||||
- `docs/consumers/pkg-promptkit.md`: explain the narrower hash versus
|
- `docs/consumers/pkg-promptkit.md`: explain the narrower hash versus
|
||||||
|
|||||||
@@ -13,15 +13,16 @@ import (
|
|||||||
)
|
)
|
||||||
|
|
||||||
type summary struct {
|
type summary struct {
|
||||||
PromptID string `json:"prompt_id"`
|
PromptID string `json:"prompt_id"`
|
||||||
SelectedProfile string `json:"selected_profile"`
|
SelectedProfile string `json:"selected_profile"`
|
||||||
Model string `json:"model"`
|
Model string `json:"model"`
|
||||||
MessageCount int `json:"message_count"`
|
MessageCount int `json:"message_count"`
|
||||||
ProfileTimeout int `json:"profile_timeout_seconds"`
|
MessageContentHash string `json:"message_content_hash"`
|
||||||
Namespaces []string `json:"namespaces"`
|
ProfileTimeout int `json:"profile_timeout_seconds"`
|
||||||
Collections []collectionSummary `json:"collections"`
|
Namespaces []string `json:"namespaces"`
|
||||||
ScopedPrompts []string `json:"scoped_prompts"`
|
Collections []collectionSummary `json:"collections"`
|
||||||
ReviewPrompts []string `json:"review_prompts"`
|
ScopedPrompts []string `json:"scoped_prompts"`
|
||||||
|
ReviewPrompts []string `json:"review_prompts"`
|
||||||
}
|
}
|
||||||
|
|
||||||
type collectionSummary struct {
|
type collectionSummary struct {
|
||||||
@@ -152,14 +153,15 @@ func run(ctx context.Context, exampleDir string, out io.Writer) error {
|
|||||||
encoder := json.NewEncoder(out)
|
encoder := json.NewEncoder(out)
|
||||||
encoder.SetIndent("", " ")
|
encoder.SetIndent("", " ")
|
||||||
return encoder.Encode(summary{
|
return encoder.Encode(summary{
|
||||||
PromptID: prepared.PromptID,
|
PromptID: prepared.PromptID,
|
||||||
SelectedProfile: prepared.SelectedProfileID,
|
SelectedProfile: prepared.SelectedProfileID,
|
||||||
Model: prepared.EffectiveModelParams.Model,
|
Model: prepared.EffectiveModelParams.Model,
|
||||||
MessageCount: len(prepared.Messages),
|
MessageCount: len(prepared.Messages),
|
||||||
ProfileTimeout: *profile.TimeoutSeconds,
|
MessageContentHash: prepared.MessageContentHash,
|
||||||
Namespaces: namespaces,
|
ProfileTimeout: *profile.TimeoutSeconds,
|
||||||
Collections: collectionSummaries,
|
Namespaces: namespaces,
|
||||||
ScopedPrompts: scopedPromptIDs,
|
Collections: collectionSummaries,
|
||||||
ReviewPrompts: reviewPromptIDs,
|
ScopedPrompts: scopedPromptIDs,
|
||||||
|
ReviewPrompts: reviewPromptIDs,
|
||||||
})
|
})
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -13,21 +13,22 @@ func TestPrepareExample(t *testing.T) {
|
|||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
var got struct {
|
var got struct {
|
||||||
PromptID string `json:"prompt_id"`
|
PromptID string `json:"prompt_id"`
|
||||||
Profile string `json:"selected_profile"`
|
Profile string `json:"selected_profile"`
|
||||||
Model string `json:"model"`
|
Model string `json:"model"`
|
||||||
MessageCount int `json:"message_count"`
|
MessageCount int `json:"message_count"`
|
||||||
Timeout int `json:"profile_timeout_seconds"`
|
MessageContentHash string `json:"message_content_hash"`
|
||||||
Namespaces []string `json:"namespaces"`
|
Timeout int `json:"profile_timeout_seconds"`
|
||||||
Collections []map[string]json.RawMessage `json:"collections"`
|
Namespaces []string `json:"namespaces"`
|
||||||
ScopedPrompts []string `json:"scoped_prompts"`
|
Collections []map[string]json.RawMessage `json:"collections"`
|
||||||
ReviewPrompts []string `json:"review_prompts"`
|
ScopedPrompts []string `json:"scoped_prompts"`
|
||||||
|
ReviewPrompts []string `json:"review_prompts"`
|
||||||
}
|
}
|
||||||
if err := json.Unmarshal(output.Bytes(), &got); err != nil {
|
if err := json.Unmarshal(output.Bytes(), &got); err != nil {
|
||||||
t.Fatal(err)
|
t.Fatal(err)
|
||||||
}
|
}
|
||||||
if got.PromptID != "support/prepare" || got.Profile != "support/fast" || got.Model != "offline-model" ||
|
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 {
|
!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)
|
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{
|
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"}},
|
"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}},
|
"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...)
|
engine, err := promptkit.NewEngine(config, opts...)
|
||||||
@@ -44,15 +44,23 @@ func TestMessageContentHashIgnoresPreparationMetadata(t *testing.T) {
|
|||||||
baseEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, false)
|
baseEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, false)
|
||||||
base := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
|
base := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
|
||||||
repeated := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
|
repeated := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first"})
|
||||||
other := contentHashEngine(t, "second", "beta", "two", "same", textOutput, false)
|
otherPrompt := contentHashEngine(t, "second", "alpha", "one", "same", textOutput, false)
|
||||||
otherPrepared := prepareContentHash(t, other, promptkit.RunRequest{PromptID: "second", APIKey: "synthetic-key", Execution: &promptkit.ExecutionTargetOverride{Model: "other-model"}})
|
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"})
|
session := prepareContentHash(t, baseEngine, promptkit.RunRequest{PromptID: "first", SessionID: "other-session"})
|
||||||
cacheEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, true)
|
cacheEngine := contentHashEngine(t, "first", "alpha", "one", "same", textOutput, true)
|
||||||
cached := prepareContentHash(t, cacheEngine, promptkit.RunRequest{PromptID: "first"})
|
cached := prepareContentHash(t, cacheEngine, promptkit.RunRequest{PromptID: "first"})
|
||||||
schemas := fstest.MapFS{"schema.json": &fstest.MapFile{Data: []byte(`{"type":"object"}`)}}
|
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, "."))
|
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"})
|
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 {
|
if prepared.MessageContentHash != base.MessageContentHash {
|
||||||
t.Errorf("%s changed content hash", name)
|
t.Errorf("%s changed content hash", name)
|
||||||
}
|
}
|
||||||
@@ -65,10 +73,10 @@ func TestMessageContentHashIgnoresPreparationMetadata(t *testing.T) {
|
|||||||
func TestMessageContentHashUsesRenderedInputBytes(t *testing.T) {
|
func TestMessageContentHashUsesRenderedInputBytes(t *testing.T) {
|
||||||
reader := &mutablePreparedArtifactReader{body: "body", hash: "first-hash"}
|
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))
|
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)
|
base := prepareContentHash(t, engine, request)
|
||||||
reader.set("body", "other-hash")
|
reader.set("body", "other-hash")
|
||||||
request.Inputs["input"] = promptkit.Inline("other")
|
request.Inputs["input"] = promptkit.File("other")
|
||||||
request.Vars["unused"] = "other"
|
request.Vars["unused"] = "other"
|
||||||
unchanged := prepareContentHash(t, engine, request)
|
unchanged := prepareContentHash(t, engine, request)
|
||||||
if unchanged.MessageContentHash != base.MessageContentHash {
|
if unchanged.MessageContentHash != base.MessageContentHash {
|
||||||
|
|||||||
Reference in New Issue
Block a user