teff.schema

teff.schema

Lightweight JSON Schema validation for structured LLM output.

Constitution Principle VI: minimal dependencies. This module provides a compact JSON Schema subset — objects, arrays, primitives, enum, oneOf, and string/number limits — implemented with stdlib only, so no jsonschema or Pydantic dependency is required.

The subset covers the practical shapes an LLM is asked to produce:

• {"type": "object", "properties": {...}, "required": [...]}
• {"type": "array", "items": {...}, "minItems"/"maxItems"}
• primitives with enum, minimum/maximum, minLength/maxLength/pattern
• oneOf / anyOf for unions and nullable fields (both are treated as alternative branches, so schemas produced by Pydantic's model_json_schema() — which emits anyOf for Optional — validate as expected)

Functions:

Name	Description
extract_json_object	Return the balanced JSON object starting at text[start] == '{'.
json_schema_from_type	Build a JSON Schema from a Python type spec.
parse_json_object	Extract and parse a JSON value from LLM output.
validate_json	Validate value against schema.

extract_json_object

extract_json_object(text, start)

Return the balanced JSON object starting at text[start] == '{'.

Source code in teff/schema.py

def extract_json_object(text: str, start: int) -> str | None:
    """Return the balanced JSON object starting at ``text[start] == '{'``."""
    depth = 0
    in_str = False
    esc = False
    for i in range(start, len(text)):
        c = text[i]
        if in_str:
            if esc:
                esc = False
            elif c == "\\":
                esc = True
            elif c == '"':
                in_str = False
            continue
        if c == '"':
            in_str = True
        elif c == "{":
            depth += 1
        elif c == "}":
            depth -= 1
            if depth == 0:
                return text[start : i + 1]
    return None

json_schema_from_type

json_schema_from_type(spec)

Build a JSON Schema from a Python type spec.

Accepts:

• a raw JSON Schema dict (returned unchanged);
• a dict[str, type] field map, e.g. {"name": str, "age": int};
• a TypedDict (or dataclass) class whose fields become properties.

Raises:

Type	Description
TypeError	If spec is none of the supported forms.

Source code in teff/schema.py

def json_schema_from_type(spec: Any) -> dict:
    """Build a JSON Schema from a Python type spec.

    Accepts:

    - a raw JSON Schema dict (returned unchanged);
    - a ``dict[str, type]`` field map, e.g.
      ``{"name": str, "age": int}``;
    - a ``TypedDict`` (or dataclass) class whose fields become
      ``properties``.

    Raises:
        TypeError: If *spec* is none of the supported forms.
    """
    if isinstance(spec, dict):
        if any(key in spec for key in ("type", "properties", "$schema")):
            return spec
        return {
            "type": "object",
            "properties": {k: _py_to_schema(v) for k, v in spec.items()},
            "required": list(spec.keys()),
        }
    if isinstance(spec, type):
        return _py_to_schema(spec)
    raise TypeError(f"cannot derive JSON Schema from {spec!r}")

parse_json_object

parse_json_object(content)

Extract and parse a JSON value from LLM output.

Tries json.loads on the whole text first, then falls back to the first balanced {...} object embedded in surrounding prose (a common failure mode for local models).

Returns:

Type	Description
Any	The parsed value.

Raises:

Type	Description
ValueError	If no valid JSON can be found in content.

Source code in teff/schema.py

def parse_json_object(content: str) -> Any:
    """Extract and parse a JSON value from LLM output.

    Tries ``json.loads`` on the whole text first, then falls back to the
    first balanced ``{...}`` object embedded in surrounding prose (a
    common failure mode for local models).

    Returns:
        The parsed value.

    Raises:
        ValueError: If no valid JSON can be found in *content*.
    """
    try:
        return json.loads(content)
    except json.JSONDecodeError:
        pass
    brace = content.find("{")
    while brace != -1:
        obj = extract_json_object(content, brace)
        if obj is not None:
            try:
                return json.loads(obj)
            except json.JSONDecodeError:
                brace = content.find("{", brace + 1)
                continue
        brace = content.find("{", brace + 1)
    raise ValueError("no valid JSON object found in LLM output")

validate_json

validate_json(value, schema)

Validate value against schema.

Returns:

Type	Description
list[str]	A list of human-readable error strings. An empty list means the
list[str]	value conforms to the schema.

Source code in teff/schema.py

def validate_json(value: Any, schema: dict) -> list[str]:
    """Validate *value* against *schema*.

    Returns:
        A list of human-readable error strings.  An empty list means the
        value conforms to the schema.
    """
    errors: list[str] = []
    _validate("$", value, schema, errors)
    return errors