Make GoDoc the public API contract
This commit is contained in:
@@ -1,151 +1,122 @@
|
||||
# Package `promptkit`
|
||||
|
||||
Import path:
|
||||
## 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"
|
||||
```
|
||||
|
||||
Package `promptkit` is the supported Go contract for in-process prompt
|
||||
preparation and execution. The declarations and their GoDoc in the
|
||||
[root package](../../doc.go) own the exact API; this guide explains how the
|
||||
pieces are used together. The [framework format reference](../formats.md) owns
|
||||
prompt, profile, and schema file contracts.
|
||||
The following Go fragments are illustrative and omit surrounding package,
|
||||
import, and error-handling code. Use the maintained example for a complete
|
||||
program.
|
||||
|
||||
## Engine Construction And Sources
|
||||
## Construct An Engine
|
||||
|
||||
Construct an engine with [`NewEngine`, `Config`, and
|
||||
`Option`](../../engine.go). `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.
|
||||
Create an engine with
|
||||
[`NewEngine`](../../engine.go). A directory-backed setup supplies a prompt
|
||||
directory and may supply profile and schema directories:
|
||||
|
||||
Nil options are ignored. Invalid construction, including a nil injected client
|
||||
or artifact reader, returns an error matching `ErrInvalidConfig`.
|
||||
```go
|
||||
engine, err := promptkit.NewEngine(promptkit.Config{
|
||||
PromptDir: "prompts",
|
||||
ProfileDir: "profiles",
|
||||
SchemaDir: "schemas",
|
||||
})
|
||||
```
|
||||
|
||||
The [source options](../../engine.go) 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
|
||||
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).
|
||||
|
||||
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](../integrations/openai-compatible-chat.md#timeout-and-cancellation)
|
||||
defines the complete timeout layering.
|
||||
## Prepare Without Model Execution
|
||||
|
||||
## Preparation And 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:
|
||||
|
||||
[`Engine.Prepare` and `Engine.Run`](../../engine.go) accept the public
|
||||
[`RunRequest`](../../types.go). `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
|
||||
```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)
|
||||
provides a complete runnable workflow using a prompt file, in-memory profile,
|
||||
and inline input.
|
||||
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).
|
||||
|
||||
[`PreparedRun` and `RunResult`](../../types.go) 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.
|
||||
## Execute And Validate
|
||||
|
||||
A generated-content validation failure returns a result with
|
||||
`Validation.Status == ValidationFailed`. An inability to perform validation
|
||||
returns an error matching `ErrValidation`.
|
||||
[`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.
|
||||
|
||||
## Requests, Inputs, And Overrides
|
||||
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.
|
||||
|
||||
The [request and value declarations](../../types.go) own the available fields,
|
||||
serialized constants, and result shapes. Use `File`, `Inline`, or
|
||||
`InlineWithURI` to construct artifact references. The
|
||||
[framework format reference](../formats.md) defines declared inputs, template
|
||||
references, output contracts, and the relationship between file values and
|
||||
request overrides.
|
||||
## Inputs, Profiles, And 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## Profiles And Credentials
|
||||
For programmatic profiles,
|
||||
[`OpenAICompatibleProfile`](../../profiles.go) converts ordinary
|
||||
OpenAI-compatible settings into a value accepted by `WithProfiles`.
|
||||
|
||||
[`OpenAICompatibleProfile`](../../profiles.go) 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.
|
||||
## Credentials
|
||||
|
||||
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](../formats.md).
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
The [`LLMClient`, `GenerateRequest`, and
|
||||
`GenerateResponse`](../../types.go) 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.
|
||||
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.
|
||||
|
||||
The [`ArtifactReader`](../../types.go) 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.
|
||||
## Handle Errors
|
||||
|
||||
Extensions should honor context cancellation and avoid logging raw prompts,
|
||||
artifacts, or credentials.
|
||||
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.
|
||||
|
||||
## Errors
|
||||
|
||||
The [public error declarations](../../engine.go) and
|
||||
[mapping](../../errors.go) 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
|
||||
## Application 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.
|
||||
API, process configuration, or deployment policy. Applications map the root
|
||||
package's results and errors into those concerns.
|
||||
|
||||
@@ -57,47 +57,15 @@ that is currently ambiguous.
|
||||
- [x] Confirm the supported JSON Schema dialect and reference boundaries,
|
||||
including whether remote references are allowed.
|
||||
|
||||
The resolved contract is:
|
||||
The selected exported API contracts are implemented and tested. Their durable
|
||||
definitions now belong to the root package declarations and GoDoc.
|
||||
|
||||
- `RunRequest.Metadata` had no observable purpose and has been removed from the
|
||||
public and internal request values.
|
||||
- One engine supports overlapping `Prepare` and `Run` calls. Built-in
|
||||
collaborators satisfy that contract; injected collaborators may be called
|
||||
concurrently and therefore share responsibility for concurrency safety.
|
||||
- Options are applied in order. Within each prompt-source, profile-source,
|
||||
in-memory-profile, schema-source, model-client, or artifact-reader category,
|
||||
the last non-nil valid option replaces the earlier value for that category.
|
||||
An invalid earlier option still makes construction fail.
|
||||
- The supported JSON values are `PreparedRun`, `RunResult`, `Artifact`,
|
||||
`ExecutionTarget`, `OutputContract`, `ValidationResult`, `TokenUsage`,
|
||||
`RenderedPrompt`, `RenderedMessage`, `CacheControl`,
|
||||
`StructuredOutputSpec`, `StructuredOutputJSONSpec`, `GenerateRequest`,
|
||||
`GenerateResponse`, `ExecutionTargetPresence`, and the public string value
|
||||
types used by them. Construction inputs such as `Config`, `RunRequest`,
|
||||
`ArtifactRef`, `ExecutionTargetOverride`, `Profile`, and
|
||||
`OpenAICompatibleProfileConfig` do not have stable JSON representations.
|
||||
Request-scoped API keys remain excluded from JSON as a security guarantee,
|
||||
including on otherwise unsupported construction values.
|
||||
- JSON timestamps use `time.Time`'s RFC 3339 representation and are omitted
|
||||
when zero. Both prepared and completed run durations use integer
|
||||
milliseconds in `duration_ms` and are omitted when zero. A prepared duration
|
||||
measures preparation only; a run-result duration measures the complete run,
|
||||
including its preparation, generation, and validation.
|
||||
- Run IDs, prompt hashes, rendered-prompt hashes, input hashes, and artifact
|
||||
hashes are non-empty correlation or equality values where produced. Their
|
||||
spelling, length, character set, and algorithm are opaque and not stable
|
||||
formats.
|
||||
- The built-in transport timeout defaults to 10 minutes. A zero or negative
|
||||
`Config.Timeout` selects that default. A supplied HTTP client's positive
|
||||
timeout takes precedence; its zero or negative timeout inherits the positive
|
||||
configured timeout or the default. These transport semantics are independent
|
||||
of caller cancellation and per-generation timeout settings.
|
||||
- JSON Schema uses Draft 2020-12; omission of `$schema` selects that dialect
|
||||
and an explicit different dialect is rejected. Same-document fragment
|
||||
references are supported. Relative references may load other schema
|
||||
documents only within a configured directory or `fs.FS` schema root.
|
||||
A single-file schema source supports only references contained in that
|
||||
document. Absolute, escaping, and remote references are not allowed.
|
||||
One format-level decision remains here until Stage 5 moves it to the framework
|
||||
format reference: JSON Schema uses Draft 2020-12, with that dialect selected
|
||||
when `$schema` is omitted. Same-document fragments and relative references
|
||||
contained by a directory or `fs.FS` schema root are supported. A single-file
|
||||
source supports only references contained in that document. Absolute,
|
||||
escaping, and remote references are rejected.
|
||||
|
||||
**Gate:** Each question has an explicit answer backed by existing behavior or
|
||||
by an accepted implementation change and proportionate tests. No later stage
|
||||
@@ -108,21 +76,21 @@ should invent a contract merely to fill a documentation gap.
|
||||
Strengthen the root package declarations so `go doc` is sufficient to
|
||||
understand exact public behavior without relying on internal documents.
|
||||
|
||||
- [ ] Add useful field-level GoDoc to configuration, request, profile,
|
||||
- [x] Add useful field-level GoDoc to configuration, request, profile,
|
||||
execution-target, result, artifact, validation, structured-output, and model
|
||||
client values.
|
||||
- [ ] Document required fields and nil, empty, and zero-value semantics.
|
||||
- [ ] Document override, replacement, profile-precedence, and copy-ownership
|
||||
- [x] Document required fields and nil, empty, and zero-value semantics.
|
||||
- [x] Document override, replacement, profile-precedence, and copy-ownership
|
||||
behavior where it belongs to the exported API.
|
||||
- [ ] Document credential inputs, redaction, and the values intentionally
|
||||
- [x] Document credential inputs, redaction, and the values intentionally
|
||||
excluded from serialization.
|
||||
- [ ] Give each public error sentinel an accurate comment and document the
|
||||
- [x] Give each public error sentinel an accurate comment and document the
|
||||
supported `errors.Is` relationships.
|
||||
- [ ] Document engine concurrency and option-composition behavior selected in
|
||||
- [x] Document engine concurrency and option-composition behavior selected in
|
||||
Stage 1.
|
||||
- [ ] Document serialization, time, run-ID, and hash semantics selected in
|
||||
- [x] Document serialization, time, run-ID, and hash semantics selected in
|
||||
Stage 1.
|
||||
- [ ] Review constructor, option, extension-interface, `Prepare`, and `Run`
|
||||
- [x] Review constructor, option, extension-interface, `Prepare`, and `Run`
|
||||
GoDoc for complete failure and cancellation expectations.
|
||||
|
||||
Update the [consumer guide](../consumers/pkg-promptkit.md) to summarize and link
|
||||
|
||||
Reference in New Issue
Block a user