Eric Rakestraw
2f42bdde39
All checks were successful
ci/woodpecker/tag/release Pipeline was successful
110 lines
4.1 KiB
Markdown
110 lines
4.1 KiB
Markdown
# 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.
|