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

package/dist/composer/requirements.txt

@@ -0,0 +1,21 @@
+# Dev/CI Python dependencies for the strategy composer (composer/).
+#
+# Mirrors the scaffold's requirements.txt convention: this repo is otherwise pure
+# TypeScript/vitest and pytest is a CI-only toolchain, so composer's Python deps are
+# declared here (not in pyproject) and installed in the `python-tests` CI job.
+#
+#   pydantic — the node registry is pydantic models; the single source of truth from
+#              which JSON Schema + catalog + validator + compiler all derive (D4, D8).
+#   jinja2   — per-node emission templates the compiler walks to produce scan.py (D8).
+#   pyyaml   — parse the authored YAML graph before validating the JSON canonical form
+#              (D6: YAML authored, JSON Schema canonical; anchors/merge keys banned).
+#   jsonschema — validate the desugared graph against composer/generated/graph.schema.json
+#              (Draft 2020-12); the validator translates its findings into teaching errors
+#              rather than re-implementing the registry's per-node param validation (slice 2).
+#
+# NO orchestration/DAG framework (LangGraph/Dagster/Prefect/Hamilton/networkx): the DAG
+# never executes as a DAG — the compiler linearizes topo order into straight-line Python.
+pydantic>=2.0
+jinja2>=3.0
+pyyaml>=6.0
+jsonschema>=4.18

package/dist/composer/templates/__init__.py

@@ -0,0 +1,13 @@
+"""templates — per-node emission templates and archetype templates-as-code (D7, D8).
+
+Two template families live here. Per-node emission templates (Jinja2, or plain f-string
+templates) sit next to their registry entries and are what the compiler walks in topo
+order to emit straight-line ``scan.py``. Archetype templates are the machine-generated
+first-draft anchors for ``composer new``: they are CODE built from the same pydantic
+registry types (never YAML-with-holes), so a template referencing a nonexistent node or
+port fails CI and cannot drift from the vocabulary. ``composer new`` binds mechanically
+bindable answers (universe, intervals, top-N, TTL, exit preset) directly and leaves
+genuinely bespoke slots (weights, thresholds, edge logic) TODO-marked WITH working
+defaults, so the emitted graph validates and compiles before any edit. (Only the
+archetypes the POC graphs need are added, in slice 6 — not all ten.)
+"""

package/dist/composer/templates/scan.py.j2

@@ -0,0 +1,31 @@
+{{ '"""' }}AUTOGENERATED by `composer compile` from {{ source_name }} — do not edit by hand.
+
+Strategy: {{ strategy }} (archetype: {{ archetype }}).
+Emitted onto the external_scanner contract: scan(inputs, ctx) -> list[dict].
+The graph is materialized straight-line in topological order; each block below is
+named with its graph node id. Regenerate with `composer compile` — edits are lost.
+
+Nodes ({{ node_count }}): {{ node_ids }}.
+{{ '"""' }}
+import time
+{% for imp in extra_imports %}import {{ imp }}
+{% endfor %}
+from composer.primitives import emitters, filters, indicators, rankers, scorers, sources, stateful
+from composer.primitives.adapter import make_adapter
+
+# Base universe — the candles_fetch whitelist, overridable via inputs["whitelist"].
+_BASE_UNIVERSE = {{ base_universe }}
+
+
+def scan(inputs, ctx):
+    _now = time.time()
+    src = make_adapter(ctx)
+    base_universe = [str(_a).upper() for _a in inputs.get("whitelist", _BASE_UNIVERSE)]
+
+{% for line in prologue %}    {{ line }}
+{% endfor %}
+{% for line in body %}    {{ line }}
+{% endfor %}
+{% for line in epilogue %}    {{ line }}
+{% endfor %}
+    return {{ return_var }}

package/dist/composer/validator/__init__.py

@@ -0,0 +1,29 @@
+"""validator — schema and graph typecheck whose teaching errors are the product.
+
+The validator parses authored YAML to JSON (anchors/merge keys banned per D6), validates
+it against the registry-generated JSON Schema, then runs the graph checks: cycle
+detection, topo-sort, port typechecking, parameter-bound checks, and unknown-node refusal
+that names the nearest valid alternatives. The graph never executes as a DAG, so these are
+~50-100 lines of plain checks, not an orchestration framework. Error format is a
+first-class deliverable (the SERR037 lesson): every error carries location (node id /
+port / line), what is wrong, and a concrete fix hint, so a small model can repair it in
+one iteration. (Implemented in slice 2 as a table of one-error-class-per-test cases.)
+
+Public API:
+    validate_text / validate_file — run the full pipeline, return a ValidationResult.
+    ValidationResult              — collected errors; .ok, .render() (text), .to_json().
+    TeachingError / Location      — the located, fix-hinted error model.
+    ERROR_CODES                   — stable code -> error-class table.
+"""
+
+from .errors import ERROR_CODES, Location, TeachingError, ValidationResult
+from .validate import validate_file, validate_text
+
+__all__ = [
+    "validate_text",
+    "validate_file",
+    "ValidationResult",
+    "TeachingError",
+    "Location",
+    "ERROR_CODES",
+]

package/dist/composer/validator/desugar.py

@@ -0,0 +1,133 @@
+"""desugar — expand the ``pipeline:`` shorthand into the canonical nodes+edges DAG (D1).
+
+Stage (b), applied BEFORE schema validation so every later stage (schema, graph checks,
+and eventually the compiler) sees exactly one representation: the DAG. The shorthand
+exists because the common case is a straight line — ``candles -> indicator -> score ->
+rank -> emit`` — and making the agent hand-wire that by port is needless friction. Once a
+strategy needs fan-out/join it drops the shorthand and writes nodes+edges directly (D1:
+"once you need joins you need named references, which is a DAG").
+
+A ``pipeline`` is a list of steps; each step is either a bare node-type string
+(``candles_fetch``) or a mapping in the same shape as a node entry (``{id?, node,
+with?}``). Consecutive steps are wired primary-output -> primary-input, where "primary"
+is the first non-``state`` output / input port the registry declares for that node. Ids
+default to the node type, de-duplicated with a ``_2`` suffix. The result is byte-for-byte
+the DAG the author would have written by hand — proven by the desugar-equivalence test.
+"""
+
+from __future__ import annotations
+
+from composer.registry import NODES_BY_NAME, PortType
+
+from .errors import Location, TeachingError
+
+
+def has_pipeline(doc: object) -> bool:
+    return isinstance(doc, dict) and "pipeline" in doc
+
+
+def _primary_output(node_name: str) -> str | None:
+    node = NODES_BY_NAME.get(node_name)
+    if node is None:
+        return None
+    for port in node.outputs:
+        if port.type != PortType.state:
+            return port.name
+    return None
+
+
+def _primary_input(node_name: str) -> str | None:
+    node = NODES_BY_NAME.get(node_name)
+    if node is None:
+        return None
+    for port in node.inputs:
+        if port.type != PortType.state:
+            return port.name
+    return None
+
+
+def desugar(doc: dict) -> tuple[dict, list[TeachingError]]:
+    """Return ``(canonical_doc, errors)``.
+
+    ``canonical_doc`` has the ``pipeline`` key replaced by generated ``nodes`` and
+    ``edges``. On a malformed pipeline the returned doc still carries whatever nodes could
+    be built, so downstream stages can pile on additional findings (errors collect, they
+    do not short-circuit).
+    """
+    errors: list[TeachingError] = []
+    steps = doc.get("pipeline")
+    if not isinstance(steps, list):
+        errors.append(
+            TeachingError(
+                code="CMP020",
+                message="`pipeline:` must be a list of node steps.",
+                fix_hint="Write `pipeline:` as a YAML list, e.g. `pipeline: [candles_fetch, sma]`.",
+            )
+        )
+        return doc, errors
+
+    if "nodes" in doc or "edges" in doc:
+        errors.append(
+            TeachingError(
+                code="CMP020",
+                message="`pipeline:` cannot be combined with explicit `nodes:`/`edges:`.",
+                fix_hint="Use EITHER the `pipeline:` shorthand OR an explicit `nodes:`+`edges:` graph, not both.",
+            )
+        )
+
+    nodes: list[dict] = []
+    edges: list[dict] = []
+    id_counts: dict[str, int] = {}
+    prev: dict | None = None  # {"id":..., "node":...}
+
+    for i, step in enumerate(steps):
+        if isinstance(step, str):
+            entry: dict = {"node": step}
+        elif isinstance(step, dict):
+            entry = dict(step)
+        else:
+            errors.append(
+                TeachingError(
+                    code="CMP020",
+                    message=f"pipeline step #{i + 1} is neither a node name nor a node mapping.",
+                    fix_hint="Each step must be a node-type string or a `{node: <name>, with: {...}}` mapping.",
+                )
+            )
+            continue
+
+        node_name = entry.get("node")
+        if not isinstance(node_name, str) or not node_name:
+            errors.append(
+                TeachingError(
+                    code="CMP020",
+                    message=f"pipeline step #{i + 1} has no `node:` type.",
+                    fix_hint="Give the step a registry node type, e.g. `- node: sma`.",
+                )
+            )
+            continue
+
+        base_id = entry.get("id") or node_name
+        count = id_counts.get(base_id, 0) + 1
+        id_counts[base_id] = count
+        node_id = base_id if count == 1 else f"{base_id}_{count}"
+
+        node: dict = {"id": node_id, "node": node_name}
+        if "with" in entry:
+            node["with"] = entry["with"]
+        nodes.append(node)
+
+        if prev is not None:
+            out_port = _primary_output(prev["node"])
+            in_port = _primary_input(node_name)
+            if out_port and in_port:
+                edges.append(
+                    {"from": f"{prev['id']}.{out_port}", "to": f"{node_id}.{in_port}"}
+                )
+            # If either node type is unknown the auto-edge is skipped; the unknown-node
+            # graph check (CMP030) will name it — no need to guess a wiring.
+        prev = node
+
+    canonical = {k: v for k, v in doc.items() if k != "pipeline"}
+    canonical["nodes"] = nodes
+    canonical["edges"] = edges
+    return canonical, errors

package/dist/composer/validator/errors.py

@@ -0,0 +1,191 @@
+"""errors — the teaching-error model; the slice-2 product (the SERR037 lesson).
+
+An unhelpful validator error ("schema violation at $.nodes[3].with") makes a small model
+guess; a *teaching* error tells it exactly where, what, and the one concrete thing to do
+next, so it repairs in a single iteration. Every error the validator emits is a
+:class:`TeachingError` carrying:
+
+    code       — a stable identifier (``CMP0xx``); never changes meaning across releases,
+                 so agents/tests can match on it.
+    location   — where: node id, port, and YAML line where each is available.
+    message    — what is wrong, in one sentence.
+    fix_hint   — one CONCRETE next action (a name to use, a command to run, a bound to
+                 respect) — not "fix the schema".
+
+All errors from one run are collected into a :class:`ValidationResult` and reported
+together, ordered by location, so the agent sees every defect at once rather than
+peeling them off one round-trip at a time. The result renders to plain text an LLM reads
+directly, and to a JSON structure for the ``--json`` CLI surface.
+
+The codes are the layered graph-semantic checks the validator adds ON TOP of JSON Schema
+param validation (which the registry-generated schema already carries in full) — the
+validator does not re-check param bounds itself, it translates the schema's findings into
+this same teaching shape and adds the checks a schema cannot express (ports, types,
+cycles, connectivity).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+# ---------------------------------------------------------------- stable error-code table
+# code -> one-line description of the error class it marks. Kept here so it is impossible
+# to add an ad-hoc code without also naming its class (and so tests can enumerate them).
+ERROR_CODES: dict[str, str] = {
+    "CMP001": "YAML could not be parsed (syntax error).",
+    "CMP002": "YAML anchors, aliases, or merge keys are not allowed (D6).",
+    "CMP003": "Document root is not a mapping / is empty.",
+    "CMP010": "Unknown parameter passed to a node's `with:` block.",
+    "CMP011": "Parameter value is out of its allowed range.",
+    "CMP012": "Parameter value has the wrong type.",
+    "CMP013": "A required parameter or top-level field is missing.",
+    "CMP014": "Document violates the graph schema (other).",
+    "CMP020": "The `pipeline:` shorthand is malformed.",
+    "CMP030": "Unknown node type (names nearest valid alternatives).",
+    "CMP031": "Duplicate node id.",
+    "CMP032": "Edge references a node id that does not exist.",
+    "CMP033": "Edge references a port that the node does not declare.",
+    "CMP034": "Edge connects two ports of incompatible type.",
+    "CMP035": "The graph contains a cycle (reports the cycle path).",
+    "CMP036": "A required input port has no incoming edge.",
+    "CMP037": "Two or more edges write to the same (non-mergeable) input port.",
+    "CMP038": "A node declares neither a registry `node:` type nor `kind: pure_fn`.",
+    # ---- pure_fn purity (D2 kind 2): static AST allowlist on the fn body ----
+    "CMP040": "A pure_fn `fn:` block is not exactly one well-formed top-level function def.",
+    "CMP041": "A pure_fn body imports a module outside the allowlist (math, statistics only).",
+    "CMP042": "A pure_fn body uses a disallowed builtin or reflection escape (I/O, eval, dunder).",
+    "CMP043": "A pure_fn body references a forbidden/undeclared name (ctx, MCP, or an external).",
+    "CMP044": "A pure_fn signature does not match its declared input ports + params.",
+    "CMP045": "A pure_fn does not return its declared outputs (arity mismatch).",
+    "CMP046": "A pure_fn writes global/nonlocal state.",
+    # ---- pure_fn inline fixture tests (run at validate time) ----
+    "CMP050": "A pure_fn inline test produced the wrong output.",
+    "CMP051": "A pure_fn inline test raised an exception when run.",
+    "CMP052": "A pure_fn inline test is malformed (unknown/ unbindable input or output).",
+    # ---- runtime-unit (slice 9): the emitted runtime.yaml, judged by the real Zod+DSL oracle ----
+    "CMP100": "Missing a required top-level runtime field (`name` or `strategy.wallet`).",
+    "CMP101": "The `risk` block has an unknown or renamed-legacy key (`.strict()` object).",
+    "CMP102": "A `risk.guard_rails` value is out of its allowed range.",
+    "CMP110": "The exit DSL preset is invalid (breaches / tier order / preset config).",
+    "CMP111": "`dsl_preset` is misplaced at the top level (must be nested under `exit:`).",
+    "CMP120": "Unmanaged strategy with no exit and no explicit `unmanaged` opt-out (composer policy).",
+    "CMP199": "The runtime.yaml failed the Zod schema for another reason.",
+}
+
+
+@dataclass(frozen=True)
+class Location:
+    """Where an error is, as precisely as the document allows.
+
+    ``node``/``port``/``line`` locate a graph defect; ``path`` locates a runtime.yaml defect
+    as the Zod/DSL dot-path (e.g. ``exit.dsl_preset.phase1.consecutive_breaches_required``) —
+    the CMP1xx runtime-unit errors (slice 9) carry it verbatim so the fix is pin-pointable."""
+
+    node: Optional[str] = None
+    port: Optional[str] = None
+    line: Optional[int] = None
+    path: Optional[str] = None
+
+    def render(self) -> str:
+        parts: list[str] = []
+        if self.node is not None:
+            parts.append(f"node {self.node!r}")
+        if self.port is not None:
+            parts.append(f"port {self.port!r}")
+        if self.path is not None:
+            parts.append(f"runtime.yaml {self.path or '(root)'}")
+        if self.line is not None:
+            parts.append(f"line {self.line}")
+        return ", ".join(parts) if parts else "document"
+
+    def to_dict(self) -> dict:
+        return {"node": self.node, "port": self.port, "line": self.line, "path": self.path}
+
+    @property
+    def _sort_key(self) -> tuple:
+        # Order by line first (defects the author sees top-to-bottom), then node/port/path.
+        return (
+            self.line if self.line is not None else 1_000_000,
+            self.node or "",
+            self.port or "",
+            self.path or "",
+        )
+
+
+@dataclass(frozen=True)
+class TeachingError:
+    """A single located, actionable validation error."""
+
+    code: str
+    message: str
+    fix_hint: str
+    location: Location = field(default_factory=Location)
+
+    def __post_init__(self) -> None:
+        if self.code not in ERROR_CODES:
+            raise KeyError(
+                f"unknown error code {self.code!r}; add it to ERROR_CODES in "
+                f"composer/validator/errors.py so every code has a documented class"
+            )
+
+    @property
+    def sort_key(self) -> tuple:
+        return self.location._sort_key + (self.code,)
+
+    def render(self) -> str:
+        return (
+            f"[{self.code}] {self.location.render()}: {self.message}\n"
+            f"        fix: {self.fix_hint}"
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "code": self.code,
+            "message": self.message,
+            "fix_hint": self.fix_hint,
+            "location": self.location.to_dict(),
+        }
+
+
+@dataclass
+class ValidationResult:
+    """The outcome of one validation run: every error, collected and reportable together."""
+
+    source: str  # a label for the validated document (path or "<text>")
+    errors: list[TeachingError] = field(default_factory=list)
+
+    def add(self, error: TeachingError) -> None:
+        self.errors.append(error)
+
+    def extend(self, errors: list[TeachingError]) -> None:
+        self.errors.extend(errors)
+
+    @property
+    def ok(self) -> bool:
+        return not self.errors
+
+    def sorted_errors(self) -> list[TeachingError]:
+        return sorted(self.errors, key=lambda e: e.sort_key)
+
+    def render(self) -> str:
+        """Plain-text verdict + every error, ordered by location — for an LLM to read."""
+        if self.ok:
+            return f"OK: {self.source} is a valid strategy graph ({0} errors)."
+        n = len(self.errors)
+        lines = [
+            f"INVALID: {self.source} has {n} error{'s' if n != 1 else ''}.",
+            "",
+        ]
+        for err in self.sorted_errors():
+            lines.append(err.render())
+            lines.append("")
+        return "\n".join(lines).rstrip() + "\n"
+
+    def to_json(self) -> dict:
+        return {
+            "source": self.source,
+            "ok": self.ok,
+            "error_count": len(self.errors),
+            "errors": [e.to_dict() for e in self.sorted_errors()],
+        }