scriptorium/docs/consumers/migrating-to-promptkit.md

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:

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:

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:

go mod tidy
go test ./...

Confirm that go.mod selects Promptkit v0.1.0 and that no Go file imports the former Scriptorium package:

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 and Go source.

Promptkit also includes migration-relevant public contracts that were not in Scriptorium v0.11.1:

• WithArtifactReader and the ArtifactReader declaration provide the artifact-reading extension described by the tagged extension-interface guide.
• ErrProfileRequired and ErrAPIKeyEnvMissing provide the specific identities described by the tagged error guide.

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.