API Reference

Core pipeline

weirding

weirding public API: the XML <-> JSON Schema IR <-> Pydantic triangle.

Exports compile, from_schema, define_model, parse, to_xml, to_schema, and dump_xml — the full edge set of the triangle (ADR-0012).

compile(xml)

Convert an XML schema document to a JSON Schema IR dict.

The JSON Schema dict is the core product of weirding. It can be consumed directly (Databricks StructType, jsonschema.validate, OpenAPI specs) or passed to from_schema() to build a typed DTO.

Parameters:

Name	Type	Description	Default
xml	str | bytes	XML schema document using the plain-attribute annotation convention or XSD. XSD requires the weirding[xsd] extra.	required

Returns:

Type	Description
JsonSchemaIR	JSON Schema-compatible dict (draft 2020-12 subset). Array fields include
JsonSchemaIR	an x-weirding-item-tag extension key naming the child element tag.

Raises:

Type	Description
SchemaError	schema document is structurally invalid.
UnsupportedDialectError	dialect cannot be detected or is unsupported.
ParseError	xml is not well-formed.

Source code in src/weirding/__init__.py

def compile(xml: str | bytes) -> JsonSchemaIR:
    """Convert an XML schema document to a JSON Schema IR dict.

    The JSON Schema dict is the core product of weirding. It can be consumed
    directly (Databricks StructType, jsonschema.validate, OpenAPI specs) or
    passed to from_schema() to build a typed DTO.

    Args:
        xml: XML schema document using the plain-attribute annotation convention
             or XSD. XSD requires the weirding[xsd] extra.

    Returns:
        JSON Schema-compatible dict (draft 2020-12 subset). Array fields include
        an x-weirding-item-tag extension key naming the child element tag.

    Raises:
        SchemaError: schema document is structurally invalid.
        UnsupportedDialectError: dialect cannot be detected or is unsupported.
        ParseError: xml is not well-formed.

    """
    return compile_schema(xml)

define_model(xml, *, builder=None)

Compile XML then build a typed DTO, naming the type from the root element tag.

Equivalent to

schema = compile(xml) return from_schema(schema, name=, builder=builder)

Parameters:

Name	Type	Description	Default
xml	str | bytes	XML schema document (plain-attribute convention or XSD).	required
builder	DTOBuilder | None	DTOBuilder implementation. Defaults to PydanticBuilder().	None

Returns:

Type	Description
type	A new type produced by the builder.

Source code in src/weirding/__init__.py

def define_model(
    xml: str | bytes,
    *,
    builder: DTOBuilder | None = None,
) -> type:
    """Compile XML then build a typed DTO, naming the type from the root element tag.

    Equivalent to:
        schema = compile(xml)
        return from_schema(schema, name=<sanitized root element tag>, builder=builder)

    Args:
        xml:     XML schema document (plain-attribute convention or XSD).
        builder: DTOBuilder implementation. Defaults to PydanticBuilder().

    Returns:
        A new type produced by the builder.

    """
    schema = compile(xml)
    name = _sanitize_name(schema.get("title", "Model"))
    return from_schema(schema, name=name, builder=builder)

from_schema(schema, *, name='Model', builder=None)

from_schema(schema: JsonSchemaIR, *, name: str = ...) -> type[BaseModel]

from_schema(schema: JsonSchemaIR, *, name: str = ..., builder: None) -> type[BaseModel]

from_schema(schema: JsonSchemaIR, *, name: str = ..., builder: DTOBuilder) -> type

Build a typed DTO class from a JSON Schema IR dict.

With the default builder (PydanticBuilder), returns a Pydantic v2 BaseModel subclass. Pass a custom DTOBuilder to produce TypedDicts, dataclasses, Spark StructType wrappers, or any other typed container.

Parameters:

Name	Type	Description	Default
schema	JsonSchemaIR	JSON Schema dict as produced by compile() or any compatible source.	required
name	str	Class name for the generated type. Must be a valid Python identifier.	'Model'
builder	DTOBuilder | None	DTOBuilder implementation. Defaults to PydanticBuilder().	None

Returns:

Type	Description
type	A new type produced by the builder. Each call with a distinct schema produces
type	a distinct class; cache the result if calling in a hot path.

Raises:

Type	Description
SchemaError	schema cannot be converted to a valid typed class.

Source code in src/weirding/__init__.py

def from_schema(
    schema: JsonSchemaIR,
    *,
    name: str = "Model",
    builder: DTOBuilder | None = None,
) -> type:
    """Build a typed DTO class from a JSON Schema IR dict.

    With the default builder (PydanticBuilder), returns a Pydantic v2
    BaseModel subclass. Pass a custom DTOBuilder to produce TypedDicts,
    dataclasses, Spark StructType wrappers, or any other typed container.

    Args:
        schema:  JSON Schema dict as produced by compile() or any compatible source.
        name:    Class name for the generated type. Must be a valid Python identifier.
        builder: DTOBuilder implementation. Defaults to PydanticBuilder().

    Returns:
        A new type produced by the builder. Each call with a distinct schema produces
        a distinct class; cache the result if calling in a hot path.

    Raises:
        SchemaError: schema cannot be converted to a valid typed class.

    """
    return (builder or PydanticBuilder()).build(schema, name=name)

parse(xml, model)

Validate and bind LLM-produced XML against a compiled model.

Deserializes the XML element tree into a dict, then calls model.model_validate(dict) to produce a typed instance.

Parameters:

Name	Type	Description	Default
xml	str | bytes	XML data document (LLM output). Must be well-formed.	required
model	type[Validatable]	Any type satisfying the Validatable protocol — in practice a type produced by define_model() or from_schema().	required

Returns:

Type	Description
Any	A validated instance of model.

Raises:

Type	Description
ParseError	xml is malformed or fails model validation.

Source code in src/weirding/__init__.py

def parse(xml: str | bytes, model: type[Validatable]) -> Any:
    """Validate and bind LLM-produced XML against a compiled model.

    Deserializes the XML element tree into a dict, then calls
    model.model_validate(dict) to produce a typed instance.

    Args:
        xml:   XML data document (LLM output). Must be well-formed.
        model: Any type satisfying the Validatable protocol — in practice a
               type produced by define_model() or from_schema().

    Returns:
        A validated instance of model.

    Raises:
        ParseError: xml is malformed or fails model validation.

    """
    parser = make_parser()
    try:
        if isinstance(xml, str):
            root = etree.fromstring(xml.encode(), parser=parser)
        else:
            root = etree.fromstring(xml, parser=parser)
    except etree.XMLSyntaxError as exc:
        raise ParseError(str(exc)) from exc

    data = _xml_to_dict(root, model)  # type: ignore
    try:
        return model.model_validate(data)
    except PydanticValidationError as exc:
        raise ParseError(str(exc)) from exc

to_xml(instance)

Serialize a Pydantic model instance to an XML string.

Element tags map to field names, scalars become text content, objects become child elements, and lists are serialized as repeated child elements using the tag name from the original schema (x-weirding-item-tag).

Round-trip guarantee: parse(to_xml(x), type(x)) == x for any instance x produced by parse().

Parameters:

Name	Type	Description	Default
instance	BaseModel	Any Pydantic BaseModel instance, including dynamically generated ones.	required

Returns:

Type	Description
str	UTF-8 XML string without an XML declaration.

Source code in src/weirding/__init__.py

def to_xml(instance: BaseModel) -> str:
    """Serialize a Pydantic model instance to an XML string.

    Element tags map to field names, scalars become text content, objects become
    child elements, and lists are serialized as repeated child elements using the
    tag name from the original schema (x-weirding-item-tag).

    Round-trip guarantee: parse(to_xml(x), type(x)) == x for any instance x
    produced by parse().

    Args:
        instance: Any Pydantic BaseModel instance, including dynamically generated ones.

    Returns:
        UTF-8 XML string without an XML declaration.

    """
    return _to_xml(instance)

to_schema(model)

Derive a JSON Schema IR dict from a Pydantic v2 model class.

The reverse edge C → B — the inverse of from_schema() (ADR-0012). Rather than reimplementing type extraction, it normalizes model.model_json_schema() into weirding's IR, so it tracks Pydantic's own type → schema logic across releases.

Array properties that lack the x-weirding-item-tag extension key (hand-written models not built by weirding) receive a synthesized tag via the same singularization fallback used by to_xml() (tags → tag, else item), keyed on the property name. Models produced by from_schema() already carry the tag and are passed through unchanged. The required list is restored as [] on any object node where Pydantic omitted it, keeping the IR symmetric with compile().

$defs / $ref produced by Pydantic for nested models are left intact; resolving them is dump_xml()'s concern, not this one. Consequently to_schema(from_schema(ir)) equals ir only modulo $ref-inlining and the additive title / default keys Pydantic injects — exact dict equality is not guaranteed.

The model is never mutated; the function operates on a deep copy of Pydantic's schema output and returns a new dict.

Parameters:

Name	Type	Description	Default
model	type[BaseModel]	A Pydantic v2 BaseModel subclass.	required

Returns:

Type	Description
JsonSchemaIR	A new JSON Schema IR dict. May contain $defs / $ref when the model has
JsonSchemaIR	nested object fields.

Raises:

Type	Description
SchemaError	The model's schema contains prefixItems (a tuple field), which is unrepresentable in the IR (ADR-0004, MEMORY rule 11).

Source code in src/weirding/__init__.py

def to_schema(model: type[BaseModel]) -> JsonSchemaIR:
    """Derive a JSON Schema IR dict from a Pydantic v2 model class.

    The reverse edge C → B — the inverse of from_schema() (ADR-0012). Rather
    than reimplementing type extraction, it normalizes model.model_json_schema()
    into weirding's IR, so it tracks Pydantic's own type → schema logic across
    releases.

    Array properties that lack the x-weirding-item-tag extension key (hand-written
    models not built by weirding) receive a synthesized tag via the same
    singularization fallback used by to_xml() (tags → tag, else item), keyed on
    the property name. Models produced by from_schema() already carry the tag and
    are passed through unchanged. The required list is restored as [] on any
    object node where Pydantic omitted it, keeping the IR symmetric with compile().

    $defs / $ref produced by Pydantic for nested models are left intact; resolving
    them is dump_xml()'s concern, not this one. Consequently
    to_schema(from_schema(ir)) equals ir only modulo $ref-inlining and the additive
    title / default keys Pydantic injects — exact dict equality is not guaranteed.

    The model is never mutated; the function operates on a deep copy of Pydantic's
    schema output and returns a new dict.

    Args:
        model: A Pydantic v2 BaseModel subclass.

    Returns:
        A new JSON Schema IR dict. May contain $defs / $ref when the model has
        nested object fields.

    Raises:
        SchemaError: The model's schema contains prefixItems (a tuple field),
            which is unrepresentable in the IR (ADR-0004, MEMORY rule 11).

    """
    return _to_schema(model)

dump_xml(ir)

Serialize a JSON Schema IR dict to a canonical XML schema document.

The reverse edge B → A — the inverse of compile() (ADR-0012). It emits a canonical ADR-0001 plain-attribute annotation XML schema document from the public JsonSchemaIR dict.

Distinct from to_xml(): dump_xml(ir) serializes a JSON Schema IR into an XML schema document — the authoring format, the inverse of compile(). to_xml(instance) serializes a model instance into XML data — the inverse of parse(). One produces a schema you could re-author; the other produces a data payload.

The composition C → A (Pydantic model → XML schema document) is exactly dump_xml(to_schema(model)); no third function exists for it (ADR-0012).

Any local $ref / $defs are inlined first; the root element name is taken from ir['title'] (falling back to "Model"). The two nullable input shapes anyOf:[T, null] and type:[T, "null"] both map to nullable="true". format and additionalProperties are dropped (no annotation-convention equivalent); const is rejected.

The function is pure: it deep-copies its input, never mutates it, and performs no I/O, logging, or network access.

Parameters:

Name	Type	Description	Default
ir	JsonSchemaIR	A JSON Schema IR dict, as produced by compile() or any compatible source. Must be acyclic and free of non-null unions.	required

Returns:

Type	Description
str	A pretty-printed XML schema document using the ADR-0001 plain-attribute
str	annotation convention.

Raises:

Type	Description
SchemaError	The IR contains a construct with no annotation-convention representation — a non-null anyOf / oneOf / allOf, a const, or a cyclic / non-local / unresolvable $ref. The message names the offending construct.

Source code in src/weirding/__init__.py

def dump_xml(ir: JsonSchemaIR) -> str:
    """Serialize a JSON Schema IR dict to a canonical XML schema document.

    The reverse edge B → A — the inverse of compile() (ADR-0012). It emits a
    canonical ADR-0001 plain-attribute annotation XML *schema document* from the
    public JsonSchemaIR dict.

    Distinct from to_xml(): dump_xml(ir) serializes a **JSON Schema IR into an XML
    schema document** — the authoring format, the inverse of compile(). to_xml(instance)
    serializes a **model instance into XML data** — the inverse of parse(). One
    produces a schema you could re-author; the other produces a data payload.

    The composition C → A (Pydantic model → XML schema document) is exactly
    dump_xml(to_schema(model)); no third function exists for it (ADR-0012).

    Any local $ref / $defs are inlined first; the root element name is taken from
    ir['title'] (falling back to "Model"). The two nullable input shapes
    anyOf:[T, null] and type:[T, "null"] both map to nullable="true". format and
    additionalProperties are dropped (no annotation-convention equivalent); const
    is rejected.

    The function is pure: it deep-copies its input, never mutates it, and performs
    no I/O, logging, or network access.

    Args:
        ir: A JSON Schema IR dict, as produced by compile() or any compatible
            source. Must be acyclic and free of non-null unions.

    Returns:
        A pretty-printed XML schema document using the ADR-0001 plain-attribute
        annotation convention.

    Raises:
        SchemaError: The IR contains a construct with no annotation-convention
            representation — a non-null anyOf / oneOf / allOf, a const, or a
            cyclic / non-local / unresolvable $ref. The message names the
            offending construct.

    """
    return _dump_xml(ir)

Prompt utilities

weirding.prompt

Prompt engineering utilities for LLM structured-output retry workflows.

RetryContext

Stateful context for an LLM structured-output retry loop.

Tracks attempt count and accumulated errors so that format_error() can produce increasingly specific retry prompts without the caller managing state.

Source code in src/weirding/prompt.py

class RetryContext:
    """Stateful context for an LLM structured-output retry loop.

    Tracks attempt count and accumulated errors so that format_error()
    can produce increasingly specific retry prompts without the caller
    managing state.
    """

    def __init__(self, model: type[BaseModel], max_attempts: int = 3) -> None:
        """Initialize with the given model and an optional max-attempts limit."""
        self._model = model
        self._max_attempts = max_attempts
        self._attempt = 0
        self._last_message: str | None = None

    @property
    def attempt(self) -> int:
        """Return the current attempt number (0-based before first error)."""
        return self._attempt

    @property
    def exceeded(self) -> bool:
        """Return True if the maximum number of retry attempts has been reached."""
        return self._attempt >= self._max_attempts

    def record_error(self, error: Exception) -> None:
        """Record a validation error and increment the attempt counter."""
        self._attempt += 1
        self._last_message = format_error(error, model=self._model)

    def retry_message(self) -> str:
        """Return the formatted error message from the last recorded error."""
        return self._last_message or ""

attempt property

Return the current attempt number (0-based before first error).

exceeded property

Return True if the maximum number of retry attempts has been reached.

__init__(model, max_attempts=3)

Initialize with the given model and an optional max-attempts limit.

Source code in src/weirding/prompt.py

def __init__(self, model: type[BaseModel], max_attempts: int = 3) -> None:
    """Initialize with the given model and an optional max-attempts limit."""
    self._model = model
    self._max_attempts = max_attempts
    self._attempt = 0
    self._last_message: str | None = None

record_error(error)

Record a validation error and increment the attempt counter.

Source code in src/weirding/prompt.py

def record_error(self, error: Exception) -> None:
    """Record a validation error and increment the attempt counter."""
    self._attempt += 1
    self._last_message = format_error(error, model=self._model)

retry_message()

Return the formatted error message from the last recorded error.

Source code in src/weirding/prompt.py

def retry_message(self) -> str:
    """Return the formatted error message from the last recorded error."""
    return self._last_message or ""

to_template(model)

Generate an XML prompt template from a compiled Pydantic model.

Produces an XML document showing the expected element structure and field types, suitable for inclusion in an LLM system prompt. Scalar fields are rendered as {type}; objects as nested elements.

Parameters:

Name	Type	Description	Default
model	type[BaseModel]	A type[BaseModel] produced by define_model() or from_schema().	required

Returns:

Type	Description
str	XML string showing the expected output format.

Source code in src/weirding/prompt.py

def to_template(model: type[BaseModel]) -> str:
    """Generate an XML prompt template from a compiled Pydantic model.

    Produces an XML document showing the expected element structure and
    field types, suitable for inclusion in an LLM system prompt. Scalar
    fields are rendered as <field>{type}</field>; objects as nested elements.

    Args:
        model: A type[BaseModel] produced by define_model() or from_schema().

    Returns:
        XML string showing the expected output format.

    """
    root = etree.Element(model.__name__)
    _render_model_fields(root, model)
    return etree.tostring(root, encoding="unicode", pretty_print=True)

format_error(error, *, model)

Format a validation error into a natural-language retry instruction.

Converts pydantic.ValidationError (or weirding.ParseError wrapping one) into a human-readable description of what the LLM got wrong, suitable for appending to a retry prompt.

Parameters:

Name	Type	Description	Default
error	Exception	The exception raised by parse() on the failed attempt.	required
model	type[BaseModel]	The model that was being validated against. Used to provide field-level context in the error message.	required

Returns:

Type	Description
str	Plain text description of the validation failures.

Source code in src/weirding/prompt.py

def format_error(error: Exception, *, model: type[BaseModel]) -> str:
    """Format a validation error into a natural-language retry instruction.

    Converts pydantic.ValidationError (or weirding.ParseError wrapping one)
    into a human-readable description of what the LLM got wrong, suitable
    for appending to a retry prompt.

    Args:
        error: The exception raised by parse() on the failed attempt.
        model: The model that was being validated against. Used to provide
               field-level context in the error message.

    Returns:
        Plain text description of the validation failures.

    """
    # Unwrap ParseError — weirding raises ParseError(str(exc)) from exc
    if isinstance(error, ParseError) and isinstance(
        error.__cause__, _PydanticValidationError
    ):
        ve = error.__cause__
    elif isinstance(error, _PydanticValidationError):
        ve = error
    else:
        return f"Unexpected error: {error}"

    lines = []
    for err in ve.errors(include_url=False, include_input=False, include_context=True):
        # PRIVACY: include_input=False is MANDATORY.
        # LLM output may contain user-submitted PII. Never echo input values
        # into retry messages — this violates CLAUDE.md privacy requirements.
        # Any future include_values=True opt-in requires explicit privacy review.
        path = _loc_to_path(err["loc"])
        msg = err["msg"]
        lines.append(f"  - {path}: {msg}" if path else f"  - {msg}")

    count = ve.error_count()
    noun = "error" if count == 1 else "errors"
    return f"The previous response had {count} validation {noun}:\n" + "\n".join(lines)

Protocols and types

weirding

weirding public API: the XML <-> JSON Schema IR <-> Pydantic triangle.

Exports compile, from_schema, define_model, parse, to_xml, to_schema, and dump_xml — the full edge set of the triangle (ADR-0012).

JsonSchemaIR = dict[str, Any] module-attribute

DTOBuilder

Bases: Protocol

Any type that can build a typed DTO class from a JSON Schema IR dict.

The default implementation is PydanticBuilder, which produces Pydantic v2 BaseModel subclasses. Custom implementations can produce TypedDicts, dataclasses, Spark StructType wrappers, or any other typed container.

Symmetric with Validatable: both ends of the pipeline are backend-neutral. Pydantic is the default, not the requirement.

Source code in src/weirding/__init__.py

@runtime_checkable
class DTOBuilder(Protocol):
    """Any type that can build a typed DTO class from a JSON Schema IR dict.

    The default implementation is PydanticBuilder, which produces Pydantic v2
    BaseModel subclasses. Custom implementations can produce TypedDicts,
    dataclasses, Spark StructType wrappers, or any other typed container.

    Symmetric with Validatable: both ends of the pipeline are backend-neutral.
    Pydantic is the default, not the requirement.
    """

    def build(self, schema: JsonSchemaIR, *, name: str) -> type:
        """Build and return a DTO class from the given JSON Schema IR."""
        ...

build(schema, *, name)

Build and return a DTO class from the given JSON Schema IR.

Source code in src/weirding/__init__.py

def build(self, schema: JsonSchemaIR, *, name: str) -> type:
    """Build and return a DTO class from the given JSON Schema IR."""
    ...

PydanticBuilder

Default DTOBuilder — produces Pydantic v2 BaseModel subclasses.

json-schema-to-pydantic. Patches applied:

• schema["additionalProperties"] == False → model_config extra="forbid"
• prefixItems must never appear in schema (enforced by _schema.py)

Source code in src/weirding/__init__.py

class PydanticBuilder:
    """Default DTOBuilder — produces Pydantic v2 BaseModel subclasses.

    Engine: json-schema-to-pydantic. Patches applied:
      - schema["additionalProperties"] == False  →  model_config extra="forbid"
      - prefixItems must never appear in schema (enforced by _schema.py)
    """

    def build(self, schema: JsonSchemaIR, *, name: str = "Model") -> type[BaseModel]:
        """Build a Pydantic BaseModel subclass from the given JSON Schema IR."""
        from weirding._models import build_model

        return build_model(schema, name=name)

build(schema, *, name='Model')

Build a Pydantic BaseModel subclass from the given JSON Schema IR.

Source code in src/weirding/__init__.py

def build(self, schema: JsonSchemaIR, *, name: str = "Model") -> type[BaseModel]:
    """Build a Pydantic BaseModel subclass from the given JSON Schema IR."""
    from weirding._models import build_model

    return build_model(schema, name=name)

Validatable

Bases: Protocol

Any type that can validate a dict into a typed instance.

Satisfied by every Pydantic BaseModel subclass. Accepting a Protocol instead of BaseModel directly keeps parse() open to non-Pydantic backends (TypeAdapter wrappers, Spark schema validators, etc.) without an API change.

Source code in src/weirding/__init__.py

@runtime_checkable
class Validatable(Protocol):
    """Any type that can validate a dict into a typed instance.

    Satisfied by every Pydantic BaseModel subclass. Accepting a Protocol
    instead of BaseModel directly keeps parse() open to non-Pydantic backends
    (TypeAdapter wrappers, Spark schema validators, etc.) without an API change.
    """

    @classmethod
    def model_validate(cls, obj: dict[str, Any]) -> Any:
        """Validate data dict and return a model instance."""
        ...

model_validate(obj) classmethod

Validate data dict and return a model instance.

Source code in src/weirding/__init__.py

@classmethod
def model_validate(cls, obj: dict[str, Any]) -> Any:
    """Validate data dict and return a model instance."""
    ...

Exceptions

weirding

weirding public API: the XML <-> JSON Schema IR <-> Pydantic triangle.

Exports compile, from_schema, define_model, parse, to_xml, to_schema, and dump_xml — the full edge set of the triangle (ADR-0012).

WeirdingError

Bases: Exception

Source code in src/weirding/_exceptions.py

class WeirdingError(Exception):
    pass

SchemaError

Bases: WeirdingError

Source code in src/weirding/_exceptions.py

class SchemaError(WeirdingError):
    pass

ParseError

Bases: WeirdingError

Source code in src/weirding/_exceptions.py

class ParseError(WeirdingError):
    pass

UnsupportedDialectError

Bases: WeirdingError

Source code in src/weirding/_exceptions.py

class UnsupportedDialectError(WeirdingError):
    pass