outschema

package
v0.54.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package outschema implements the output contract of `suga run --output-schema` and sugasdk.Prompt.OutputSchema (design docs/design/2026-10-22-output-schema-design.md): compile a caller's JSON Schema in a sandbox, extract JSON from a model answer, check it, and render what a report, a trace event and a correction message need.

The package is pure: no store, no runner, no I/O beyond what a caller hands in. A schema is treated as data - it never loads external resources and nothing in it is executed.

Index

Constants

View Source
const (
	// KindSize: the schema is bigger than MaxSchemaBytes.
	KindSize = "size"
	// KindTopLevel: the schema is neither a JSON object nor a boolean.
	KindTopLevel = "toplevel"
	// KindSyntax: the schema is not JSON at all.
	KindSyntax = "syntax"
	// KindExternalRef: the schema refers to a resource that is not inline.
	KindExternalRef = "external_ref"
	// KindUnknownDraft: $schema names a draft this compiler does not know.
	KindUnknownDraft = "unknown_draft"
	// KindInvalidSchema: the schema does not satisfy its meta schema.
	KindInvalidSchema = "invalid_schema"
)

Compile error kinds; the entry layer reports them as usage errors (exit 2).

View Source
const (
	// SourceWhole: the whole answer is the JSON value.
	SourceWhole = "whole"
	// SourceFenced: a fenced code block (“`json or unlabelled) holds it.
	SourceFenced = "fenced"
	// SourceSubstring: a balanced {...}/[...] inside the prose holds it.
	SourceSubstring = "substring"
	// SourceNone: the answer holds no JSON value (reported as no_json).
	SourceNone = "no_json"
)

Sources of a checked JSON value; they are reported to the caller and in the trace event, so the caller never has to guess (design 3.3).

View Source
const (
	// MaxErrors caps the errors a report, a trace event and a correction message
	// carry: a small schema can produce hundreds of them.
	MaxErrors = 8
	// MaxErrorChars caps one error message: a meta-schema message can be long.
	MaxErrorChars = 200
)
View Source
const (
	// MaxSchemaBytes caps one contract (design 6.2): the schema travels with
	// every request of the call, so a bigger one would cost more context than it
	// buys; splitting it into inline $defs is the caller's remedy.
	MaxSchemaBytes = 32 << 10
)

Variables

This section is empty.

Functions

func CorrectionText

func CorrectionText(res Result) string

CorrectionText is the injected turn that hands a failing check back to the model: the errors only - the answer and the schema are already in its context - plus the one way to answer (design 4.2).

func PromptBlock

func PromptBlock(schema []byte) string

PromptBlock is the ephemeral context block of one request: the contract, with its boundary spelled out. It is never stored in the session (design 4.2).

Types

type CompileError

type CompileError struct {
	Kind    string
	Message string
	// Params are the values of the placeholders of a translated line of Kind (url,
	// draft, detail, limit, actual): the display layer renders Kind + Params in the
	// UI language, while Message stays the same text for sugasdk and its callers.
	Params map[string]any
}

CompileError is a schema the caller has to fix before a turn may start. Message is one line: the entry layer prints it as is when it has no translated line for Kind.

func (*CompileError) Error

func (e *CompileError) Error() string

type Contract

type Contract struct {
	// contains filtered or unexported fields
}

Contract is one compiled caller schema.

func Compile

func Compile(raw []byte) (*Contract, error)

Compile validates and compiles a caller schema. The returned error is always a *CompileError; every failure is a usage error of the caller, not a bug.

func (*Contract) Check

func (c *Contract) Check(answer string) Result

Check extracts JSON from answer in the fixed order of design 3.3 and checks every candidate until one satisfies the schema. A failing check reports the errors of the last candidate (the likeliest final answer).

func (*Contract) Raw

func (c *Contract) Raw() []byte

Raw is the schema text the contract was compiled from (trimmed), for the per-request context block.

type Error

type Error struct {
	// Path is the JSON path of the offending value, e.g. $, $.items[0].id. A
	// numeric object key renders as an index (known, harmless: the path only
	// feeds text and the trace, never the decision).
	Path string
	// Message is the localized reason, one line, at most MaxErrorChars runes.
	Message string
}

Error is one validation problem of a checked answer.

func (Error) String

func (e Error) String() string

String renders the error the way reports print it: "$: missing property ...".

type Result

type Result struct {
	// Passed: a candidate satisfied the schema.
	Passed bool
	// Source says where the checked value came from (whole/fenced/substring);
	// no_json means the answer held no JSON value at all.
	Source string
	// Value is the passing candidate's raw JSON, compacted.
	Value json.RawMessage
	// Errors are the problems of the last candidate tried (empty on success).
	Errors []Error
}

Result is the outcome of checking one answer against a contract.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL