Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

12.0 KB
Raw Blame
"""Random schemas inside the structured-output subset, and an independent view
of them for tests.

The generators draw from a seeded ``random.Random`` and use only the standard
library. :class:`RNode` is built here from the caller's schema without any help
from the code under test, so a test that reads it does not share a mistake
with that code.
"""

from __future__ import annotations

import random
from dataclasses import dataclass, field
from typing import Any

STR_POOL = ["open", "closed", "approved", "rejected", "a", "b", "x"]
# How deep the root object nests.
MAX_DEPTH = 4


def gen_schema(rng: random.Random) -> dict[str, Any]:
    """A schema that passes the structural checks.

    Entries of ``$defs`` the root cannot reach are dropped, because every entry
    must be reachable.
    """
    defs: dict[str, Any] = {}
    plain_defs: list[str] = []  # usable as the value branch of a nullable union
    for i in range(rng.randint(0, 3)):
        name = f"d{i}"
        node = _gen_node(rng, 2, defs, plain_defs, allow_nullable=rng.random() < 0.3)
        defs[name] = node
        if isinstance(node.get("type"), str):
            plain_defs.append(name)
    root = _gen_object(rng, MAX_DEPTH, defs, plain_defs, nprops=rng.randint(1, 5))
    reachable = _reachable_defs(root, defs)
    kept = {name: node for name, node in defs.items() if name in reachable}
    if kept:
        root["$defs"] = kept
    return root


def _refs_in(node: Any) -> list[str]:
    found: list[str] = []
    if isinstance(node, dict):
        if "$ref" in node:
            found.append(node["$ref"].removeprefix("#/$defs/"))
        for value in node.values():
            found.extend(_refs_in(value))
    elif isinstance(node, list):
        for value in node:
            found.extend(_refs_in(value))
    return found


def _reachable_defs(root: dict[str, Any], defs: dict[str, Any]) -> set[str]:
    reached: set[str] = set()
    pending = _refs_in(root)
    while pending:
        name = pending.pop()
        if name in reached:
            continue
        reached.add(name)
        pending.extend(_refs_in(defs[name]))
    return reached


def _maybe_desc(rng: random.Random, node: dict[str, Any]) -> dict[str, Any]:
    if rng.random() < 0.3:
        node["description"] = rng.choice(["Some field.", "Format: date.", "值"])
    if rng.random() < 0.1:
        node["title"] = "T"
    return node


def _gen_object(
    rng: random.Random,
    depth: int,
    defs: dict[str, Any],
    plain_defs: list[str],
    nprops: int | None = None,
) -> dict[str, Any]:
    if nprops is None:
        nprops = rng.choice([0, 1, 2, 2, 3])
    props = {
        f"p{i}": _gen_node(rng, depth - 1, defs, plain_defs, allow_nullable=True)
        for i in range(nprops)
    }
    return _maybe_desc(
        rng,
        {
            "type": "object",
            "properties": props,
            "required": list(props),
            "additionalProperties": False,
        },
    )


def _gen_plain(
    rng: random.Random, depth: int, defs: dict[str, Any], plain_defs: list[str]
) -> dict[str, Any]:
    """A node with a single non-null type."""
    kinds = [
        "string",
        "integer",
        "number",
        "boolean",
        "senum",
        "ienum",
        "const",
        "bconst",
        "nenum",
        "nconst",
        "iconst",
    ]
    if depth > 0:
        kinds += ["object", "object", "array", "array"]
    k = rng.choice(kinds)
    if k == "object":
        return _gen_object(rng, depth, defs, plain_defs)
    if k == "array":
        items = _gen_node(rng, depth - 1, defs, plain_defs, rng.random() < 0.3)
        return _maybe_desc(rng, {"type": "array", "items": items})
    if k == "senum":
        values = rng.sample(STR_POOL, rng.randint(1, 3))
        return _maybe_desc(rng, {"type": "string", "enum": values})
    if k == "ienum":
        values = rng.sample([1, 2, 3, 5], rng.randint(1, 3))
        return _maybe_desc(rng, {"type": "integer", "enum": values})
    if k == "const":
        return _maybe_desc(rng, {"type": "string", "const": rng.choice(STR_POOL)})
    if k == "nenum":
        values = rng.sample([1.5, 2, -0.25, 3.0, 1e3], rng.randint(1, 3))
        return _maybe_desc(rng, {"type": "number", "enum": values})
    if k == "nconst":
        return _maybe_desc(rng, {"type": "number", "const": rng.choice([7, 2.5, 4.0])})
    if k == "iconst":
        return _maybe_desc(rng, {"type": "integer", "const": rng.choice([7, 0, -2])})
    if k == "bconst":
        return {"type": "boolean", "const": rng.choice([True, False])}
    return _maybe_desc(rng, {"type": k})


def _either_order(rng: random.Random, first: Any, second: Any) -> list[Any]:
    """``[first, second]`` or ``[second, first]``, each half of the time."""
    return [first, second] if rng.random() < 0.5 else [second, first]


def _gen_node(
    rng: random.Random,
    depth: int,
    defs: dict[str, Any],
    plain_defs: list[str],
    allow_nullable: bool,
) -> dict[str, Any]:
    if defs and rng.random() < 0.2:
        name = rng.choice(list(defs))
        ref = {"$ref": f"#/$defs/{name}"}
        if allow_nullable and name in plain_defs and rng.random() < 0.5:
            return _maybe_desc(
                rng, {"anyOf": _either_order(rng, ref, {"type": "null"})}
            )
        return ref
    node = _gen_plain(rng, depth, defs, plain_defs)
    if allow_nullable and rng.random() < 0.4:
        if rng.random() < 0.5:
            node["type"] = _either_order(rng, node["type"], "null")
            if "enum" in node:
                node["enum"] = node["enum"] + [None]
            if "const" in node:
                node["enum"] = [node.pop("const"), None]
        else:
            return {"anyOf": _either_order(rng, node, {"type": "null"})}
    return node


# --- an independent view of a schema ------------------------------------------------


@dataclass
class RNode:
    """What a position of a schema allows, read straight from the schema."""

    kind: str
    nullable: bool = False
    enum_list: list[Any] | None = None  # the non-null enum values
    props: list[tuple[str, RNode]] = field(default_factory=list)
    items: RNode | None = None

    @property
    def single(self) -> bool:
        """Whether the node is not nullable and allows exactly one value."""
        return (
            not self.nullable
            and self.enum_list is not None
            and len(self.enum_list) == 1
        )


def build_rnode(
    raw: dict[str, Any], defs: dict[str, Any], nullable: bool = False
) -> RNode:
    """The :class:`RNode` of a position; ``defs`` is the root's ``$defs``."""
    while "$ref" in raw:
        raw = defs[raw["$ref"].removeprefix("#/$defs/")]
    if "anyOf" in raw:
        value = next(b for b in raw["anyOf"] if b != {"type": "null"})
        return build_rnode(value, defs, True)
    declared = raw["type"]
    types = declared if isinstance(declared, list) else [declared]
    node = RNode(
        kind=next(t for t in types if t != "null"),
        nullable=nullable or "null" in types,
    )
    values = [raw["const"]] if "const" in raw else raw.get("enum")
    if values is not None:
        node.enum_list = [v for v in values if v is not None]
    if node.kind == "object":
        node.props = [
            (name, build_rnode(child, defs))
            for name, child in raw["properties"].items()
        ]
    if node.kind == "array":
        node.items = build_rnode(raw["items"], defs)
    return node


def root_rnode(schema: dict[str, Any]) -> RNode:
    """The :class:`RNode` of a whole schema."""
    return build_rnode(schema, schema.get("$defs", {}))


# --- instances, decisions and writings ------------------------------------------------

MARKER = "__NOT_EXPRESSIBLE__"


def gen_value(rng: random.Random, n: RNode) -> Any:
    """A value the node allows."""
    if n.enum_list is not None:
        return rng.choice(n.enum_list)
    pools: dict[str, list[Any]] = {
        "string": ["Alice", "1 Main St", "2025-03-03", "x y", "é中\U0001f600", 'q"\\'],
        "integer": [0, 1, 7, -3],
        "number": [0, 1.5, 2, -0.25],
        "boolean": [True, False],
    }
    return rng.choice(pools[n.kind])


def gen_instance(
    rng: random.Random, n: RNode, is_root: bool = True, p_bad: float = 0.04
) -> Any:
    """An instance that is mostly valid for the copy, sometimes broken."""
    r = rng.random()
    if not is_root:
        if r < 0.12:
            return None
        if r < 0.17:
            return rng.choice(["", "  ", "\t"])
        if r < 0.20 and n.kind == "string":
            return MARKER
    if rng.random() < p_bad:
        wrong = [MARKER, "x" + MARKER, 3, "zz", True, [], {}, None, 2.5, 1.0, 1]
        return rng.choice(wrong)
    if n.kind == "object":
        d = {k: gen_instance(rng, c, False, p_bad) for k, c in n.props}
        if n.props and rng.random() < p_bad:
            d.pop(rng.choice([k for k, _ in n.props]))
        if rng.random() < p_bad:
            d["zz_extra"] = 1
        return d
    if n.kind == "array":
        assert n.items is not None
        return [
            gen_instance(rng, n.items, False, p_bad) for _ in range(rng.randint(0, 3))
        ]
    return gen_value(rng, n)


# A decision is what the final answer says, whatever way it is written:
#   ("val", v) stated      ("ns",) not stated      ("nx",) stated, cannot be written
#   ("obj", [..]) ("arr", [..])      ("nonelist",) the answer says there are none
Decision = tuple[Any, ...]


def gen_decision(rng: random.Random, n: RNode, is_root: bool = False) -> Decision:
    if n.kind == "object":
        if not is_root and rng.random() < 0.25:
            return ("ns",)
        return ("obj", [gen_decision(rng, c) for _, c in n.props])
    if n.kind == "array":
        assert n.items is not None
        r = rng.random()
        if r < 0.2:
            return ("ns",)
        if r < 0.3:
            return ("nonelist",)
        return ("arr", [gen_decision(rng, n.items) for _ in range(rng.randint(1, 3))])
    r = rng.random()
    if r < 0.5:
        return ("val", gen_value(rng, n))
    return ("ns",) if r < 0.85 else ("nx",)


def render(
    rng: random.Random,
    d: Decision,
    n: RNode,
    in_object: bool = False,
    is_root: bool = False,
) -> Any:
    """One way of writing decision ``d``."""
    tag = d[0]
    if tag == "val":
        return d[1]
    if tag == "nx":
        return MARKER if n.kind == "string" else None
    if tag == "nonelist":
        return []
    if tag == "obj":
        return {k: render(rng, cd, c, True) for (k, c), cd in zip(n.props, d[1])}
    if tag == "arr":
        assert n.items is not None
        return [render(rng, cd, n.items) for cd in d[1]]
    return skeleton(rng, n) if is_root else render_ns(rng, n, in_object)


def render_ns(rng: random.Random, n: RNode, in_object: bool) -> Any:
    """Every writing of "the answer says nothing here"; inside an object a
    property with one allowed value may also be written as that value."""
    if n.kind == "object":
        return None if rng.random() < 0.5 else skeleton(rng, n)
    if n.kind == "array":
        assert n.items is not None
        if rng.random() < 0.5:
            return None
        return [render_ns(rng, n.items, False) for _ in range(rng.randint(1, 3))]
    choices: list[Any] = [None, None, "", "  "]
    if in_object and n.single:
        assert n.enum_list is not None
        choices.append(n.enum_list[0])
    return rng.choice(choices)


def skeleton(rng: random.Random, n: RNode) -> dict[str, Any]:
    return {k: render_ns(rng, c, True) for k, c in n.props}


def lookup(root: RNode, path: str) -> RNode:
    """The node at a JSON Pointer made of property names and indices."""
    n = root
    for seg in path.split("/")[1:]:
        n = dict(n.props)[seg] if n.kind == "object" else n.items  # type: ignore[assignment]
    return n


def synth_valid(n: RNode) -> Any:
    """Some value the node allows."""
    if n.enum_list is not None:
        return n.enum_list[0]
    if n.kind == "object":
        return {k: synth_valid(c) for k, c in n.props}
    if n.kind == "array":
        return []
    return {"string": "s", "integer": 1, "number": 1.5, "boolean": True}[n.kind]