Documentation
¶
Overview ¶
Package encoding provides a pluggable framework to describe, encode and decode structured data for agentic flows. It is primarily used to:
- Generate “format instructions” from a Go type that can be embedded in prompts to guide LLMs to return well‑structured outputs.
- Marshal/Unmarshal LLM outputs to/from Go structs using JSON, YAML, TOML or custom encoders.
- Optionally validate decoded outputs using struct validation tags.
The package exposes SchemaEncoder implementations for popular formats and a generic TypedOutputParser[T] that leverages an encoder to parse LLM output directly into a target Go type.
Example: Generate format instructions and parse JSON output
package encoding
// Define the expected shape of the model response.
type Weather struct {
City string `json:"city" jsonschema:"description=City name"`
TempC int `json:"temp_c" jsonschema:"description=Temperature in Celsius"`
}
// Create a JSON‑Schema based parser and obtain instructions to include in a prompt.
parser, err := NewTypedOutputParser(Weather{}, ModeJSONSchema)
if err != nil {
// handle error
}
// Put this in your prompt so the LLM knows how to format its output.
instructions := parser.GetFormatInstructions()
// Later, parse the model output into the typed struct.
// For example, given a model output like:
// {"city":"Paris","temp_c":22}
res, err := parser.Parse(`{"city":"Paris","temp_c":22}`)
if err != nil {
// handle parse/validation error
}
_ = res // use *Weather
Example: Switch to YAML or TOML while keeping the same Go type
_ = func() error {
_, err := NewTypedOutputParser(Weather{}, ModeYAML) // or ModeTOML
return err
}
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ModeDefault = ModeJSONSchema
ModeDefault is the default mode for the encoder. Applications may override it.
Functions ¶
func NewSimpleOutputParser ¶
func NewSimpleOutputParser() chatmodel.OutputParser[chatmodel.String]
NewSimpleOutputParser constructs a new SimpleOutputParser.
Types ¶
type Mode ¶
type Mode = string
Mode defines the encoding/decoding strategy and schema style used for instructing and parsing model outputs.
const ( // ModeJSON marshals/unmarshals using plain JSON. ModeJSON Mode = "json" // ModeJSONSchema generates JSON Schema‑based instructions and uses JSON. ModeJSONSchema Mode = "json_schema" // ModeJSONSchemaStrict enforces required properties (provider support varies). ModeJSONSchemaStrict Mode = "json_schema_strict" // ModeYAML marshals/unmarshals using YAML. ModeYAML Mode = "yaml" // ModeTOML marshals/unmarshals using TOML. ModeTOML Mode = "toml" // ModePlainText accepts raw text without structure. ModePlainText Mode = "plain_text" // ModeCustom is reserved for application‑provided encoders. ModeCustom Mode = "custom" )
type SchemaEncoder ¶
type SchemaEncoder interface {
// Marshal encodes a value into the underlying wire format (e.g. JSON).
Marshal(req any) ([]byte, error)
// Unmarshal decodes data in the underlying wire format into the provided
// destination value (pointer required for structs/slices/maps).
Unmarshal([]byte, any) error
// GetFormatInstructions returns instructions (often including a schema)
// that can be embedded in prompts to guide LLM output formatting.
GetFormatInstructions() string
}
SchemaEncoder describes a codec that can marshal/unmarshal values and produce human‑readable “format instructions” describing the expected output schema for prompting.
func PredefinedSchemaEncoder ¶
func PredefinedSchemaEncoder(mode Mode, req any) (SchemaEncoder, error)
PredefinedSchemaEncoder returns a SchemaEncoder for a given Mode and example value (used to derive schema). For structured modes it inspects the provided value's type to build an appropriate schema for prompt instructions.
Returns an error if the mode is not recognized.
type SchemaStreamEncoder ¶
type SchemaStreamEncoder interface {
// Read consumes text chunks and produces decoded values on the returned
// channel until the context is done or the input closes.
Read(context.Context, <-chan string) <-chan any
// GetFormatInstructions returns instructions to guide streaming output.
GetFormatInstructions() string
// EnableValidate enables validation of decoded values if supported.
EnableValidate()
}
SchemaStreamEncoder describes a streaming decoder for incremental model outputs. Implementations read from a stream of text chunks and emit decoded values when enough data is available.
type SimpleOutputParser ¶
type SimpleOutputParser struct{}
SimpleOutputParser is a no‑op output parser that returns trimmed text. It is useful when you want to surface raw model output without imposing any structure.
func (*SimpleOutputParser) GetFormatInstructions ¶
func (p *SimpleOutputParser) GetFormatInstructions() string
GetFormatInstructions returns an empty string because no structure is enforced.
func (*SimpleOutputParser) Parse ¶
func (p *SimpleOutputParser) Parse(text string) (*chatmodel.String, error)
Parse trims whitespace and returns the result as chatmodel.String.
func (*SimpleOutputParser) Type ¶
func (p *SimpleOutputParser) Type() string
Type returns a stable identifier for this parser.
type TypedOutputParser ¶
type TypedOutputParser[T any] struct { // contains filtered or unexported fields }
TypedOutputParser parses output from an LLM into Go structs. By providing NewTypedOutputParser with a struct value, a schema is generated to help LLMs format responses with the desired structure.
func NewTypedOutputParser ¶
func NewTypedOutputParser[T any](sourceType T, mode Mode) (*TypedOutputParser[T], error)
NewTypedOutputParser creates an output parser that structures data according to a given schema, as defined by struct field names and types. Tagging the field with "json" will explicitly use that value as the field name. Tagging with "describe" will add a line comment for the LLM to understand how to generate data, helpful when the field's name is insufficient.
func (*TypedOutputParser[T]) GetFormatInstructions ¶
func (p *TypedOutputParser[T]) GetFormatInstructions() string
GetFormatInstructions returns a string describing the format of the output.
func (*TypedOutputParser[T]) Parse ¶
func (p *TypedOutputParser[T]) Parse(text string) (*T, error)
Parse parses the output of an LLM call.
func (*TypedOutputParser[T]) Type ¶
func (p *TypedOutputParser[T]) Type() string
Type returns the string type key uniquely identifying this class of parser
func (*TypedOutputParser[T]) WithValidation ¶
func (p *TypedOutputParser[T]) WithValidation(validate bool)
WithValidation enables or disables validation for parsed outputs when the underlying encoder supports it.
Source Files
Directories