68 lines
3.1 KiB
Markdown
68 lines
3.1 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.
|
|
|
|
## Prompt Definitions
|
|
|
|
`internal/promptdef` loads prompt definitions from an operating-system
|
|
filesystem or an `fs.FS`. It discovers YAML deterministically, decodes fields
|
|
strictly, validates definitions, selects an ID and optional version, and
|
|
resolves file-backed message content within the selected source.
|
|
|
|
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 strictly decoded execution profiles from an
|
|
operating-system filesystem or an `fs.FS`. It validates required profile data,
|
|
rejects raw API keys, and supports a primary repository with fallback only
|
|
when the primary reports that a profile is absent.
|
|
|
|
`internal/profile/builtin` embeds the maintained built-in profile catalog and
|
|
can place a caller-selected repository ahead of that catalog. Profile behavior
|
|
is owned by the
|
|
[profile repository tests](../../internal/profile/repository_test.go), while
|
|
catalog completeness, duplicate IDs, and overlay behavior 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`. Validation can be skipped, require non-empty output,
|
|
require JSON, or apply a JSON Schema loaded with the source's path semantics.
|
|
Invalid generated content is returned as a validation result; inability to
|
|
load, register, or compile a schema is an operational error.
|
|
|
|
The [validator tests](../../internal/validate/standard_validator_test.go) own
|
|
basic, JSON, JSON Schema, source resolution, schema loading, compilation, and
|
|
content-failure behavior.
|