123 lines
4.6 KiB
Markdown
123 lines
4.6 KiB
Markdown
# 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](../../doc.go) own exact field, option, serialization,
|
|
concurrency, ownership, failure, and cancellation semantics. The
|
|
[framework format reference](../formats.md) owns prompt, profile, and schema
|
|
file contracts.
|
|
|
|
Import the package as:
|
|
|
|
```go
|
|
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`](../../engine.go). A directory-backed setup supplies a prompt
|
|
directory and may supply profile and schema directories:
|
|
|
|
```go
|
|
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](../../engine.go) for composition, precedence,
|
|
validation, and default transport behavior. Source discovery, format
|
|
validation, and profile precedence are defined by the
|
|
[framework format reference](../formats.md).
|
|
|
|
## Prepare Without Model Execution
|
|
|
|
[`Engine.Prepare`](../../engine.go) resolves the selected prompt and profile,
|
|
loads inputs and any structured-output schema, and renders messages without
|
|
calling a model client:
|
|
|
|
```go
|
|
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](../../examples/go-library/prepare/main.go)
|
|
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](../../types.go).
|
|
|
|
## Execute And Validate
|
|
|
|
[`Engine.Run`](../../engine.go) 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](../../types.go) for the
|
|
returned data and the `Engine.Run` GoDoc for failure and cancellation
|
|
semantics. The
|
|
[OpenAI-compatible integration contract](../integrations/openai-compatible-chat.md)
|
|
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](../../types.go) defines nil, empty, zero, replacement,
|
|
copy, and credential behavior. The
|
|
[framework format reference](../formats.md) defines how those request values
|
|
interact with prompt definitions, file-backed profiles, built-ins, schemas,
|
|
and framework defaults.
|
|
|
|
For programmatic profiles,
|
|
[`OpenAICompatibleProfile`](../../profiles.go) 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](../../types.go).
|
|
|
|
## Extension Interfaces
|
|
|
|
Inject an [`LLMClient` or `ArtifactReader`](../../types.go) 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](../../engine.go). 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.
|