@senpi/runtime 3.0.9-dev.20260710204324 → 3.0.9-dev.feat-strategy-compos.20260716233548

package/dist/composer/pure_fn/purity.py

@@ -0,0 +1,311 @@
+"""purity — the static AST gate on a pure_fn body (D2 kind 2; CMP04x teaching errors).
+
+Sandbox MECHANICS are punted for the POC (HLD open question): there is no RestrictedPython
+and no OS sandbox. The one gate is this static AST allowlist, run in the validator BEFORE
+anything executes, so an impure function is refused with a located, fix-hinted teaching
+error rather than doing I/O at runtime. The rules (each its own CMP04x class):
+
+    CMP040  the `fn:` block is not exactly one well-formed top-level `def`
+            (also: reserved / duplicate-across-nodes function name, unsupported construct).
+    CMP041  imports a module outside the allowlist — only `math` and `statistics`.
+    CMP042  uses a disallowed builtin or reflection escape (open/exec/eval/__import__/
+            getattr/print/... or any dunder attribute access like `x.__globals__`).
+    CMP043  references a forbidden or undeclared NAME (`ctx`, `senpi_mcp`, an un-imported
+            module, an external global) — this is where a ctx/MCP reference is caught.
+    CMP044  the function signature does not match the declared input ports + params.
+    CMP045  the function does not return its declared outputs (arity mismatch).
+    CMP046  writes global/nonlocal state (a `global`/`nonlocal` statement).
+
+Purity is checked against the DECLARED ports/params, not the wired graph, so it is a
+property of the node alone and reproducible in isolation (the fixture unit-test story).
+"""
+
+from __future__ import annotations
+
+import ast
+from typing import Optional
+
+from composer.validator.errors import Location, TeachingError
+
+from .models import PureFnNode
+
+# Only these two modules may be imported by a pure_fn body (POC allowlist).
+ALLOWED_MODULES = frozenset({"math", "statistics"})
+
+# Builtins a pure_fn MAY reference. Deliberately small — pure numeric/collection work only.
+SAFE_BUILTINS = frozenset({
+    "abs", "all", "any", "bool", "dict", "divmod", "enumerate", "filter", "float",
+    "frozenset", "int", "len", "list", "map", "max", "min", "pow", "range", "reversed",
+    "round", "set", "sorted", "str", "sum", "tuple", "zip", "isinstance",
+})
+
+# Builtins whose mere reference is an escape hatch (I/O, dynamic eval, reflection).
+DANGEROUS_BUILTINS = frozenset({
+    "open", "exec", "eval", "compile", "__import__", "input", "globals", "locals",
+    "vars", "getattr", "setattr", "delattr", "hasattr", "dir", "memoryview",
+    "breakpoint", "exit", "quit", "help", "print", "__builtins__",
+})
+
+# Names a pure_fn's function may NOT take, because the emitted scan.py binds them for the
+# primitives/scaffold surface (a pure_fn def is emitted nested inside scan()).
+RESERVED_FN_NAMES = frozenset({
+    "scan", "inputs", "ctx", "src", "time", "base_universe", "make_adapter",
+    "emitters", "filters", "indicators", "rankers", "scorers", "sources", "stateful",
+    "math", "statistics",
+})
+
+
+def _err(code: str, message: str, fix_hint: str, node_id: str, line: Optional[int]) -> TeachingError:
+    return TeachingError(
+        code=code, message=message, fix_hint=fix_hint,
+        location=Location(node=node_id, line=line),
+    )
+
+
+def _bound_names(fn: ast.FunctionDef) -> set[str]:
+    """Every name bound anywhere in the function (params, assignments, loops, imports,
+    comprehensions, except-as, nested defs/lambdas + their args) plus the fn's own name."""
+    bound: set[str] = {fn.name}
+
+    def add_args(args: ast.arguments) -> None:
+        for a in (*args.posonlyargs, *args.args, *args.kwonlyargs):
+            bound.add(a.arg)
+        if args.vararg:
+            bound.add(args.vararg.arg)
+        if args.kwarg:
+            bound.add(args.kwarg.arg)
+
+    add_args(fn.args)
+    for node in ast.walk(fn):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)):
+            if node is not fn:
+                if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                    bound.add(node.name)
+                add_args(node.args)
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+            bound.add(node.id)
+        elif isinstance(node, (ast.Import, ast.ImportFrom)):
+            for alias in node.names:
+                bound.add((alias.asname or alias.name).split(".")[0])
+        elif isinstance(node, ast.ExceptHandler) and node.name:
+            bound.add(node.name)
+        elif isinstance(node, (ast.comprehension,)):
+            for t in ast.walk(node.target):
+                if isinstance(t, ast.Name):
+                    bound.add(t.id)
+    return bound
+
+
+def _check_signature(fn: ast.FunctionDef, pfn: PureFnNode, errors: list, line) -> None:
+    a = fn.args
+    expected = [p.name for p in pfn.inputs] + [p.name for p in pfn.params]
+    got = [arg.arg for arg in (*a.posonlyargs, *a.args)]
+    extra = []
+    if a.vararg:
+        extra.append("*" + a.vararg.arg)
+    if a.kwarg:
+        extra.append("**" + a.kwarg.arg)
+    for kw in a.kwonlyargs:
+        extra.append(kw.arg)
+    if got != expected or extra:
+        errors.append(_err(
+            "CMP044",
+            f"pure_fn {pfn.id!r} signature is ({', '.join(got + extra) or ''}) but its "
+            f"declared inputs+params require ({', '.join(expected)}).",
+            f"Write `def {fn.name}({', '.join(expected)}):` — the parameters must be exactly "
+            f"the declared input ports then the params, in order, with no *args/**kwargs.",
+            pfn.id, line,
+        ))
+
+
+def _check_returns(fn: ast.FunctionDef, pfn: PureFnNode, errors: list, line) -> None:
+    n_out = len(pfn.outputs)
+    value_returns = [
+        n for n in ast.walk(fn)
+        if isinstance(n, ast.Return) and n.value is not None
+    ]
+    out_names = ", ".join(p.name for p in pfn.outputs)
+    if not value_returns:
+        errors.append(_err(
+            "CMP045",
+            f"pure_fn {pfn.id!r} never returns a value but declares output(s) ({out_names}).",
+            f"End the function with `return {out_names}` producing its declared output(s).",
+            pfn.id, line,
+        ))
+        return
+    for ret in value_returns:
+        is_tuple = isinstance(ret.value, ast.Tuple)
+        if n_out == 1 and is_tuple and len(ret.value.elts) != 1:
+            errors.append(_err(
+                "CMP045",
+                f"pure_fn {pfn.id!r} returns {len(ret.value.elts)} values but declares 1 "
+                f"output ({out_names}).",
+                f"Return a single {out_names} value, not a tuple.",
+                pfn.id, line,
+            ))
+            return
+        if n_out > 1:
+            if not is_tuple:
+                errors.append(_err(
+                    "CMP045",
+                    f"pure_fn {pfn.id!r} declares {n_out} outputs ({out_names}) but a return "
+                    f"does not return a tuple of {n_out} values.",
+                    f"Return a {n_out}-tuple `return {out_names}` matching the declared outputs.",
+                    pfn.id, line,
+                ))
+                return
+            if len(ret.value.elts) != n_out:
+                errors.append(_err(
+                    "CMP045",
+                    f"pure_fn {pfn.id!r} returns {len(ret.value.elts)} values but declares "
+                    f"{n_out} outputs ({out_names}).",
+                    f"Return exactly {n_out} values `return {out_names}`.",
+                    pfn.id, line,
+                ))
+                return
+
+
+def check_purity(pfn: PureFnNode, used_fn_names: set[str]) -> list[TeachingError]:
+    """Return every purity teaching error for one pure_fn node (empty == pure).
+
+    ``used_fn_names`` accumulates function names already claimed by earlier pure_fn nodes,
+    so a duplicate name (which would shadow in the shared emitted scan.py) is a CMP040.
+    """
+    errors: list[TeachingError] = []
+    line = pfn.line
+
+    if not pfn.fn_src.strip():
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} has no `fn:` function body.",
+            "Add an `fn:` block containing exactly one top-level `def`.", pfn.id, line,
+        ))
+        return errors
+    if not pfn.outputs:
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} declares no `outputs:`.",
+            "Declare at least one typed output port under `outputs:`.", pfn.id, line,
+        ))
+
+    try:
+        tree = ast.parse(pfn.fn_src)
+    except SyntaxError as exc:
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} body is not valid Python: {exc.msg}.",
+            "Fix the syntax; the `fn:` block must be one well-formed `def`.", pfn.id, line,
+        ))
+        return errors
+
+    defs = [n for n in tree.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))]
+    others = [
+        n for n in tree.body
+        if not isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef, ast.Import, ast.ImportFrom))
+    ]
+    if others:
+        errors.append(_err(
+            "CMP040", f"pure_fn {pfn.id!r} body has top-level code outside its `def`.",
+            "The `fn:` block must be exactly one `def` (plus, at most, allow-listed imports).",
+            pfn.id, line,
+        ))
+    if len(defs) != 1 or isinstance(defs[0], ast.AsyncFunctionDef):
+        errors.append(_err(
+            "CMP040",
+            f"pure_fn {pfn.id!r} must contain exactly one synchronous top-level `def` "
+            f"(found {len(defs)}).",
+            "Write a single plain `def name(...):` (no `async def`, no extra defs).",
+            pfn.id, line,
+        ))
+        return errors
+
+    fn = defs[0]
+    if fn.name in RESERVED_FN_NAMES:
+        errors.append(_err(
+            "CMP040",
+            f"pure_fn {pfn.id!r} function name {fn.name!r} is reserved by the emitted scan.py.",
+            f"Rename the function (reserved: sorted({sorted(RESERVED_FN_NAMES)[:4]})... and the "
+            f"primitive modules).",
+            pfn.id, line,
+        ))
+    elif fn.name in used_fn_names:
+        errors.append(_err(
+            "CMP040",
+            f"pure_fn {pfn.id!r} function name {fn.name!r} is already used by another pure_fn.",
+            "Give each pure_fn a distinct function name so they do not collide in scan.py.",
+            pfn.id, line,
+        ))
+    used_fn_names.add(fn.name)
+
+    _check_signature(fn, pfn, errors, line)
+    _check_returns(fn, pfn, errors, line)
+
+    bound = _bound_names(fn)
+
+    for node in ast.walk(fn):
+        # imports (anywhere) — allowlist only
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name.split(".")[0] not in ALLOWED_MODULES:
+                    errors.append(_err(
+                        "CMP041",
+                        f"pure_fn {pfn.id!r} imports {alias.name!r}, which is not allowed.",
+                        f"A pure_fn may import only {sorted(ALLOWED_MODULES)} — remove this import.",
+                        pfn.id, line,
+                    ))
+        elif isinstance(node, ast.ImportFrom):
+            if (node.module or "").split(".")[0] not in ALLOWED_MODULES:
+                errors.append(_err(
+                    "CMP041",
+                    f"pure_fn {pfn.id!r} imports from {node.module!r}, which is not allowed.",
+                    f"A pure_fn may import only {sorted(ALLOWED_MODULES)} — remove this import.",
+                    pfn.id, line,
+                ))
+        # global / nonlocal writes
+        elif isinstance(node, (ast.Global, ast.Nonlocal)):
+            kw = "global" if isinstance(node, ast.Global) else "nonlocal"
+            errors.append(_err(
+                "CMP046",
+                f"pure_fn {pfn.id!r} uses `{kw}` — a pure_fn may not write outside its own scope.",
+                f"Remove the `{kw}` statement; compute and `return` values instead.",
+                pfn.id, line,
+            ))
+        # generators / awaits are not pure straight-line functions
+        elif isinstance(node, (ast.Yield, ast.YieldFrom, ast.Await)):
+            errors.append(_err(
+                "CMP042",
+                f"pure_fn {pfn.id!r} uses a generator/await construct.",
+                "A pure_fn must be a plain synchronous function that returns a value.",
+                pfn.id, line,
+            ))
+        # dunder attribute access (reflection escape: x.__globals__ / ().__class__)
+        elif isinstance(node, ast.Attribute):
+            if node.attr.startswith("__") and node.attr.endswith("__"):
+                errors.append(_err(
+                    "CMP042",
+                    f"pure_fn {pfn.id!r} accesses dunder attribute {node.attr!r} (reflection escape).",
+                    "Remove the dunder attribute access; a pure_fn may not reach runtime internals.",
+                    pfn.id, line,
+                ))
+        # name loads
+        elif isinstance(node, ast.Name) and isinstance(node.ctx, ast.Load):
+            n = node.id
+            if n in bound or n in SAFE_BUILTINS or n in ALLOWED_MODULES:
+                continue
+            if n in DANGEROUS_BUILTINS:
+                errors.append(_err(
+                    "CMP042",
+                    f"pure_fn {pfn.id!r} uses the disallowed builtin {n!r} (I/O or dynamic execution).",
+                    f"Remove {n!r}; a pure_fn may only do numeric/collection work "
+                    f"(no I/O, no eval/exec/import).",
+                    pfn.id, line,
+                ))
+            else:
+                errors.append(_err(
+                    "CMP043",
+                    f"pure_fn {pfn.id!r} references undeclared name {n!r} "
+                    f"(no ctx/MCP/I/O and no external globals are available).",
+                    f"A pure_fn sees only its parameters ({', '.join(a.arg for a in fn.args.args)}), "
+                    f"locals, {sorted(ALLOWED_MODULES)}, and safe builtins — declare {n!r} as an "
+                    f"input port or compute it locally.",
+                    pfn.id, line,
+                ))
+
+    return errors

package/dist/composer/pure_fn/runtests.py

@@ -0,0 +1,155 @@
+"""runtests — run a pure_fn's inline fixture tests at validation time (CMP05x).
+
+A pure_fn node may carry inline ``tests:`` — a list of ``{name, inputs, expect}`` fixture
+cases. Because a pure_fn is pure by construction (statically enforced in
+``composer.pure_fn.purity``), a failing unit test is a DEFECT IN THE FUNCTION, catchable
+before deploy — so the validator RUNS the cases (same-process, the POC decision) and
+turns any failure into a teaching error:
+
+    CMP050  a case produced the wrong output (shows expected vs got).
+    CMP051  a case raised an exception when run.
+    CMP052  a case is malformed (does not bind a required arg, or names an unknown output).
+
+Execution is only reached AFTER purity passes for the node, so the body is already known
+to touch nothing but its parameters, ``math``/``statistics``, and safe builtins. We still
+exec it under a restricted ``__builtins__`` (the same allowlist) so the test harness cannot
+accidentally widen what the function can do.
+"""
+
+from __future__ import annotations
+
+import builtins as _builtins
+import math
+import statistics
+from typing import Optional
+
+from composer.validator.errors import Location, TeachingError
+
+from .models import PureFnNode
+from .purity import SAFE_BUILTINS
+
+
+def _safe_import(name, *_a, **_k):
+    if name in ("math", "statistics"):
+        return __import__(name)
+    raise ImportError(f"pure_fn may not import {name!r}")
+
+
+def _safe_namespace() -> dict:
+    safe = {n: getattr(_builtins, n) for n in SAFE_BUILTINS if hasattr(_builtins, n)}
+    safe["__import__"] = _safe_import
+    return {"__builtins__": safe, "math": math, "statistics": statistics}
+
+
+def _short(value) -> str:
+    text = repr(value)
+    return text if len(text) <= 200 else text[:197] + "..."
+
+
+def run_inline_tests(pfn: PureFnNode) -> list[TeachingError]:
+    """Run every inline test for one (already-pure) pure_fn node; return teaching errors."""
+    if not pfn.tests:
+        return []
+
+    fd = pfn.function_def()
+    if fd is None:  # pragma: no cover - purity guarantees a def by the time we run
+        return []
+
+    ns = _safe_namespace()
+    try:
+        exec(compile(pfn.fn_src, f"<pure_fn {pfn.id}>", "exec"), ns)  # noqa: S102 - purity-gated
+    except Exception as exc:  # noqa: BLE001
+        return [TeachingError(
+            code="CMP051",
+            message=f"pure_fn {pfn.id!r} body failed to load for testing: {exc!r}.",
+            fix_hint="Fix the function body so it defines cleanly.",
+            location=Location(node=pfn.id, line=pfn.line),
+        )]
+    fn = ns.get(fd.name)
+
+    sig_names = [p.name for p in pfn.inputs] + [p.name for p in pfn.params]
+    param_defaults = {p.name: p.default for p in pfn.params}
+    out_names = [p.name for p in pfn.outputs]
+
+    errors: list[TeachingError] = []
+    for i, case in enumerate(pfn.tests):
+        name = case.get("name", f"#{i + 1}")
+        loc = Location(node=pfn.id, line=pfn.line)
+        given = case.get("inputs") or {}
+        expect = case.get("expect")
+
+        if not isinstance(given, dict) or not isinstance(expect, dict):
+            errors.append(TeachingError(
+                code="CMP052",
+                message=f"pure_fn {pfn.id!r} test {name!r} is malformed (needs mapping `inputs`/`expect`).",
+                fix_hint="Give the test `inputs:` (a mapping of port/param -> value) and `expect:` "
+                         "(a mapping of output-port -> expected value).",
+                location=loc,
+            ))
+            continue
+
+        if set(expect) != set(out_names):
+            errors.append(TeachingError(
+                code="CMP052",
+                message=f"pure_fn {pfn.id!r} test {name!r} `expect:` keys {sorted(expect)} "
+                        f"are not the declared outputs {out_names}.",
+                fix_hint=f"`expect:` must have exactly the output-port keys {out_names}.",
+                location=loc,
+            ))
+            continue
+
+        try:
+            args = []
+            for arg_name in sig_names:
+                if arg_name in given:
+                    args.append(given[arg_name])
+                elif arg_name in param_defaults:
+                    args.append(param_defaults[arg_name])
+                else:
+                    raise KeyError(arg_name)
+        except KeyError as missing:
+            errors.append(TeachingError(
+                code="CMP052",
+                message=f"pure_fn {pfn.id!r} test {name!r} does not bind required argument {missing}.",
+                fix_hint=f"Provide a value for {missing} under the test's `inputs:` "
+                         f"(signature: {sig_names}).",
+                location=loc,
+            ))
+            continue
+
+        try:
+            result = fn(*args)
+        except Exception as exc:  # noqa: BLE001
+            errors.append(TeachingError(
+                code="CMP051",
+                message=f"pure_fn {pfn.id!r} test {name!r} raised {exc!r}.",
+                fix_hint="Make the function handle this input without raising (guard missing keys, "
+                         "empty series, division by zero, etc.).",
+                location=loc,
+            ))
+            continue
+
+        if len(out_names) == 1:
+            actual = {out_names[0]: result}
+        else:
+            if not isinstance(result, (tuple, list)) or len(result) != len(out_names):
+                errors.append(TeachingError(
+                    code="CMP050",
+                    message=f"pure_fn {pfn.id!r} test {name!r} returned {_short(result)}, "
+                            f"expected {len(out_names)} outputs {out_names}.",
+                    fix_hint=f"Return a {len(out_names)}-tuple matching {out_names}.",
+                    location=loc,
+                ))
+                continue
+            actual = dict(zip(out_names, result))
+
+        if actual != expect:
+            errors.append(TeachingError(
+                code="CMP050",
+                message=f"pure_fn {pfn.id!r} test {name!r} failed: expected {_short(expect)}, "
+                        f"got {_short(actual)}.",
+                fix_hint="Fix the function (or the expected value) so this fixture case passes.",
+                location=loc,
+            ))
+
+    return errors

package/dist/composer/registry/__init__.py

@@ -0,0 +1,40 @@
+"""registry — the node registry, single source of truth for the whole composer (D4, D8).
+
+Every node the composer knows is declared here once as a pydantic model carrying its
+name, typed input/output ports, parameter schema, docstring, example snippet, and cost
+note. The JSON Schema for the graph format, the ~1-2k-token catalog index, the per-node
+``describe`` text, the validator's type rules, and the compiler's emission all derive
+from these models, so none of them can drift and a registry entry with a bogus port type
+fails at model construction rather than at use. This closed world is what lets the agent
+know authoritatively what is possible: an unknown node becomes a precise validator
+refusal and feasibility is checkable at interview time. (Populated in slice 1 with the
+primitive subset the POC graphs need — sources, indicators, filters, rankers, emitters.)
+
+Public API:
+    models   — NodeDef / Port / Param / PortType / NodeKind and the construction validators.
+    nodes    — NODES (the 26 corpus primitives), NODES_BY_NAME, sorted_nodes(), KIND_ORDER.
+    generate — deterministic artifact generation (JSON Schema + catalog + describe).
+"""
+
+from .models import (
+    SCHEMA_VERSION,
+    NodeDef,
+    NodeKind,
+    Param,
+    Port,
+    PortType,
+)
+from .nodes import KIND_ORDER, NODES, NODES_BY_NAME, sorted_nodes
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "NodeDef",
+    "NodeKind",
+    "Param",
+    "Port",
+    "PortType",
+    "KIND_ORDER",
+    "NODES",
+    "NODES_BY_NAME",
+    "sorted_nodes",
+]