Documentation
¶
Index ¶
- Variables
- func Clean(id string) string
- func CloneSchema(schema map[string]any) map[string]any
- func CompleteJSON(jsonStr string) string
- func ConvertTo[T any](v any) (T, bool)
- func ConvertToExact[T any](v any) (T, error)
- func ExtractJSON(text string) (any, error)
- func ExtractJSONFromMarkdown(md string) string
- func GetJSONObjectLines(text string) []string
- func HasJSONValue(raw json.RawMessage) bool
- func InferJSONSchema(x any) *jsonschema.Schema
- func IsNil[T any](v T) bool
- func JSONString(x any) string
- func MapToStruct[T any](m map[string]any) (T, error)
- func NormalizeInput(data any, schema map[string]any) (any, error)
- func ParsePartialJSON(jsonStr string) (any, error)
- func PrettyJSONString(x any) string
- func PromptStateFromContext(ctx context.Context) any
- func ReadJSONFile(filename string, pvalue any) error
- func SchemaAsMap(s *jsonschema.Schema) map[string]any
- func SchemaMapFor[T any]() map[string]any
- func StructToMap[T any](v T) (map[string]any, error)
- func UnmarshalAndNormalize[T any](input json.RawMessage, schema map[string]any) (T, error)
- func UnmarshalAndNormalizeWith[T any](input json.RawMessage, schema map[string]any, compiled *CompiledSchema) (T, error)
- func ValidJSON(s string) bool
- func ValidateIsJSONArray(schema map[string]any) bool
- func ValidateJSON(dataBytes json.RawMessage, schema map[string]any) error
- func ValidateRaw(dataBytes json.RawMessage, schemaBytes json.RawMessage) error
- func ValidateValue(data any, schema map[string]any) error
- func WalkSubschemas(schema map[string]any, visit func(map[string]any) map[string]any)
- func WithPromptState(ctx context.Context, getState func() any) context.Context
- func WriteJSONFile(filename string, value any) error
- func Zero[T any]() T
- type CompiledSchema
- type ContextKey
- type Environment
- type ExtractItemsResult
Constants ¶
This section is empty.
Variables ¶
var ErrTypeMismatch = errors.New("type mismatch")
ErrTypeMismatch reports that a value's Go type cannot be reinterpreted as the requested type in ConvertToExact.
This package cannot classify it, since core/status depends on this one. A caller that surfaces the failure past the framework boundary must attach a sentinel users can match, as ai.ErrInputTypeMismatch does.
var ToolChunkSenderKey = NewContextKey[func(context.Context, any)]()
ToolChunkSenderKey is the context key for streaming raw model response chunks from within a tool. Set by ai/generate.go (handleToolRequests), read by ai/exp/tool (SendChunk). The any value is *ai.ModelResponseChunk (typed as any to avoid a circular import).
var ToolPartialSenderKey = NewContextKey[func(context.Context, any)]()
ToolPartialSenderKey is the context key for streaming partial tool responses. Set by ai/generate.go (handleToolRequests), read by ai/exp/tool (SendPartial).
Functions ¶
func CloneSchema ¶ added in v1.12.0
CloneSchema returns a deep copy of schema, so a transform applied to the result cannot reach the caller's map. Values other than nested schemas and their arrays are the scalars JSON decodes to, which are immutable.
func CompleteJSON ¶ added in v1.3.0
CompleteJSON attempts to complete an incomplete JSON string. The result is always valid JSON.
Containers are closed innermost first, so an object nested in an array is closed before the array. A string value cut off mid-stream is kept and closed, minus any dangling escape sequence, and a truncated keyword is finished because only one keyword can start with a given letter. A tail that cannot be finished without inventing a value is dropped instead: a half-written key, a key whose value has not arrived yet, or a truncated number such as "1.".
Input that is malformed rather than truncated is cut back to the last position that was still well formed, which is why the grammar is tracked at all: a trailing comma before a closer, a container opened where a key belongs, or a raw control character inside a string all end the scan and take everything after them with it.
func ConvertTo ¶ added in v1.10.0
ConvertTo is ConvertToExact for callers that only need to know whether the conversion was possible.
func ConvertToExact ¶ added in v1.12.0
ConvertToExact converts a dynamically typed value to T.
It accepts a value that is already a T, a *T (a nil pointer yields the zero value), or a value in the JSON wire form the framework's transports produce (map[string]any, []any, a scalar), which it decodes into T. A nil value yields the zero value.
Reinterpreting one struct as an unrelated struct is refused with an error wrapping ErrTypeMismatch: a JSON round-trip between two unrelated structs succeeds while leaving every field zero, so the caller would otherwise get a blank value instead of a diagnosis.
When T cannot carry JSON's types on its own, meaning T is an interface or a map, slice or array whose elements are, the decoded value is normalized against the schema inferred from v (see NormalizeInput) so that an integer stays an int64 instead of widening to float64. That is what the reflection API does to action input, so a value reaches T with the same Go types whichever way it arrived. It also drops null-valued keys, as the wire does.
func ExtractJSON ¶ added in v1.3.0
ExtractJSON extracts JSON from string with lenient parsing rules. It handles both complete and partial JSON structures.
func ExtractJSONFromMarkdown ¶ added in v0.1.0
ExtractJSONFromMarkdown returns the contents of the first fenced code block in the markdown text md. It matches code blocks with "json" identifier (case-insensitive) or code blocks without any language identifier. If there is no matching block, it returns md.
func GetJSONObjectLines ¶ added in v1.0.5
GetJSONObjectLines splits a string by newlines, trims whitespace from each line, and returns a slice containing only the lines that start with '{'.
func HasJSONValue ¶ added in v1.10.0
func HasJSONValue(raw json.RawMessage) bool
HasJSONValue reports whether raw carries an actual JSON value: it is non-empty and not the JSON null literal, ignoring surrounding whitespace.
func InferJSONSchema ¶
func InferJSONSchema(x any) *jsonschema.Schema
InferJSONSchema infers a JSON schema from a Go value.
Recursion is detected by stack: while a struct type T is being reflected, T is marked in-progress. Any nested encounter of T (a self-reference) returns an "any" schema; T is unmarked when its reflection completes. Each top-level occurrence of T (siblings, repeats) gets its own full reflection — so a struct used in multiple fields produces the correct schema each time.
We can't observe reflection completion through the library's Mapper hook alone, so each struct type is reflected via a sub-Reflector. The Mapper's defer fires when the sub-Reflector returns, which is the exit point.
func IsNil ¶ added in v1.4.0
IsNil returns true if v is nil or a nil pointer/interface/map/slice/channel/func.
func JSONString ¶
JSONString returns json.Marshal(x) as a string. If json.Marshal returns an error, jsonString returns the error text as a JSON string beginning "ERROR:".
func MapToStruct ¶ added in v1.4.0
MapToStruct converts a map[string]any to a struct of type T via JSON round-trip.
func NormalizeInput ¶ added in v1.0.4
NormalizeInput recursively traverses a data structure and performs normalization: 1. Removes any fields with null values 2. Converts instances of float64 into int64 or float64 based on the schema's "type" property
func ParsePartialJSON ¶ added in v1.3.0
ParsePartialJSON attempts to parse incomplete JSON by completing it.
func PrettyJSONString ¶ added in v0.1.0
PrettyJSONString returns json.MarshalIndent(x, "", " ") as a string. If json.MarshalIndent returns an error, jsonString returns the error text as a JSON string beginning "ERROR:".
func PromptStateFromContext ¶ added in v1.10.0
PromptStateFromContext returns the state attached by WithPromptState, or nil if none is attached. The getter is invoked on each call.
func ReadJSONFile ¶
ReadJSONFile JSON-decodes the contents of filename into pvalue, which must be a pointer.
func SchemaAsMap ¶ added in v0.1.0
func SchemaAsMap(s *jsonschema.Schema) map[string]any
SchemaAsMap converts json schema struct to a map (JSON representation). The map is rebuilt from JSON on every call, so the caller owns it and may mutate it in place; memoizing the result here would break callers that do.
func SchemaMapFor ¶ added in v1.12.0
SchemaMapFor returns the JSON schema inferred from type T as a map, or nil for interface types (e.g. `any`), whose zero value carries no type information to infer from. Like SchemaAsMap, the returned map is freshly built on every call and belongs to the caller.
func StructToMap ¶ added in v1.4.0
StructToMap converts a struct to map[string]any via JSON round-trip.
func UnmarshalAndNormalize ¶ added in v1.1.0
UnmarshalAndNormalize unmarshals JSON input, normalizes it according to the schema, validates it, and converts it to the target type T. For 'any' types, it preserves the actual types from the normalized data. For structured types, it marshals and unmarshals to properly populate the fields.
func UnmarshalAndNormalizeWith ¶ added in v1.10.0
func UnmarshalAndNormalizeWith[T any](input json.RawMessage, schema map[string]any, compiled *CompiledSchema) (T, error)
UnmarshalAndNormalizeWith is UnmarshalAndNormalize with an optional precompiled schema: when compiled is non-nil, validation uses it instead of recompiling schema, which matters on per-chunk streaming hot paths. schema is still used for normalization and must describe the same schema.
func ValidateIsJSONArray ¶ added in v0.5.0
ValidateIsJSONArray will validate if the schema represents a JSON array.
func ValidateJSON ¶
func ValidateJSON(dataBytes json.RawMessage, schema map[string]any) error
ValidateJSON will validate JSON against the expected schema. It will return an error if it doesn't match the schema, otherwise it will return nil.
func ValidateRaw ¶
func ValidateRaw(dataBytes json.RawMessage, schemaBytes json.RawMessage) error
ValidateRaw will validate JSON data against the JSON schema. It will return an error if it doesn't match the schema, otherwise it will return nil.
func ValidateValue ¶
ValidateValue will validate any value against the expected schema. It will return an error if it doesn't match the schema, otherwise it will return nil.
func WalkSubschemas ¶ added in v1.12.0
WalkSubschemas replaces every subschema reachable from schema with visit's result: the members of properties, the items schema, a schema-valued additionalProperties, and the branches of anyOf, oneOf, and allOf, at every depth. Non-schema values (a boolean subschema, say) are left alone.
schema itself is not visited, since a transform that widens or annotates fields usually means something different for the root. Apply visit to it directly when it should be included.
func WithPromptState ¶ added in v1.10.0
WithPromptState returns ctx carrying a getter for the state exposed to prompt templates via {{@state}}. getState is evaluated lazily at render time, so it observes the latest state rather than a snapshot taken when the context was built. A nil getState detaches any state previously attached.
func WriteJSONFile ¶
WriteJSONFile writes value to filename as JSON.
Types ¶
type CompiledSchema ¶ added in v1.10.0
type CompiledSchema struct {
// contains filtered or unexported fields
}
CompiledSchema is a JSON schema precompiled for repeated validation, e.g. per-chunk validation on streaming transports, where recompiling the schema for every payload would dominate the hot path. A nil *CompiledSchema (from a nil schema) accepts every value, matching ValidateValue's nil handling.
func CompileSchema ¶ added in v1.10.0
func CompileSchema(schema map[string]any) (*CompiledSchema, error)
CompileSchema compiles schema for repeated validation with CompiledSchema.ValidateValue. A nil schema compiles to a nil CompiledSchema, which accepts every value.
func (*CompiledSchema) ValidateValue ¶ added in v1.10.0
func (c *CompiledSchema) ValidateValue(data any) error
ValidateValue validates data against the compiled schema, with the same behavior and error shape as ValidateValue.
type ContextKey ¶
type ContextKey[T any] struct { // contains filtered or unexported fields }
A ContextKey is a unique, typed key for a value stored in a context.
func NewContextKey ¶
func NewContextKey[T any]() ContextKey[T]
NewContextKey returns a context key for a value of type T.
func (ContextKey[T]) FromContext ¶
func (k ContextKey[T]) FromContext(ctx context.Context) T
FromContext returns the value associated with this key in the context, or the internal.Zero value for T if the key is not present.
func (ContextKey[T]) NewContext ¶
func (k ContextKey[T]) NewContext(ctx context.Context, value T) context.Context
NewContext returns ctx augmented with this key and the given value.
type Environment ¶
type Environment string
An Environment is the execution context in which the program is running.
const ( EnvironmentDev Environment = "dev" // development: testing, debugging, etc. EnvironmentProd Environment = "prod" // production: user data, SLOs, etc. )
type ExtractItemsResult ¶ added in v1.3.0
ExtractItemsResult contains the result of extracting items from an array.
func ExtractItems ¶ added in v1.3.0
func ExtractItems(text string, cursor int) ExtractItemsResult
ExtractItems extracts complete objects from the first array found in the text. Processes text from the cursor position and returns both complete items and the new cursor position.
Source Files