270 lines
14 KiB
Markdown
270 lines
14 KiB
Markdown
# Promptkit v0.11 Adoption
|
|
|
|
## Status And Intent
|
|
|
|
Accepted feature direction, recorded on 2026-09-26; implementation is pending.
|
|
Upgrade directly from Promptkit v0.9.0 to v0.11.0, including the intervening
|
|
v0.10.0 catalog transition. This document defines the desired end state and
|
|
the changes from the current baseline. The [implementation plan](implementation.md)
|
|
owns sequencing, concrete interface choices, verification steps, and unresolved
|
|
implementation decisions.
|
|
|
|
The target is complete definition compatibility, controllable transient
|
|
retries, an optional whole-run deadline, and modest opt-in execution diagnostics.
|
|
This is a focused adapter and configuration update, not another architecture
|
|
migration. Optional diagnostics are included in the desired feature set.
|
|
“Optional” means callers opt in, not that diagnostics may be silently omitted
|
|
from the completed adoption or appear in default output.
|
|
|
|
[ADR 0004](../adr/0004-definition-boundary.md) and the
|
|
[architecture policy](../policy/architecture.md) govern scope. Promptkit remains
|
|
the parser, validator, execution engine, and owner of framework defaults.
|
|
Scriptorium remains a simple executable application for independent prompt
|
|
executions, with shared operational state where required for backend limits.
|
|
|
|
## Baseline And Upstream Changes
|
|
|
|
Scriptorium currently selects Promptkit v0.9.0 and the v1.0.0 backend catalog
|
|
modules. It already supports CLI execution, rendering, prompt/profile
|
|
inspection, HTTP execution, configured backends, and presence-aware execution
|
|
overrides. It does not expose transient retry settings, a whole-run deadline,
|
|
or execution observers. CLI execution currently supplies a background context.
|
|
|
|
The upstream review covered the local tagged release v0.11.0 at commit
|
|
`db05b56166ca2d8650dfaf660e1cf0eed3932e1d`. Its canonical references are:
|
|
|
|
- [v0.10.0 migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.10.0/docs/releases/v0.10.0.md);
|
|
- [v0.11.0 release notes](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/releases/v0.11.0.md);
|
|
- [definition formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/formats.md);
|
|
- [execution and retry integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/integrations/openai-compatible-chat.md);
|
|
- [consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/docs/consumers/pkg-promptkit.md); and
|
|
- [observation declarations](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/observations.go).
|
|
|
|
A diagnostic run using a temporary module file compiled Scriptorium against
|
|
v0.11.0. The existing test suite reported one failing profile-inspection case
|
|
that selects the removed `deepseek-4-flash` profile; other packages passed.
|
|
This establishes an initial migration issue, not proof of complete behavioral
|
|
compatibility or coverage of the new capabilities. The diagnostic did not
|
|
change the repository dependency pin.
|
|
|
|
Neither intervening release adds declarative prompt/profile fields requiring
|
|
new adapter plumbing. The definition-facing changes concern catalog contents
|
|
and resolution precedence. Retry and observer APIs are execution controls;
|
|
their adoption is a deliberate case-by-case choice under ADR 0004.
|
|
|
|
## Dependency And Definition Compatibility
|
|
|
|
### Target End State
|
|
|
|
Scriptorium uses tagged Promptkit v0.11.0 through its supported root package,
|
|
with the catalog versions selected by that release:
|
|
|
|
- `promptkit-backend-openrouter/v2` v2.20260922.1;
|
|
- `promptkit-backend-rakestrawhome/v2` v2.20260922.0.
|
|
|
|
Valid definitions for the selected Promptkit version remain usable through
|
|
Scriptorium's existing sources and adapters, subject to its established HTTP
|
|
artifact and deployment boundaries. Rendering and inspection remain offline
|
|
operations that do not generate model output.
|
|
|
|
The maintained names `promptkit-openrouter-standard` and
|
|
`promptkit-openrouter-auto` work wherever a profile ID is accepted, including
|
|
prompt defaults, explicit selection, inheritance, and profile inspection.
|
|
They are opt-in choices, not new Scriptorium defaults. Ordinary custom-source
|
|
precedence remains intact.
|
|
|
|
A stable maintained name is not a frozen model/settings selection. External
|
|
catalog entries can change or disappear across upgrades; inheriting from one
|
|
does not create a frozen copy. Complete application-owned profiles remain the
|
|
appropriate choice when an application owns its model and settings.
|
|
|
|
### Change From Baseline
|
|
|
|
The module graph and active definition fixtures reflect the released v0.11
|
|
catalogs rather than v0.9's catalogs. The selected catalog removes
|
|
`deepseek-3-2`, `deepseek-4-flash`, and `deepseek-4-pro`; newer DeepSeek names
|
|
are not compatibility aliases. Migration guidance offers an available catalog
|
|
profile, a maintained Promptkit name, or a complete application-owned definition.
|
|
Application-owned examples retain fixed settings where that is their purpose.
|
|
|
|
Definition conformance and focused resolution coverage protect Scriptorium's
|
|
adapter boundary without duplicating the upstream parser or catalog. Existing
|
|
dependency boundaries also apply to the new `/v2` module paths.
|
|
|
|
## Controllable Transient Retries
|
|
|
|
### Target End State
|
|
|
|
Expose `transient_retries` in application configuration, with a CLI execution
|
|
override and an HTTP request override. Preserve value presence throughout:
|
|
|
|
| Value | Meaning |
|
|
| --- | --- |
|
|
| Omitted | Inherit the engine setting, ultimately Promptkit's default. |
|
|
| Zero | Disable additional transient attempts. |
|
|
| Positive integer | Permit that many additional transient attempts. |
|
|
| Negative integer | Invalid configuration or request. |
|
|
|
|
Adopt Promptkit's default of two additional attempts rather than silently
|
|
pinning the previous single-attempt behavior. Users must be able to select zero
|
|
explicitly. Request overrides take precedence over application configuration;
|
|
omission must not accidentally become an explicit zero.
|
|
|
|
Promptkit alone owns eligible statuses, attempt execution, backoff,
|
|
`Retry-After`, and capacity coordination. Scriptorium adds no outer model retry
|
|
loop. Transient retries and structural repairs have distinct budgets: each
|
|
generation, including each repair generation, receives its transient budget.
|
|
Retries do not imply exactly-once generation or complete billing knowledge.
|
|
|
|
### Change From Baseline
|
|
|
|
Application settings reach `promptkit.Config.TransientRetries`, including the
|
|
shared server engine, and request overrides reach
|
|
`promptkit.RunRequest.TransientRetries`. This adds execution controls, not
|
|
prompt/profile schema fields or provider model parameters. Strict decoding and
|
|
presence-aware mapping preserve inheritance and explicit zero. User and
|
|
operations guidance makes the changed default, latency/cost implications, and
|
|
independent repair budget visible. Cancellation and shared backend limits
|
|
remain effective during retrying executions.
|
|
|
|
## Optional Whole-Run Deadline
|
|
|
|
### Target End State
|
|
|
|
Callers can opt into a total execution deadline independently of the existing
|
|
generation timeout. No new default deadline is imposed. Existing timeout
|
|
controls must not silently change meaning: in v0.11.0 they apply per generation
|
|
attempt, whereas a whole-run deadline bounds the overall operation, including
|
|
preparation, capacity waiting, retry delays, attempts, and repairs as supported
|
|
by the upstream context contract.
|
|
|
|
Expose this choice through CLI execution and HTTP execution. Derive any timeout
|
|
context from the caller's existing context, so a caller cancellation or earlier
|
|
deadline still wins. This is a cancellation boundary, not a guarantee of
|
|
instantaneous interruption of arbitrary callback or filesystem code.
|
|
|
|
### Change From Baseline
|
|
|
|
CLI execution can carry a selected deadline instead of always using an
|
|
unbounded background context. HTTP execution can shorten the incoming context
|
|
without losing parent cancellation or changing server lifecycle behavior.
|
|
Total-run duration handling is separate from existing attempt-timeout conversion.
|
|
The interval covers the engine invocation, not adapter parsing, engine creation,
|
|
or output writing. Provider retry timing can exceed local backoff limits;
|
|
per-attempt timeouts do not cap that complete invocation.
|
|
|
|
## Opt-In Execution Reports
|
|
|
|
### Target End State
|
|
|
|
Provide a modest terminal execution report for CLI and HTTP callers who opt
|
|
in. Capture selected metadata through `RunRequest.Observer`, including attempt,
|
|
retry, repair, timing, outcome, and presence-aware usage information. Reports
|
|
should be available for completed successful and failed execution invocations
|
|
when Promptkit supplies terminal observations. Do not invent execution data for
|
|
failures that occur before invocation.
|
|
|
|
Keep generated CLI content on stdout or the existing output path. Execution
|
|
reports use a separate destination. Ordinary CLI output and HTTP response
|
|
shapes remain unchanged when reporting is not requested.
|
|
|
|
The report has a Scriptorium-owned schema rather than serializing upstream
|
|
events directly: `ExecutionEvent` has no stable JSON contract. Preserve unknown
|
|
usage versus reported zero, and incomplete versus complete observed totals.
|
|
Existing successful-result usage semantics remain unchanged. A terminal total
|
|
is an aggregate, not another attempt to add to the bill; no report is a billing
|
|
ledger.
|
|
|
|
### Change From Baseline
|
|
|
|
Both adapters have opt-in reporting and explicit application-owned report DTOs.
|
|
Per-request collection adds no shared mutable report state, durable storage,
|
|
callback I/O, or event archive. Operational failures can carry reports without
|
|
manufacturing partial `RunResult` values. Default output remains unchanged.
|
|
|
|
Reports exclude prompt and response bodies, credentials, headers, endpoint URLs,
|
|
provider diagnostic text, and raw errors. Selected identifiers remain potentially
|
|
sensitive even when observations are content-free. Reports are concise terminal
|
|
metadata, not a general telemetry framework, event stream, or durable history.
|
|
|
|
## Errors And Compatibility
|
|
|
|
Preserve existing CLI exit classifications and HTTP `502 / llm_failed`
|
|
classification for generation failures. Keep safe public messages rather than
|
|
exposing provider error bodies or parsing diagnostic strings.
|
|
|
|
Promptkit adds `ErrTransport`, `ErrMalformedResponse`, `ErrRetriesExhausted`, and
|
|
`RetryExhaustedError`. Use their public identities to support optional structured
|
|
failure details in execution diagnostics, including actual attempts where
|
|
available. Retry exhaustion and the final cause are distinct facts; do not lose
|
|
the underlying failure category by flattening them into one label.
|
|
|
|
Capacity and validation behavior remains intact. Whole-run deadline and caller
|
|
cancellation outcomes are deliberate adapter classifications, distinct from a
|
|
provider-attempt timeout while the caller context is still live. The implementation
|
|
plan owns the exact presentation choices. Existing generation-error codes do
|
|
not need a breaking replacement for this upgrade.
|
|
|
|
## Licensing And Distribution Review
|
|
|
|
Promptkit v0.11.0 changes from GPLv3 to LGPL-3.0-or-later. Scriptorium's current
|
|
binary workflow produces statically linked Go executables, and upstream's
|
|
[license summary](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.0/README.md#license)
|
|
explicitly calls out distribution considerations for that model. Catalog and
|
|
other dependency licenses remain separate.
|
|
|
|
Before distributing the upgraded binaries, resolve the applicable notices,
|
|
license texts, source availability, and any required materials or permissions
|
|
for recombination with a modified library. Record the chosen distribution
|
|
approach and make any corresponding packaging/documentation changes. This
|
|
roadmap is not a legal determination or a complete compliance checklist.
|
|
|
|
Do not automatically relicense Scriptorium, assume that library source alone
|
|
settles every distribution requirement, or alter historical release contents.
|
|
Licensing review is a concrete adoption prerequisite, not a new blanket manual
|
|
approval gate for every future release.
|
|
|
|
## Documentation And Delivery
|
|
|
|
Current documentation links to the selected v0.11.0 contracts once implemented.
|
|
CLI, HTTP, configuration, and operations documents own their respective new
|
|
behavior; internal docs explain adapter mapping; release notes summarize
|
|
compatibility impact. Historical release notes and ADR decision content remain
|
|
unchanged. Current examples and migration guidance reflect the selected version.
|
|
|
|
The upgrade merits a minor Scriptorium release, not a compatibility patch,
|
|
with prominent migration guidance for removed profiles, changed retry behavior,
|
|
the explicit single-attempt option, and timeout layering. Any later decision to
|
|
defer part of the target leaves that feature visibly incomplete until delivered.
|
|
|
|
Use the existing [release policy](../policy/release.md) and
|
|
[runbook](../release.md). This roadmap authorizes no publication. No new ADR is
|
|
needed unless a later decision changes the established product or compatibility
|
|
boundaries.
|
|
|
|
## Completion Criteria
|
|
|
|
- The tagged dependency and selected catalog modules are adopted without
|
|
unsupported imports or local dependency substitutions.
|
|
- Existing definition conformance tests and focused maintained-profile tests
|
|
pass; removed profile IDs have explicit migration guidance, not silent aliases.
|
|
- Retry settings preserve omission and zero across configuration, CLI, and HTTP;
|
|
Promptkit remains the sole retry/capacity implementation.
|
|
- Optional total deadlines bound the caller operation without redefining
|
|
per-attempt timeouts or disabling parent cancellation.
|
|
- Opt-in terminal reports provide safe, isolated, presence-aware execution
|
|
metadata without changing default output or creating durable workflow state.
|
|
Any deferred reporting work remains visibly incomplete.
|
|
- Existing error classifications remain compatible, with deliberate handling
|
|
of the new public identities and context outcomes.
|
|
- The licensing/distribution approach is resolved before upgraded binary
|
|
distribution, and any required materials are included in the chosen workflow.
|
|
- Affected contracts, examples, migration guidance, and release notes match
|
|
implemented behavior. Relevant tests remain offline and credential-free,
|
|
and normal development and release validation pass.
|
|
|
|
Concrete interface decisions and the remaining distribution question are recorded
|
|
in the [implementation plan](implementation.md). They do not expand the product
|
|
into conversations, follow-up messages, application-owned semantic retry loops,
|
|
prepared-handle coordination, or multi-step workflows.
|