88 lines
3.4 KiB
Markdown
88 lines
3.4 KiB
Markdown
# Adapter Internals
|
|
|
|
## Purpose
|
|
|
|
Scriptorium adapters translate executable inputs into Promptkit public requests
|
|
and translate Promptkit results or errors back to CLI or HTTP behavior. They
|
|
own IO and presentation mechanics, not framework decisions.
|
|
|
|
External contracts are canonical in the [CLI reference](../cli.md) and
|
|
[HTTP API reference](../api.md). Promptkit's public engine contract is
|
|
described by its tagged
|
|
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.1.0/docs/consumers/pkg-promptkit.md).
|
|
|
|
## Components And Collaborators
|
|
|
|
- `cmd/scriptorium` passes process arguments and streams to
|
|
`internal/adapter/cli`.
|
|
- `internal/adapter/cli` resolves settings through `internal/config`,
|
|
constructs `promptkit.Engine`, maps CLI values to `promptkit.RunRequest`,
|
|
and owns output files, summaries, and exit codes.
|
|
- `internal/adapter/http` strictly decodes request DTOs, maps them to Promptkit
|
|
public values, calls its adapter-owned `Runner` interface, and maps results
|
|
and errors to HTTP DTOs.
|
|
- `internal/format` renders `promptkit.PreparedRun` values as deterministic text
|
|
or JSON.
|
|
|
|
## Wiring Flows
|
|
|
|
### CLI
|
|
|
|
`run` calls `promptkit.Engine.Run`; `render` calls
|
|
`promptkit.Engine.Prepare`. Both share request mapping for prompt/profile
|
|
selection, file inputs, variables, and presence-aware execution overrides.
|
|
Omitted framework settings remain zero values so Promptkit resolves its own
|
|
defaults.
|
|
|
|
`serve` constructs Scriptorium's restricted HTTP artifact reader, injects it
|
|
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
|
adapter's consumer-owned `Runner` interface, and starts the server.
|
|
|
|
### HTTP
|
|
|
|
The handler enforces transport limits and strict JSON decoding before mapping
|
|
DTOs into `promptkit.RunRequest`, `promptkit.ArtifactRef`, and
|
|
`promptkit.ExecutionTargetOverride`. On success it reads Promptkit artifact,
|
|
validation, model, usage, and metadata values directly.
|
|
|
|
Failure mapping uses `errors.Is` against Promptkit's public sentinels and the
|
|
HTTP reader's Scriptorium-owned containment and size errors. Wrapped reader
|
|
errors preserve their identity through Promptkit's artifact-load boundary.
|
|
|
|
## Package-Local Guarantees
|
|
|
|
- Adapters contain no copied framework types or orchestration.
|
|
- Configuration is resolved before Promptkit engine construction.
|
|
- Explicit numeric overrides preserve presence, including zero.
|
|
- HTTP DTO and error mapping remains stable and transport-owned.
|
|
- Resolved secrets are not serialized or printed.
|
|
- No adapter creates durable run state.
|
|
|
|
## Verification
|
|
|
|
Inspect:
|
|
|
|
- `internal/adapter/cli/run_test.go`
|
|
- `internal/adapter/http/handler_test.go`
|
|
- `internal/adapter/http/artifact_reader_test.go`
|
|
- `internal/format/prepared_run_test.go`
|
|
- `internal/adapter/dependency_test.go`
|
|
|
|
The adapter tests protect parsing, configuration mapping, output, status
|
|
mapping, restricted artifacts, and representative real Promptkit-engine
|
|
workflows. The dependency test protects the repository boundary.
|
|
|
|
## Change Recipes
|
|
|
|
For a CLI or HTTP change:
|
|
|
|
1. identify the Scriptorium-owned external contract;
|
|
2. map through Promptkit public values without copying framework semantics;
|
|
3. add or update the narrow application-owned test;
|
|
4. update the canonical Scriptorium contract; and
|
|
5. coordinate and tag Promptkit first if a required public capability is
|
|
genuinely absent.
|
|
|
|
Update [source internals](sources.md) when application source locations or HTTP
|
|
artifact containment changes.
|