rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/circulax/results.py

@@ -0,0 +1,291 @@
+"""Circulax v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``run_optical`` circulax parse shape (``measurements[]``
+with volt value, target, margin, and pass/fail status plus the
+transient grid) onto a typed measurement table, a transient
+series dataset with a bound trace view, measurements, and
+findings. Pure function of the parsed output: no I/O, no tool
+calls, deterministic ids derived from the run id. PASS
+measurements keep value, target, margin, and status.
+"""
+
+TASK = "run_optical"
+
+_DIAG_CAP = 240
+_INLINE_CAP = 1024
+
+_SEVERITY = {"error": "error", "warning": "warning"}
+
+
+def _cap(text):
+    """Cap one diagnostic string at the bundle prose limit.
+
+    Args:
+        text: Raw diagnostic text, possibly unbounded tool prose.
+
+    Returns:
+        The text unchanged when short, else truncated with an
+            ellipsis marker.
+    """
+    text = text if isinstance(text, str) else str(text)
+    if len(text) <= _DIAG_CAP:
+        return text
+    return text[: _DIAG_CAP - 3] + "..."
+
+
+def _quantity(value, unit):
+    """Build one v1 Quantity, mapping unitless to dimensionless.
+
+    Args:
+        value: Numeric value.
+        unit: Unit string, possibly empty for unitless measures.
+
+    Returns:
+        Quantity mapping with an explicit unit.
+    """
+    return {"value": float(value), "unit": unit if unit else "1"}
+
+
+def _limit(item):
+    """Pick the binding target bound for one measurement.
+
+    Args:
+        item: v0 measurement with a ``target`` min/max mapping.
+
+    Returns:
+        The bound closest to the measured value (the margin
+            binding bound), or None when the target is empty.
+    """
+    target = item.get("target") or {}
+    scored = []
+    if target.get("min") is not None:
+        scored.append((float(item["value"]) - float(target["min"]),
+                        float(target["min"])))
+    if target.get("max") is not None:
+        scored.append((float(target["max"]) - float(item["value"]),
+                        float(target["max"])))
+    if not scored:
+        return None
+    return min(scored)[1]
+
+
+def _downsample(values):
+    """Stride-downsample one sample list to the inline cap.
+
+    Args:
+        values: Sample values in stored order.
+
+    Returns:
+        (samples, downsampled) pair with at most _INLINE_CAP
+            entries, stride-picked deterministically.
+    """
+    values = list(values)
+    if len(values) <= _INLINE_CAP:
+        return values, False
+    step = -(-len(values) // _INLINE_CAP)
+    return values[::step], True
+
+
+def _provenance(project_id, run_id, tools, provenance):
+    """Build ResultProvenance, defaulting to a placeholder closure.
+
+    Args:
+        project_id: Project the run belongs to.
+        run_id: Run the bundle describes.
+        tools: Tool ingredient mappings (id, version, digest?).
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Provenance mapping valid against the v1 schema.
+    """
+    if provenance is not None:
+        return provenance
+    ref = {"scope": "project", "id": project_id, "revision": "r1"}
+    return {
+        "snapshot": dict(ref),
+        "input_lock": dict(ref),
+        "closure_hash": "0" * 64,
+        "tools": [
+            {
+                "id": item["id"],
+                "version": item.get("version", ""),
+                "digest": item.get("digest", "0" * 64),
+            }
+            for item in tools
+        ],
+        "parents": [],
+    }
+
+
+def normalize(parsed, *, run_id, project_id="project", target=None,
+              tools=(), provenance=None):
+    """Normalize one circulax parse output to a v1 ResultBundle.
+
+    Measurement rows become a table dataset plus a bound table
+    view; the transient becomes a time series dataset with a
+    bound trace view; violations become findings with capped
+    messages. PASS measurements keep value, target, margin, and
+    status. A malformed circuit (no transient) reports
+    not_converged with its error finding.
+
+    Args:
+        parsed: v0 parse mapping with ``measurements[]``,
+            ``transient``, and ``violations[]``.
+        run_id: Run the bundle describes (anchors all ids).
+        project_id: Project the run belongs to.
+        target: v1 target mapping; project kind by default.
+        tools: Tool ingredient mappings for provenance.
+        provenance: Full provenance mapping when the caller has
+            one; a deterministic placeholder otherwise.
+
+    Returns:
+        Schema-valid ResultBundle mapping.
+    """
+    measurements_in = parsed.get("measurements") or []
+    transient = parsed.get("transient") or {}
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:measurements"
+    datasets = [
+        {
+            "id": table_id,
+            "kind": "table",
+            "row_count": len(measurements_in),
+            "columns": [
+                {
+                    "id": f"{table_id}:name",
+                    "name": "name",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [item["name"] for item in measurements_in],
+                },
+                {
+                    "id": f"{table_id}:value",
+                    "name": "value",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(item["value"]) for item in measurements_in],
+                },
+                {
+                    "id": f"{table_id}:margin",
+                    "name": "margin",
+                    "dtype": "float64",
+                    "unit": "1",
+                    "data": [float(item["margin"]) for item in measurements_in],
+                },
+                {
+                    "id": f"{table_id}:status",
+                    "name": "status",
+                    "dtype": "utf8",
+                    "unit": "1",
+                    "data": [item["status"] for item in measurements_in],
+                },
+            ],
+            "conditions": [],
+        }
+    ]
+    views = [
+        {
+            "id": f"{run_id}:view:measurements",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "measurements",
+        }
+    ]
+    grid, _ = _downsample(transient.get("t_s") or [])
+    curve, _ = _downsample(transient.get("v_V") or [])
+    if grid and curve:
+        ds_id = f"{run_id}:dataset:transient"
+        axis_id = f"{ds_id}:time"
+        sig_id = f"{ds_id}:voltage"
+        observe = transient.get("observe", "out")
+        datasets.append(
+            {
+                "id": ds_id,
+                "kind": "series",
+                "analysis": "tran",
+                "axes": [
+                    {
+                        "id": axis_id,
+                        "name": "time",
+                        "quantity": "time",
+                        "unit": "s",
+                        "kind": "continuous",
+                        "scale": "linear",
+                        "values": [float(v) for v in grid],
+                    }
+                ],
+                "signals": [
+                    {
+                        "id": sig_id,
+                        "name": observe,
+                        "quantity": "voltage",
+                        "unit": "V",
+                        "values": {
+                            "storage": "inline",
+                            "dtype": "float64",
+                            "shape": [len(curve)],
+                            "data": [float(v) for v in curve],
+                        },
+                    }
+                ],
+                "conditions": [],
+            }
+        )
+        views.append(
+            {
+                "id": f"{run_id}:view:transient",
+                "kind": "traces",
+                "dataset_id": ds_id,
+                "name": observe,
+                "x_axis": axis_id,
+                "traces": [
+                    {"signal": sig_id, "transform": "identity",
+                     "axis": "left"}
+                ],
+            }
+        )
+    measurements = []
+    for item in measurements_in:
+        entry = {
+            "name": item["name"],
+            "value": _quantity(item["value"], item.get("unit", "")),
+            "margin": _quantity(item["margin"], item.get("unit", "")),
+            "status": "PASS" if item["status"] == "pass" else "FAIL",
+        }
+        bound = _limit(item)
+        if bound is not None:
+            entry["limit"] = _quantity(bound, item.get("unit", ""))
+        measurements.append(entry)
+    findings = [
+        {
+            "id": f"{run_id}:finding:{index}",
+            "severity": _SEVERITY.get(v.get("severity"), "info"),
+            "code": v.get("rule", "circuit"),
+            "message": _cap(v.get("message", "")),
+        }
+        for index, v in enumerate(violations)
+    ]
+    converged = not any(
+        v.get("rule") in ("circuit", "transient") for v in violations
+    )
+    return {
+        "schema": "rocketeda/results/v1",
+        "ref": {"scope": "project", "id": run_id, "revision": "r1"},
+        "run_id": run_id,
+        "task": TASK,
+        "target": dict(target)
+        if target is not None
+        else {"project_id": project_id, "kind": "project"},
+        "state": "complete",
+        "freshness": "current",
+        "convergence": "converged" if converged else "not_converged",
+        "provenance": _provenance(project_id, run_id, tools, provenance),
+        "datasets": datasets,
+        "views": views,
+        "measurements": measurements,
+        "findings": findings,
+        "artifacts": [],
+        "logs": [],
+        "gaps": [],
+    }

rocket_engine/adapters/cli/README.md

@@ -0,0 +1,34 @@
+# Adapters/cli — headless command surface
+
+## Responsibility (project decision)
+
+Every engine operation invokable, every event printable: the terminal
+client for debugging the headless engine without RocketIDE. Bare
+args drop into the interactive REPL; `run <op> [key=value ...]`
+runs one op; `--batch FILE`/`-` batch-executes; `--json` gives
+stable machine envelopes. Entry: `python -m rocket_engine` (a
+`[project.scripts]` `rocket-engine` alias can point at
+`adapters.cli:main` once packaging wires it).
+
+## Boundaries
+
+Same as every transport: protocol ↔ ports only. No logic. argv
+parsing/formatting lives here; op-call parsing and dispatch live in
+the use-case layer (`execution.dispatch`, the inbound port shared
+with console/MCP over the one catalog). Adapters never call each
+other.
+
+## Routing
+
+- Parent rules → `../README.md`.
+
+## Exits (honest)
+
+- 0 execution-ok, EVEN when the verdict is FAIL (verdicts live in
+  the payload, never in exit codes — same rule as solvers).
+- 1 engine error. 2 usage error (unknown op/args).
+
+## Status
+
+Live (CLI-DISPATCH). Console history replays as CLI batch scripts
+by construction — same dispatch, same grammar.

rocket_engine/adapters/cli/__init__.py

@@ -0,0 +1,305 @@
+"""CLI inbound adapter: argv parsing + result formatting over dispatch.
+
+`rocket-engine` (this module via `python -m rocket_engine`): bare
+args drop into the interactive REPL; `run <op> [key=value ...]`
+runs one op; `--batch FILE`/`-` batch-executes op lines; `--json`
+gives stable machine output. Op text parses through the one parser
+of record (`execution.dispatch`); this adapter never parses op
+calls itself, never calls another adapter, and holds no rules.
+
+Exits: 0 execution-ok EVEN when the verdict is FAIL (verdicts live
+in the payload, never in exit codes); 1 engine error; 2 usage
+error (unknown op/args). Batch aggregates: any usage error -> 2,
+else any engine error -> 1, else 0.
+"""
+
+import json
+import sys
+
+from ...composition import Engine
+from ...execution.dispatch import OpDispatcher, parse_op_call, parse_op_tokens
+from ...execution.errors import UsageError
+from ..errors import AdapterError, error_payload
+
+__all__ = ["EXIT_ENGINE_ERROR", "EXIT_OK", "EXIT_USAGE", "USAGE", "main"]
+
+EXIT_OK = 0
+EXIT_ENGINE_ERROR = 1
+EXIT_USAGE = 2
+
+USAGE = """usage: rocket-engine [--project ID] [--actor NAME] [--request-id ID] [--json] [--batch FILE|-] [run <op> [key=value ...]]
+
+No args drops into the interactive REPL (one op call per line,
+blank lines and `#` comments skipped, `quit` to leave). `run`
+executes one op call; `--batch` executes every op-call line of a
+file (`-` reads stdin). `--json` prints stable machine envelopes.
+`--request-id` stamps a caller id on a single `run` (batch and
+REPL lines always mint their own, so repeats stay distinct).
+Op calls are `<operation> [key=value ...]` with YAML-scalar values
+(`benches=[ac,tran]`, `deck={tool: klayout}`); quote values with
+spaces. Every call — queries and operations alike — goes through
+submit, the one admission path.
+
+Exits: 0 execution-ok (even when the verdict is FAIL — read the
+payload); 1 engine error; 2 usage error (unknown op/args).
+"""
+
+
+def _split_flag(token, name):
+    prefix = f"--{name}="
+    if token.startswith(prefix):
+        return token[len(prefix):]
+    return None
+
+
+def _parse_argv(argv):
+    options = {"json": False, "batch": None, "project": "default",
+               "actor": "cli", "request_id": None, "help": False}
+    rest = []
+    i = 0
+    while i < len(argv):
+        token = argv[i]
+        if token == "--json":
+            options["json"] = True
+        elif token in ("--help", "-h"):
+            options["help"] = True
+        elif token == "--batch":
+            i += 1
+            if i >= len(argv):
+                raise UsageError(
+                    "invalid_command", "`--batch` needs a FILE (`-` for stdin).")
+            options["batch"] = argv[i]
+        elif token == "--project":
+            i += 1
+            if i >= len(argv):
+                raise UsageError("invalid_command", "`--project` needs an ID.")
+            options["project"] = argv[i]
+        elif token == "--actor":
+            i += 1
+            if i >= len(argv):
+                raise UsageError("invalid_command", "`--actor` needs a NAME.")
+            options["actor"] = argv[i]
+        elif token == "--request-id":
+            i += 1
+            if i >= len(argv):
+                raise UsageError(
+                    "invalid_command", "`--request-id` needs an ID.")
+            options["request_id"] = argv[i]
+        elif _split_flag(token, "batch") is not None:
+            options["batch"] = _split_flag(token, "batch")
+        elif _split_flag(token, "project") is not None:
+            options["project"] = _split_flag(token, "project")
+        elif _split_flag(token, "actor") is not None:
+            options["actor"] = _split_flag(token, "actor")
+        elif _split_flag(token, "request-id") is not None:
+            options["request_id"] = _split_flag(token, "request-id")
+        elif token == "--":
+            rest.extend(argv[i + 1:])
+            break
+        elif token.startswith("-"):
+            raise UsageError("invalid_command", f"Unknown flag: {token}.")
+        else:
+            rest.extend(argv[i:])
+            break
+        i += 1
+    return options, rest
+
+
+def _envelope(operation, ok, payload):
+    body = {"operation": operation, "ok": ok}
+    body["result" if ok else "error"] = payload
+    return json.dumps(body, sort_keys=True, default=str)
+
+
+def _human_summary(operation, result):
+    if isinstance(result, dict):
+        verdict = result.get("verdict")
+        if isinstance(verdict, dict) and "status" in verdict:
+            line = f"{operation}: {verdict['status']}"
+            if result.get("run_id"):
+                line += f" (run {result['run_id']})"
+            return line
+        return f"{operation}: ok"
+    return f"{operation}: {result}"
+
+
+def _emit_result(operation, result, as_json, stdout):
+    if as_json:
+        stdout.write(_envelope(operation, True, result) + "\n")
+    else:
+        stdout.write(_human_summary(operation, result) + "\n")
+
+
+def _emit_error(operation, exc, as_json, stdout, stderr):
+    payload = error_payload(exc)
+    if as_json:
+        stdout.write(_envelope(operation, False, payload) + "\n")
+    else:
+        line = f"error [{payload['code']}]: {payload['message']}"
+        if payload.get("fields"):
+            line += f" (fields: {', '.join(payload['fields'])})"
+        stderr.write(line + "\n")
+        if isinstance(exc, UsageError):
+            stderr.write(USAGE)
+
+
+def _classify(exc):
+    if isinstance(exc, UsageError):
+        return EXIT_USAGE
+    return EXIT_ENGINE_ERROR
+
+
+def _run_single(dispatch, options, op_tokens, stdout, stderr):
+    if not op_tokens:
+        _emit_error(None, UsageError("invalid_command", "`run` needs an operation."),
+                    options["json"], stdout, stderr)
+        return EXIT_USAGE
+    try:
+        operation, arguments = parse_op_tokens(op_tokens)
+    except UsageError as exc:
+        _emit_error(op_tokens[0], exc, options["json"], stdout, stderr)
+        return EXIT_USAGE
+    try:
+        result = dispatch.execute(operation, arguments,
+                                  request_id=options["request_id"])
+    except Exception as exc:  # engine errors stay data, never tracebacks
+        _emit_error(operation, exc, options["json"], stdout, stderr)
+        return _classify(exc)
+    _emit_result(operation, result, options["json"], stdout)
+    return EXIT_OK
+
+
+def _iter_batch_lines(source, stdin):
+    if source == "-":
+        return stdin.read().splitlines()
+    try:
+        with open(source, encoding="utf-8") as handle:
+            return handle.read().splitlines()
+    except OSError as exc:
+        raise AdapterError(
+            "batch_unreadable", f"Cannot read batch file {source}: {exc}."
+        ) from exc
+
+
+def _run_batch(dispatch, options, source, stdin, stdout, stderr):
+    try:
+        lines = _iter_batch_lines(source, stdin)
+    except Exception as exc:
+        _emit_error(None, exc, options["json"], stdout, stderr)
+        return _classify(exc)
+    worst = EXIT_OK
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        try:
+            operation, result = dispatch.execute_line(stripped)
+        except UsageError as exc:
+            _emit_error(stripped.split()[0] if stripped.split() else None,
+                        exc, options["json"], stdout, stderr)
+            worst = max(worst, EXIT_USAGE)
+            continue
+        except Exception as exc:
+            # execute_line parsed this line already; re-parse only to
+            # label the envelope — it cannot fail here.
+            operation = parse_op_call(stripped)[0]
+            _emit_error(operation, exc, options["json"], stdout, stderr)
+            worst = max(worst, EXIT_ENGINE_ERROR)
+            continue
+        _emit_result(operation, result, options["json"], stdout)
+    return worst
+
+
+def _run_repl(dispatch, options, stdin, stdout, stderr):
+    interactive = stdin.isatty() if hasattr(stdin, "isatty") else False
+    if interactive:
+        stdout.write("rocket> ")
+        stdout.flush()
+    while True:
+        line = stdin.readline()
+        if line == "":
+            break
+        stripped = line.strip()
+        if interactive:
+            stdout.write("rocket> ")
+            stdout.flush()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped in ("exit", "quit"):
+            break
+        if stripped == "help":
+            stdout.write(USAGE)
+            continue
+        try:
+            operation, result = dispatch.execute_line(stripped)
+        except UsageError as exc:
+            _emit_error(stripped.split()[0] if stripped.split() else None,
+                        exc, options["json"], stdout, stderr)
+            continue
+        except Exception as exc:
+            operation = parse_op_call(stripped)[0]
+            _emit_error(operation, exc, options["json"], stdout, stderr)
+            continue
+        _emit_result(operation, result, options["json"], stdout)
+    return EXIT_OK
+
+
+def main(argv=None, engine=None, stdin=None, stdout=None, stderr=None):
+    """Run the CLI; return the process exit code (never raise for use).
+
+    Bare args drop into the REPL, `run` executes one op, `--batch`
+    executes op lines; usage and engine failures become exit codes,
+    never tracebacks.
+
+    Args:
+        argv: Argument vector without the program name; defaults to
+            sys.argv[1:].
+        engine: Engine to dispatch against; constructed from
+            --project/--actor when omitted.
+        stdin: Input stream for the REPL and `--batch -`.
+        stdout: Stream for results and machine envelopes.
+        stderr: Stream for human-readable errors plus usage.
+
+    Returns:
+        Process exit code: 0 execution-ok (even when the verdict
+        is FAIL), 1 engine error, 2 usage error.
+
+    Caution: Exit zero is not PASS — the verdict lives in the
+        payload; read it, never the exit code.
+    """
+    argv = list(sys.argv[1:] if argv is None else argv)
+    stdin = sys.stdin if stdin is None else stdin
+    stdout = sys.stdout if stdout is None else stdout
+    stderr = sys.stderr if stderr is None else stderr
+    try:
+        options, rest = _parse_argv(argv)
+    except UsageError as exc:
+        _emit_error(None, exc, False, stdout, stderr)
+        return EXIT_USAGE
+    if options["help"]:
+        stdout.write(USAGE)
+        return EXIT_OK
+    if options["batch"] is not None and rest[:1] == ["run"]:
+        _emit_error(None, UsageError("invalid_command",
+                                     "Cannot combine `run` with `--batch`."),
+                    options["json"], stdout, stderr)
+        return EXIT_USAGE
+    if engine is None:
+        engine = Engine(options["project"], actor=options["actor"])
+    dispatch = OpDispatcher(engine, project_id=options["project"],
+                            actor=options["actor"])
+    if rest[:1] == ["run"]:
+        return _run_single(dispatch, options, rest[1:], stdout, stderr)
+    if rest:
+        _emit_error(None, UsageError("invalid_command",
+                                     f"Unknown command: {rest[0]} (want `run`)."),
+                    options["json"], stdout, stderr)
+        return EXIT_USAGE
+    if options["batch"] is not None:
+        return _run_batch(dispatch, options, options["batch"], stdin,
+                          stdout, stderr)
+    return _run_repl(dispatch, options, stdin, stdout, stderr)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())