promptkit/docs/consumers/pkg-promptkit.md

Package promptkit

Import path:

import "gitea.maximumdirect.net/eric/promptkit"

Package promptkit is the supported Go contract for in-process prompt preparation and execution. The declarations and their GoDoc in the root package own the exact API; this guide explains how the pieces are used together. The framework format reference owns prompt, profile, and schema file contracts.

Engine Construction And Sources

Construct an engine with NewEngine, Config, and Option. PromptDir is required unless a prompt source option is supplied. ProfileDir optionally overlays built-in profiles, and an empty SchemaDir uses the current directory. Timeout is the transport-wide safety cap for the built-in OpenAI-compatible client. An optional HTTPClient is cloned; its positive timeout takes precedence.

Nil options are ignored. Invalid construction, including a nil injected client or artifact reader, returns an error matching ErrInvalidConfig.

The source options replace their matching directory source:

• WithPromptFS and WithPromptFile select prompt definitions;
• WithProfileFS and WithProfileFile overlay built-in profiles;
• WithProfiles adds in-memory profiles ahead of file and built-in profiles;
• WithSchemaFS and WithSchemaFile select JSON Schema documents;
• WithLLMClient replaces the built-in model client; and
• WithArtifactReader replaces the default reader for every input.

Source selection, path resolution, strict decoding, profile overlays, and file-to-request precedence are defined in the framework format reference.

Per-generation timeout values from profiles or requests are independent of the transport cap and caller context. An explicit request value of zero disables only the per-generation deadline. The outbound integration contract defines the complete timeout layering.

Preparation And Execution

Engine.Prepare and Engine.Run accept the public RunRequest. Prepare resolves the prompt, profile, input artifacts, validation contract, and rendered messages without calling an LLM. Run performs the same preparation, calls the configured client, and validates the generated content. The maintained offline preparation example provides a complete runnable workflow using a prompt file, in-memory profile, and inline input.

PreparedRun and RunResult expose copied public values. Preparation returns effective settings, hashes, rendered messages, selected profile, structured-output information, and timing without resolved secrets or model output. Execution adds the generated artifact and raw output, validation state, model metadata, usage, run ID, and duration.

A generated-content validation failure returns a result with Validation.Status == ValidationFailed. An inability to perform validation returns an error matching ErrValidation.

Requests, Inputs, And Overrides

The request and value declarations own the available fields, serialized constants, and result shapes. Use File, Inline, or InlineWithURI to construct artifact references. The framework format reference defines declared inputs, template references, output contracts, and the relationship between file values and request overrides.

ExecutionTargetOverride uses pointers for numeric settings so an explicit zero remains distinct from no override. ExtraParams accepts JSON-compatible strings, booleans, finite numbers, string-keyed objects, arrays or slices, and nil. Unsupported values, non-string map keys, non-finite numbers, and cycles match ErrInvalidConfig in profiles or ErrInvalidRequest in request overrides.

Returned requests, profiles, prepared values, results, artifacts, maps, and slices are isolated from internal engine state. Consumers and injected extensions should not retain or mutate values owned by another caller.

Profiles And Credentials

OpenAICompatibleProfile constructs an ordinary in-memory profile for an OpenAI-compatible chat-completions endpoint. WithProfiles rejects duplicate IDs in one call and gives in-memory profiles precedence over explicit file sources and built-ins.

Raw API keys do not belong in profiles. File-backed profiles may name an environment variable, while an in-memory profile can require a request key. A direct RunRequest.APIKey is request-scoped and takes precedence over an environment lookup for the built-in client. Profile fields, ranges, built-ins, precedence, and credential rules are owned by the framework format reference.

API keys are excluded from JSON, prepared values, and results. The public String and GoString methods report only whether a direct key is present. Avoid reflection-based dumps of request structs, which can bypass that redaction.

Extension Interfaces

The LLMClient, GenerateRequest, and GenerateResponse boundary lets a consumer replace model generation. Injected clients receive copied rendered messages, effective settings, explicit numeric-setting presence, structured-output constraints, and the request-scoped key. They return generated content and token usage.

The ArtifactReader boundary replaces the default inline and file reader for every input. Readers provide artifact content and metadata; the engine fills an empty artifact name from the input-map key. A reader error matches ErrArtifactLoad while preserving the original identity for errors.Is. A nil artifact with a nil error is also an artifact-load failure.

Extensions should honor context cancellation and avoid logging raw prompts, artifacts, or credentials.

Errors

The public error declarations and mapping preserve these sentinel checks through errors.Is:

• ErrInvalidConfig
• ErrInvalidRequest
• ErrPromptNotFound
• ErrProfileNotFound
• ErrProfileRequired
• ErrPromptLoad
• ErrProfileLoad
• ErrAPIKeyEnvMissing
• ErrArtifactLoad
• ErrPromptRender
• ErrLLMGenerate
• ErrValidation

ErrProfileRequired and ErrAPIKeyEnvMissing also match ErrInvalidRequest, allowing either broad request handling or a specific condition. Wrapped collaborator errors retain their identity where the public contract promises it.

Consumer Boundary

Promptkit is an importable library. It does not own a command, inbound HTTP API, process configuration, or deployment policy. Scriptorium is one downstream application that maps this root package contract into those application concerns.