diff --git a/.gitignore b/.gitignore index 0dc898f..5bc850c 100644 --- a/.gitignore +++ b/.gitignore @@ -56,6 +56,8 @@ mono_crash.* [Dd]ebugPublic/ [Rr]elease/ [Rr]eleases/ +!docs/releases/ +!docs/releases/*.md x64/ x86/ [Ww][Ii][Nn]32/ @@ -433,4 +435,3 @@ FodyWeavers.xsd # JetBrains Rider *.sln.iml - diff --git a/README.md b/README.md index aa21003..60eddb6 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ a model. For complete invocation and output behavior, see the - [HTTP API reference](docs/api.md) - [Operations guide](docs/operations.md) - [Consumer integration overview](docs/consumers/api.md) +- [Migration from the former Go package](docs/consumers/migrating-to-promptkit.md) - [Subprocess integration](docs/integrations/subprocess.md) - [Architecture policy](docs/policy/architecture.md) - [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/formats.md) diff --git a/docs/consumers/api.md b/docs/consumers/api.md index ff41182..f683f34 100644 --- a/docs/consumers/api.md +++ b/docs/consumers/api.md @@ -16,6 +16,8 @@ Go applications that need an in-process prompt framework should import Promptkit directly. The tagged [Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md) owns that interface; Scriptorium does not provide a Go library package. +Consumers arriving from the former Scriptorium Go API should follow the +[migration guide](migrating-to-promptkit.md). ## Consumer Responsibilities diff --git a/docs/consumers/migrating-to-promptkit.md b/docs/consumers/migrating-to-promptkit.md new file mode 100644 index 0000000..f89ff0f --- /dev/null +++ b/docs/consumers/migrating-to-promptkit.md @@ -0,0 +1,109 @@ +# Migrate From Scriptorium To Promptkit + +## Supported Migration Boundary + +Scriptorium `v0.11.1` at +`gitea.maximumdirect.net/eric/scriptorium` is the final release that provides +the former in-process Go framework. Promptkit `v0.1.0` at +`gitea.maximumdirect.net/eric/promptkit` is the destination for that framework +API. Scriptorium `v0.12.0` and later provide the CLI and HTTP application only. + +There is no Scriptorium compatibility facade, alias package, forwarding +package, or deprecated wrapper. A consumer that cannot migrate may remain +pinned to Scriptorium `v0.11.1`, but that framework-bearing line does not +provide the slim application release. + +## Update A Go Consumer + +Start from a clean consumer checkout and review the pending diff before +committing it. Add the published Promptkit module: + +```sh +go get gitea.maximumdirect.net/eric/promptkit@v0.1.0 +``` + +For an ordinary consumer that imports the former root package under its +default name, replace the exact import and package qualifier, then format the +changed Go files: + +```sh +git grep -l \ + '"gitea.maximumdirect.net/eric/scriptorium"' \ + -- '*.go' | + while IFS= read -r go_file + do + perl -pi -e \ + 's{"gitea.maximumdirect.net/eric/scriptorium"}{"gitea.maximumdirect.net/eric/promptkit"}g; s{\bscriptorium\.}{promptkit.}g' \ + "$go_file" + gofmt -w "$go_file" + done +``` + +Inspect the resulting diff. Consumers that used an import alias should retain +or deliberately rename that alias instead of applying the qualifier +replacement mechanically. + +Remove the now-unused Scriptorium requirement through module tidiness and run +the consumer's complete tests: + +```sh +go mod tidy +go test ./... +``` + +Confirm that `go.mod` selects Promptkit `v0.1.0` and that no Go file imports +the former Scriptorium package: + +```sh +test "$( + go list -m -f '{{.Path}}@{{.Version}}' \ + gitea.maximumdirect.net/eric/promptkit +)" = 'gitea.maximumdirect.net/eric/promptkit@v0.1.0' +if git grep -n \ + 'gitea.maximumdirect.net/eric/scriptorium' \ + -- '*.go' +then + printf '%s\n' 'a former Scriptorium Go import remains' >&2 + exit 1 +fi +``` + +## Compatibility And Additions + +Promptkit preserves the established engine, request, result, profile, +source-option, model-client, artifact, validation-value, and public-error +shapes where practical. Exact declarations and current behavior belong to the +tagged [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md) +and Go source. + +Promptkit also includes migration-relevant public contracts that were not in +Scriptorium `v0.11.1`: + +- [`WithArtifactReader`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/engine.go#L96-L105) + and the + [`ArtifactReader` declaration](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/types.go#L129-L135) + provide the artifact-reading extension described by the tagged + [extension-interface guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md#extension-interfaces). +- [`ErrProfileRequired` and `ErrAPIKeyEnvMissing`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/engine.go#L28-L40) + provide the specific identities described by the tagged + [error guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md#errors). + +Use those tagged owners for exact signatures, wrapping guarantees, and +extension behavior. + +## Verify Consumer Behavior + +Source compatibility is only the first check. Exercise the behavior the +consumer actually relies upon, especially: + +- prompt, profile, and schema source selection; +- direct and environment-based credentials; +- caller, generation, and transport timeout layering; +- output validation and validation-failure handling; +- injected model-client and artifact-reader extensions; and +- every `errors.Is` branch used for recovery or classification. + +Also verify any serialized values, redaction expectations, filesystem policy, +and provider integration behavior that crosses the consumer's own boundary. +Promptkit owns the in-process framework contract; Scriptorium owns only its +executable CLI and HTTP application interfaces. diff --git a/docs/releases/v0.12.0.md b/docs/releases/v0.12.0.md new file mode 100644 index 0000000..fad894a --- /dev/null +++ b/docs/releases/v0.12.0.md @@ -0,0 +1,36 @@ +# Scriptorium v0.12.0 + +## Breaking Project Boundary + +Scriptorium is now an executable-only CLI and HTTP application. This is a +breaking change for Go consumers: the former root Go package is not included, +and no compatibility facade is provided. + +Scriptorium `v0.11.1` was the final framework-bearing release. Former Go +consumers should follow the +[migration guide](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/consumers/migrating-to-promptkit.md) +and adopt +[Promptkit `v0.1.0`](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md) +for in-process prompt preparation and execution. + +## Application Interfaces + +The Scriptorium command-line and HTTP application interfaces remain. Their +canonical documentation defines the supported commands, configuration, +requests, responses, operational behavior, and deployment responsibilities: + +- [CLI reference](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/cli.md) +- [HTTP API reference](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/api.md) +- [Configuration reference](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/config.md) +- [Operations guide](https://gitea.maximumdirect.net/eric/scriptorium/src/tag/v0.12.0/docs/operations.md) + +## Framework Dependency And Consumers + +The released Scriptorium binaries use Promptkit `v0.1.0` as their framework +dependency. Promptkit owns the reusable engine, source formats, profiles, +generation boundary, and validation contracts. See the +[Promptkit Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md) +for that supported API. + +All known downstream Go consumers were migrated to Promptkit before this +release.