63 lines
3.3 KiB
Go
63 lines
3.3 KiB
Go
// Package promptkit provides an embeddable engine for preparing and executing
|
|
// prompt-defined LLM workflows.
|
|
//
|
|
// Applications construct an [Engine] with [NewEngine], select filesystem or
|
|
// in-memory sources and optional engine-scoped [Backend] registrations, and
|
|
// call [Engine.InspectProfile], [Engine.Prepare], [Engine.PrepareExecution],
|
|
// [Engine.Run], or [Engine.RunPrepared]. Concrete registries, repositories,
|
|
// validators, and the built-in OpenAI-compatible client remain internal
|
|
// implementation details.
|
|
//
|
|
// # Concurrency and ownership
|
|
//
|
|
// An Engine supports concurrent InspectProfile, Prepare, PrepareExecution, Run,
|
|
// and RunPrepared calls. Engine-local backend policies bound admitted Run and
|
|
// RunPrepared calls and model generations where configured, while different
|
|
// backend pools and unlimited backends continue independently. An injected
|
|
// [LLMClient] or [ArtifactReader] can therefore still receive concurrent calls
|
|
// and must be safe for that use.
|
|
//
|
|
// NewEngine copies in-memory profiles and backend definitions. Prepare,
|
|
// PrepareExecution, and Run copy request maps, slices, pointer values, and
|
|
// JSON-compatible extra parameters before using them. InspectProfile returns
|
|
// copied profile inspection values. Returned values and values passed to
|
|
// extension interfaces are likewise isolated from engine state. Callers own
|
|
// those copies and may mutate them after the call that supplied or returned
|
|
// them.
|
|
//
|
|
// # Security and sensitive data
|
|
//
|
|
// The default artifact reader treats [File] paths as caller-selected operating
|
|
// system paths. It does not restrict them to an application root or impose an
|
|
// inbound request-size policy. Promptkit is not an inbound request or
|
|
// untrusted-input security boundary. Applications must validate and restrict
|
|
// untrusted input before constructing a request, or install an [ArtifactReader]
|
|
// that enforces their filesystem, authorization, and size policies.
|
|
//
|
|
// Rendered messages, input and output [Artifact] bodies, [RunResult.RawOutput],
|
|
// and [ValidationResult.Errors] may contain sensitive data. Credential
|
|
// exclusion and redaction do not sanitize those values. Applications and
|
|
// injected collaborators are responsible for access control, retention,
|
|
// logging, and secret handling appropriate to their data.
|
|
//
|
|
// # JSON
|
|
//
|
|
// Stable JSON representations are provided for [PreparedRun], [RunResult],
|
|
// [Artifact], [ExecutionTarget], [OutputContract], [ValidationResult],
|
|
// [TokenUsage], [RenderedPrompt], [RenderedMessage], [CacheControl],
|
|
// [StructuredOutputSpec], [StructuredOutputJSONSpec], [GenerateRequest],
|
|
// [GenerateResponse], [ExecutionTargetPresence], and the string value types
|
|
// used by those values.
|
|
//
|
|
// Construction, inspection, and handle values, including [Config], [Backend],
|
|
// [RunRequest], [ArtifactRef], [ExecutionTargetOverride], [Profile],
|
|
// [OpenAICompatibleProfileConfig], [ProfileInspection], and
|
|
// [PreparedExecution], do not have stable JSON representations. Direct API
|
|
// keys are nevertheless excluded from JSON for every public value.
|
|
//
|
|
// JSON timestamps use time.Time's RFC 3339 encoding and are omitted when zero.
|
|
// PreparedRun and RunResult durations are encoded as integer milliseconds in
|
|
// duration_ms and omitted when zero. Run IDs and all exposed hashes are opaque:
|
|
// their spelling, length, character set, and algorithm are not API contracts.
|
|
package promptkit
|