simantic 0.2.0__py3-none-any.whl

simantic/__init__.py

@@ -0,0 +1,85 @@
+"""Python control of the Simantic simulators.
+
+One package covers both engines, because co-simulation puts them together:
+`analog-cli` for circuits and `sim` for firmware.
+
+    import simantic
+
+    with simantic.Sim(elf="fw.elf", repl="board.repl") as sim:   # live control
+        sim.expect("ready"); sim.run_for(0.5)
+    run = simantic.run_firmware("fw.elf", repl="board.repl",
+                                expect=["RESULT: PASS"])          # one-shot
+    report = simantic.run_tests("hardware/psu")                   # analog
+
+Neither binary is bundled. Point `$SIMANTIC_ANALOG_CLI` and `$SIMANTIC_SIM`
+at them, or put them on PATH.
+
+Installing this package also registers a pytest plugin that turns the
+manifests a project already keeps — `*.sim.toml` testplans and `test.yaml`
+fixture manifests — into individually addressable pytest items.
+
+The MCP-based agent session lives in `simantic.agent` and is not re-exported
+here: `Sim` is the Python surface; MCP is an adapter for chat clients.
+"""
+
+from ._locate import BinaryNotFound, analog_cli
+from .analog import AnalogCliError, plan_path, plan_test_names, run_tests
+from .fixtures import (
+    Manifest,
+    ModelLibraryUnavailable,
+    UnsupportedManifest,
+    load_manifest,
+)
+from .mcu import ServerNotConfigured, SimError, SimRun, sim_binary
+from .mcu import run as run_firmware
+from .pyrite import pyrite_binary
+from .pyrite import run as run_pyrite
+from .engine import EngineNotFound, engine_dir
+from .session import ExpectTimeout, Match, Sim
+from .report import (
+    Expect,
+    Finding,
+    Measurement,
+    ReportError,
+    Summary,
+    Test,
+    TestReport,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # analog
+    "AnalogCliError",
+    "Expect",
+    "Finding",
+    "Measurement",
+    "ReportError",
+    "Summary",
+    "Test",
+    "TestReport",
+    "analog_cli",
+    "plan_path",
+    "plan_test_names",
+    "run_tests",
+    # firmware
+    "Manifest",
+    "ModelLibraryUnavailable",
+    "ServerNotConfigured",
+    "SimError",
+    "SimRun",
+    "UnsupportedManifest",
+    "load_manifest",
+    "pyrite_binary",
+    "run_firmware",
+    "run_pyrite",
+    "sim_binary",
+    # scripted sessions (sim --control-stdio)
+    "Sim",
+    "Match",
+    "ExpectTimeout",
+    "EngineNotFound",
+    "engine_dir",
+    # shared
+    "BinaryNotFound",
+]

simantic/__main__.py

@@ -0,0 +1,10 @@
+"""`python -m simantic`, equivalent to the `simantic` command.
+
+The generated launcher lands in the environment's bin/ (Scripts\\ on Windows),
+which is not always on PATH. This entry point needs only an interpreter that
+can import the package, so it works wherever the install did.
+"""
+
+from ._cli import main
+
+raise SystemExit(main())

simantic/_cli.py

@@ -0,0 +1,139 @@
+"""The `simantic` command: authenticate, install binaries, report status.
+
+Thin by design. It exists so `pip install simantic` is followed by two
+obvious commands rather than a documentation hunt, not to become a third
+CLI alongside the simulators.
+"""
+
+from __future__ import annotations
+
+import argparse
+import getpass
+import sys
+
+from . import auth, install, telemetry
+from ._locate import BinaryNotFound, locate
+from .mcu import BINARY as SIM_BINARY
+from .mcu import ENV_VAR as SIM_ENV
+from ._locate import BINARY as ANALOG_BINARY
+from ._locate import ENV_VAR as ANALOG_ENV
+from .pyrite import BINARY as PYRITE_BINARY
+from .pyrite import ENV_VAR as PYRITE_ENV
+
+BINARIES = (
+    (ANALOG_BINARY, ANALOG_ENV),
+    (SIM_BINARY, SIM_ENV),
+    (PYRITE_BINARY, PYRITE_ENV),
+)
+
+
+def _auth(args) -> int:
+    token = args.token
+    if token is None and not sys.stdin.isatty():
+        token = sys.stdin.read().strip()
+    if token is not None:
+        credentials = auth.login(token)
+    elif sys.stdin.isatty() and not args.no_browser:
+        credentials = auth.browser_login()
+    else:
+        # Echo off: argv is visible to `ps`, and so is a shell history entry.
+        token = getpass.getpass("Personal access token (smtc_...): ").strip()
+        credentials = auth.login(token)
+
+    where = auth.sim_id_path()
+    who = f" for {credentials.email}" if credentials.email else ""
+    print(f"Credentials saved to {where}{who}")
+    return 0
+
+
+def _install(args) -> int:
+    names = args.binary or [name for name, _ in BINARIES] + [install.ENGINE_KEY]
+    failures = 0
+    for name in names:
+        try:
+            if name == install.ENGINE_KEY:
+                path = install.install_engine(force=args.force, channel=args.channel)
+            else:
+                path = install.install(name, force=args.force, channel=args.channel)
+            print(f"{name}: {path}")
+        except install.InstallError as exc:
+            print(f"{name}: {exc}", file=sys.stderr)
+            failures += 1
+    # Partial success is still useful — one engine may be published and the
+    # other not — so report it without discarding what did install.
+    return 1 if failures == len(names) else 0
+
+
+def _status(args) -> int:
+    try:
+        credentials = auth.load()
+        who = credentials.email or "(no email recorded)"
+        print(f"authenticated: {who}")
+    except auth.NotAuthenticated as exc:
+        print(f"not authenticated: {exc}")
+
+    print(f"binaries in: {install.bin_dir()}")
+    for name, env in BINARIES:
+        try:
+            print(f"  {name}: {locate(name, env)}")
+        except BinaryNotFound:
+            print(f"  {name}: not found (run `simantic install {name}`)")
+    engine = install.installed_engine()
+    print(f"  engine: {engine if engine else 'not found (fetched on first use, or `simantic install engine`)'}")
+    print(telemetry.describe())
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    # prog is left to argparse so usage reflects however it was invoked:
+    # `simantic`, the short `smtc`, or `python -m simantic`.
+    parser = argparse.ArgumentParser(
+        description="Simantic SDK: authentication and binaries."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_auth = sub.add_parser("auth", help="store backend credentials in ~/.sim_id")
+    p_auth.add_argument(
+        "--token",
+        help="personal access token; opens a browser sign-in, or reads stdin "
+        "when piped, when omitted",
+    )
+    p_auth.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="prompt for a token instead of opening a browser",
+    )
+    p_auth.set_defaults(func=_auth)
+
+    p_install = sub.add_parser("install", help="download simulator binaries")
+    p_install.add_argument("binary", nargs="*", help="defaults to all known binaries and the engine")
+    p_install.add_argument(
+        "--force", action="store_true", help="re-download even if already present"
+    )
+    p_install.add_argument(
+        "--channel",
+        help="release channel to install from (default: latest, or $SIMANTIC_CHANNEL)",
+    )
+    p_install.set_defaults(func=_install)
+
+    sub.add_parser("status", help="show credentials and resolved binaries").set_defaults(
+        func=_status
+    )
+
+    args = parser.parse_args(argv)
+    telemetry.record(f"cli.{args.command}")
+    try:
+        result = args.func(args)
+        # A CLI invocation is a natural moment to upload: the user is not
+        # waiting on a simulation, and the spool is due at most hourly.
+        telemetry.flush()
+        return result
+    except (auth.AuthError, install.InstallError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simantic/_locate.py

@@ -0,0 +1,76 @@
+"""Finding the simulator binaries.
+
+The SDK never bundles a binary: it drives whichever one the caller points at.
+Resolution order, most explicit first:
+
+1. an explicit argument
+2. the binary's environment variable
+3. ~/.simantic/bin, where `simantic install` puts things
+4. a `_bin/` directory inside this package
+5. PATH
+
+A deliberate `simantic install` outranks a bundled `_bin/` copy, so fetching
+a newer binary actually takes effect. The `_bin/` step is what would let a
+platform-specific wheel ship a binary and be found with no change here.
+"""
+
+import os
+import shutil
+from pathlib import Path
+
+
+class BinaryNotFound(RuntimeError):
+    """Raised when a simulator binary cannot be located."""
+
+
+def locate(
+    binary: str,
+    env_var: str,
+    explicit: str | os.PathLike[str] | None = None,
+) -> Path:
+    """Resolve `binary`, or raise BinaryNotFound explaining how to supply it."""
+    if explicit is not None:
+        path = Path(explicit)
+        if not path.exists():
+            raise BinaryNotFound(f"{path} does not exist")
+        return path
+
+    env = os.environ.get(env_var)
+    if env:
+        path = Path(env)
+        if not path.exists():
+            raise BinaryNotFound(f"${env_var} points at {path}, which does not exist")
+        return path
+
+    # Imported here: install imports nothing from this module, but keeping the
+    # dependency one-way makes that impossible to get wrong later.
+    from .install import bin_dir
+
+    try:
+        managed = bin_dir() / binary
+    except Exception:  # no HOME and no $SIMANTIC_HOME — just skip this step
+        managed = None
+    if managed is not None and managed.exists():
+        return managed
+
+    bundled = Path(__file__).parent / "_bin" / binary
+    if bundled.exists():
+        return bundled
+
+    found = shutil.which(binary)
+    if found:
+        return Path(found)
+
+    raise BinaryNotFound(
+        f"no {binary!r} binary found. Run `simantic install {binary}`, put it on "
+        f"PATH, or set ${env_var} to its location."
+    )
+
+
+ENV_VAR = "SIMANTIC_ANALOG_CLI"
+BINARY = "analog-cli"
+
+
+def analog_cli(explicit: str | os.PathLike[str] | None = None) -> Path:
+    """Resolve the analog-cli binary, or raise BinaryNotFound."""
+    return locate(BINARY, ENV_VAR, explicit)

simantic/agent.py

@@ -0,0 +1,175 @@
+"""A session against the pyrite MCP server.
+
+The CLI runner is one-shot: arguments in, transcript out, no state between
+calls. That suits a pytest item and suits nothing that needs to look around
+while firmware is stopped.
+
+This is the other shape. `pyrite-mcp` keeps a machine alive and exposes it
+as JSON-RPC tools over stdio, so a caller can break, step, read memory and
+registers, and continue — each call structured going in and coming out,
+with no argument strings to build or output to scrape.
+
+    with Session() as sim:
+        sim.call("simulate", elf="fw.elf", board="stm32f401")
+        print(sim.tools())
+
+The process is an implementation detail of the transport; the interface is
+the tool surface, which the server owns and this module does not duplicate.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from ._locate import locate
+from . import telemetry
+
+ENV_VAR = "SIMANTIC_PYRITE_MCP"
+BINARY = "pyrite-mcp"
+
+PROTOCOL_VERSION = "2024-11-05"
+
+
+class SessionError(RuntimeError):
+    """The server could not be started, or refused a call."""
+
+
+class ToolError(SessionError):
+    """A tool ran and reported failure. Distinct so a caller can react to a
+    failed operation without treating it as a broken session."""
+
+
+def mcp_binary(explicit: str | os.PathLike[str] | None = None) -> Path:
+    """Resolve the pyrite-mcp binary, or raise BinaryNotFound."""
+    return locate(BINARY, ENV_VAR, explicit)
+
+
+class Session:
+    """A live pyrite engine, addressed by tool name."""
+
+    def __init__(self, binary: str | os.PathLike[str] | None = None) -> None:
+        self._next_id = 0
+        try:
+            self._proc = subprocess.Popen(
+                [str(mcp_binary(binary))],
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,  # diagnostics only; stdout is the protocol
+                text=True,
+                bufsize=1,
+            )
+        except OSError as exc:
+            raise SessionError(f"cannot start {BINARY}: {exc}") from None
+        self._request("initialize", {"protocolVersion": PROTOCOL_VERSION})
+
+    # --- protocol ---
+
+    def _request(self, method: str, params: dict[str, Any]) -> Any:
+        self._next_id += 1
+        message = {
+            "jsonrpc": "2.0",
+            "id": self._next_id,
+            "method": method,
+            "params": params,
+        }
+        if self._proc.poll() is not None:
+            raise SessionError(f"{BINARY} exited with {self._proc.returncode}")
+        try:
+            self._proc.stdin.write(json.dumps(message) + "\n")
+            self._proc.stdin.flush()
+        except (BrokenPipeError, ValueError):
+            raise SessionError(f"{BINARY} closed its input") from None
+
+        # One response per request, in order: the server is single-threaded
+        # over stdio, so the next line is this call's answer.
+        line = self._proc.stdout.readline()
+        if not line:
+            raise SessionError(f"{BINARY} closed its output during {method!r}")
+        try:
+            response = json.loads(line)
+        except json.JSONDecodeError as exc:
+            raise SessionError(f"{BINARY} sent invalid JSON: {exc}") from None
+        if "error" in response:
+            detail = response["error"]
+            raise SessionError(f"{method} failed: {detail.get('message', detail)}")
+        return response.get("result")
+
+    # --- surface ---
+
+    def tools(self) -> list[str]:
+        """Every tool this server exposes, by name."""
+        result = self._request("tools/list", {})
+        return [t["name"] for t in result.get("tools", [])]
+
+    def call(self, tool: str, **arguments: Any) -> Any:
+        """Invoke a tool. Returns its parsed result.
+
+        A tool that reports failure raises ToolError rather than returning a
+        payload the caller has to inspect to notice something went wrong.
+        """
+        telemetry.record(f"mcp.{tool}")
+        result = self._request("tools/call", {"name": tool, "arguments": arguments})
+        payload = _parsed(result)
+        # The envelope's isError is not trusted: pyrite-mcp sets it on
+        # successful calls too, so it does not distinguish one from the
+        # other. The payload's own `error` does, and is what the tools
+        # themselves report through. Envelope flag only when there is no
+        # payload to ask.
+        if isinstance(payload, dict) and "error" in payload:
+            if payload["error"] is not None:
+                raise ToolError(f"{tool}: {payload['error']}")
+            return payload
+        if isinstance(result, dict) and result.get("isError") and not isinstance(payload, dict):
+            raise ToolError(f"{tool}: {_text_of(result)}")
+        return payload
+
+    # --- lifecycle ---
+
+    def close(self) -> None:
+        if self._proc.poll() is None:
+            try:
+                self._proc.stdin.close()
+            except (BrokenPipeError, ValueError):
+                pass
+            try:
+                self._proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._proc.kill()
+                self._proc.wait()
+
+    def __enter__(self) -> Session:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+def _text_of(result: dict) -> str:
+    """The text blocks of an MCP result, joined."""
+    parts = [
+        block.get("text", "")
+        for block in result.get("content", [])
+        if isinstance(block, dict) and block.get("type") == "text"
+    ]
+    return "\n".join(p for p in parts if p)
+
+
+def _parsed(result: Any) -> Any:
+    """A tool result as data where it is data, and as text where it is not.
+
+    Tools return their payload as a JSON string inside a text block, so the
+    caller would otherwise parse every response by hand.
+    """
+    if not isinstance(result, dict):
+        return result
+    text = _text_of(result)
+    if not text:
+        return result
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        return text

simantic/analog.py

@@ -0,0 +1,94 @@
+"""Driving `analog-cli` from Python.
+
+The CLI is the source of truth; this module is a typed subprocess wrapper
+around its JSON contract, not a reimplementation of anything it does.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import tomllib
+from collections.abc import Sequence
+from pathlib import Path
+
+from ._locate import analog_cli
+from . import telemetry
+from .report import ReportError, TestReport
+
+#: Exit codes that still produce a report: everything ran, verdicts inside.
+#: 0 = all passed, 1 = at least one test failed or errored.
+_REPORT_EXITS = frozenset({0, 1})
+
+_EXIT_MEANINGS = {
+    2: "bad project",
+    3: "kicad-cli not found",
+    4: "the runner itself failed",
+    6: "testplan invalid or unreadable",
+}
+
+
+class AnalogCliError(RuntimeError):
+    """analog-cli exited with a code that carries no report."""
+
+    def __init__(self, code: int, stderr: str) -> None:
+        meaning = _EXIT_MEANINGS.get(code, "unknown failure")
+        super().__init__(f"analog-cli exited {code} ({meaning})\n{stderr.strip()}")
+        self.code = code
+        self.stderr = stderr
+
+
+def run_tests(
+    project: str | os.PathLike[str],
+    *,
+    plan: str | os.PathLike[str] | None = None,
+    only: Sequence[str] | None = None,
+    binary: str | os.PathLike[str] | None = None,
+    timeout: float | None = None,
+) -> TestReport:
+    """Run a project's testplan and return the parsed report.
+
+    `project` is a directory or .kicad_pro. Without `plan`, analog-cli uses
+    the project's <name>.sim.toml, falling back to its built-in static checks.
+    A failing test is a normal outcome and comes back in the report; only
+    conditions that prevent a run at all raise AnalogCliError.
+    """
+    telemetry.record("sdk.run_tests")
+    cmd = [str(analog_cli(binary)), "test", "-p", str(project), "--format", "json"]
+    if plan is not None:
+        cmd += ["--plan", str(plan)]
+    for name in only or ():
+        cmd += ["--only", name]
+
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+    if proc.returncode not in _REPORT_EXITS:
+        raise AnalogCliError(proc.returncode, proc.stderr)
+
+    try:
+        data = json.loads(proc.stdout)
+    except json.JSONDecodeError as exc:
+        raise ReportError(
+            f"analog-cli exited {proc.returncode} but did not emit JSON: {exc}"
+        ) from exc
+    return TestReport.from_json(data)
+
+
+def plan_path(project: str | os.PathLike[str]) -> Path | None:
+    """The <name>.sim.toml a project directory would use, if it exists."""
+    path = Path(project)
+    directory = path.parent if path.suffix == ".kicad_pro" else path
+    candidates = sorted(directory.glob("*.sim.toml"))
+    return candidates[0] if candidates else None
+
+
+def plan_test_names(plan: str | os.PathLike[str]) -> list[str]:
+    """Names of the [[test]] tables in a .sim.toml testplan, in file order.
+
+    Read directly so a test runner can enumerate cases without invoking the
+    CLI once per collection. Unnamed tables are skipped: --only matches by
+    name, so a nameless test is not individually addressable.
+    """
+    with open(plan, "rb") as fh:
+        data = tomllib.load(fh)
+    return [t["name"] for t in data.get("test", []) if "name" in t]