Align PromptKit architecture documentation
This commit is contained in:
@@ -9,7 +9,7 @@ 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.11.2/docs/consumers/pkg-promptkit.md).
|
||||
[Go consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md).
|
||||
|
||||
## Components And Collaborators
|
||||
|
||||
@@ -17,11 +17,13 @@ described by its tagged
|
||||
`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.
|
||||
exposes application and captured framework configuration inspection, and
|
||||
owns output files, summaries, and exit codes.
|
||||
- `internal/config` delegates application YAML decoding, default resolution,
|
||||
overrides, and validation ordering to ConfigKit. The CLI supplies only
|
||||
explicitly visited application flags as overrides and renders safe structured
|
||||
load diagnostics on stderr.
|
||||
load diagnostics on stderr. Promptkit uses ConfigKit to load framework
|
||||
sources under its own definition and format contract.
|
||||
- `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.
|
||||
@@ -53,6 +55,15 @@ preparation or generation.
|
||||
formats a safe application-owned effective profile view. It intentionally does
|
||||
not require prompt, schema, or artifact sources.
|
||||
|
||||
`inspect configuration` builds the same engine from the selected native
|
||||
Promptkit source sequence, reads its captured configuration view, and delegates
|
||||
effective output and explanation to Promptkit's native writers. The adapter
|
||||
projects captured source records into its small JSON DTO. Its validation
|
||||
operation constructs the engine without preparing a request. Framework source
|
||||
semantics and report redaction are owned by Promptkit; the [CLI
|
||||
contract](../cli.md#framework-configuration-inspection) documents the exposed
|
||||
operations and their deliberately limited redaction scope.
|
||||
|
||||
The `config` family loads the same application ConfigKit result once and uses
|
||||
its validation, effective-output, source, and explanation views directly. It
|
||||
does not construct a Promptkit engine. The CLI maps source records into a small
|
||||
@@ -62,11 +73,14 @@ JSON DTO for `sources`; `show` and `explain` use ConfigKit's own writers.
|
||||
with `promptkit.WithArtifactReader`, passes the engine through the HTTP
|
||||
adapter's consumer-owned `Runner` interface, and starts the server.
|
||||
|
||||
The command paths assemble the engine from the same resolved prompt, profile,
|
||||
and schema directories plus configured custom backends. Each backend is mapped
|
||||
to Promptkit's public `Backend` value and registered during engine construction,
|
||||
so one constructed server engine retains one immutable backend registry and its
|
||||
associated capacity state.
|
||||
The command paths assemble the engine from application-selected framework
|
||||
source files and directories plus the schema directory and retry setting.
|
||||
Individual files become import-enabled ConfigKit inputs; directory selections
|
||||
are expanded through Promptkit's directory-input helper. Scriptorium supplies
|
||||
those ordered underlays through Promptkit's public configuration API rather
|
||||
than parsing or mapping framework definitions itself. The server constructs
|
||||
one engine, which retains the framework's backend registry and associated
|
||||
capacity state across requests.
|
||||
|
||||
### HTTP
|
||||
|
||||
|
||||
@@ -7,13 +7,13 @@ public behavior belongs in the linked contracts.
|
||||
| Component | Implemented responsibility | References |
|
||||
| --- | --- | --- |
|
||||
| `cmd/scriptorium` | Process entrypoint that delegates arguments and streams to the CLI adapter. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/adapter/cli` | Parses execution and application-configuration inspection commands, resolves settings, constructs Promptkit engines only for execution/definition inspection, maps requests, and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/adapter/cli` | Parses execution, application-configuration, and captured framework-configuration inspection commands; resolves settings; constructs Promptkit engines for execution, definition inspection, and framework inspection; maps requests; and owns process output and exit behavior. | [CLI contract](../cli.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
||||
| `internal/adapter/http` | Owns routes, DTOs, strict decoding, limits, Promptkit request/result mapping, public error mapping, and restricted HTTP artifact reading. | [HTTP API](../api.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
||||
| `internal/config` | Selects application sources, supplies the ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md) |
|
||||
| `internal/config` | Selects application sources, supplies the application ConfigKit definition and explicit overrides, and converts resolved settings for runtime use. | [configuration contract](../config.md), [adapter internals](adapters.md), [source internals](sources.md) |
|
||||
| `internal/defaults` | Holds Scriptorium-owned application and HTTP defaults. | [configuration contract](../config.md) |
|
||||
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/format` | Formats Promptkit prepared-run and prompt/profile inspection values for CLI text or JSON output; framework-configuration output uses Promptkit's native captured view and writers. | [CLI contract](../cli.md), [adapter internals](adapters.md) |
|
||||
| `internal/report` | Projects one terminal Promptkit observation into Scriptorium-owned execution metadata. | [adapter internals](adapters.md) |
|
||||
|
||||
Framework implementation packages are provided by
|
||||
[Promptkit v0.11.2](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/consumers/pkg-promptkit.md)
|
||||
[Promptkit v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
|
||||
and are not part of this repository.
|
||||
|
||||
@@ -5,20 +5,24 @@
|
||||
This document covers Scriptorium-owned source locations and the restricted HTTP
|
||||
artifact reader. Prompt, profile, schema, and ordinary artifact semantics are
|
||||
owned by the tagged
|
||||
[Promptkit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.2/docs/formats.md).
|
||||
[Promptkit v0.12.0 format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
|
||||
|
||||
## Application Source Locations
|
||||
|
||||
`internal/config` resolves `prompt_dir`, `profile_dir`, and `schema_dir` from
|
||||
Scriptorium defaults, configuration files, and CLI overrides. It also resolves
|
||||
the application-owned `backends` mapping into sorted engine settings.
|
||||
`internal/adapter/cli` passes the directories into `promptkit.Config` and maps
|
||||
each configured backend to Promptkit's public engine registration when
|
||||
constructing an engine shared by the command path.
|
||||
`internal/config` resolves the ordered `promptkit_sources` sequence and
|
||||
`schema_dir` from application configuration and explicit CLI overrides. It
|
||||
owns selector-shape validation, not framework file parsing. During engine
|
||||
construction, `internal/adapter/cli` turns file selections into import-enabled
|
||||
ConfigKit inputs and expands directory selections with
|
||||
`promptkit.DirectoryInputs`, then passes the ordered groups as Promptkit
|
||||
configuration underlays. The shared Promptkit engine receives the selected
|
||||
schema directory and retry setting as well.
|
||||
|
||||
Scriptorium does not search, parse, validate, or overlay framework source files
|
||||
itself. Promptkit owns prompt selection, profile built-ins and overlays, schema
|
||||
resolution, ordinary file artifacts, and the related error identities.
|
||||
Promptkit uses ConfigKit to load and compose those framework inputs according
|
||||
to Promptkit's own schema and format. Scriptorium does not parse or validate
|
||||
Promptkit definitions. Promptkit owns definition selection and validation,
|
||||
profile built-ins and overlays, schema resolution, ordinary file artifacts,
|
||||
captured framework configuration inspection, and related error identities.
|
||||
|
||||
The [configuration reference](../config.md) owns Scriptorium's source-location
|
||||
fields and precedence. Maintained files under `examples/` are application
|
||||
@@ -26,13 +30,15 @@ inputs that use Promptkit's tagged formats.
|
||||
|
||||
## Application Configuration Boundary
|
||||
|
||||
`internal/config` contains a ConfigKit-native `Document` definition. Its
|
||||
fresh defaults come from Scriptorium's existing default constants; its resolver
|
||||
records only actual trimming, path cleaning, and render-format normalization.
|
||||
The validator reports application retry, size-limit, and format errors without
|
||||
mutating the document or exposing rejected values. Application path values keep
|
||||
working-directory-relative meaning. ConfigKit owns strict YAML decoding and
|
||||
presence semantics, including dynamic integer values in backend parameters.
|
||||
`internal/config` contains the application-owned ConfigKit-native `Document`
|
||||
definition. Its fresh defaults come from Scriptorium's existing default
|
||||
constants; its resolver records only actual trimming, path cleaning, and
|
||||
render-format normalization. The validator reports selector-shape, retry,
|
||||
size-limit, and format errors without mutating the document or exposing
|
||||
rejected values. Application path values keep working-directory-relative
|
||||
meaning. ConfigKit owns strict application YAML decoding and presence
|
||||
semantics. Framework configuration is separately loaded by Promptkit through
|
||||
ConfigKit under Promptkit's own schema and source contract.
|
||||
|
||||
The `Load` boundary selects an explicit file, the first existing implicit
|
||||
configuration file, or ConfigKit's defaults-only source. Only absence advances
|
||||
@@ -45,11 +51,10 @@ select one named overlay when requested. ConfigKit uses the selected file's
|
||||
canonical directory as the source root; the application does not widen it.
|
||||
Application path values retain process-working-directory-relative meaning.
|
||||
|
||||
ConfigKit resolves effective sibling inheritance after source assembly and
|
||||
overrides, before typed decoding. Runtime conversion and Promptkit registration
|
||||
consume those resolved values through the existing `Settings` path. The
|
||||
[configuration reference](../config.md#application-mapping-inheritance) owns
|
||||
the application-visible inheritance behavior.
|
||||
Runtime conversion consumes the resolved application values through the
|
||||
existing `Settings` path. Promptkit receives selected framework sources only
|
||||
after application configuration has loaded and validated; its source merge,
|
||||
definition validation, and captured inspection view remain framework-owned.
|
||||
|
||||
Every configuration-loading command uses this boundary. The CLI maps only
|
||||
explicitly visited application flags to ConfigKit overrides and prints
|
||||
@@ -57,8 +62,11 @@ structured load diagnostics before engine construction. The old application
|
||||
YAML decoder and merge path have been removed.
|
||||
Application `config` inspection reuses the result's frozen effective,
|
||||
provenance, and history views without constructing an engine or reloading
|
||||
sources. It does not resolve API-key environment values; ordinary backend
|
||||
parameters remain visible by the selected inspection policy.
|
||||
sources. It does not resolve credentials. `inspect configuration` separately
|
||||
constructs an engine and exposes Promptkit's captured framework view; only its
|
||||
framework `show` and `explain` reports receive Promptkit's native,
|
||||
credential-shaped redaction. Neither inspection family is a general-purpose
|
||||
filter for arbitrary sensitive values.
|
||||
|
||||
## Restricted HTTP Artifact Reader
|
||||
|
||||
|
||||
Reference in New Issue
Block a user