quantlab-factor-agent 0.1.0__py3-none-any.whl

factor_agent/gate/_checks.py

@@ -0,0 +1,85 @@
+"""Static checks on candidate code, before anything runs.
+
+The syntax is an allow-list: assignments, arithmetic and comparisons, calls,
+``def``/``return``, ``for``/``while``/``if`` and ``with`` blocks over plain
+names and constants. Anything else, attribute access included, is refused.
+"""
+
+import ast
+
+#: The syntax candidate code may use.
+_ALLOWED_NODES = (
+    ast.Module, ast.Expr, ast.Assign, ast.AugAssign, ast.Name, ast.Load, ast.Store,
+    ast.Constant, ast.Tuple, ast.List, ast.Subscript, ast.Slice,
+    ast.BinOp, ast.UnaryOp, ast.BoolOp, ast.Compare, ast.IfExp, ast.Call, ast.keyword,
+    ast.operator, ast.unaryop, ast.boolop, ast.cmpop,
+    ast.FunctionDef, ast.arguments, ast.arg, ast.Return,
+    ast.For, ast.While, ast.If, ast.Break, ast.Continue, ast.Pass, ast.With, ast.withitem,
+)
+
+#: Clearer reasons for the refusals a proposer is most likely to hit.
+_REASONS = {
+    ast.Import: "import is not allowed",
+    ast.ImportFrom: "import is not allowed",
+    ast.ClassDef: "class definitions are not allowed",
+}
+
+
+def static_reasons(code: str, names: frozenset[str]) -> list[str]:
+    """Return why ``code`` is refused before it runs; empty when it may run.
+
+    ``names`` are the names the code may read without binding them (the vocabulary's).
+    """
+    try:
+        tree = ast.parse(code, mode="exec")
+    except SyntaxError as exc:
+        return [f"syntax error at line {exc.lineno}: {exc.msg}"]
+    reasons = _reasons(tree, names, _bound_names(tree))
+    if "alpha" not in _bound_names(tree):
+        reasons.append("the code never assigns alpha; it must end by assigning the factor to alpha")
+    return list(dict.fromkeys(reasons))
+
+
+def expression_reasons(expression: str, names: frozenset[str]) -> list[str]:
+    """Return why ``expression`` (a derived field's formula) is refused: one expression over ``names`` only."""
+    try:
+        tree = ast.parse(expression, mode="eval")
+    except SyntaxError as exc:
+        return [f"syntax error: {exc.msg}; a formula is one expression"]
+    return list(dict.fromkeys(_reasons(tree, names, set())))
+
+
+def _reasons(tree: ast.AST, names: frozenset[str], bound: set[str]) -> list[str]:
+    reasons: list[str] = []
+    for node in ast.walk(tree):
+        line = getattr(node, "lineno", None)
+        where = f"line {line}: " if line else ""
+        if type(node) in _REASONS:
+            reasons.append(where + _REASONS[type(node)])
+        elif isinstance(node, ast.Attribute):
+            reasons.append(f"{where}attribute access (.{node.attr}) is not allowed")
+        elif not isinstance(node, _ALLOWED_NODES + (ast.Expression,)):
+            reasons.append(f"{where}{type(node).__name__} is not allowed in candidate code")
+        elif isinstance(node, ast.Name) and node.id.startswith("__"):
+            reasons.append(f"{where}the name {node.id} is reserved; candidate code may not read or bind a name with two leading underscores")
+        elif (
+            isinstance(node, ast.Name)
+            and isinstance(node.ctx, ast.Load)
+            and node.id not in names
+            and node.id not in bound
+        ):
+            reasons.append(f"{where}name {node.id} is not in the vocabulary (its fields, operators and builtins)")
+    return reasons
+
+
+def _bound_names(tree: ast.AST) -> set[str]:
+    """Return every name the code binds: assignments, loop targets, functions and their arguments."""
+    names = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store):
+            names.add(node.id)
+        elif isinstance(node, ast.FunctionDef):
+            names.add(node.name)
+        elif isinstance(node, ast.arg):
+            names.add(node.arg)
+    return names

factor_agent/gate/_constraints.py

@@ -0,0 +1,85 @@
+"""Checks on a built graph: size, parameter values, dimensions and complexity.
+
+Complexity is measured on the candidate's own nodes: a derived field (such
+as ``vwap``) counts as one node and one field, and the bar mask the
+NaN-preserving operators add is not the candidate's. Parameter values and
+dimensions are the vocabulary's checks.
+"""
+
+from typing import TYPE_CHECKING
+
+from factor_agent.gate._canonical import canonical_hashes
+from factor_agent.gate.graph import Graph
+
+if TYPE_CHECKING:
+    from factor_agent.config import GateConfig
+    from factor_agent.gate.vocabulary import Vocabulary
+
+#: Magnitudes of constants that carry no tuning: zero and one (NaN is not counted either).
+_STRUCTURAL = (0.0, 1.0)
+
+
+def check(graph: Graph, config: "GateConfig", vocabulary: "Vocabulary") -> tuple[list[str], dict]:
+    """Return the reasons ``graph`` is refused (empty if none) and its statistics under ``config``'s limits."""
+    reasons: list[str] = []
+    fields, nodes, operators, constants = _candidate_part(graph, vocabulary)
+    if nodes > config.max_nodes:
+        reasons.append(f"the graph has {nodes} nodes, more than the limit of {config.max_nodes}")
+    vocabulary_reasons, dimension = vocabulary.check(graph)
+    reasons += vocabulary_reasons
+    ratio = constants / max(operators, 1)
+    if ratio > config.max_free_parameter_ratio:
+        reasons.append(
+            f"{constants} hand-set constants over {operators} operators is a free-parameter ratio of "
+            f"{ratio:.2f}, above {config.max_free_parameter_ratio:g}; express the mechanism with fewer constants"
+        )
+    if len(fields) > config.max_base_fields:
+        reasons.append(
+            f"the factor reads {len(fields)} input fields ({', '.join(fields)}), more than {config.max_base_fields}"
+        )
+    stats = {
+        "nodes": nodes,
+        "operators": operators,
+        "free_parameters": constants,
+        "free_parameter_ratio": round(ratio, 4),
+        "base_fields": fields,
+        "dimension": dimension,
+    }
+    return reasons, stats
+
+
+def _candidate_part(graph: Graph, vocabulary: "Vocabulary") -> tuple[list[str], int, int, int]:
+    """Return the input fields the candidate reads and its node, operator and hand-set constant counts.
+
+    A derived input counts as one node; the bar mask counts as none.
+    """
+    hashes = canonical_hashes(graph)
+    derived, mask = vocabulary.reference_hashes
+    fields, seen = set(), set()
+    nodes = operators = constants = 0
+    stack = [len(graph.nodes) - 1]
+    while stack:
+        i = stack.pop()
+        if i in seen:
+            continue
+        seen.add(i)
+        node = graph.nodes[i]
+        if hashes[i] in mask:
+            continue
+        nodes += 1
+        if hashes[i] in derived:
+            fields.add(derived[hashes[i]])
+            continue
+        if node.op == "Input":
+            column = dict(node.attrs)["name"]
+            fields.add(vocabulary.field_name(column))
+            continue
+        if node.op != "ConstantOp":
+            operators += 1
+        params = vocabulary.spec(node.op).params
+        constants += sum(
+            1 for key, value in node.attrs
+            if params.get(key, "") == vocabulary.constant_set and value != "nan" and abs(float(value)) not in _STRUCTURAL
+        )
+        stack += list(node.inputs) + ([] if node.parent is None else [node.parent])
+    return sorted(fields), nodes, operators, constants

factor_agent/gate/_dimension.py

@@ -0,0 +1,177 @@
+"""Dimension inference: what each node of a graph measures, from the operators' dimension rules.
+
+A dimension is a pair of exponents ``(dollars, shares)``, from the units of
+the fields: a price ``(1, -1)``, a volume or a share count ``(0, 1)``, money
+(an amount traded or a statement total) ``(1, 0)``, a pure number (a ratio)
+``(0, 0)``, a variance of price ``(2, -2)``. The rules are linear in the
+exponents, so this basis gives the verdicts the earlier ``(price, volume)``
+basis gave on price and volume. The rules are the framework's fixed set;
+each operator of the operator file picks one (``OPERATOR_RULES``).
+
+Besides those, a node may be a comparison (``BOOL``), a constant that
+takes whatever dimension it is combined with (``ANY``), a window loop (``LOOP``) or something the rules cannot say (``UNKNOWN``, e.g. the log
+of a price). An invalid combination, such as price plus volume, is a reason
+to reject; ``UNKNOWN`` is passed on.
+"""
+
+from fractions import Fraction
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from factor_agent.gate.vocabulary import Vocabulary
+
+BOOL = "bool"
+ANY = "any"
+LOOP = "loop"
+UNKNOWN = "unknown"
+PURE = (Fraction(0), Fraction(0))
+
+_NAMES = {PURE: "pure number", (1, -1): "price", (0, 1): "volume", (1, 0): "money"}
+_BASES = ("dollars", "shares")
+
+
+def name(dim) -> str:
+    """Return a readable name: ``"price"``, ``"money"``, ``"dollars^2/shares^2"``, ``"unknown"``..."""
+    if isinstance(dim, str):
+        return {BOOL: "comparison", ANY: "constant"}.get(dim, dim)
+    if dim in _NAMES:
+        return _NAMES[dim]
+    up = [f"{base}^{e}" if e != 1 else base for base, e in zip(_BASES, dim) if e > 0]
+    down = [f"{base}^{-e}" if e != -1 else base for base, e in zip(_BASES, dim) if e < 0]
+    return ("*".join(up) or "1") + ("/" + "*".join(down) if down else "")
+
+
+class _Invalid(Exception):
+    pass
+
+
+def infer(graph, vocabulary: "Vocabulary") -> tuple[object, list[str]]:
+    """Return the factor's dimension and the reasons the graph's dimensions are invalid (empty if none).
+
+    An ``Input`` has the dimension of the field reading its column; each
+    operator follows the rule ``vocabulary`` gives it.
+    """
+    dims: list = []
+    reasons: list[str] = []
+    for node in graph.nodes:
+        spec = vocabulary.spec(node.op)
+        attrs = dict(node.attrs)
+        ins = [dims[i] for i in node.inputs]
+        try:
+            _check_kinds(node.op, spec.inputs, ins)
+            if spec.dimension == "input":
+                exponents = vocabulary.column_dimension(attrs["name"])
+                dims.append(UNKNOWN if exponents is None else tuple(Fraction(e) for e in exponents))
+            else:
+                dims.append(OPERATOR_RULES[spec.dimension](node.op, ins, attrs))
+        except _Invalid as exc:
+            reasons.append(str(exc))
+            dims.append(UNKNOWN)
+    output = dims[-1]
+    if output == BOOL:
+        reasons.append("alpha is a comparison (true or false), not a number; turn it into a number with Select")
+    elif output == ANY:
+        reasons.append("alpha is a constant; it must depend on the inputs")
+    elif output == LOOP:
+        reasons.append("alpha is a window loop; reduce it with a Reduce* operator")
+    return output, list(dict.fromkeys(reasons))
+
+
+def _check_kinds(op: str, kinds: tuple[str, ...], ins: list) -> None:
+    """Every input must be what the operator expects: a number, a comparison or a loop."""
+    for position, dim in enumerate(ins):
+        kind = kinds[position] if position < len(kinds) else "series"
+        if kind == "condition" and dim not in (BOOL, UNKNOWN):
+            raise _Invalid(f"{op} needs a comparison as input {position + 1}, got a {name(dim)}")
+        if kind == "loop" and dim != LOOP:
+            raise _Invalid(f"{op} needs a ForeachBackWindow loop as input {position + 1}")
+        if kind == "series" and dim == BOOL:
+            raise _Invalid(f"{op} takes a number but gets a comparison; turn it into a number with Select")
+        if kind == "series" and dim == LOOP:
+            raise _Invalid(f"{op} takes a series but gets a loop; read the loop with IterValue")
+
+
+def _known(*dims) -> bool:
+    return UNKNOWN not in dims
+
+
+def _unify(op: str, a, b):
+    if a == ANY:
+        return b
+    if b == ANY or a == b:
+        return a
+    if not _known(a, b):
+        return UNKNOWN
+    raise _Invalid(f"{op} combines a {name(a)} with a {name(b)}")
+
+
+def _numeric(d):
+    """A constant in a product counts as a pure number."""
+    return PURE if d == ANY else d
+
+
+def _add(a, b, sign=1):
+    a, b = _numeric(a), _numeric(b)
+    if not _known(a, b):
+        return UNKNOWN
+    return (a[0] + sign * b[0], a[1] + sign * b[1])
+
+
+def _times(d, factor: Fraction):
+    if d in (UNKNOWN, ANY):
+        return d
+    return (d[0] * factor, d[1] * factor)
+
+
+def _scale(op, ins, attrs):
+    # Multiplying by zero gives 0 where x has data and NaN where it has none:
+    # it combines with anything, as a constant does.
+    if op == "MulConst" and attrs["value"] == 0:
+        return ANY
+    if op == "DivConst" and attrs.get("swap"):
+        return _times(ins[0], Fraction(-1))
+    return ins[0]
+
+
+def _pure_only(op, ins, attrs):
+    return PURE if all(_numeric(d) == PURE for d in ins) else UNKNOWN
+
+
+def _power(op, ins, attrs):
+    base, exponent = (_numeric(d) for d in ins)
+    return PURE if base == PURE and exponent == PURE else UNKNOWN
+
+
+def _select(op, ins, attrs):
+    # A choice between two constants depends on its condition: a pure number.
+    chosen = _unify(op, ins[1], ins[2])
+    return PURE if chosen == ANY else chosen
+
+
+def _compare(op, ins, attrs):
+    _unify(op, ins[0], ins[1])
+    return BOOL
+
+
+#: The dimension rules an operator may pick, by name.
+OPERATOR_RULES = {
+    "constant": lambda op, ins, attrs: ANY,
+    "same": lambda op, ins, attrs: ins[0],
+    "first": lambda op, ins, attrs: ins[0],
+    "second": lambda op, ins, attrs: ins[1],
+    "pure": lambda op, ins, attrs: PURE,
+    "match": lambda op, ins, attrs: _unify(op, ins[0], ins[1]),
+    "product": lambda op, ins, attrs: ANY if ins[0] == ins[1] == ANY else _add(ins[0], ins[1]),
+    "quotient": lambda op, ins, attrs: ANY if ins[0] == ins[1] == ANY else _add(ins[0], ins[1], -1),
+    "scale": _scale,
+    "square": lambda op, ins, attrs: _times(ins[0], Fraction(2)),
+    "sqrt": lambda op, ins, attrs: _times(ins[0], Fraction(1, 2)),
+    "transcendental": _pure_only,
+    "repeated_product": _pure_only,
+    "power": _power,
+    "select": _select,
+    "compare": _compare,
+    "compare_constant": lambda op, ins, attrs: BOOL,
+    "logic": lambda op, ins, attrs: BOOL,
+    "loop": lambda op, ins, attrs: LOOP,
+}

factor_agent/gate/_originality.py

@@ -0,0 +1,146 @@
+"""Originality against the zoo: rewrites, parameter-only refinements and large common subtrees.
+
+All three compare canonical graphs (``_canonical``):
+
+- a rewrite is a candidate whose canonical graph, without rank-keeping or rank-reversing
+  root operators, is a zoo factor's;
+- a parameter-only refinement has a zoo factor's shape: the same graph up
+  to its windows, lags and constants;
+- a common subtree is a node of the candidate whose canonical hash is a
+  node of a zoo factor; its size counts the distinct nodes under it as the
+  graph-size limit does (a derived input is one node, the bar mask none),
+  and the largest one may not exceed the limit (AlphaAgent's largest common
+  subtree, MIT; the limit of 5 nodes is QuantaAlpha's).
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from factor_agent.gate._canonical import canonical_hashes, canonical_terms, ranked_root, shape_key, term_key
+from factor_agent.gate.graph import Graph
+
+if TYPE_CHECKING:
+    from factor_agent.gate.vocabulary import Vocabulary
+    from factor_agent.zoo import Zoo, ZooEntry
+
+#: Characters of a common subtree quoted in a reason.
+_RENDER_LIMIT = 400
+
+#: Factors named in one reason before the rest are counted.
+_NAMED = 3
+
+
+@dataclass(frozen=True)
+class _Index:
+    """What a graph is compared by: its node hashes, its ranked root and that root's shape."""
+
+    hashes: frozenset[str]
+    root: str
+    shape: str
+
+
+#: Indexes of zoo graphs by ``id``, with the graph kept so the id stays its own.
+_INDEXES: dict[int, tuple[Graph, _Index]] = {}
+
+
+def _index(graph: Graph) -> _Index:
+    """Return the graph's index, cached for zoo graphs (a graph's attributes may be unhashable lists)."""
+    cached = _INDEXES.get(id(graph))
+    if cached is None or cached[0] is not graph:
+        root = ranked_root(canonical_terms(graph)[-1])
+        cached = _INDEXES[id(graph)] = (graph, _Index(frozenset(canonical_hashes(graph)), term_key(root), shape_key(root)))
+    return cached[1]
+
+
+def reasons(graph: Graph, zoo: "Zoo", max_common_nodes: int, vocabulary: "Vocabulary") -> list[str]:
+    """Return why ``graph`` is not original against ``zoo`` (empty if it is); ``vocabulary`` names its fields."""
+    root = ranked_root(canonical_terms(graph)[-1])
+    mine = _Index(frozenset(), term_key(root), shape_key(root))
+    entries = [(entry, _index(entry.graph)) for entry in zoo.entries]
+    rewrites = [entry for entry, index in entries if index.root == mine.root]
+    if rewrites:
+        terms = canonical_terms(graph)
+        root = max((i for i, term in enumerate(terms) if term_key(term) == mine.root), default=len(terms) - 1)
+        return [
+            f"the factor rewrites {_names(rewrites)}: {render(graph, root, vocabulary)} is that factor's whole graph, up to "
+            "a transform that keeps or reverses its ranking; propose a different mechanism"
+        ]
+    found = []
+    tuned = [entry for entry, index in entries if index.shape == mine.shape]
+    if tuned:
+        found.append(
+            f"the factor is {_names(tuned)} with other windows or parameter values only; a refinement must "
+            "change the expression of the mechanism, not its parameters"
+        )
+    size, node, sharing = _largest_common_subtree(graph, entries, vocabulary)
+    if size > max_common_nodes:
+        found.append(
+            f"the factor shares a {size}-node subtree with {_names(sharing)}, more than the limit of "
+            f"{max_common_nodes}: {render(graph, node, vocabulary)}; express the mechanism without reusing that expression"
+        )
+    return found
+
+
+def _largest_common_subtree(graph: Graph, entries: list, vocabulary: "Vocabulary") -> tuple[int, int | None, list["ZooEntry"]]:
+    """Return the size and node of the candidate's largest subtree found in a zoo factor, and those factors."""
+    hashes = canonical_hashes(graph)
+    sizes = _subtree_sizes(graph, hashes, vocabulary)
+    best, node, sharing = 0, None, []
+    for i in sorted(range(len(hashes)), key=lambda i: -sizes[i]):
+        if sizes[i] <= best and node is not None:
+            break
+        holders = [entry for entry, index in entries if hashes[i] in index.hashes]
+        if holders:
+            best, node, sharing = sizes[i], i, holders
+    return best, node, sharing
+
+
+def _subtree_sizes(graph: Graph, hashes: list[str], vocabulary: "Vocabulary") -> list[int]:
+    """Return the number of distinct nodes under each node, itself included."""
+    derived, mask = vocabulary.reference_hashes
+    reach: list[frozenset[str]] = []
+    for i, node in enumerate(graph.nodes):
+        if hashes[i] in mask:
+            reach.append(frozenset())
+        elif hashes[i] in derived:
+            reach.append(frozenset({hashes[i]}))
+        else:
+            under = [reach[j] for j in node.inputs] + ([] if node.parent is None else [reach[node.parent]])
+            reach.append(frozenset({hashes[i]}).union(*under))
+    return [len(r) for r in reach]
+
+
+def _names(entries: list["ZooEntry"]) -> str:
+    named = ", ".join(entry.label for entry in entries[:_NAMED])
+    rest = len(entries) - _NAMED
+    return named + (f" and {rest} more" if rest > 0 else "")
+
+
+def render(graph: Graph, node: int, vocabulary: "Vocabulary") -> str:
+    """Return the expression under ``node`` as candidate code would write it."""
+    hashes = canonical_hashes(graph)
+    derived, mask = vocabulary.reference_hashes
+
+    def render(i: int) -> str:
+        n = graph.nodes[i]
+        if hashes[i] in derived:
+            return derived[hashes[i]]
+        attrs = dict(n.attrs)
+        if n.op == "Input":
+            return vocabulary.written(attrs["name"])
+        if n.op == "ConstantOp":
+            return _display(attrs["value"])
+        inputs = [j for j in n.inputs if hashes[j] not in mask]
+        if n.op == "Add" and len(inputs) == 1:  # a NaN-preserving stand-in: the operator plus the bar mask
+            return render(inputs[0])
+        values = [_display(v) for k, v in n.attrs if not (k == "swap" and not v)]
+        return f"{n.op}({', '.join([render(j) for j in inputs] + values)})"
+
+    text = render(node)
+    return text if len(text) <= _RENDER_LIMIT else text[:_RENDER_LIMIT] + "..."
+
+
+def _display(value) -> str:
+    if isinstance(value, float) and value.is_integer():
+        return str(int(value))
+    return f"{value:g}" if isinstance(value, float) else str(value)

factor_agent/gate/_sandbox.py

@@ -0,0 +1,105 @@
+"""The sandbox subprocess: run candidate code once and send back its graph.
+
+Reads ``{"code": ..., "memory_mb": ..., "vocabulary": ...}`` on standard input and writes on
+standard output the ``READY`` line once it has started, then one JSON object:
+``{"graph": [...]}`` or ``{"reasons": [...]}``.
+The parent runs it with ``python -I``, an empty environment, a scratch
+working directory, a timeout, a memory watchdog and, where bubblewrap is
+installed, its own filesystem view; the code sees only the namespace of
+the vocabulary, rebuilt here from the parent's ``Vocabulary.sources``.
+Where the platform allows it (Linux), the address space is also capped
+here, so an allocation past the limit fails at once.
+"""
+
+import json
+import resource
+import sys
+
+from KunQuant.Op import OpBase, Output
+from KunQuant.Stage import Function
+
+from factor_agent.gate import MEMORY_REASON, READY
+from factor_agent.gate.graph import Graph
+from factor_agent.gate.vocabulary import PeriodLagError, Vocabulary
+
+
+def build(code: str, memory_mb: int, vocabulary: Vocabulary) -> dict:
+    """Run ``code`` over ``vocabulary`` and return the message for the parent."""
+    try:
+        scope = vocabulary.execute(code)
+    except MemoryError:
+        return {"reasons": [MEMORY_REASON.format(memory_mb=memory_mb)]}
+    except PeriodLagError as exc:
+        return {"reasons": [str(exc)]}
+    except Exception as exc:  # the candidate's own error, reported back to it
+        return {"reasons": [f"graph build failed: {type(exc).__name__}: {exc}{_bad_input(exc, code, vocabulary)}"]}
+    if "alpha" not in scope:
+        return {"reasons": ["the code never assigns alpha"]}
+    alpha = scope["alpha"]
+    if isinstance(alpha, (tuple, list)):
+        return {"reasons": [f"alpha holds {len(alpha)} values; a candidate has exactly one output"]}
+    if not isinstance(alpha, OpBase):
+        return {"reasons": [f"alpha must be an operator, got {type(alpha).__name__}"]}
+    try:
+        graph = Graph.record(alpha, vocabulary)
+    except ValueError as exc:
+        return {"reasons": [str(exc)]}
+    try:
+        output, ops = graph.build({})
+        Function(ops + [Output(output, "alpha")])
+    except Exception as exc:
+        return {"reasons": [f"graph build failed: {type(exc).__name__}: {exc}"]}
+    return {"graph": graph.to_json()}
+
+
+def _bad_input(exc: Exception, code: str, vocabulary: Vocabulary) -> str:
+    """Where KunQuant's "Bad inputs" came from: the candidate's line and the operator given a number, or "" for any other error.
+
+    KunQuant names only the type of the value, so the fix of a candidate
+    with many numbers had no way to tell which one to change.
+    """
+    line = op = inputs = None
+    tb = exc.__traceback__
+    while tb is not None:
+        frame = tb.tb_frame
+        if frame.f_code.co_filename == "<candidate>":
+            line = tb.tb_lineno
+        elif frame.f_code is OpBase.__init__.__code__:
+            op, inputs = frame.f_locals.get("self"), frame.f_locals.get("inputs")
+        tb = tb.tb_next
+    if line is None or op is None or not inputs:
+        return ""
+    position, value = next(((k, v) for k, v in enumerate(inputs, 1) if not isinstance(v, OpBase)), (None, None))
+    if position is None:
+        return ""
+    name = vocabulary.recorded_name(type(op)) or type(op).__name__
+    source = code.splitlines()[line - 1].strip() if line <= len(code.splitlines()) else ""
+    return f": on line {line} ({source}), input {position} of {name} is the number {value!r}, not an operator"
+
+
+def _cap_address_space(memory_mb: int) -> None:
+    """Cap the address space at what is mapped now plus ``memory_mb``; a no-op where unsupported."""
+    try:
+        with open("/proc/self/statm") as statm:
+            mapped = int(statm.read().split()[0]) * resource.getpagesize()
+        _, hard = resource.getrlimit(resource.RLIMIT_AS)
+        resource.setrlimit(resource.RLIMIT_AS, (mapped + memory_mb * 2**20, hard))
+    except (OSError, ValueError):
+        pass  # macOS has no /proc and does not enforce RLIMIT_AS; the parent's watchdog applies
+
+
+def main() -> None:
+    """Read the request, build, write the reply."""
+    request = json.load(sys.stdin)
+    out = sys.stdout
+    sys.stdout = sys.stderr  # nothing the code does can corrupt the reply
+    vocabulary = Vocabulary.from_sources(request["vocabulary"])
+    _cap_address_space(request["memory_mb"])
+    out.write(READY.decode())
+    out.flush()  # started: the graph build's time counts from here
+    json.dump(build(request["code"], request["memory_mb"], vocabulary), out)
+    out.flush()
+
+
+if __name__ == "__main__":
+    main()