Package `promptkit`

Purpose

This guide helps Go consumers assemble Promptkit and choose the main preparation or execution workflow. The declarations and GoDoc in the root package own exact field, option, serialization, concurrency, ownership, failure, and cancellation semantics. The framework format reference owns prompt, profile, and schema file contracts.

Import the package as:

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

The following Go fragments are illustrative and omit surrounding package, import, and error-handling code. Use the maintained example for a complete program.

Construct An Engine

Create an engine with NewEngine. A directory-backed setup supplies a prompt directory and may supply profile and schema directories:

engine, err := promptkit.NewEngine(promptkit.Config{
	PromptDir:  "prompts",
	ProfileDir: "profiles",
	SchemaDir:  "schemas",
})

Options support single-file or fs.FS sources, in-memory profiles, and injected artifact or model clients. Consult the constructor and option GoDoc for composition, precedence, validation, and default transport behavior. Source discovery, format validation, and profile precedence are defined by the framework format reference.

Prepare Without Model Execution

Engine.Prepare resolves the selected prompt and profile, loads inputs and any structured-output schema, and renders messages without calling a model client:

prepared, err := engine.Prepare(ctx, promptkit.RunRequest{
	PromptID: "meeting.summary",
	Inputs: map[string]promptkit.ArtifactRef{
		"note": promptkit.Inline("Synthetic meeting notes"),
	},
})

The maintained offline preparation example shows a complete runnable setup with a prompt file, in-memory profile, and inline input. Exact request requirements and prepared-result fields belong to the RunRequest and PreparedRun GoDoc.

Execute And Validate

Engine.Run performs the same preparation, invokes the configured model client, classifies the generated artifact, and validates the content. A completed content check may return ValidationFailed in the result; an operational inability to validate returns an error.

Use the RunResult and ValidationResult GoDoc for the returned data and the Engine.Run GoDoc for failure and cancellation semantics. The OpenAI-compatible integration contract owns the built-in client's outbound HTTP behavior.

Inputs, Profiles, And Overrides

Use File, Inline, or InlineWithURI to construct request inputs. A request can select a profile explicitly or use the prompt's default profile, and can replace execution settings or the complete output contract.

The public value GoDoc defines nil, empty, zero, replacement, copy, and credential behavior. The framework format reference defines how those request values interact with prompt definitions, file-backed profiles, built-ins, schemas, and framework defaults.

For programmatic profiles, OpenAICompatibleProfile converts ordinary OpenAI-compatible settings into a value accepted by WithProfiles.

Credentials

File-backed profiles name an environment variable; in-memory profiles can require a direct request key. Direct keys are request-scoped and are excluded from supported JSON values and the package's String and GoString summaries. The exact precedence and redaction guarantees belong to RunRequest, GenerateRequest, and the profile GoDoc.

Extension Interfaces

Inject an LLMClient or ArtifactReader when the built-in behavior does not fit the application. Their GoDoc defines concurrent use, context handling, ownership of copied values, nil responses, and preservation of collaborator errors.

Handle Errors

Use errors.Is with the public error sentinels and operation GoDoc. The declarations distinguish invalid construction, invalid requests, absent sources, source-loading failures, collaborator failures, and operational validation failures. Specific request conditions may also match the broader ErrInvalidRequest, and injected collaborator identities are preserved where documented.

Application Boundary

Promptkit is an importable library. It does not own a command, inbound HTTP API, process configuration, or deployment policy. Applications map the root package's results and errors into those concerns.

4.6 KiB Raw Blame History

Package promptkit