Documentation
¶
Overview ¶
Package generation is kb's client for the generation model: short literals (summaries, aliases, criteria, drafts) over OpenRouter chat completions with a strict JSON schema and reasoning disabled. It shares the run budget and the receipts log with internal/decisions; every literal it returns is still validated by the caller's code before use.
Index ¶
Constants ¶
const ( ReasonInvalidOutput = "invalid_output" ReasonTimeout = decisions.ReasonTimeout ReasonRetries = decisions.ReasonRetries ReasonHTTPStatus = decisions.ReasonHTTPStatus ReasonBudget = decisions.ReasonBudget )
Failure reasons recorded in receipts and wrapped in ErrFailed.
Variables ¶
var ( // ErrNotConfigured is returned by New when no OpenRouter API key is set. ErrNotConfigured = errors.New("generation: OPENROUTER_API_KEY is not set; the generation model is required ([generation] + [openrouter])") // ErrBudget is returned when the shared run budget is exhausted before a // call; nothing is sent. ErrBudget = errors.New("generation: run budget exhausted") // ErrFailed is returned when every attempt on every model failed; the // wrapped message names the last reason. ErrFailed = errors.New("generation: no valid output") // ErrInvalidOutput is wrapped together with ErrFailed when the last // failure was output that failed the schema or the request's Validate // hook, so callers can report it as undecided:invalid_output. ErrInvalidOutput = errors.New("generation: invalid output") // ErrInvalidRequest marks a request that cannot be sent (missing kind, // prompt, schema name, or a schema that is not a JSON object schema). ErrInvalidRequest = errors.New("generation: invalid request") // ErrExcluded is returned, without any call, for a request whose // Subject matches the topic's `decisions.exclude` globs (spec §14). ErrExcluded = errors.New("generation: subject excluded by decisions.exclude") )
Functions ¶
func DedupeStrings ¶
DedupeStrings trims values, drops empty ones and case-insensitive duplicates, and keeps the first spelling in the original order.
func ValidateLiteral ¶
ValidateLiteral checks one generated literal: non-empty, no leading or trailing whitespace, no line breaks, and at most maxLen runes (maxLen ≤ 0 disables the length check).
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client generates schema-checked JSON. It is safe for concurrent use.
func (*Client) Generate ¶
Generate returns the model's JSON output for req, validated against the top level of req.Schema. Identical requests (models, system, prompt, schema) are served from the topic's receipts. Each model gets 1+retries attempts under the per-attempt deadline, then the fallback model gets the same. Errors: ErrBudget (nothing sent), ErrFailed (every attempt failed), decisions.ErrAuth (401/402/403, sticky), ErrInvalidRequest, ErrExcluded (Subject matches req.Topic.Exclude; nothing sent), ctx errors.
func (*Client) Summary ¶
func (c *Client) Summary() decisions.GenerationSummary
Summary returns the client's part of the run summary; set it as decisions.Summary.Generation before printing Summary.Lines.
type Options ¶
type Options struct {
Config config.GenerationConfig
APIKey string
APIURL string
HTTPClient *http.Client
Budget *decisions.Budget
Receipts *decisions.Receipts
Now func() time.Time
Sleep func(ctx context.Context, d time.Duration) error
Logger *slog.Logger
}
Options configure a Client. Only Config and APIKey are required. Share Budget and Receipts with the decision engine (Engine.Budget, Engine.Receipts) so a run has one ceiling and one log per topic.
type Request ¶
type Request struct {
// Topic locates the receipts log (Topic.Root) and records the contract.
Topic decisions.TopicRef
// Kind names the literal (summary, aliases, criterion, contract_draft,
// ...); receipts record purpose "generate:<kind>".
Kind string
// Subject is the document path or id, for receipts.
Subject string
System string
Prompt string
// SchemaName and Schema form the strict json_schema response format. The
// schema must describe a JSON object.
SchemaName string
Schema json.RawMessage
// Validate, when set, runs the caller's domain checks on schema-valid
// output before it is accepted. Rejected output counts as
// invalid_output: the attempt is retried, then the fallback model is
// tried, and it is never recorded as decided, so the receipts cache
// never serves it. Cached output is re-checked too. It must be a pure
// function of the output.
Validate func(json.RawMessage) error
}
Request is one generation request.
Source Files