diff --git a/README.md b/README.md index bd4d055..5a0f781 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/consumers/pkg-promptkit.md b/docs/consumers/pkg-promptkit.md index 7c27c42..0fd4c7f 100644 --- a/docs/consumers/pkg-promptkit.md +++ b/docs/consumers/pkg-promptkit.md @@ -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 diff --git a/docs/internal/runner.md b/docs/internal/runner.md index 3a8abea..b5a2692 100644 --- a/docs/internal/runner.md +++ b/docs/internal/runner.md @@ -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. diff --git a/docs/releases/v0.24.0.md b/docs/releases/v0.24.0.md new file mode 100644 index 0000000..77128d7 --- /dev/null +++ b/docs/releases/v0.24.0.md @@ -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) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 6bbf5b4..876bd4b 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.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 diff --git a/examples/go-library/prepare/main.go b/examples/go-library/prepare/main.go index 7fbb5de..0e84afa 100644 --- a/examples/go-library/prepare/main.go +++ b/examples/go-library/prepare/main.go @@ -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, }) } diff --git a/examples/go-library/prepare/main_test.go b/examples/go-library/prepare/main_test.go index 6247249..9e1ebda 100644 --- a/examples/go-library/prepare/main_test.go +++ b/examples/go-library/prepare/main_test.go @@ -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) } diff --git a/message_content_hash_contract_test.go b/message_content_hash_contract_test.go index 8011812..1f8af8f 100644 --- a/message_content_hash_contract_test.go +++ b/message_content_hash_contract_test.go @@ -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 {