rocket-engine 0.0.2b1__py3-none-any.whl

rocket_engine/adapters/meow/results.py

@@ -0,0 +1,218 @@
+"""Meow v1 normalizer: v0 parse output to a ResultBundle.
+
+Maps the ``run_em`` parse shape (``measurements[]`` with ratio
+value, target, margin, and pass/fail status plus convergence
+values) onto a typed metrics table, a bound 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_em"
+
+_DIAG_CAP = 240
+
+_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 _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 meow parse output to a v1 ResultBundle.
+
+    Metric rows become a table dataset plus a bound table view;
+    violations become findings with capped messages. PASS
+    measurements keep value, target, margin, and status. A
+    malformed device (no metrics) reports not_converged with its
+    error finding.
+
+    Args:
+        parsed: v0 parse mapping with ``measurements[]`` 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 []
+    violations = parsed.get("violations") or []
+    table_id = f"{run_id}:dataset:metrics"
+    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:metrics",
+            "kind": "table",
+            "dataset_id": table_id,
+            "name": "em metrics",
+        }
+    ]
+    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", "device"),
+            "message": _cap(v.get("message", "")),
+        }
+        for index, v in enumerate(violations)
+    ]
+    converged = not any(
+        v.get("rule") in ("device", "s_param", "convergence")
+        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/mutation/__init__.py

@@ -0,0 +1,192 @@
+"""Mutation adapter: run_mutation with the mcy provider."""
+
+import re
+import shutil
+import sqlite3
+import subprocess
+from pathlib import Path
+
+from ...execution.errors import ExecutionError
+from ...interfaces import ToolAdapter
+from ..errors import AdapterError
+
+OPERATION = "run_mutation"
+_TOOL = "mcy"
+_DB = "database/db.sqlite3"
+_OUTPUT_RE = re.compile(r"^(\d+)\s+(\S+)\s*$")
+
+
+def _parse_output_txt(text):
+    """Parse one output.txt streaming verdict file.
+
+    Args:
+        text: output.txt text with `<idx> <RESULT>` per line.
+
+    Returns:
+        List of {mutation_id, result} rows.
+    """
+    rows = []
+    for line in (text or "").splitlines():
+        match = _OUTPUT_RE.match(line.strip())
+        if match is None:
+            continue
+        rows.append({"mutation_id": int(match.group(1)),
+                     "result": match.group(2)})
+    return rows
+
+
+class McyAdapter(ToolAdapter):
+    """run_mutation via mcy: sqlite DB plus output.txt streaming.
+
+    Serves the run_mutation operation with tool `mcy`. Primary
+    results come from database/db.sqlite3 via stdlib sqlite3;
+    output.txt `<idx> <RESULT>` rows stream per-task verdicts
+    before DB commit. Never scrapes list/source/status stdout.
+
+    Job keys:
+        project (required): Mcy project dir with database/.
+        test: Test name for run scoping.
+        workdir: Run directory (default ".").
+        timeout_s: Budget in seconds (default 600).
+
+    Args:
+        runner: Optional isolated runner; direct subprocess when None.
+    """
+
+    def __init__(self, runner=None):
+        self._runner = runner
+
+    parse_output_txt = staticmethod(_parse_output_txt)
+
+    def capabilities(self, target):
+        """Report the served operation and tool.
+
+        Args:
+            target: Target the capabilities are reported for.
+
+        Returns:
+            Capability mapping with operations and tool.
+        """
+        return {"operations": [OPERATION], "tool": _TOOL, "db": _DB}
+
+    def preflight(self, job):
+        """Check operation, project dir, and mcy presence.
+
+        Args:
+            job: Solver job with operation run_mutation plus project.
+
+        Returns:
+            Checked mapping with project, binary, and timeout.
+
+        Raises:
+            AdapterError: unsupported_operation, invalid_reference
+                for a missing project, missing_dependency when mcy
+                is absent (BLOCKED-needs-host).
+        """
+        if job.get("operation") != OPERATION:
+            raise AdapterError(
+                "unsupported_operation",
+                f"Mcy handles {OPERATION}, got {job.get('operation')}.")
+        project = job.get("project")
+        if not project or not Path(project).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Mcy project not found: {project}.")
+        binary = shutil.which(_TOOL)
+        if binary is None:
+            raise AdapterError(
+                "missing_dependency",
+                "BLOCKED-needs-host: mcy not on PATH (oss-cad-suite).")
+        timeout = job.get("timeout_s", 600)
+        if (not isinstance(timeout, (int, float))
+                or isinstance(timeout, bool) or not timeout > 0):
+            raise AdapterError("invalid_command", f"Bad timeout: {timeout!r}.")
+        checked = {"project": str(project), "binary": binary,
+                   "timeout_s": timeout, "test": job.get("test")}
+        if self._runner is not None:
+            try:
+                self._runner.preflight()
+            except ExecutionError as exc:
+                raise AdapterError(exc.code, str(exc)) from exc
+        return checked
+
+    def execute(self, job):
+        """Run mcy on the project under a timeout.
+
+        Args:
+            job: Solver job with operation run_mutation plus project.
+
+        Returns:
+            Native output with exit_code, stdout/stderr, results,
+                and db file.
+        """
+        checked = self.preflight(job)
+        workdir = job.get("workdir", checked["project"])
+        if not Path(workdir).is_dir():
+            raise AdapterError(
+                "invalid_reference", f"Workdir not found: {workdir}.")
+        argv = [checked["binary"], "run"]
+        if checked["test"]:
+            argv.extend(["--test", str(checked["test"])])
+        try:
+            proc = subprocess.run(argv, capture_output=True, text=True,
+                                  timeout=checked["timeout_s"], cwd=workdir)
+        except subprocess.TimeoutExpired as exc:
+            raise AdapterError(
+                "runner_unavailable", "Mcy run timed out.") from exc
+        results = self.read_db(Path(workdir) / _DB)
+        return {"exit_code": proc.returncode, "stdout": proc.stdout,
+                "stderr": proc.stderr, "results": results,
+                "db_file": _DB}
+
+    def parse(self, native_output):
+        """Parse DB results to coverage plus uncovered violations.
+
+        Args:
+            native_output: Native output with the results rows.
+
+        Returns:
+            {total, violations[], coverage, source}.
+
+        Raises:
+            AdapterError: runner_unavailable with no results.
+        """
+        results = native_output.get("results")
+        if not isinstance(results, list) or not results:
+            raise AdapterError(
+                "runner_unavailable", "Mcy output has no results.")
+        uncovered = [r for r in results
+                     if str(r.get("result", "")).upper() != "COVERED"
+                     and str(r.get("result", "")).upper() != "PASS"]
+        coverage = ((len(results) - len(uncovered)) / len(results)
+                    if results else 0.0)
+        violations = [{"rule": "mutation_uncovered", "severity": "error",
+                       "message": f"Mutation {r.get('mutation_id')}"
+                                  f" {r.get('result')}."}
+                      for r in uncovered]
+        return {"total": len(violations), "violations": violations,
+                "coverage": coverage, "source": "db",
+                "db_file": native_output.get("db_file", _DB)}
+
+    @staticmethod
+    def read_db(path):
+        """Read cached results from one mcy sqlite DB.
+
+        Args:
+            path: database/db.sqlite3 path (missing reads as empty).
+
+        Returns:
+            Results rows (empty when the DB is absent).
+        """
+        if not Path(path).is_file():
+            return []
+        try:
+            conn = sqlite3.connect(str(path))
+            try:
+                rows = conn.execute(
+                    "SELECT mutation_id, test, result FROM results").fetchall()
+            finally:
+                conn.close()
+        except Exception:
+            return []
+        return [{"mutation_id": r[0], "test": r[1], "result": r[2]}
+                for r in rows]

rocket_engine/adapters/ngspice/README.md

@@ -0,0 +1,28 @@
+# ngspice adapter
+
+`run_spice` behind the ToolAdapter port (SIM-SKY130).
+
+Job: `sources` (netlists, `.end` lines stripped), `measurements`
+(`name`/`expr`/`min`/`max`/`unit`), `analyses` (default `op`),
+`options` (default `wnflag=1`), `params` (`.param` lines),
+`corner` (default `tt`), `temp_c` (default 27), optional `pdk`
+(`id`/`revision`/`model_rel`/`engine_root`, resolved through the
+PDK store so a wrong rev fails loudly before any sim).
+
+Staging: `ngspice_deck.spice` (preamble + bodies + generated
+`.control` with `let`/`print meas_*`) plus `.spiceinit`
+(neutral base lines plus the lane profile extras, see
+`../profile.py` and `docs/pdk/<lane>/profile.yaml`). Runs
+`ngspice -b -o ngspice.log ngspice_deck.spice`.
+
+Simulator needs are profile-driven (PDK-PROFILE pattern): the
+default model relpath and `.spiceinit` extras come from the PDK
+lane profile, never from adapter special-cases. An explicit
+`model_rel` in the job pin always wins; a PDK with no sim
+profile and no explicit `model_rel` fails loudly
+(`invalid_command`, never a guessed relpath).
+
+Parse: `meas_* = value` lines evaluated against bounds (SAX
+`measurements` shape); a sim yielding no values synthesizes
+`sim_fail` violations carrying ngspice's own error text. The
+verdict always comes from parsed output, never the exit code.