structured

Documentation

Overview

Package structured implements a LangChain-v1 style structured output framework for Go. It mirrors langchain's ResponseFormat with ToolStrategy, ProviderStrategy, and AutoStrategy, plus schema compilation and validation.

Index

• Variables
• func ToolSchemaFor(s Strategy) map[string]any
• func Validate(r *ResponseFormat) error
• type AutoStrategy
  • func NewAuto(schema Schema) *AutoStrategy
  • func (a *AutoStrategy) Kind() string
  • func (a *AutoStrategy) Schema() Schema
• type MultipleOutputsError
  • func (e *MultipleOutputsError) Error() string
• type ProviderStrategy
  • func NewProvider(schema Schema) *ProviderStrategy
  • func (p *ProviderStrategy) Kind() string
  • func (p *ProviderStrategy) Schema() Schema
• type ResponseFormat
  • func NewResponseFormat(s Strategy) *ResponseFormat
• type Schema
• type Strategy
  • func ResolveAuto(r *ResponseFormat, supportsProvider bool) Strategy
• type ToolStrategy
  • func NewTool(schema Schema) *ToolStrategy
  • func (t *ToolStrategy) Kind() string
  • func (t *ToolStrategy) Schema() Schema
• type ValidationError
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) Unwrap() error

Variables

var ErrInvalidSchema = errors.New("structured: invalid schema")

ErrInvalidSchema is returned when a schema cannot be compiled.

Functions

func ToolSchemaFor

func ToolSchemaFor(s Strategy) map[string]any

ToolSchemaFor returns the tool binding schema for a ToolStrategy. This is the schema wrapped as a tool whose output is the structured response.

func Validate

func Validate(r *ResponseFormat) error

Validate checks the response format for internal consistency.

Types

type AutoStrategy

type AutoStrategy struct {
	SchemaDoc   Schema
	Name        string
	Description string
}

AutoStrategy selects ToolStrategy or ProviderStrategy at runtime based on the model's capabilities.

func NewAuto

func NewAuto(schema Schema) *AutoStrategy

NewAuto builds an AutoStrategy from a schema.

func (*AutoStrategy) Kind

func (a *AutoStrategy) Kind() string

Kind implements Strategy.

func (*AutoStrategy) Schema

func (a *AutoStrategy) Schema() Schema

Schema implements Strategy.

type MultipleOutputsError

type MultipleOutputsError struct {
	ToolNames []string
}

MultipleOutputsError is returned when a ToolStrategy produced more than one structured tool call.

func (*MultipleOutputsError) Error

func (e *MultipleOutputsError) Error() string

type ProviderStrategy

type ProviderStrategy struct {
	SchemaDoc   Schema
	Name        string
	Description string
}

ProviderStrategy drives structured output using provider-native structured output (e.g. OpenAI json_schema, Anthropic). Only providers that support it can use it.

func NewProvider

func NewProvider(schema Schema) *ProviderStrategy

NewProvider builds a ProviderStrategy from a schema.

func (*ProviderStrategy) Kind

func (p *ProviderStrategy) Kind() string

Kind implements Strategy.

func (*ProviderStrategy) Schema

func (p *ProviderStrategy) Schema() Schema

Schema implements Strategy.

type ResponseFormat

type ResponseFormat struct {
	Strategy Strategy
}

ResponseFormat wraps a strategy and the schema it applies to.

func NewResponseFormat

func NewResponseFormat(s Strategy) *ResponseFormat

NewResponseFormat wraps a strategy into a ResponseFormat.

type Schema

type Schema = map[string]any

Schema is a JSON Schema document (Draft 2020-12) used to constrain output.

type Strategy

type Strategy interface {
	// Kind returns the strategy kind: "tool", "provider", or "auto".
	Kind() string
	// Schema returns the JSON schema the strategy constrains output to.
	Schema() Schema
}

Strategy is the interface implemented by all structured output strategies.

func ResolveAuto

func ResolveAuto(r *ResponseFormat, supportsProvider bool) Strategy

ResolveAuto selects the strategy to use for a given model. If the strategy is Auto and the model supports provider-native structured output, a Provider strategy is returned; otherwise a Tool strategy.

type ToolStrategy

type ToolStrategy struct {
	SchemaDoc          Schema
	Name               string
	Description        string
	ToolMessageContent string
	// HandleErrors controls retry behavior on validation failure. nil means
	// default (retry with a generic error message).
	HandleErrors any
}

ToolStrategy drives structured output by binding the schema to a tool and asking the model to call it. It works across all providers.

func NewTool

func NewTool(schema Schema) *ToolStrategy

NewTool builds a ToolStrategy from a schema.

func (*ToolStrategy) Kind

func (t *ToolStrategy) Kind() string

Kind implements Strategy.

func (*ToolStrategy) Schema

func (t *ToolStrategy) Schema() Schema

Schema implements Strategy.

type ValidationError

type ValidationError struct {
	SchemaName string
	Cause      error
}

ValidationError is returned when a model output does not match the schema.

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error