2026-07-28 19:43:57 +00:00
# Migrate From Scriptorium To Promptkit
2026-11-18 19:25:54 +00:00
This historical first hop targets Promptkit v0.11.1 and its former module
path. For the current public module `go.maximumdirect.net/promptkit` and the
ID-only configuration cutover, follow the
[current upgrade guide ](upgrading-promptkit.md ) afterward and consult the
2026-11-19 14:39:10 +00:00
[current Go consumer guide ](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/804a4d32b23aa2e7973400bb0a322a7016574c9f/docs/consumers/pkg-promptkit.md ).
2026-11-18 19:25:54 +00:00
2026-07-28 19:43:57 +00:00
## Supported Migration Boundary
Scriptorium `v0.11.1` at
`gitea.maximumdirect.net/eric/scriptorium` is the final release that provides
2026-09-26 22:01:03 +00:00
the former in-process Go framework. Promptkit `v0.11.1` at
2026-07-28 19:43:57 +00:00
`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
2026-09-26 22:01:03 +00:00
go get gitea.maximumdirect.net/eric/promptkit@v0 .11.1
2026-07-28 19:43:57 +00:00
```
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 ./...
```
2026-09-26 22:01:03 +00:00
Confirm that `go.mod` selects Promptkit `v0.11.1` and that no Go file imports
2026-07-28 19:43:57 +00:00
the former Scriptorium package:
```sh
test "$(
go list -m -f '{{.Path}}@{{.Version}}' \
gitea.maximumdirect.net/eric/promptkit
2026-09-26 22:01:03 +00:00
)" = 'gitea.maximumdirect.net/eric/promptkit@v0 .11.1'
2026-07-28 19:43:57 +00:00
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
2026-09-26 22:01:03 +00:00
tagged [Promptkit consumer guide ](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md )
2026-07-28 19:43:57 +00:00
and Go source.
Promptkit also includes migration-relevant public contracts that were not in
Scriptorium `v0.11.1` :
2026-09-26 22:01:03 +00:00
- [`WithArtifactReader` ](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/engine.go#L169-L174 )
2026-07-28 19:43:57 +00:00
and the
2026-09-26 22:01:03 +00:00
[`ArtifactReader` declaration ](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/types.go#L315 )
2026-07-28 19:43:57 +00:00
provide the artifact-reading extension described by the tagged
2026-09-26 22:01:03 +00:00
[extension-interface guide ](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md#extension-interfaces ).
- [`ErrProfileRequired` and `ErrAPIKeyEnvMissing` ](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/engine.go#L33-L48 )
2026-07-28 19:43:57 +00:00
provide the specific identities described by the tagged
2026-09-26 22:01:03 +00:00
[error guide ](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md#handle-errors ).
2026-07-28 19:43:57 +00:00
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.