yera.ui.rendering.forms

Render schema-backed settings controls and parse their submissions.

Rendering starts from Yera's inlined form schema and escapes labels, descriptions, option values, errors, and current values while assembling controls. Parsing is a separate boundary: submitted values are normalized by their declared Python annotations and then validated by Pydantic.

Excluded fields are neither rendered nor accepted. Disabled fields remain visible, but parsing ignores submitted replacements and preserves their existing values when an existing model is supplied.

Symbols

def inference_form_policy — Restrict reasoning controls to the selected model's capabilities.
class InferenceFormPolicy — Restrict inference controls to capabilities supported by a model.
def parse_model_form — Normalize submitted settings values into a validated Pydantic model.
def render_model_fields — Render editable settings controls for a Pydantic model.
def render_schema_fields — Render trusted controls from an inlined Yera form schema.

inference_form_policy

inference_form_policy(
    capabilities: LLMCapabilities | None,
) → InferenceFormPolicy

Restrict reasoning controls to the selected model's capabilities.

Effort controls remain enabled only for effort-based reasoning models and, when declared, use the model's supported reasoning levels. Budget controls remain enabled only for budget-based reasoning models. Unknown capabilities disable both controls rather than assuming support.

Parameters

capabilities
type: LLMCapabilities | None

Capabilities advertised by the selected model, or None when no capability record is available.

Returns

type: InferenceFormPolicy

Disabled fields and runtime-restricted choices for its inference form.

InferenceFormPolicy

Restrict inference controls to capabilities supported by a model.

Fields

disabled
type: frozenset[str] (required)

Fields shown for context but unavailable for editing.

choices
type: collections.abc.Mapping[str, tuple[object, ...]] (required)

Per-field option subsets advertised by the active model.

Methods


InferenceFormPolicy.__init__

__init__(
    disabled: frozenset[str],
    choices: Mapping[str, tuple[object, ...]],
) → None

parse_model_form

parse_model_form(
    model_type: type[ModelT],
    form: Mapping[str, object],
    exclude: frozenset[str] = frozenset(),
    disabled: frozenset[str] = frozenset(),
    existing: ModelT | None = None,
) → ModelT

Normalize submitted settings values into a validated Pydantic model.

Parsing supports the scalar settings controls exposed by render_model_fields. Excluded fields are ignored. Disabled fields ignore submitted values and retain their values from existing. Missing checkboxes become False, blank optional strings become None, and multiline string lists are stripped and emptied lines removed.

Pydantic performs the final type conversion and model validation. Rendering errors from nested runtime forms are outside this settings-specific parser.

Parameters

model_type
type: type[ModelT]

Pydantic model class defining the accepted settings.

form
type: Mapping[str, object]

Submitted form values keyed by schema field name.

exclude
type: frozenset[str] = frozenset()

Field names that must not be read.

disabled
type: frozenset[str] = frozenset()

Field names whose submitted values must be ignored.

existing
type: ModelT | None = None

Existing model providing values for disabled fields.

Returns

type: ModelT

A validated instance of model_type.

Raises

TypeError

If existing has another model type, or a field or submitted value uses an unsupported representation.

pydantic.ValidationError

If normalized values fail model validation.

render_model_fields

render_model_fields(
    model: BaseModel,
    id_prefix: str,
    exclude: frozenset[str] = frozenset(),
    disabled: frozenset[str] = frozenset(),
    choices: Mapping[str, tuple[object, ...]] | None = None,
) → TrustedHTML

Render editable settings controls for a Pydantic model.

Every included model field must provide a title and description. The model is converted through Yera's form-schema boundary, checked against the settings widget subset, and then rendered by render_schema_fields.

Parameters

model
type: BaseModel

Model containing current validated values.

id_prefix
type: str

Prefix used to create unique HTML control identifiers.

exclude
type: frozenset[str] = frozenset()

Field names omitted from the form.

disabled
type: frozenset[str] = frozenset()

Field names shown but unavailable for editing or submission.

choices
type: Mapping[str, tuple[object, ...]] | None = None

Optional per-field option subsets supplied by runtime capabilities.

Returns

type: TrustedHTML

Trusted HTML containing escaped controls for supported model fields.

Raises

ValueError

If an included field lacks a title or description.

TypeError

If an included field uses an unsupported settings widget.

render_schema_fields

render_schema_fields(
    schema: Mapping[str, JsonValue],
    values: Mapping[str, JsonValue],
    id_prefix: str,
    exclude: frozenset[str] = frozenset(),
    disabled: frozenset[str] = frozenset(),
    choices: Mapping[str, tuple[object, ...]] | None = None,
    errors: Mapping[str, list[str]] | None = None,
    readonly: bool = False,
) → TrustedHTML

Render trusted controls from an inlined Yera form schema.

The renderer selects controls from each field's schema and UI metadata, escapes all schema-derived labels and values, and supports nested groups, repeated rows, variants, validation messages, and runtime-restricted choices. Read-only rendering shows secrets only as set or unset.

Parameters

schema
type: Mapping[str, JsonValue]

Inlined form schema produced by form_schema.

values
type: Mapping[str, JsonValue]

Current JSON-compatible values keyed by field name. A missing value falls back to its schema default.

id_prefix
type: str

Prefix used to create unique HTML control identifiers.

exclude
type: frozenset[str] = frozenset()

Dotted field paths omitted from the rendered output.

disabled
type: frozenset[str] = frozenset()

Dotted field paths shown but unavailable for editing or submission.

choices
type: Mapping[str, tuple[object, ...]] | None = None

Optional per-field option subsets supplied by runtime capabilities.

errors
type: Mapping[str, list[str]] | None = None

Validation messages keyed by dotted field path.

readonly
type: bool = False

Render values as a record without editable row controls.

Returns

type: TrustedHTML

Trusted HTML containing escaped, schema-derived form controls.

Raises

TypeError

If a schema field uses a widget the renderer does not support.