Document Scriptorium as a Promptkit application
This commit is contained in:
@@ -2,115 +2,86 @@
|
||||
|
||||
## Purpose
|
||||
|
||||
Adapters translate external inputs into public engine requests and translate
|
||||
public results or errors back to their interface. They own IO and presentation
|
||||
mechanics; use-case decisions remain behind the root `scriptorium` facade.
|
||||
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), [HTTP API
|
||||
reference](../api.md), and [Go package contract](../consumers/pkg-scriptorium.md).
|
||||
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` parses commands, resolves application settings through
|
||||
`internal/config`, constructs the public engine, and owns process output
|
||||
handling.
|
||||
- `internal/adapter/http` decodes DTOs, maps them to public run requests,
|
||||
calls its local public `Runner` interface, and maps public errors and results
|
||||
to HTTP DTOs.
|
||||
- The root `scriptorium` package maps its public types and options to internal
|
||||
collaborators and maps selected internal errors to public sentinels.
|
||||
- `internal/format` formats public prepared runs for the 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
|
||||
|
||||
The CLI resolves configuration before constructing the public engine. `run`
|
||||
calls `Engine.Run` with a public request and `render` calls `Engine.Prepare`
|
||||
with the same request mapping. `serve` constructs the HTTP-owned restricted
|
||||
artifact reader, injects it with `WithArtifactReader`, passes the resulting
|
||||
engine directly to the HTTP handler, and starts the server.
|
||||
`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.
|
||||
|
||||
Parser state records whether numeric runtime values were explicitly supplied.
|
||||
That presence is carried into `scriptorium.ExecutionTargetOverride`, allowing
|
||||
the engine to distinguish omitted values from explicit zero overrides.
|
||||
`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 first enforces transport limits, strict JSON decoding, and the
|
||||
minimal request shape. It maps DTO values to public types without deciding
|
||||
prompt selection, source behavior, or validation semantics. On success it maps
|
||||
the public result to the response DTO; on failure it uses `errors.Is` over
|
||||
public framework errors and HTTP-local artifact-policy errors to choose the
|
||||
public error mapping.
|
||||
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.
|
||||
|
||||
The [HTTP API reference](../api.md) owns the route, DTO schema, status codes,
|
||||
and externally observable limit behavior.
|
||||
|
||||
### Public Go Facade
|
||||
|
||||
`NewEngine` applies public options, selects filesystem, `fs.FS`, single-file,
|
||||
or in-memory dependencies, and constructs a runner. The conversion functions
|
||||
copy maps and slices across the boundary so callers do not receive internal
|
||||
domain values. The facade maps selected internal errors to the public sentinel
|
||||
set and keeps direct request API keys out of public results.
|
||||
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 do not embed framework orchestration or source-loading decisions.
|
||||
- Configuration is resolved before adapter dependency composition.
|
||||
- CLI and HTTP consume the public engine without a repairer; a repairer remains
|
||||
available only through explicit internal runner construction.
|
||||
- DTO conversion preserves explicit numeric-override presence.
|
||||
- Error mapping matches error identities, not error text.
|
||||
- No adapter creates durable run state; caller-selected output files are not
|
||||
application state.
|
||||
- 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.
|
||||
|
||||
## Failure And Verification Boundaries
|
||||
## Verification
|
||||
|
||||
Keep external error payloads concise, preserve strict external decoding, and do
|
||||
not serialize resolved secret values. Validation content failures remain result
|
||||
state; runtime failures remain errors for the relevant adapter to map.
|
||||
|
||||
Inspect focused tests when changing this area:
|
||||
Inspect:
|
||||
|
||||
- `internal/adapter/cli/run_test.go`
|
||||
- `internal/adapter/http/handler_test.go`
|
||||
- `engine_test.go`
|
||||
- `internal/adapter/http/artifact_reader_test.go`
|
||||
- `internal/format/prepared_run_test.go`
|
||||
- `internal/adapter/dependency_test.go`
|
||||
|
||||
Run the affected adapter package tests and recheck the relevant canonical
|
||||
contract. The [testing policy](../policy/testing.md) owns global test
|
||||
sufficiency guidance.
|
||||
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
|
||||
|
||||
### Application Configuration Fields
|
||||
For a CLI or HTTP change:
|
||||
|
||||
1. Add the field to the relevant `internal/config` shape and default handling.
|
||||
2. Parse and validate it, then preserve configuration and CLI-override
|
||||
precedence while wiring it through its consuming adapter.
|
||||
3. Add focused configuration and adapter tests for parsing, mapping, and
|
||||
effective behavior.
|
||||
4. Update the [configuration contract](../config.md) and any affected external
|
||||
contract.
|
||||
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.
|
||||
|
||||
### CLI Flags
|
||||
|
||||
1. Add the flag to the relevant parser in `internal/adapter/cli/run.go`.
|
||||
2. Keep command scope and application-configuration precedence intentional.
|
||||
3. Add or update parser and command tests in
|
||||
`internal/adapter/cli/run_test.go`.
|
||||
4. Update the [CLI contract](../cli.md) and affected maintained examples.
|
||||
|
||||
### Adapter Capabilities
|
||||
|
||||
1. Define or reuse an adapter-local consumer interface with public facade
|
||||
types when a test seam is needed.
|
||||
2. Implement translation and IO behavior without moving framework decisions out
|
||||
of the public engine.
|
||||
3. Add focused mapping, parsing, and error-behavior tests.
|
||||
4. Update this document and the affected public or integration contract. Update
|
||||
[source internals](sources.md) when source-loading behavior changes.
|
||||
Update [source internals](sources.md) when application source locations or HTTP
|
||||
artifact containment changes.
|
||||
|
||||
Reference in New Issue
Block a user