Help us shape the future of Go! Take the 2026 Go Developer Survey

params

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package params owns generation parameter definitions, values, and adjustment.

Index

Constants

View Source 
const (
	BoundMaxForm            = "max %s"
	BoundMinForm            = "min %s"
	BoundsAndValuesConflict = "size bounds and allowed values both declared"
	NegativeMaxMultipleForm = "negative maxMultiple %d"
	RangeBoundNegative      = "negative range bound"
	RangeInverted           = "minValue %s exceeds maxValue %s"
	ReasonModelLimits       = "%s limits"
	ReasonSupersededBySize  = "superseded by Size %s"
	ValuesAndRangeConflict  = "allowed values and a range both declared"
)

The internal/params section of the copy catalog, one constant per entry.

Variables

This section is empty.

Functions

func Adjust 

func Adjust(inputs FlagInputs, definitions Definitions, modelLabel string) (Values, []Adjustment, error)

Adjust applies model parameter definitions and returns request values and adjustment notices. It leaves supplied inputs unchanged and returns completed values and notices on failure; modelLabel identifies the model in notices and conflicting-constraint errors.

func CheckFlagInputTypes 

func CheckFlagInputTypes(inputs FlagInputs, paramFlags []Flag) error

CheckFlagInputTypes rejects the first stored input that differs from its declared Go type. Repeatable flags require a string slice; inputs without a flag definition are not checked.

func ConstraintFault 

func ConstraintFault(param *Definition) string

ConstraintFault returns the first constraint error in a parameter configuration, or an empty string when it is valid.

func FormatValue 

func FormatValue(paramVal any) string

FormatValue returns the textual representation of a parameter value.

func GuidanceMissing 

func GuidanceMissing(paramCfg *Definition, paramFlag *Flag) bool

GuidanceMissing reports whether a parameter lacks declared constraints and flag value guidance. Boolean flags need no value guidance.

func ParseDimensions 

func ParseDimensions(size string) (parsedWidth, parsedHeight int, isValid bool)

ParseDimensions takes WxH dimensions and returns positive width and height values and whether parsing succeeded.

func ParseValue 

func ParseValue(dataType DataType, rawValue string) (any, error)

ParseValue parses parameter text according to the requested data type and returns its typed value.

func PickSize 

func PickSize(sizes []string, landscape bool, tierH int, requestedRatio Nullable[float64]) string

PickSize selects declared dimensions by orientation, nearest short edge, nearest supplied ratio, and declaration order. If the requested orientation has no candidate, it considers both orientations.

func Value 

func Value[T any](paramVals map[FlagType]any, param FlagType) (T, error)

Value reads a typed parameter, returning its zero value when absent. A stored value of another type returns ErrParamValueTypeMismatch naming the parameter.

Types

type Adjustment 

type Adjustment struct {
	FlagID   FlagType `json:"flagID"`
	Type     Change   `json:"type"`
	InputVal string   `json:"inputVal"`
	WireVal  string   `json:"wireVal"`
	Comment  string   `json:"comment"`
}

Adjustment records one adjustment to a supplied generation parameter.

  • FlagID: the parameter that is adjusted
  • Type: the kind of adjustment
  • InputVal: the value supplied by the user
  • WireVal: the resulting value
  • Comment: additional user-facing detail about the adjustment

type Change 

type Change string

Change identifies how a generation parameter was altered. 

const (
	ChangeSnapped   Change = "snapped"
	ChangeDropped   Change = "dropped"
	ChangeRejected  Change = "rejected"
	ChangeCapped    Change = "capped"
	ChangeRaised    Change = "raised"
	ChangeForced    Change = "forced"
	ChangeDerived   Change = "derived"
	ChangeConformed Change = "conformed"
	ChangeIgnored   Change = "ignored"
)

Change values identify the supported parameter adjustments.

  • ChangeSnapped: replaced by the nearest supported value
  • ChangeDropped: omitted because the supplied value could not be used
  • ChangeRejected: omitted because the supplied value was not allowed
  • ChangeCapped: reduced to a maximum value
  • ChangeRaised: increased to a minimum value
  • ChangeForced: replaced by a provider-required value
  • ChangeDerived: calculated from another supplied value
  • ChangeConformed: altered to match a model requirement
  • ChangeIgnored: omitted because another value superseded it or the model does not use it

type DataType 

type DataType string

DataType identifies a parameter value's data type. 

const (
	DataString  DataType = "string"
	DataNumber  DataType = "number"
	DataInteger DataType = "integer"
	DataBoolean DataType = "boolean"
)

Parameter value data types.

  • DataString: text values
  • DataNumber: floating-point values
  • DataInteger: integer values
  • DataBoolean: boolean values

type Definition 

type Definition struct {
	ParamID          string            `json:"paramID,omitempty"`
	FlagID           FlagType          `json:"flagID"`
	Required         bool              `json:"required,omitempty"`
	AllowedValues    []string          `json:"allowedValues,omitempty"`
	MinValue         Nullable[float64] `json:"minValue,omitzero"`
	MaxValue         Nullable[float64] `json:"maxValue,omitzero"`
	MaxMultiple      int               `json:"maxMultiple,omitempty"`
	CustomSize       *SizeBounds       `json:"customSize,omitempty"`
	RuleDescription  string            `json:"ruleDescription,omitempty"`
	ModelInfoComment string            `json:"modelInfoComment,omitempty"`
}

Definition contains a model's provider mapping and constraints for one parameter.

  • ParamID: the provider request key, or empty when request code handles the parameter
  • FlagID: the command flag that supplies the parameter
  • AllowedValues: the accepted parameter values
  • MinValue: the optional minimum numeric value
  • MaxValue: the optional maximum numeric value
  • MaxMultiple: the maximum number of values accepted for a repeatable parameter
  • CustomSize: the optional constraints for free-form dimensions
  • RuleDescription: the user-facing description of a parameter adjustment rule
  • ModelInfoComment: expanded model-specific guidance appended on the model's details page
  • Required: whether the provider's documentation names the parameter as required; a record declaring nothing is optional

The encoding carries only what a record declares: the request key and every constraint are absent when empty, and an unset bound is absent rather than null.

type Definitions 

type Definitions []Definition

Definitions contains the declared parameter configurations for a model.

func (Definitions) Param 

func (definitions Definitions) Param(flag FlagType) (Definition, bool)

Param returns a flag's declared configuration and whether it exists.

type Flag 

type Flag struct {
	FlagID        FlagType `json:"flagID"`
	FlagName      string   `json:"flagName"`
	DataType      DataType `json:"dataType"`
	Aliases       []string `json:"aliases,omitempty"`
	Description   string   `json:"description"`
	ExampleValues []string `json:"exampleValues,omitempty"`
	Comment       string   `json:"comment,omitempty"`
	TextHint      string   `json:"textHint,omitempty"`
	AllowMultiple bool     `json:"allowMultiple,omitempty"`
}

Flag describes a generation parameter's identifier, accepted names, type, and help text.

  • FlagID: the parameter's canonical flag name
  • FlagName: the parameter name shown to users ("Duration", "Aspect ratio")
  • DataType: the parameter's value type
  • Aliases: alternate flag names
  • Description: the parameter description shown in help output
  • ExampleValues: example values shown in help output
  • Comment: additional parameter guidance shown in help output
  • TextHint: the value placeholder shown in help output
  • AllowMultiple: whether the parameter accepts multiple values

The encoding carries only what a record declares: an empty alias list, example list, comment, or hint is absent.

func Flags 

func Flags() []Flag

Flags returns generation parameter records in declaration order. Each call creates independent records that callers may modify.

type FlagInputs 

type FlagInputs map[FlagType]any

FlagInputs maps supplied parameter names to their parsed values.

func (FlagInputs) Supplied 

func (userInputs FlagInputs) Supplied(flag FlagType) bool

Supplied reports whether a parameter has a meaningful supplied value. Thought output requires true, and input media requires at least one source.

type FlagType 

type FlagType string

FlagType identifies a generation parameter by its command flag name. 

const (
	FlagTypeAspect        FlagType = "aspect-ratio"
	FlagTypeResolution    FlagType = "resolution"
	FlagTypeQuality       FlagType = "quality"
	FlagTypeThinkingLevel FlagType = "thinking-level"
	FlagTypeThoughts      FlagType = "include-thoughts"
	FlagTypeDuration      FlagType = "duration"
	FlagTypeImageN        FlagType = "num-images"
	FlagTypeOutputFormat  FlagType = "output-format"
	FlagTypeInputMedia    FlagType = "input-media"
	FlagTypeSize          FlagType = "size"
)

Parameter names identify the generation values that models may accept.

  • FlagTypeAspect: the requested aspect ratio
  • FlagTypeResolution: the requested resolution
  • FlagTypeQuality: the requested quality
  • FlagTypeThinkingLevel: the requested thinking level
  • FlagTypeThoughts: whether provider thoughts are requested
  • FlagTypeDuration: the requested video duration
  • FlagTypeImageN: the requested number of images
  • FlagTypeOutputFormat: the requested image format
  • FlagTypeInputMedia: an input-media path
  • FlagTypeSize: the requested width and height

type Nullable 

type Nullable[T any] struct {
	// contains filtered or unexported fields
}

Nullable distinguishes an explicitly supplied value from absence.

  • value: the stored value, including its type's zero value
  • isSet: whether a value was explicitly supplied

func GetSetIf 

func GetSetIf[T any](provided bool, val T) Nullable[T]

GetSetIf returns a set Nullable only when provided is true.

func (Nullable[T]) MarshalJSON 

func (n Nullable[T]) MarshalJSON() ([]byte, error)

MarshalJSON encodes the stored value, or the JSON null token when none was set.

func (*Nullable[T]) UnmarshalJSON 

func (n *Nullable[T]) UnmarshalJSON(data []byte) error

UnmarshalJSON replaces n with the decoded value, or clears it for null. An invalid value returns a decoding error without changing n.

func (Nullable[T]) ValIf 

func (n Nullable[T]) ValIf() (T, bool)

ValIf returns the stored value and whether it was set.

func (Nullable[T]) ValOr 

func (n Nullable[T]) ValOr(defaultVal T) T

ValOr returns the stored value or defaultVal when unset.

type SizeBounds 

type SizeBounds struct {
	MaxRatio   float64 `json:"maxRatio,omitempty"`
	MinEdge    int     `json:"minEdge,omitempty"`
	MaxEdge    int     `json:"maxEdge,omitempty"`
	MinPx      int     `json:"minPx,omitempty"`
	MaxPx      int     `json:"maxPx,omitempty"`
	EdgeIncrem int     `json:"edgeIncrem,omitempty"`
	LongEdge   int     `json:"longEdge,omitempty"`
}

SizeBounds contains constraints for free-form image dimensions.

  • MaxRatio: the maximum ratio between the longer and shorter edges
  • MinEdge: the minimum shorter edge
  • MaxEdge: the maximum longer edge
  • MinPx: the minimum pixel count
  • MaxPx: the maximum pixel count
  • EdgeIncrem: the required increment for each edge
  • LongEdge: the longer edge used to derive dimensions from an aspect ratio

type Values 

type Values map[FlagType]any

Values maps parameter names to values that are ready for a provider request.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.