104 lines
5.2 KiB
Markdown
104 lines
5.2 KiB
Markdown
# Internal Sources And Validation
|
|
|
|
## Purpose
|
|
|
|
This document describes Promptkit's implemented internal source, artifact,
|
|
rendering, and output-validation behavior. The
|
|
[architecture policy](../policy/architecture.md) owns the library boundary and
|
|
dependency rules. None of these internal packages is a supported consumer API,
|
|
and the root engine assembles them behind its public source options and values.
|
|
The [framework format reference](../formats.md) owns the exact file fields,
|
|
validation modes, built-in catalog, and source precedence.
|
|
|
|
## Prompt Definitions
|
|
|
|
`internal/promptdef` discovers YAML deterministically, decodes and validates
|
|
definitions, selects an ID and optional version, and resolves file-backed
|
|
message content within the selected operating-system or `fs.FS` source.
|
|
|
|
Exact prompt inspection performs one point-in-time lookup through that same
|
|
repository and validates referenced message content before returning declared
|
|
metadata. It does not parse templates or read profile, input, or schema
|
|
sources, and it does not retain the definition for a later execution.
|
|
|
|
Its package tests own prompt selection, strict decoding, definition validation,
|
|
duplicate detection, and source containment:
|
|
[prompt-definition repository tests](../../internal/promptdef/repository_test.go).
|
|
|
|
## Profiles And Built-Ins
|
|
|
|
`internal/profile` loads and validates execution profiles from an
|
|
operating-system filesystem or an `fs.FS`. Its overlay repository consults the
|
|
next repository only when the higher-precedence repository reports that a
|
|
profile is absent. Strict YAML decoding recognizes the optional `backend`
|
|
field, trims its value, and requires a model plus at least one non-blank
|
|
backend or endpoint. Loading does not check registry membership because the
|
|
available registry belongs to the assembled engine; the runner checks
|
|
membership during preparation and exact profile inspection.
|
|
|
|
The root engine assembles profile repositories in precedence order: in-memory
|
|
profiles, one ordinary configured source, then the embedded built-in catalog.
|
|
An explicit file or `fs.FS` profile source replaces `Config.ProfileDir` within
|
|
the ordinary configured-source category.
|
|
|
|
Exact profile inspection performs one point-in-time lookup through those
|
|
profile sources and checks the resolved target without reading prompt, input,
|
|
or schema sources. It does not retain that lookup for a later execution.
|
|
|
|
`internal/profile/builtin` embeds the maintained built-in profile catalog.
|
|
Every embedded profile selects `openrouter` and inherits its endpoint and
|
|
credential environment-variable name from the built-in backend registry rather
|
|
than repeating those values. Profile loading and overlay behavior are owned by
|
|
the [profile repository tests](../../internal/profile/repository_test.go),
|
|
while catalog completeness, the backend-selection invariant, and duplicate IDs
|
|
are owned by the
|
|
[built-in repository tests](../../internal/profile/builtin/repository_test.go).
|
|
|
|
## Ordinary Artifacts
|
|
|
|
`internal/artifact` resolves inline references and unrestricted,
|
|
caller-selected file paths. It copies content into an artifact, records
|
|
metadata and a content hash, applies a content-type fallback, and honors
|
|
context cancellation.
|
|
|
|
This ordinary reader does not implement an inbound HTTP security boundary. In
|
|
particular, it does not constrain files to an application root or impose an
|
|
HTTP request-size policy. Scriptorium's restricted HTTP reader remains an
|
|
application concern outside Promptkit. The
|
|
[artifact reader tests](../../internal/artifact/reader_test.go) own the
|
|
implemented reader behavior and failures.
|
|
|
|
## Rendering
|
|
|
|
`internal/prompt` renders definition messages as Go templates using named
|
|
artifacts and variables. It carries message roles, session IDs, and cache
|
|
control into the rendered prompt. The
|
|
[renderer tests](../../internal/prompt/renderer_test.go) own rendering behavior.
|
|
|
|
## Schemas And Output Validation
|
|
|
|
`internal/validate` provides validators backed by an operating-system
|
|
filesystem or an `fs.FS`. Invalid generated content is returned as a validation
|
|
result; inability to load, register, or compile a schema is an operational
|
|
error.
|
|
|
|
For executable preparation, the built-in validators create a frozen validation
|
|
plan. None, basic, and JSON modes retain the effective output contract without
|
|
source access. JSON Schema mode loads the root document, resolves and compiles
|
|
every transitive reference during preparation, and retains the compiled
|
|
validator. The provider-facing structured-output metadata uses that same
|
|
captured root document.
|
|
|
|
`PrepareExecution` also completes prompt and profile selection, artifact
|
|
loading and hashing, session and message rendering, and target resolution.
|
|
`RunPrepared` uses the retained source-derived state and validation plan; it
|
|
does not reopen prompt, profile, input, or schema sources and does not rerender
|
|
the request. By contrast, ordinary `Prepare` produces a preparation value only:
|
|
a later `Run` performs its own source resolution and preparation.
|
|
|
|
The [validator tests](../../internal/validate/standard_validator_test.go) own
|
|
basic, JSON, JSON Schema, source resolution, schema loading, compilation,
|
|
frozen-reference behavior, and content-failure behavior. Prepared execution
|
|
orchestration is owned by the
|
|
[use-case tests](../../internal/usecase/prepared_execution_test.go).
|