Document PromptKit configuration ownership and capture
This commit is contained in:
@@ -83,35 +83,38 @@ retain an empty backend ID, which the published JSON omits. Successful
|
||||
completion responses and recorded profile manifests identify the adapter
|
||||
provider as `promptkit`.
|
||||
|
||||
The CLI's profile-inspection engine and the production adapter use the same
|
||||
profile-source construction to apply the configured profile directory or file,
|
||||
the optional registered fallback profile assets, and the optional conventional
|
||||
`local` backend. Preflight therefore resolves the same profile sources and
|
||||
backend membership as runtime without performing generation. Fallback assets
|
||||
are mounted only when at least one source is registered. The production D&D
|
||||
registrar contributes its `dnd-extraction` fallback, and the maintained D&D
|
||||
prompts select that logical ID by default. PromptKit owns source precedence and
|
||||
profile parsing and inheritance: an operator-provided matching profile takes precedence over a
|
||||
fallback profile without Notarius merging either document.
|
||||
When the registration is absent, a profile selecting `backend: local` fails
|
||||
inspection instead of falling back to a built-in or endpoint-only target.
|
||||
The CLI's profile-inspection engine and production adapter use the same source
|
||||
assembly: PromptKit catalogs, one application group containing registered
|
||||
prompts and fallback profiles, the selected operator file or directory, and
|
||||
the optional final `local` backend registration. Execution, preflight, and
|
||||
inspection therefore capture the same effective definitions. PromptKit and
|
||||
ConfigKit compose recursively across groups while retaining each input's file
|
||||
context; inputs within a group compose strictly. Operator imports are enabled
|
||||
for the selected operator input, and imports retain their declaring file's
|
||||
relative resource roots. PromptKit validates final effective definitions at
|
||||
engine construction. It does not run a separate audit that rejects a malformed
|
||||
definition superseded by a later overlay. The D&D registrar contributes its
|
||||
`dnd-extraction` fallback, and maintained D&D prompts select that logical ID
|
||||
by default. A profile selecting `backend: local` requires the optional local
|
||||
registration.
|
||||
|
||||
Before execution, the adapter also contributes a non-secret checkpoint
|
||||
fingerprint for the effective PromptKit profile source. It combines the
|
||||
identity of PromptKit's compiled-in profile catalog with a deterministic digest
|
||||
of every YAML profile in the configured profile directory, or of the configured
|
||||
profile file, and a deterministic digest of the flattened fallback profile
|
||||
assets. The fingerprint contains neither profile content nor source paths. It
|
||||
covers inherited pipeline profiles, explicit binding profiles, and
|
||||
prompt-selected defaults, so changing a model or other profile setting cannot
|
||||
reuse checkpoints created under the
|
||||
prior profile source. This cache identity is independent of durable
|
||||
profile provenance: run manifests continue to list only profiles actually
|
||||
observed during LLM calls. When the local backend is registered, a second
|
||||
fingerprint hashes its trimmed endpoint behind a stable marker. Changing that
|
||||
semantic execution target invalidates checkpoint reuse. The raw endpoint is not
|
||||
stored in checkpoint identity, and the local concurrency limit is excluded
|
||||
because it changes scheduling rather than execution semantics.
|
||||
Each engine captures its definitions at construction. A later source-file edit
|
||||
does not mutate an existing engine; constructing a new engine captures the
|
||||
updated view. Before execution, the adapter computes one immutable,
|
||||
versioned `promptkit_configuration` checkpoint identity from public captured
|
||||
inspection APIs. The private digest covers captured effective configuration,
|
||||
all effective profile targets and credential-policy metadata (including
|
||||
provider parameters), and every effective prompt ID/version and captured
|
||||
content hash. The identity also includes PromptKit and the selected OpenRouter
|
||||
and Rakestrawhome catalog versions. Local-backend concurrency settings remain
|
||||
excluded because they affect scheduling; its endpoint is represented only in
|
||||
the private digest, never as checkpoint metadata. Neither the private digest
|
||||
payload, raw sources, paths, endpoints, provider parameters, nor prompt bodies
|
||||
are published. An existing engine retains its identity after files change; a
|
||||
new engine gets the identity of its newly captured definitions. This replaces
|
||||
the former live-file profile and local-endpoint fingerprints. Run manifests
|
||||
remain independent and list only profile choices actually observed during LLM
|
||||
calls.
|
||||
|
||||
## Shared Provider-Call Limit
|
||||
|
||||
@@ -140,11 +143,16 @@ only by the Notarius scheduler.
|
||||
## Prompt And Schema Assets
|
||||
|
||||
An `AssetRegistry` collects prompt, schema, and optional fallback-profile
|
||||
filesystems from production module families. It flattens registered roots into
|
||||
the corresponding PromptKit filesystems and rejects invalid roots, unreadable
|
||||
assets, duplicate paths, and missing prompt or schema files during preparation.
|
||||
Fallback assets receive a safe content digest for checkpoint identity; raw
|
||||
paths and bytes are never included. The framework’s `promptfs` helper combines
|
||||
filesystems from production module families. It retains each registered root's
|
||||
filesystem context when constructing PromptKit's application source group.
|
||||
Schema files are supplied separately through the engine's schema filesystem;
|
||||
PromptKit reads and validates a selected schema while preparing that request,
|
||||
not while constructing the configuration snapshot. Prompt and fallback
|
||||
definitions are validated after native source composition, and referenced
|
||||
prompt content is captured with the engine. Checkpoint identity uses captured
|
||||
prompt content hashes rather than rescanning live files or hashing only
|
||||
content-file paths. Raw paths and bytes are never included. The framework’s
|
||||
`promptfs` helper combines
|
||||
module-selected prompt files with reusable domain fragments without making the
|
||||
framework depend on D&D content.
|
||||
|
||||
@@ -294,6 +302,10 @@ When debug recording is enabled, the pipeline decorates the shared client. The
|
||||
wrapper records prepared prompt and response material, timing, selected profile
|
||||
and backend, effective model parameters, and call identifiers in the run’s
|
||||
debug bundle, including material available from a failed structured completion.
|
||||
The profile-inspection CLI projects copied values into its Notarius-owned
|
||||
neutral JSON DTO; effective configuration and explanation remain PromptKit's
|
||||
redacted YAML and source-history views. Credential names and `APIKeyRequired`
|
||||
metadata are configuration metadata, not credential-availability checks.
|
||||
Effective parameters use PromptKit's stable lower-case JSON field names and may
|
||||
include `backend_id`. For a successful completion, a debug-write failure is
|
||||
surfaced; when the completion already failed, its call error remains the
|
||||
|
||||
Reference in New Issue
Block a user