yr.Struct
BaseModelConditionBase 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
Extract structured information from a short biography:
import yera as yr
class Person(yr.Struct):
name: str
age: int
occupation: str
biography = "Dr. John Smith is a 36-year-old data scientist."
person = Person.fill(instruction=f"Extract details from: {biography}")
Methods
Struct.__init_subclass__
__init_subclass__(
expects_result: bool = False,
**kwargs,
) → NoneInitialize a struct subclass and normalize its annotations.
Parameters
Whether instances are expected as LLM tool results.
Pydantic model configuration inherited by the subclass.
Struct.expects_result
expects_result() → boolReturn whether this struct expects an LLM result.
Returns
Whether the struct is configured as a result type.
Struct.get_tool_name
get_tool_name() → strReturn the tool name used when calling the LLM.
Returns
The struct class name.
Struct.get_call_id
get_call_id() → strReturn the stored tool call ID, or raise if unset.
Returns
The call ID string assigned via set_call_id.
Raises
If no call ID has been set (__call_id__ is None).
Struct.set_call_id
set_call_id(
call_id: str,
) → NoneSet the tool call ID for this struct instance.
Parameters
String identifier assigned by the LLM tool-calling API.
Struct.fill
fill(
instruction: str | None = None,
on_wire: bool = False,
**kwargs,
) → SelfGenerate 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
Optional instruction describing the value to generate.
Whether the generated structured response should remain in the conversation sent with later model requests.
Provider-specific generation options forwarded to the
active LLM, such as temperature.
Returns
An instance of the calling subclass, populated from the LLM's response.
Examples
Generate a structured fact with explicit model controls:
import yera as yr
class CountryFact(yr.Struct):
country: str
capital: str
population: int
fact = CountryFact.fill(
instruction="Describe Spain.",
on_wire=True,
temperature=0,
)
Struct.form
form(
label: str | None = None,
cancel_label: str | None = None,
) → Self | NoneAsk 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 or the user cancels.
Parameters
Optional question shown above the form.
Optional label for an action that returns None
without validating the form.
Returns
An instance built from the accepted submission, or None when cancellation is enabled and selected.
Examples
Present a form that the user may leave without submitting:
import yera as yr
class TripRequest(yr.Struct):
destination: str
travellers: int = 1
request = TripRequest.form(
"Plan a trip",
cancel_label="Not now",
)
if request is None:
yr.markdown("No trip was planned.")
Struct.__hash__
__hash__() → intHash 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.
Returns
A hash derived recursively from the struct's field values.
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',
) → dictReturn the JSON schema for this struct with extra strictness applied.
Overridden to ensure all nested objects have additionalProperties: false.
Parameters
Whether field aliases should be used as schema keys.
Template used for generated schema references.
JSON Schema generator implementation.
Whether to generate validation or serialization schema.
Representation used for primitive unions.
Returns
A JSON schema dict with additionalProperties: false for all objects.