Align PromptKit architecture documentation

This commit is contained in:
2026-10-04 13:11:48 +00:00
parent b913ef0d07
commit beaaea2f1a
8 changed files with 104 additions and 55 deletions

View File

@@ -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