promptkit

package module
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 25, 2026 License: GPL-3.0 Imports: 25 Imported by: 0

README

Promptkit

Promptkit is a reusable Go library for preparing and executing prompt-defined LLM workflows. Its module path is:

gitea.maximumdirect.net/eric/promptkit

The root promptkit package provides the supported public engine. Consumers can configure filesystem or in-memory prompt, profile, and schema sources, prepare requests without generation, run requests with the built-in OpenAI-compatible client, or inject their own model client and artifact reader.

Quickstart

Run the maintained offline preparation example from the repository root:

go run ./examples/go-library/prepare

It loads a repository-local prompt, supplies an in-memory profile and inline input, and prints deterministic preparation metadata without contacting a provider or requiring credentials. Read the example source, the Go package consumer guide, and the framework format reference to build a consumer workflow.

Contributors should start with the development guide. The architecture policy defines the library boundary and constraints that framework work must preserve.

Release Guidance

Consumers upgrading from v0.7.0 to v0.8.0 should read the v0.8.0 changelog and migration guide.

Earlier adopters can consult the v0.7.0 changelog and migration guide.

Consumers upgrading from v0.5.0 to v0.6.0 can consult the v0.6.0 changelog and migration guide.

Consumers upgrading from v0.4.0 to v0.5.0 can consult the v0.5.0 changelog and migration guide.

Consumers upgrading from v0.3.0 to v0.4.0 should read the v0.4.0 changelog and adoption guide.

Consumers upgrading from v0.2.0 to v0.3.0 should read the v0.3.0 changelog.

Consumers moving from v0.1.0 to v0.2.0 should read the v0.2.0 changelog and migration guide.

Scriptorium is the CLI and HTTP application built on Promptkit.

Promptkit is licensed under the GNU General Public License version 3.

Documentation

Overview

Provider-derived GenerationError accessor values are untrusted and can contain sensitive request or schema fragments. Applications must apply their own disclosure policy before logging, displaying, or returning them.

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.

Index

Constants

View Source 
const BackendLocal = "local"

BackendLocal is the case-sensitive conventional ID used by LocalBackend. It is not a built-in or reserved backend and must be registered with WithBackend.

View Source 
const BackendOpenRouter = backend.OpenRouterID

BackendOpenRouter is the reserved ID of Promptkit's built-in OpenRouter backend.

View Source 
const BackendRakestrawHome = backend.RakestrawHomeID

BackendRakestrawHome is the reserved ID of Promptkit's built-in Rakestrawhome backend.

Variables

View Source 
var (
	// ErrInvalidRequest identifies a request whose required values, overrides,
	// credentials, or effective settings are invalid.
	ErrInvalidRequest = errors.New("invalid run request")
	// ErrPromptNotFound identifies a requested prompt ID or version that is not
	// present in the selected prompt source. It does not also match
	// ErrPromptLoad.
	ErrPromptNotFound = errors.New("prompt not found")
	// ErrProfileNotFound identifies a selected profile ID that is absent from
	// every configured profile source. It does not also match ErrProfileLoad.
	ErrProfileNotFound = errors.New("profile not found")
	// ErrProfileRequired identifies a request for which neither RunRequest.ProfileID
	// nor the selected prompt's default profile is present. Such an error also
	// matches ErrInvalidRequest.
	ErrProfileRequired = errors.New("profile selection is required")
	// ErrPromptLoad identifies a failure to read, decode, validate, select, or
	// hash a prompt definition, except for the not-found case represented by
	// ErrPromptNotFound.
	ErrPromptLoad = errors.New("failed to load prompt definition")
	// ErrProfileLoad identifies a failure to read, decode, validate, or select
	// an execution profile or resolve its backend, except for the profile
	// not-found case represented by ErrProfileNotFound.
	ErrProfileLoad = errors.New("failed to load execution profile")
	// ErrAPIKeyEnvMissing identifies an explicitly required APIKeyEnv whose
	// environment variable is unset or empty after direct RunRequest.APIKey
	// precedence is applied. Such an error also matches ErrInvalidRequest.
	ErrAPIKeyEnvMissing = errors.New("api_key_env points to an unset environment variable")
	// ErrArtifactLoad identifies a failure to resolve an input artifact. Errors
	// returned by an injected ArtifactReader remain available through errors.Is.
	ErrArtifactLoad = errors.New("failed to load artifact")
	// ErrPromptRender identifies a failure to render prompt messages or the
	// session ID from the resolved inputs and variables.
	ErrPromptRender = errors.New("failed to render prompt")
	// ErrCapacityExceeded identifies a Run or RunPrepared rejected because the
	// selected backend already admitted ConcurrencyLimit + QueueCapacity calls.
	// A [CapacityError] reports the selected backend ID. It is not an invalid
	// request, an LLM or provider rate-limit response, or ErrLLMGenerate.
	ErrCapacityExceeded = errors.New("backend capacity exceeded")
	// ErrLLMGenerate identifies a model-client failure or a nil successful
	// response. A built-in OpenAI-compatible non-2xx response is available as a
	// [GenerationError]. Errors returned by an injected LLMClient remain
	// available through errors.Is.
	ErrLLMGenerate = errors.New("failed to generate output")
	// ErrValidation identifies an operational failure to load or compile a
	// schema or validate output. A completed validation whose Status is
	// ValidationFailed is returned in RunResult without this error.
	ErrValidation = errors.New("failed to validate output")
)
View Source 
var ErrInvalidConfig = errors.New("invalid engine configuration")

ErrInvalidConfig identifies invalid engine construction, including missing required configuration, invalid options or backend registrations, and a nil Engine receiver.

Functions

This section is empty.

Types

type Artifact 

type Artifact struct {
	// Name is artifact metadata. During input preparation the engine fills an
	// empty reader-supplied name with the request input-map key.
	Name string `json:"name"`
	// ContentType is the media type reported by the reader or derived for
	// generated output.
	ContentType string `json:"content_type"`
	// Body is the artifact content. Engine boundaries copy this slice.
	Body []byte `json:"body"`
	// URI is optional source or result provenance metadata.
	URI string `json:"uri"`
	// Size is content-size metadata in bytes.
	Size int64 `json:"size"`
	// Hash is an opaque content equality value when the producing reader
	// supplies one. Its format and algorithm are not API contracts.
	Hash string `json:"hash"`
}

Artifact represents loaded or generated content and has a stable JSON representation. Body uses encoding/json's base64 representation for []byte.

type ArtifactReader 

type ArtifactReader interface {
	Read(context.Context, ArtifactRef) (*Artifact, error)
}

ArtifactReader resolves a prompt input reference into its content.

Read may be called concurrently. It must honor ctx cancellation to make Prepare, PrepareExecution, and Run responsive to cancellation. The engine passes a copied ref and immediately copies the returned Artifact.Body; it does not retain either value. Readers supply artifact metadata, and the engine assigns an input-map name only when the returned artifact name is empty.

An injected reader owns any application-specific path containment, authorization, content-size, and content-type policy. It must protect sensitive references and bodies in its logging and in any copies it retains. It may reuse or mutate the returned artifact and body after Read returns.

Returning a non-nil error makes the engine return an error matching ErrArtifactLoad while preserving the reader error through errors.Is. Returning a nil artifact with a nil error also produces ErrArtifactLoad.

type ArtifactRef 

type ArtifactRef struct {
	// Type must be ArtifactRefInline or ArtifactRefFile.
	Type ArtifactRefType
	// URI is the file path for ArtifactRefFile and optional provenance metadata
	// for ArtifactRefInline.
	URI string
	// Body is the content for ArtifactRefInline, where an empty value is valid,
	// and is ignored for ArtifactRefFile.
	Body string
}

ArtifactRef identifies prompt input content. It has no stable JSON representation. Prefer File, Inline, or InlineWithURI to construct one.

func File 

func File(path string) ArtifactRef

File returns a file-backed artifact reference whose URI is path.

The default artifact reader accepts path only when it resolves to a regular operating-system file, checking that condition before and after opening it. It reads synchronously in bounded chunks and checks context cancellation before opening, before and after each read, and before returning the artifact; it cannot interrupt a filesystem operation already in progress. It does not restrict path to an application root or impose a size limit. Applications accepting untrusted paths must validate them before calling Promptkit or use WithArtifactReader to enforce application policy.

func Inline 

func Inline(body string) ArtifactRef

Inline returns an inline artifact reference whose Body is body and whose URI is empty. An empty body is a valid, explicitly supplied input.

func InlineWithURI 

func InlineWithURI(uri string, body string) ArtifactRef

InlineWithURI returns an inline artifact reference with body content and uri provenance metadata. An empty body is a valid, explicitly supplied input.

type ArtifactRefType 

type ArtifactRefType string

ArtifactRefType identifies how an ArtifactRef supplies content. 

const (
	// ArtifactRefInline selects ArtifactRef.Body as the content.
	ArtifactRefInline ArtifactRefType = "inline"
	// ArtifactRefFile selects the filesystem path in ArtifactRef.URI.
	ArtifactRefFile ArtifactRefType = "file"
)

type Backend added in v0.2.0 

type Backend struct {
	// ID is the stable, case-sensitive registry key. NewEngine trims it and
	// requires a non-blank value. Built-in backend IDs are reserved.
	ID string
	// Endpoint is the OpenAI-compatible base endpoint. NewEngine trims it and
	// requires an absolute HTTP or HTTPS URL with a host and without user
	// information, a query string, or a fragment. Paths are allowed.
	Endpoint string
	// APIKeyEnv optionally names an environment lookup source for an API key.
	// NewEngine trims it and requires the portable form [A-Za-z_][A-Za-z0-9_]*.
	// A direct RunRequest.APIKey takes precedence. When no usable credential is
	// available, the built-in client omits Authorization; injected clients own
	// their own credential-resolution behavior. Store only the name, never a
	// credential value.
	APIKeyEnv string
	// ExtraParams contains backend-wide request defaults. Values must be
	// JSON-compatible, finite, acyclic, and keyed by non-empty strings. Keys
	// must not be model, session_id, messages, temperature, max_tokens, top_p,
	// service_tier, reasoning_effort, or response_format. An empty map supplies
	// no defaults. NewEngine deeply copies the map and rejects excessively deep
	// or large values for safety.
	ExtraParams map[string]any
	// ConcurrencyLimit is the maximum number of simultaneous model-generation
	// calls allowed for this backend within one Engine. Zero leaves the backend
	// unlimited. A negative value makes NewEngine fail with ErrInvalidConfig.
	ConcurrencyLimit int
	// QueueCapacity controls how many additional Run or RunPrepared calls may
	// be admitted beyond ConcurrencyLimit. Nil uses 1024 when ConcurrencyLimit
	// is positive; a pointer uses its exact value, including zero. The pointed-to
	// value must be non-negative, and QueueCapacity must be nil when
	// ConcurrencyLimit is zero. Their sum must fit in an int. WithBackend copies
	// the value and does not retain the pointer.
	QueueCapacity *int
}

Backend configures one engine-scoped OpenAI-compatible backend.

Backend has no stable JSON representation. Use keyed literals so additions to this configuration value do not break source compatibility.

func LocalBackend added in v0.3.0 

func LocalBackend(endpoint string, concurrencyLimit int) Backend

LocalBackend returns a caller-owned Backend for a conventional local OpenAI-compatible endpoint. It sets ID to BackendLocal and copies endpoint and concurrencyLimit into Endpoint and ConcurrencyLimit without normalization or validation. APIKeyEnv, ExtraParams, and QueueCapacity keep their zero values.

LocalBackend does not read environment variables, register the value, or mutate engine or package state. Supply the returned value through WithBackend; NewEngine then applies the ordinary backend validation and concurrency semantics, including default queue capacity for a positive limit, unlimited behavior for zero, and ErrInvalidConfig for a negative limit.

type CacheControl 

type CacheControl struct {
	// Type identifies the cache behavior.
	Type CacheControlType `json:"type"`
	// TTL is an optional provider cache lifetime.
	TTL string `json:"ttl,omitempty"`
}

CacheControl describes provider cache metadata attached to prompt content and has a stable JSON representation.

type CacheControlType 

type CacheControlType string

CacheControlType identifies provider cache behavior for prompt content. CacheControlType has a stable JSON string representation. 

const (
	// CacheControlEphemeral requests provider-defined ephemeral caching.
	CacheControlEphemeral CacheControlType = "ephemeral"
)

type CapacityError added in v0.4.0 

type CapacityError struct {
	// BackendID is the normalized registered backend ID whose admission was
	// rejected.
	BackendID string
}

CapacityError reports bounded admission rejected for a selected backend.

Engine-produced values identify only rejection at Promptkit's bounded Engine.Run or Engine.RunPrepared admission boundary. BackendID is the normalized registered backend ID used for routing and capacity; endpoint overrides do not change it. Every engine-produced value is nonnil and has a nonblank BackendID. Provider errors, active-generation waiting, and caller cancellation are not represented by this type.

Callers own returned values and may mutate BackendID without affecting engine state or another error. CapacityError and its default Go encoding have no stable JSON contract. Consumer-constructed values do not establish that an engine rejected work.

func (*CapacityError) Error added in v0.4.0 

func (e *CapacityError) Error() string

Error returns diagnostic wording that is not a parsing contract. It is safe to call on a nil receiver or a value with a blank BackendID.

func (*CapacityError) Unwrap added in v0.4.0 

func (e *CapacityError) Unwrap() error

Unwrap returns ErrCapacityExceeded so errors.Is and errors.As can be used together. It is safe to call on a nil receiver or a zero value.

type Config 

type Config struct {
	// PromptDir is the directory searched recursively for prompt definitions.
	// It is required unless a WithPromptFS or WithPromptFile option supplies the
	// prompt source.
	PromptDir string
	// ProfileDir is an optional ordinary configured source whose profiles take
	// precedence over application fallback and embedded built-in profiles. An
	// empty value selects the lower-precedence sources unless a profile-source
	// option supplies the ordinary source.
	ProfileDir string
	// SchemaDir is the root for JSON Schema files. An empty value uses the
	// current directory. WithSchemaFS or WithSchemaFile replaces this source.
	SchemaDir string
	// Timeout is the transport-wide safety cap for the built-in LLM client
	// when HTTPClient is absent or has a non-positive timeout. A zero or negative
	// value selects the 10-minute default.
	Timeout time.Duration
	// HTTPClient is cloned for the built-in LLM client. Its positive Timeout
	// takes precedence over Timeout. A zero or negative client Timeout inherits
	// Timeout or the 10-minute default. The supplied client is not mutated. This
	// field is ignored when WithLLMClient is used.
	HTTPClient *http.Client
}

Config selects the directory-backed sources and built-in model-client transport used by NewEngine. Config has no stable JSON representation.

type Engine 

type Engine struct {
	// contains filtered or unexported fields
}

Engine inspects prompts and profiles and prepares and runs Promptkit prompt requests.

An Engine is safe for concurrent calls to Engine.InspectPrompt, Engine.InspectProfile, Engine.Prepare, Engine.PrepareExecution, Engine.Run, and Engine.RunPrepared. Each Engine owns independent backend-capacity pools that coordinate Run and RunPrepared admission and model generation. Injected collaborators may still be invoked concurrently across different backend pools or for unlimited backends.

func NewEngine 

func NewEngine(cfg Config, opts ...Option) (*Engine, error)

NewEngine constructs an Engine from configuration and options.

Options are applied in order according to Option. PromptDir is required unless a prompt-source option is present. Construction validates option arguments, in-memory profiles, and backend registrations but defers reading and validating prompt, file-backed profile, and schema contents until Prepare or Run needs them.

NewEngine returns an error matching ErrInvalidConfig for invalid configuration, options, or backend-capacity policies. Each constructed Engine has independent backend-capacity pools. Construction does not perform model requests or require credentials.

func (*Engine) InspectProfile added in v0.4.0 

func (e *Engine) InspectProfile(ctx context.Context, profileID string) (*ProfileInspection, error)

InspectProfile resolves one explicit profile without selecting a prompt or starting execution work.

InspectProfile trims surrounding whitespace from profileID and looks up the resulting nonblank ID exactly and case-sensitively through the engine's in-memory, ordinary configured-source, application fallback, and built-in profile precedence. It applies the framework timeout baseline, selected backend, and then selected profile to EffectiveModelParams without a request override. BackendID is empty for an endpoint-only profile.

APIKeyEnv in the returned target is an environment-variable name, never its value. APIKeyRequired instead reports a direct credential requirement and is mutually exclusive with a nonblank APIKeyEnv. InspectProfile neither derives an ID from a prompt default_profile nor checks credential availability, so an absent or blank named environment variable is not an error.

The returned ProfileInspection and all nested mutable values are caller-owned. Filesystem-backed inspection is a point-in-time lookup and does not freeze the profile for a later execution. This method does not load a prompt, render, read artifacts or schemas, admit backend capacity, contact a provider, or generate model output.

A nil Engine returns an error matching ErrInvalidConfig. A blank profile ID matches ErrInvalidRequest. An absent exact ID matches ErrProfileNotFound and not ErrProfileLoad. Malformed or unreadable profile data, an unknown backend, or an invalid resolved target matches ErrProfileLoad. Cancellation during profile loading matches ErrProfileLoad while preserving the context error. InspectProfile returns no partial result on error.

func (*Engine) InspectPrompt added in v0.4.0 

func (e *Engine) InspectPrompt(
	ctx context.Context,
	promptID string,
	promptVersion string,
) (*PromptInspection, error)

InspectPrompt resolves one explicit prompt definition without selecting a profile or starting execution work.

InspectPrompt requires a nonblank promptID. It passes nonblank promptID and promptVersion values unchanged to the engine's ordinary, case-sensitive prompt selection. An empty version succeeds only when that source has one selected ID; a nonempty version selects one exact ID/version pair. The configured prompt source is used without merging, fallback, or enumeration.

A successful result proves that the selected definition and any referenced message content files were structurally loaded. Inputs are returned in definition order. DefaultProfileID is declared metadata only and is not resolved. OutputContract is the normalized declared contract, with a JSON Schema path when declared but without loading or compiling that schema. PromptHash is the same opaque equality value as PreparedRun.PromptHash for the selected definition and observed source state; its spelling, length, encoding, algorithm, and security properties are not contracts.

This method does not return prompt bodies, templates, source paths, schemas, rendered messages, or execution settings. It does not resolve a profile or credential, read artifacts or schemas, render, validate, admit capacity, contact a provider, or generate model output. The returned PromptInspection and its input slice are caller-owned. Filesystem-backed inspection is a point-in-time lookup and does not freeze a definition for later execution.

A nil Engine returns an error matching ErrInvalidConfig. A blank prompt ID matches ErrInvalidRequest. An absent exact ID or version matches ErrPromptNotFound and not ErrPromptLoad. Malformed, unreadable, duplicate, ambiguous, referenced-content, or hashing failures match ErrPromptLoad. Cancellation during lookup matches ErrPromptLoad while preserving the context error. InspectPrompt returns no partial result on error.

func (*Engine) Prepare 

func (e *Engine) Prepare(ctx context.Context, req RunRequest) (*PreparedRun, error)

Prepare resolves and renders a prompt request without calling an LLM.

Prepare selects the prompt and profile, resolves any selected backend and effective execution settings, resolves the output contract, loads and hashes inputs, loads structured-output schema metadata when required, and renders the session ID and messages. The returned PreparedRun is owned by the caller and never contains a resolved API-key value, model output, or validation result.

A nil Engine returns an error matching ErrInvalidConfig. Request and preparation failures may match ErrInvalidRequest, ErrPromptNotFound, ErrPromptLoad, ErrProfileNotFound, ErrProfileLoad, ErrProfileRequired, ErrAPIKeyEnvMissing, ErrArtifactLoad, ErrPromptRender, or ErrValidation as applicable. Cancellation is passed to the active collaborator and is reported in the applicable operation category; no general errors.Is relationship to ctx.Err is promised. Prepare returns no partial result on error.

func (*Engine) PrepareExecution added in v0.4.0 

func (e *Engine) PrepareExecution(ctx context.Context, req RunRequest) (*PreparedExecution, error)

PrepareExecution completely prepares a prompt request without calling the configured LLMClient or reserving backend admission capacity.

The returned opaque handle is bound to this Engine and permits one Engine.RunPrepared invocation. Preparation freezes the selected sources, rendered messages, effective settings, inputs, provider structured-output metadata, and validation resources needed by that invocation. The handle retains a direct RunRequest.APIKey only in private execution state; PreparedExecution.Details is credential-redacted.

The context governs preparation only. Cancellation after this method returns does not invalidate the handle or propagate to RunPrepared. PrepareExecution returns the same error categories as Engine.Prepare and returns no handle on error. A nil Engine returns an error matching ErrInvalidConfig.

func (*Engine) Run 

func (e *Engine) Run(ctx context.Context, req RunRequest) (*RunResult, error)

Run prepares a request, invokes the configured LLMClient, and validates the generated output.

A content-validation failure is a successful run whose RunResult.Validation has Status ValidationFailed. When its output contract has a positive repair budget, a failed eligible validation can make bounded additional model calls and stops at the first valid candidate. Exhaustion returns the final failed validation result with cumulative usage and actual repair attempts. An inability to generate or validate returns an error and no partial result.

Run can return every error category documented by Engine.Prepare, plus ErrCapacityExceeded and ErrLLMGenerate. An engine admission rejection is discoverable as CapacityError and still matches ErrCapacityExceeded. It occurs before artifacts, schemas, rendering, or model generation because the selected backend's admission capacity is full; it does not match ErrInvalidRequest or ErrLLMGenerate. A built-in OpenAI-compatible non-2xx response is discoverable as GenerationError. Errors from injected clients remain available through errors.Is. Cancellation while waiting for model-generation capacity matches both ErrLLMGenerate and the context error. Cancellation otherwise follows the active collaborator's documented behavior. A nil Engine returns ErrInvalidConfig. Run returns no partial result on error.

func (*Engine) RunPrepared added in v0.4.0 

func (e *Engine) RunPrepared(ctx context.Context, prepared *PreparedExecution) (*RunResult, error)

RunPrepared atomically claims and executes a handle created by Engine.PrepareExecution.

A valid owning-Engine invocation consumes the handle's one attempt before credential revalidation, backend admission, generation, or validation. Cancellation, capacity rejection, generation failure, operational validation failure, and success all leave the handle unusable. A nil, zero-value, foreign-Engine, discarded, claimed, or used handle returns an error matching ErrInvalidRequest; a nil Engine returns ErrInvalidConfig and does not claim the handle.

The supplied context governs this execution attempt independently of the preparation context. It covers credential revalidation, admission, generation, validation, and any bounded output repair. Result timing begins after the claim and excludes preparation and consumer-held delay.

RunPrepared can return ErrInvalidRequest, ErrAPIKeyEnvMissing, ErrCapacityExceeded, ErrLLMGenerate, or ErrValidation as applicable while preserving documented collaborator and context identities. An engine admission rejection is discoverable as CapacityError and still matches ErrCapacityExceeded. A built-in OpenAI-compatible non-2xx response is discoverable as GenerationError. A completed content-validation rejection, including repair exhaustion, is returned in RunResult, not as an operational error. An operational error returns no partial RunResult.

type ExecutionTarget 

type ExecutionTarget struct {
	// BackendID is the effective routing identity selected by the profile. It
	// remains unchanged when a profile or request overrides Endpoint and is
	// empty for endpoint-only profiles. It is supplied to injected LLMClient
	// implementations as part of the effective target.
	BackendID string `json:"backend_id,omitempty"`
	// Endpoint is the normalized absolute HTTP or HTTPS model-provider base URL.
	// It has a host and no user information, query, or fragment.
	Endpoint string `json:"endpoint"`
	// Model is the provider model identifier.
	Model string `json:"model"`
	// Temperature is the resolved sampling temperature from 0 through 2. Zero
	// leaves the field unspecified to compatible providers unless the
	// corresponding ExecutionTargetPresence bit is true.
	Temperature float64 `json:"temperature"`
	// MaxTokens is the non-negative resolved output-token limit. Zero leaves
	// the limit unspecified to compatible providers unless the corresponding
	// ExecutionTargetPresence bit is true.
	MaxTokens int `json:"max_tokens"`
	// TopP is the resolved nucleus-sampling value from 0 through 1. Zero leaves
	// the field unspecified to compatible providers unless the corresponding
	// ExecutionTargetPresence bit is true.
	TopP float64 `json:"top_p"`
	// TimeoutSeconds is the non-negative per-generation deadline. Zero disables
	// this deadline without disabling caller cancellation or the transport cap.
	TimeoutSeconds int `json:"timeout_seconds"`
	// ServiceTier is an optional provider-specific request tier.
	ServiceTier string `json:"service_tier"`
	// ReasoningEffort is the effective opaque provider-specific reasoning
	// setting. An empty value instructs model clients to omit reasoning.
	ReasoningEffort string `json:"reasoning_effort"`
	// APIKeyEnv is the resolved name of an optional environment lookup source,
	// not its credential value. The built-in client omits Authorization when no
	// usable direct or environment credential is available; injected clients may
	// resolve this metadata differently.
	APIKeyEnv string `json:"api_key_env"`
	// ExtraParams contains copied JSON-compatible provider parameters.
	ExtraParams map[string]any `json:"extra_params"`
}

ExecutionTarget represents effective model runtime settings and has a stable JSON representation. It never exposes a resolved API-key value.

type ExecutionTargetOverride 

type ExecutionTargetOverride struct {
	// Endpoint replaces the profile or backend endpoint when non-empty without
	// changing the effective BackendID. Preparation trims it and requires an
	// absolute HTTP or HTTPS URL with a host and no user information, query, or
	// fragment.
	Endpoint string
	// Model replaces the profile model when non-empty.
	Model string
	// Temperature, when non-nil, must point to a value from 0 through 2. A
	// pointed-to zero is explicitly present; nil inherits a lower-precedence
	// value and otherwise leaves the provider control unspecified.
	Temperature *float64
	// MaxTokens, when non-nil, must point to a non-negative value. A pointed-to
	// zero is explicitly present; nil inherits a lower-precedence value and
	// otherwise leaves the provider control unspecified.
	MaxTokens *int
	// TopP, when non-nil, must point to a value from 0 through 1. A pointed-to
	// zero is explicitly present; nil inherits a lower-precedence value and
	// otherwise leaves the provider control unspecified.
	TopP *float64
	// TimeoutSeconds, when non-nil, must point to a non-negative value. A
	// pointed-to zero disables the per-generation deadline.
	TimeoutSeconds *int
	// ServiceTier replaces the profile value when non-blank.
	ServiceTier string
	// ReasoningEffort controls the per-run reasoning setting. Nil inherits the
	// profile value. A pointer to a non-blank string trims and replaces the
	// profile value. A pointer to an empty or whitespace-only string clears the
	// inherited value and disables reasoning for this run. Non-blank values
	// are opaque and are not validated against a fixed vocabulary.
	ReasoningEffort *string
	// APIKeyEnv replaces the profile or backend optional environment lookup
	// source when non-blank. A direct RunRequest.APIKey still takes precedence.
	// The built-in client omits Authorization when neither source has a usable
	// value; injected clients may resolve this metadata differently.
	APIKeyEnv string
	// ExtraParams, when non-empty, replaces the complete profile or backend map.
	// Values must be JSON-compatible: nil, booleans, finite numbers, strings,
	// arrays or slices, and maps with non-empty string keys. Cycles and
	// excessively deep or large values are invalid.
	ExtraParams map[string]any
}

ExecutionTargetOverride represents per-request runtime setting overrides and has no stable JSON representation.

Non-empty string fields replace profile and backend values. Non-nil pointer fields replace profile values and preserve explicit zero or empty values. A non-empty ExtraParams map replaces the complete profile or backend map rather than merging keys. Empty string fields, nil pointers, and a nil or empty ExtraParams map inherit lower-precedence values. An optional provider control that remains zero is unspecified; TimeoutSeconds retains its framework deadline when no higher-precedence value is present.

type ExecutionTargetPresence 

type ExecutionTargetPresence struct {
	// Temperature reports a non-nil ExecutionTargetOverride.Temperature.
	Temperature bool `json:"temperature"`
	// MaxTokens reports a non-nil ExecutionTargetOverride.MaxTokens.
	MaxTokens bool `json:"max_tokens"`
	// TopP reports a non-nil ExecutionTargetOverride.TopP.
	TopP bool `json:"top_p"`
	// TimeoutSeconds reports a non-nil ExecutionTargetOverride.TimeoutSeconds.
	TimeoutSeconds bool `json:"timeout_seconds"`
}

ExecutionTargetPresence tracks which numeric runtime settings were explicit request overrides, including explicit zero values. It has a stable JSON representation and is supplied to injected LLM clients so they can preserve omission semantics.

type GenerateRequest 

type GenerateRequest struct {
	// Prompt contains the rendered session ID and messages.
	Prompt RenderedPrompt `json:"prompt"`
	// Target contains effective model settings without the direct API key.
	Target ExecutionTarget `json:"target"`
	// TargetPresence distinguishes inherited numeric zeros from explicit
	// request overrides.
	TargetPresence ExecutionTargetPresence `json:"target_presence"`
	// StructuredOutput contains provider response constraints when requested.
	StructuredOutput *StructuredOutputSpec `json:"structured_output,omitempty"`
	// APIKey is the direct request-scoped credential, if any. It is excluded
	// from JSON, String, and GoString output.
	APIKey string `json:"-"`
}

GenerateRequest is passed to an injected LLM client and has a stable JSON representation. Its String and GoString methods omit rendered content and direct credentials.

func (GenerateRequest) GoString 

func (r GenerateRequest) GoString() string

GoString returns a concise request summary without exposing direct API keys or rendered prompt content. Reflection-based formatting does not carry this guarantee.

func (GenerateRequest) String 

func (r GenerateRequest) String() string

String returns a concise request summary without exposing direct API keys or rendered prompt content. Reflection-based formatting does not carry this guarantee.

type GenerateResponse 

type GenerateResponse struct {
	// Content is the generated output. It may be explicitly empty; Promptkit
	// applies the effective output contract to classify it.
	Content string `json:"content"`
	// Usage is the client's token accounting.
	Usage TokenUsage `json:"usage"`
}

GenerateResponse is returned by an injected LLM client and has a stable JSON representation.

type GenerationError added in v0.7.0 

type GenerationError struct {
	// contains filtered or unexported fields
}

GenerationError reports a non-2xx response from Promptkit's built-in OpenAI-compatible client during Engine.Run or Engine.RunPrepared.

Engine-produced values are immutable, caller-owned values. Use errors.Is to match ErrLLMGenerate and errors.As with a *GenerationError target to obtain this type. The four provider accessors expose untrusted provider-controlled values that can contain sensitive request or schema fragments. Applications must apply their own disclosure policy before logging, displaying, or returning them to another caller.

Accessors, Error, GoString, and Unwrap are safe on a nil receiver and a zero value. Default and Go-syntax formatting deliberately redact provider details. GenerationError has no stable JSON representation.

func (*GenerationError) Error added in v0.7.0 

func (e *GenerationError) Error() string

Error returns a redacted diagnostic that is not a parsing contract.

func (*GenerationError) GoString added in v0.7.0 

func (e *GenerationError) GoString() string

GoString returns the same redacted diagnostic as Error.

func (*GenerationError) ProviderCode added in v0.7.0 

func (e *GenerationError) ProviderCode() string

ProviderCode returns the normalized provider error code, if present. Its value is untrusted and may contain sensitive data.

func (*GenerationError) ProviderMessage added in v0.7.0 

func (e *GenerationError) ProviderMessage() string

ProviderMessage returns the bounded normalized provider diagnostic, if present. Its value is untrusted and may contain sensitive data.

func (*GenerationError) ProviderType added in v0.7.0 

func (e *GenerationError) ProviderType() string

ProviderType returns the normalized provider error type, if present. Its value is untrusted and may contain sensitive data.

func (*GenerationError) StatusCode added in v0.7.0 

func (e *GenerationError) StatusCode() int

StatusCode returns the received provider HTTP status code, or zero for a nil receiver or zero value.

func (*GenerationError) Unwrap added in v0.7.0 

func (e *GenerationError) Unwrap() error

Unwrap returns ErrLLMGenerate. It is safe to call on a nil receiver or zero value.

type LLMClient 

type LLMClient interface {
	Generate(context.Context, GenerateRequest) (*GenerateResponse, error)
}

LLMClient executes rendered prompts for Engine.Run and Engine.RunPrepared.

Generate is scheduled according to the resolved backend's capacity policy. It may still be called concurrently for different backend pools or unlimited backends. Cancellation while waiting for capacity can prevent Generate from being called. Once invoked, it must honor context cancellation to make Run and RunPrepared responsive to cancellation. The request and all nested maps, slices, and pointers are client-owned copies and may be mutated or retained without affecting engine state.

Generate receives rendered messages and may receive a direct API key. A client must protect those values and any raw output in its logging, storage, and retained copies. It is responsible for the cancellation behavior of any work it starts and for synchronizing access to retained or shared data.

An arbitrary returned error makes Run or RunPrepared return ErrLLMGenerate while preserving the client error through errors.Is rather than translating it. A nil response with a nil error also produces ErrLLMGenerate. Promptkit copies the non-nil response before returning from either method.

type OpenAICompatibleProfileConfig 

type OpenAICompatibleProfileConfig struct {
	// ID becomes Profile.ID.
	ID string
	// BaseProfileID becomes Profile.BaseProfileID. A non-blank value permits the
	// resulting Profile to inherit target fields when it is selected or inspected.
	BaseProfileID string
	// BackendID becomes Profile.BackendID.
	BackendID string
	// Endpoint becomes Profile.Endpoint.
	Endpoint string
	// Model becomes Profile.Model.
	Model string
	// APIKeyRequired becomes Profile.APIKeyRequired.
	APIKeyRequired bool
	// Temperature becomes Profile.Temperature.
	Temperature float64
	// MaxTokens becomes Profile.MaxTokens.
	MaxTokens int
	// TopP becomes Profile.TopP.
	TopP float64
	// TimeoutSeconds becomes Profile.TimeoutSeconds.
	TimeoutSeconds int
	// ServiceTier becomes Profile.ServiceTier.
	ServiceTier string
	// ReasoningEffort becomes Profile.ReasoningEffort.
	ReasoningEffort string
	// ExtraParams becomes a shallow-copied Profile.ExtraParams map. NewEngine
	// performs validation and a deep copy when WithProfiles applies the result.
	ExtraParams map[string]any
}

OpenAICompatibleProfileConfig configures an OpenAI-compatible in-memory profile.

It contains ordinary profile fields for OpenAI-compatible chat-completions endpoints. BaseProfileID and APIKeyRequired follow Profile. Raw API keys do not belong in this config. OpenAICompatibleProfileConfig has no stable JSON representation and is not validated until its resulting Profile is supplied through WithProfiles to NewEngine.

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option customizes engine construction.

NewEngine applies options in argument order and ignores nil options. Within each prompt-source, ordinary-profile-source, fallback-profile-source, in-memory-profile, schema-source, model-client, and artifact-reader category, the last non-nil valid option replaces earlier options in that category. WithBackend is the additive exception: unique registrations accumulate, and a repeated backend ID is an error rather than a replacement. An invalid option fails construction even if a later option would replace it.

func WithArtifactReader 

func WithArtifactReader(reader ArtifactReader) Option

WithArtifactReader replaces the default reader for every input artifact reference, regardless of its ArtifactRef.Type.

A nil reader makes NewEngine fail with ErrInvalidConfig. The reader may be called concurrently.

func WithBackend added in v0.2.0 

func WithBackend(backend Backend) Option

WithBackend adds one Backend registration to the constructed Engine.

Registrations accumulate in option order. Every normalized ID must be unique across consumer registrations and built-ins; a duplicate or invalid definition makes NewEngine fail with ErrInvalidConfig. Built-in IDs, including BackendOpenRouter and BackendRakestrawHome, cannot be replaced. The immutable registration is scoped to the resulting Engine and cannot be enumerated, replaced, removed, or mutated after construction. WithBackend does not install package-global state.

func WithFallbackProfileFS added in v0.5.0 

func WithFallbackProfileFS(fsys fs.FS, root string) Option

WithFallbackProfileFS supplies application-owned fallback profile definitions from fsys under root.

Profile lookup checks, in order, profiles supplied by WithProfiles; the ordinary configured source selected by WithProfileFile, WithProfileFS, or Config.ProfileDir; this fallback source; and Promptkit's embedded built-in profiles. Each source supplies a complete profile definition; profile fields are not merged between sources. Only an absent profile ID proceeds to the next source. A matching read, parse, duplicate, validation, or credential format failure stops resolution.

Files use the ordinary strict profile YAML and api_key_env credential rules. Loading and validation are lazy: NewEngine validates this option's arguments but does not read profile files. fsys must be non-nil and root must be nonblank; otherwise NewEngine returns an error matching ErrInvalidConfig. Repeating this option replaces the earlier valid fallback source.

This option controls profile-definition lookup, not provider or generation failover.

func WithLLMClient 

func WithLLMClient(client LLMClient) Option

WithLLMClient replaces the built-in model client used by Engine.Run and Engine.RunPrepared.

A nil client makes NewEngine fail with ErrInvalidConfig. The Engine schedules Generate calls according to the selected backend's capacity policy, but the client may still be called concurrently across different backend pools or for unlimited backends. The client is not used by Engine.Prepare or Engine.PrepareExecution.

func WithProfileFS 

func WithProfileFS(fsys fs.FS, root string) Option

WithProfileFS loads execution profiles from fsys under root.

Profiles from this ordinary configured source take precedence over application fallback and built-in profiles. Profile YAML must use api_key_env for environment-based credentials; raw API keys are rejected. fsys must be non-nil and root must be non-empty; otherwise NewEngine fails with ErrInvalidConfig. This option replaces Config.ProfileDir and earlier file or FS profile-source options, but remains below WithProfiles in precedence.

func WithProfileFile 

func WithProfileFile(path string) Option

WithProfileFile loads execution profiles from the single profile file at path.

The profile takes precedence over application fallback and built-in profiles. Profile YAML must use api_key_env for environment-based credentials; raw API keys are rejected. path must name an existing non-directory file when NewEngine applies the option. This option replaces Config.ProfileDir and earlier file or FS profile-source options, but remains below WithProfiles in precedence.

func WithProfiles 

func WithProfiles(profiles ...Profile) Option

WithProfiles configures in-memory profiles that take precedence over ordinary configured, application fallback, and built-in profiles.

NewEngine locally validates and copies every profile. IDs must be unique within one call. An invalid local definition, duplicate ID, or unsupported ExtraParams value makes construction fail with ErrInvalidConfig. A derived profile's base reference and resolved target completeness are checked when it is selected or inspected. Repeating WithProfiles replaces the complete earlier in-memory set rather than merging it.

func WithPromptFS 

func WithPromptFS(fsys fs.FS, root string) Option

WithPromptFS loads prompt definitions from fsys under root.

The source uses the same strict prompt YAML rules as configured prompt directories, and prompt content_file paths resolve within this source. fsys must be non-nil and root must be non-empty; otherwise NewEngine fails with ErrInvalidConfig. This option replaces Config.PromptDir and earlier prompt-source options.

func WithPromptFile 

func WithPromptFile(path string) Option

WithPromptFile loads prompt definitions from the single prompt file at path.

Relative prompt content_file paths resolve from the file's directory. path must name an existing non-directory file when NewEngine applies the option. This option replaces Config.PromptDir and earlier prompt-source options.

func WithSchemaFS 

func WithSchemaFS(fsys fs.FS, root string) Option

WithSchemaFS loads JSON Schema documents from fsys under root.

Prompt schema_path values resolve within this source when schema validation or structured output is requested. fsys must be non-nil and root must be non-empty; otherwise NewEngine fails with ErrInvalidConfig. This option replaces Config.SchemaDir and earlier schema-source options.

func WithSchemaFile 

func WithSchemaFile(path string) Option

WithSchemaFile loads JSON Schema documents from the single schema file at path.

Prompt schema_path values refer to the file's base name. path must name an existing non-directory file when NewEngine applies the option. This option replaces Config.SchemaDir and earlier schema-source options.

type OutputContract 

type OutputContract struct {
	// Format selects generated artifact metadata. An empty value in a non-nil
	// request replacement defaults to FormatText.
	Format OutputFormat `json:"format"`
	// ValidationMode selects the content check. Use one of the declared
	// ValidationMode constants.
	ValidationMode ValidationMode `json:"validation_mode"`
	// SchemaPath is required when ValidationMode is ValidationJSONSchema and is
	// ignored by other modes.
	SchemaPath string `json:"schema_path"`
	// RepairAttempts is an additional generation-call budget from zero through
	// three. Zero is single-pass. A positive value is valid only with basic,
	// json, or json_schema validation.
	RepairAttempts int `json:"repair_attempts"`
}

OutputContract defines output and validation requirements and has a stable JSON representation.

A non-nil RunRequest.Validation replaces the complete prompt contract. It does not merge fields. The public Engine performs bounded correction after a failed eligible validation when RepairAttempts is positive.

type OutputFormat 

type OutputFormat string

OutputFormat identifies the media format of generated output. OutputFormat has a stable JSON string representation. 

const (
	// FormatText identifies plain-text output.
	FormatText OutputFormat = "text"
	// FormatMarkdown identifies Markdown output.
	FormatMarkdown OutputFormat = "markdown"
	// FormatJSON identifies JSON output.
	FormatJSON OutputFormat = "json"
)

type PreparedExecution added in v0.4.0 

type PreparedExecution struct {
	// contains filtered or unexported fields
}

PreparedExecution is an opaque, in-process handle for one completely prepared execution. A handle is bound to the Engine that created it and permits one Engine.RunPrepared invocation.

PreparedExecution contains no supported serializable state and cannot be used as a restartable job. Copying the value preserves the same shared lifecycle; it does not create another execution attempt.

func (*PreparedExecution) Details added in v0.4.0 

func (p *PreparedExecution) Details() PreparedRun

Details returns a fresh caller-owned, credential-redacted copy of the prepared request details. Mutating the result cannot affect execution or a later Details call. Details remains available after execution or discard.

A nil receiver or zero-value PreparedExecution returns a zero PreparedRun.

func (*PreparedExecution) Discard added in v0.4.0 

func (p *PreparedExecution) Discard()

Discard invalidates an unclaimed handle and drops Promptkit's references to its execution-only state. Discard is nil-safe and idempotent. It does not cancel an execution that has already claimed the handle; use the Engine.RunPrepared context for cancellation.

func (PreparedExecution) GoString added in v0.4.0 

func (p PreparedExecution) GoString() string

GoString returns a constant Go-syntax representation that exposes no retained request, rendered content, or credential data.

func (PreparedExecution) String added in v0.4.0 

func (p PreparedExecution) String() string

String returns a constant representation that exposes no retained request, rendered content, or credential data.

type PreparedRun 

type PreparedRun struct {
	// PromptID is the selected prompt identifier.
	PromptID string `json:"prompt_id"`
	// PromptVersion is the selected prompt version.
	PromptVersion string `json:"prompt_version,omitempty"`
	// PromptHash is an opaque equality value for the selected definition.
	PromptHash string `json:"prompt_hash,omitempty"`
	// SelectedProfileID is the explicit request profile or prompt default that
	// supplied execution settings.
	SelectedProfileID string `json:"selected_profile_id"`
	// SelectedBackendID equals EffectiveModelParams.BackendID. It is empty for
	// an endpoint-only profile.
	SelectedBackendID string `json:"selected_backend_id,omitempty"`
	// EffectiveModelParams contains settings resolved from the framework timeout
	// baseline, selected backend, profile, and then request overrides. Unset
	// optional provider controls remain zero rather than reporting a provider
	// default. It excludes resolved API-key values.
	EffectiveModelParams ExecutionTarget `json:"effective_model_params"`
	// OutputContract is the complete effective output contract.
	OutputContract OutputContract `json:"output_contract"`
	// StructuredOutput is non-nil for JSON Schema validation and contains the
	// provider-facing response constraint passed to an LLM client.
	StructuredOutput *StructuredOutputSpec `json:"structured_output,omitempty"`
	// InputHashes maps every supplied input name to its opaque artifact hash.
	InputHashes map[string]string `json:"input_hashes,omitempty"`
	// SessionID is the effective direct or rendered session identifier, if any.
	SessionID string `json:"session_id,omitempty"`
	// RenderedPromptHash is an opaque equality value for SessionID and Messages.
	RenderedPromptHash string `json:"rendered_prompt_hash"`
	// Messages are the rendered messages that Run or RunPrepared passes to the
	// LLM client.
	Messages []RenderedMessage `json:"messages"`
	// StartTime is the UTC time at which preparation began.
	StartTime time.Time `json:"start_time,omitempty"`
	// EndTime is the UTC time at which preparation completed.
	EndTime time.Time `json:"end_time,omitempty"`
	// DurationMS is preparation elapsed time in integer milliseconds. JSON uses
	// duration_ms and omits a zero value.
	DurationMS int64 `json:"duration_ms,omitempty"`
}

PreparedRun contains prepared prompt execution state returned by Engine.Prepare or PreparedExecution.Details. It does not include resolved API key values, model output, validation results, or internal target presence metadata. PreparedRun has a stable JSON representation.

All maps, slices, pointers, and schema values are caller-owned copies. JSON timestamps use RFC 3339 and zero timing values are omitted. Hash formats are opaque.

func (PreparedRun) MarshalJSON added in v0.2.0 

func (r PreparedRun) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for PreparedRun. It uses RFC 3339 timestamps, integer duration_ms, and omits zero timing values.

type Profile 

type Profile struct {
	// ID is the required non-blank profile identifier. WithProfiles trims it.
	ID string
	// BaseProfileID optionally names one base profile. WithProfiles trims it. A
	// non-blank value permits required target fields to be inherited when the
	// profile is selected or inspected, which is also when reference existence
	// and resolved completeness are checked. A blank value leaves this as a
	// standalone profile.
	BaseProfileID string
	// BackendID optionally selects an engine backend. WithProfiles trims it.
	// Backend membership is checked when a request selects the profile; an
	// unknown ID makes preparation fail with ErrProfileLoad.
	BackendID string
	// Endpoint is the model-provider base URL. A standalone Profile requires an
	// endpoint when BackendID is blank; a derived Profile may inherit either
	// field. A non-blank endpoint overrides the backend endpoint when
	// non-blank. WithProfiles trims it and requires an absolute HTTP or HTTPS URL
	// with a host and no user information, query, or fragment.
	Endpoint string
	// Model is the provider model identifier. It is required for a standalone
	// Profile and may be inherited by a derived Profile.
	Model string
	// Temperature is from 0 through 2. Zero leaves the provider control
	// unspecified.
	Temperature float64
	// MaxTokens is non-negative. Zero leaves the provider control unspecified.
	MaxTokens int
	// TopP is from 0 through 1. Zero leaves the provider control unspecified
	// rather than selecting an explicit zero.
	TopP float64
	// TimeoutSeconds is non-negative. Zero retains the framework deadline.
	TimeoutSeconds int
	// ServiceTier is optional; a blank value leaves it unspecified.
	ServiceTier string
	// ReasoningEffort is optional; a blank value leaves it unspecified.
	ReasoningEffort string
	// APIKeyRequired clears a backend's inherited API-key environment name and
	// requires a non-blank RunRequest.APIKey unless the request explicitly
	// supplies ExecutionTargetOverride.APIKeyEnv. When false, a named
	// environment source remains optional. It does not store a credential.
	APIKeyRequired bool
	// ExtraParams contains provider-specific JSON-compatible values. An empty
	// map inherits backend request defaults, when any. WithProfiles validates
	// and deeply copies it during NewEngine. Excessively deep or large values
	// are rejected for safety.
	ExtraParams map[string]any
}

Profile is an in-memory execution profile for library consumers.

A standalone Profile is equivalent to a loaded profile file after local validation. A derived profile names BaseProfileID and can inherit target fields when selected or inspected. Raw API keys do not belong in profiles; use APIKeyRequired to require callers to provide a RunRequest.APIKey or explicit request ExecutionTargetOverride.APIKeyEnv, or use profile YAML api_key_env with file and FS profile sources. Profile has no stable JSON representation.

WithProfiles locally validates and copies Profile values during NewEngine. It checks base-reference existence and resolved target completeness when a derived profile is selected or inspected. Zero Temperature, MaxTokens, and TopP values and blank ServiceTier and ReasoningEffort values leave those provider controls unspecified. A zero TimeoutSeconds retains the framework deadline, while an empty ExtraParams map inherits backend request defaults. Use ExecutionTargetOverride pointer fields to request an explicit numeric zero.

func OpenAICompatibleProfile 

func OpenAICompatibleProfile(cfg OpenAICompatibleProfileConfig) Profile

OpenAICompatibleProfile returns an in-memory Profile for an OpenAI-compatible chat-completions endpoint. A non-blank BaseProfileID permits its target fields to be inherited when the profile is selected or inspected.

It does not register global state, maintain a model catalog, or resolve credentials. If APIKeyRequired is true, callers satisfy it with RunRequest.APIKey or an explicit request ExecutionTargetOverride.APIKeyEnv. Raw API keys do not belong in profiles.

The function copies the ExtraParams map itself but does not recursively copy nested values. Validation and a deep copy occur when NewEngine applies a WithProfiles option containing the returned Profile.

type ProfileInspection added in v0.4.0 

type ProfileInspection struct {
	// ProfileID is the trimmed, exact profile ID inspected by the engine.
	ProfileID string
	// EffectiveModelParams contains settings resolved from the framework timeout
	// baseline, selected backend, and then profile, without a request override.
	// Unset optional provider controls remain zero rather than reporting a
	// provider default. APIKeyEnv is an environment-variable name, never its
	// credential value.
	EffectiveModelParams ExecutionTarget
	// APIKeyRequired reports that a later execution must supply a direct API
	// key or an explicit request environment override. It is mutually exclusive
	// with a nonblank EffectiveModelParams.APIKeyEnv.
	APIKeyRequired bool
}

ProfileInspection is the caller-owned result of Engine.InspectProfile. It has no stable JSON representation.

EffectiveModelParams contains a copied effective target. APIKeyRequired is separate from that target to preserve ExecutionTarget's general execution and stable JSON contracts.

type PromptInputDefinition added in v0.4.0 

type PromptInputDefinition struct {
	// Name is the normalized prompt input name.
	Name string
	// Required is the prompt definition's declared required flag. When true,
	// preparation fails if the input is omitted. A false value does not account
	// for input references in message or session-ID templates.
	Required bool
	// ContentType is the declared input media-type metadata.
	ContentType string
	// Description is the declared human-readable input description.
	Description string
}

PromptInputDefinition describes one declared prompt input. It has no stable JSON representation.

type PromptInspection added in v0.4.0 

type PromptInspection struct {
	// PromptID is the normalized ID of the selected prompt definition.
	PromptID string
	// PromptVersion is the normalized version of the selected prompt definition.
	PromptVersion string
	// PromptHash is the opaque equality value for the selected definition.
	PromptHash string
	// DefaultProfileID is declared metadata and is not resolved by inspection.
	DefaultProfileID string
	// Inputs contains caller-owned declared input metadata in definition order.
	Inputs []PromptInputDefinition
	// OutputContract is the normalized contract declared by the definition.
	OutputContract OutputContract
}

PromptInspection is the caller-owned result of Engine.InspectPrompt. It has no stable JSON representation.

Inputs contains copied declared input metadata in definition order. OutputContract is the normalized contract declared by the prompt definition, rather than a request-level effective override. PromptHash is opaque.

type RenderedMessage 

type RenderedMessage struct {
	// Role is the definition-supplied chat role.
	Role string `json:"role"`
	// Content is the rendered message text.
	Content string `json:"content"`
	// CacheControl is optional provider cache metadata.
	CacheControl *CacheControl `json:"cache_control,omitempty"`
}

RenderedMessage is a rendered chat message and has a stable JSON representation.

type RenderedPrompt 

type RenderedPrompt struct {
	// SessionID is the optional effective direct or rendered session
	// identifier supplied to the model client.
	SessionID string `json:"session_id,omitempty"`
	// Messages contains rendered messages in definition order.
	Messages []RenderedMessage `json:"messages"`
}

RenderedPrompt is the fully rendered prompt passed to an LLM client and has a stable JSON representation.

type RunRequest 

type RunRequest struct {
	// PromptID is the required non-empty prompt identifier.
	PromptID string
	// PromptVersion optionally selects one version of PromptID. When empty, the
	// prompt source must contain exactly one matching version.
	PromptVersion string
	// ProfileID selects an execution profile. When empty, the prompt's default
	// profile is used; if both are empty, the error matches ErrProfileRequired
	// and ErrInvalidRequest.
	ProfileID string
	// SessionID optionally supplies a direct per-run session identifier. A
	// nonblank value is trimmed and overrides the prompt definition's
	// session_id template. A blank value supplies no direct override. The
	// maximum is 256 Unicode code points after trimming. A direct value is
	// opaque consumer metadata, not a credential, and may be exposed in
	// prepared values, results, collaborator requests, provider requests, and
	// provider observability. Callers should use stable, non-sensitive
	// identifiers. An overlong direct value makes Prepare, PrepareExecution, or
	// Run return an error matching ErrInvalidRequest.
	SessionID string
	// APIKey is a request-scoped direct credential. It takes precedence over
	// APIKeyEnv, is passed to the selected LLMClient, and is never included in
	// prepared values, results, hashes, JSON, String, or GoString output. A
	// successful PrepareExecution retains it only in the opaque handle until
	// RunPrepared claims the handle or Discard invalidates it.
	APIKey string `json:"-"`
	// Inputs maps prompt input names to references. A nil or empty map is valid
	// only when the selected prompt and its templates require no inputs.
	Inputs map[string]ArtifactRef
	// Vars supplies Go-template data for messages and the session ID. Nil and
	// empty maps are equivalent.
	Vars map[string]string
	// Execution optionally overrides individual execution settings. Nil uses
	// the selected profile over its backend, when any, and the framework
	// baseline.
	Execution *ExecutionTargetOverride
	// Validation optionally replaces the prompt's complete output contract. It
	// does not merge individual fields. Nil uses the prompt contract.
	Validation *OutputContract
}

RunRequest selects one prompt execution. It has no stable JSON representation.

Prepare, PrepareExecution, and Run copy the request's maps, pointers, and nested JSON-compatible values before using them. The caller may mutate the request after any method returns. A successful PrepareExecution retains its own private execution snapshot for RunPrepared. Excessively deep or large JSON-shaped values are rejected for safety.

func (RunRequest) GoString 

func (r RunRequest) GoString() string

GoString returns a concise request summary without exposing the direct API key or input and variable contents. Reflection-based formatting does not carry this guarantee.

func (RunRequest) String 

func (r RunRequest) String() string

String returns a concise request summary without exposing the direct API key or input and variable contents. Reflection-based formatting does not carry this guarantee.

type RunResult 

type RunResult struct {
	// RunID is an opaque identifier for this invocation.
	RunID string `json:"run_id"`
	// Artifact contains the generated output and derived metadata.
	Artifact Artifact `json:"artifact"`
	// RawOutput is the exact generated content before artifact classification
	// and validation.
	RawOutput string `json:"raw_output"`
	// Validation records the completed content check.
	Validation ValidationResult `json:"validation"`
	// PromptID is the selected prompt identifier.
	PromptID string `json:"prompt_id"`
	// PromptVersion is the selected prompt version.
	PromptVersion string `json:"prompt_version,omitempty"`
	// PromptHash is the same opaque definition equality value exposed by
	// PreparedRun.
	PromptHash string `json:"prompt_hash,omitempty"`
	// SessionID is the effective direct or rendered session identifier, if any.
	// JSON omits an empty value.
	SessionID string `json:"session_id,omitempty"`
	// RenderedPromptHash is the same opaque rendered-prompt equality value
	// computed during preparation.
	RenderedPromptHash string `json:"rendered_prompt_hash"`
	// SelectedProfileID identifies the profile used for execution.
	SelectedProfileID string `json:"selected_profile_id"`
	// SelectedBackendID equals EffectiveModelParams.BackendID. It is empty for
	// an endpoint-only profile.
	SelectedBackendID string `json:"selected_backend_id,omitempty"`
	// ModelName is the effective model name and equals
	// EffectiveModelParams.Model.
	ModelName string `json:"model_name"`
	// Endpoint is the effective base endpoint and equals
	// EffectiveModelParams.Endpoint.
	Endpoint string `json:"endpoint"`
	// EffectiveModelParams contains the settings supplied to the LLM client,
	// excluding resolved API-key values.
	EffectiveModelParams ExecutionTarget `json:"effective_model_params"`
	// InputHashes are the opaque input equality values computed during
	// preparation.
	InputHashes map[string]string `json:"input_hashes,omitempty"`
	// Usage is the token accounting reported by the LLM client.
	Usage TokenUsage `json:"usage"`
	// StartTime is the UTC time immediately before ordinary Run preparation or
	// after RunPrepared claims its handle.
	StartTime time.Time `json:"start_time,omitempty"`
	// EndTime is the UTC time after generation and validation complete.
	EndTime time.Time `json:"end_time,omitempty"`
	// Duration covers preparation, generation, and validation for Run. For
	// RunPrepared it covers only the execution attempt after claim and excludes
	// preparation and consumer-held delay. JSON represents it as integer
	// milliseconds in duration_ms and omits a zero value.
	Duration time.Duration `json:"-"`
}

RunResult contains generated output, validation state, and run metadata. RunResult has a stable JSON representation and round-trips its Duration through the duration_ms JSON field.

All maps, slices, and nested values are caller-owned copies. JSON timestamps use RFC 3339 and zero timing values are omitted. Run IDs and hash formats are opaque.

func (RunResult) MarshalJSON added in v0.2.0 

func (r RunResult) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for RunResult. It encodes Duration as integer milliseconds in duration_ms and omits zero timing values.

func (*RunResult) UnmarshalJSON added in v0.2.0 

func (r *RunResult) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler for RunResult. It decodes duration_ms into Duration with millisecond precision. A duration_ms outside the range representable by time.Duration returns an error without changing the receiver.

type StructuredOutputJSONSpec 

type StructuredOutputJSONSpec struct {
	// Name is the provider-facing schema name.
	Name string `json:"name"`
	// Strict requests strict provider enforcement of Schema.
	Strict bool `json:"strict"`
	// Schema is a caller-owned copy of the loaded JSON Schema document.
	Schema any `json:"schema"`
}

StructuredOutputJSONSpec contains provider-facing JSON Schema output constraints and has a stable JSON representation.

type StructuredOutputSpec 

type StructuredOutputSpec struct {
	// Type identifies the structured-output mechanism.
	Type StructuredOutputType `json:"type"`
	// JSONSchema contains constraints when Type is StructuredOutputJSONSchema.
	JSONSchema *StructuredOutputJSONSpec `json:"json_schema,omitempty"`
}

StructuredOutputSpec describes provider-level structured output and has a stable JSON representation.

type StructuredOutputType 

type StructuredOutputType string

StructuredOutputType identifies provider-level structured output modes. StructuredOutputType has a stable JSON string representation. 

const (
	// StructuredOutputJSONSchema supplies JSON Schema response constraints.
	StructuredOutputJSONSchema StructuredOutputType = "json_schema"
)

type TokenUsage 

type TokenUsage struct {
	// PromptTokens is the reported input-token count.
	PromptTokens int `json:"prompt_tokens"`
	// CompletionTokens is the reported generated-token count.
	CompletionTokens int `json:"completion_tokens"`
	// TotalTokens is the reported total-token count.
	TotalTokens int `json:"total_tokens"`
	// CachedTokens is the reported cached-input-token count.
	CachedTokens int `json:"cached_tokens"`
	// CacheWriteTokens is the reported cache-write-token count.
	CacheWriteTokens int `json:"cache_write_tokens"`
}

TokenUsage contains model-client token accounting and has a stable JSON representation. Promptkit preserves values reported by the client and does not derive or reconcile them.

type ValidationMode 

type ValidationMode string

ValidationMode identifies how generated output is checked. ValidationMode has a stable JSON string representation. 

const (
	// ValidationNone skips content validation.
	ValidationNone ValidationMode = "none"
	// ValidationBasic requires non-empty output.
	ValidationBasic ValidationMode = "basic"
	// ValidationJSON requires syntactically valid JSON.
	ValidationJSON ValidationMode = "json"
	// ValidationJSONSchema requires JSON that satisfies OutputContract.SchemaPath.
	ValidationJSONSchema ValidationMode = "json_schema"
)

type ValidationResult 

type ValidationResult struct {
	// Status is Passed, Failed, or Skipped.
	Status ValidationStatus `json:"status"`
	// Mode is the effective validation mode.
	Mode ValidationMode `json:"mode"`
	// Errors contains validation diagnostics when Status is ValidationFailed.
	Errors []string `json:"errors,omitempty"`
	// SchemaPath is the effective schema path for JSON Schema validation.
	SchemaPath string `json:"schema_path,omitempty"`
	// RepairAttempts is the number of corrective generation calls actually
	// started for this result.
	RepairAttempts int `json:"repair_attempts"`
	// IsValid is true for ValidationPassed and ValidationSkipped and false for
	// ValidationFailed.
	IsValid bool `json:"is_valid"`
}

ValidationResult represents a completed output check and has a stable JSON representation. An operational inability to perform validation is returned as ErrValidation instead of a ValidationResult.

type ValidationStatus 

type ValidationStatus string

ValidationStatus identifies the completed state of an output check. ValidationStatus has a stable JSON string representation. 

const (
	// ValidationPassed means the generated output satisfied its contract.
	ValidationPassed ValidationStatus = "passed"
	// ValidationFailed means validation completed and rejected the generated
	// output. Engine.Run and Engine.RunPrepared return this status in a result,
	// not as an error.
	ValidationFailed ValidationStatus = "failed"
	// ValidationSkipped means ValidationNone selected no content check.
	ValidationSkipped ValidationStatus = "skipped"
)

Source Files

View all Source files

Directories

Path Synopsis
examples
go-library/prepare command
go-library/run command
internal
artifact
backend
Package backend owns validated, immutable OpenAI-compatible backend definitions.
 Package backend owns validated, immutable OpenAI-compatible backend definitions.
capacity
Package capacity coordinates engine-local run admission and model-generation concurrency for configured backends.
 Package capacity coordinates engine-local run admission and model-generation concurrency for configured backends.
defaults
domain
filecatalog
jsonvalue
Package jsonvalue validates and defensively copies bounded JSON-compatible value trees used by configuration, request, and prepared-state boundaries.
 Package jsonvalue validates and defensively copies bounded JSON-compatible value trees used by configuration, request, and prepared-state boundaries.
llm
profile
profile/builtin
prompt
promptdef
usecase
validate

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.