yera 0.5.0

yr.Struct

Inherits: BaseModel
Subclasses: Condition

Base class for structured-generation specs.

Subclass Struct to declare the shape of a value the LLM should produce, then call fill on the subclass to generate a populated instance from a prompt.

Unknown fields are rejected at construction time: structs are intended to be fixed in structure, separating data (the struct) from behaviour (defined elsewhere). Passing fields not declared on the subclass raises a ValidationError.

Examples

python
class Person(Struct):
    name: str
    age: int
    occupation: str

bio = "Dr. John Smith is a 36-year-old data scientist."

Person.fill(bio)

Person(name='John Smith', age=36, occupation='data scientist')

Methods

__init_subclass__ — Initialise subclass with an expects result field populated.
expects_result — Return whether this struct expects an LLM result.
get_tool_name — Return the tool name (class name) used when calling the LLM.
get_call_id — Return the stored tool call ID, or raise if unset.
set_call_id — Set the tool call ID for this struct instance.
fill — Generate an instance of this struct from a prompt.
form — Ask the user to fill in this struct as a form.
__hash__ — Hash by field values, recursively freezing containers.
model_json_schema — Return the JSON schema for this struct with extra strictness applied.

Struct.__init_subclass__

__init_subclass__(
    expects_result: bool = False,
    **kwargs,
) → None

Initialise subclass with an expects result field populated.

Struct.expects_result

expects_result() → bool

Return whether this struct expects an LLM result.

Struct.get_tool_name

get_tool_name() → str

Return the tool name (class name) used when calling the LLM.

Struct.get_call_id

get_call_id() → str

Return the stored tool call ID, or raise if unset.

Returns

type: str

The call ID string assigned via set_call_id.

Raises

ValueError

If no call ID has been set (__call_id__ is None).

Struct.set_call_id

set_call_id(
    call_id: str,
) → None

Set the tool call ID for this struct instance.

Parameters

call_id
type: str

String identifier assigned by the LLM tool-calling API.

Struct.fill

fill(
    instruction: str | None = None,
    on_wire: bool = False,
    **kwargs,
) → Self

Generate an instance of this struct from a prompt.

Sends the prompt to the active LLM and parses its response into an instance of the calling subclass.

Parameters

instruction
type: str | None = None

extra prompt instruction to inform struct generation.

on_wire
type: bool = False

whether the llm text output from this fill is included back in the context.

**kwargs
type: str | int | float | bool

Additional options forwarded to the underlying LLM (e.g. provider-specific generation parameters).

Returns

type: Self

An instance of the calling subclass, populated from the LLM's response.

Struct.form

form(
    label: str | None = None,
) → Self

Ask the user to fill in this struct as a form.

Each field is presented with a widget suited to its type. Submissions that fail validation are shown again with their errors until one is valid.

Parameters

label
type: str | None = None

Optional question shown above the form.

Returns

type: Self

An instance of the calling subclass built from the accepted submission.

Examples

python
class Deploy(Struct):
    service: str
    replicas: int = 1

Deploy.form("Deploy which service?")

Struct.__hash__

__hash__() → int

Hash by field values, recursively freezing containers.

Allows Struct instances to be used as members in hashable containers and as dict keys. Mutating fields after hashing will make the instance unfindable in the collection; treat hashed structs as immutable.

Struct.model_json_schema

model_json_schema(
    by_alias: bool = True,
    ref_template: str = DEFAULT_REF_TEMPLATE,
    schema_generator: type[GenerateJsonSchema] = _StrictSchema,
    mode: JsonSchemaMode = 'validation',
    union_format: Literal['any_of', 'primitive_type_array'] = 'any_of',
) → dict

Return the JSON schema for this struct with extra strictness applied.

Overridden to ensure all nested objects have additionalProperties: false.

Returns

type: dict

A JSON schema dict with additionalProperties: false for all objects.