asp-studio 0.1.0__py3-none-any.whl

asp_studio/__init__.py

@@ -0,0 +1,18 @@
+"""ASP Studio: answer sets, graph and a step-by-step fixpoint animator for Answer Set Programming in Python.
+
+    import asp_studio as asp
+    res = asp.solve("a :- not b. b :- not a.")      # clingo Python API under the hood
+    asp.show(res)                                   # visualizer in a Jupyter / VS Code notebook
+
+In a notebook: ``%load_ext asp_studio`` and start a cell with ``%%asp``.
+"""
+from .solver import Diagnostic, Result, solve
+from .render import iframe, page, show
+
+__version__ = "0.1.0"
+__all__ = ["solve", "show", "Result", "Diagnostic", "page", "iframe", "load_ipython_extension", "__version__"]
+
+
+def load_ipython_extension(ipython):  # `%load_ext asp_studio`
+    from .magic import load_ipython_extension as _load
+    _load(ipython)

asp_studio/__main__.py

@@ -0,0 +1,65 @@
+"""``python -m asp_studio program.lp`` (or ``asp-studio program.lp``): solve files and write a standalone HTML report."""
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+import webbrowser
+from typing import List, Optional
+
+from .render import page
+from .solver import solve
+
+
+def _fail(message: str, code: int = 2) -> int:
+    print(f"error: {message}", file=sys.stderr)
+    return code
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    ap = argparse.ArgumentParser(prog="asp-studio", description="Solve ASP files and write an interactive HTML report.")
+    ap.add_argument("files", nargs="+", type=pathlib.Path, help=".lp files (joined in order)")
+    ap.add_argument("-n", "--models", type=int, default=0, help="max answer sets (0 = all)")
+    ap.add_argument("-o", "--options", default="", help='extra clingo options, e.g. "--opt-mode=optN"')
+    ap.add_argument("-t", "--timeout", type=float, default=10.0, help="seconds (default 10)")
+    ap.add_argument("--out", type=pathlib.Path, help="output file (default: <first file>.html)")
+    ap.add_argument("--tab", default="animator", choices=["animator", "answers", "graph", "console"])
+    ap.add_argument("--theme", default="auto", choices=["auto", "light", "dark"])
+    ap.add_argument("--open", action="store_true", help="open the report in the browser")
+    a = ap.parse_args(argv)
+
+    if a.models < 0:
+        return _fail("--models must be 0 or greater")
+    if a.timeout <= 0:
+        return _fail("--timeout must be greater than 0")
+    for f in a.files:
+        if f.is_dir():
+            return _fail(f"{f} is a directory, not a file")
+        if not f.is_file():
+            return _fail(f"{f} does not exist")
+        try:
+            f.read_text(encoding="utf-8")
+        except UnicodeDecodeError as e:
+            return _fail(f"{f} is not UTF-8 text ({e.reason} at byte {e.start}); is it an ASP file?")
+        except OSError as e:
+            return _fail(f"cannot read {f}: {e.strerror or e}")
+    res = solve(list(a.files), models=a.models, options=a.options, timeout=a.timeout)
+
+    out = a.out or a.files[0].with_suffix(".html")
+    try:
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(page(res, tab=a.tab, theme=a.theme, max_height=100000, title=a.files[0].name), encoding="utf-8")
+    except OSError as e:
+        return _fail(f"cannot write {out}: {e.strerror or e}", 1)
+
+    for d in res.diagnostics:
+        print(f"{d.file}:{d.line}:{d.col}: {d.severity}: {d.message.splitlines()[0]}", file=sys.stderr)
+    status = res.error or f"{res.result}, {len(res)} model(s), {res.ms} ms"
+    print(f"{status} -> {out}")
+    if a.open:
+        webbrowser.open(out.resolve().as_uri())
+    return 1 if res.error else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

asp_studio/magic.py

@@ -0,0 +1,48 @@
+"""IPython cell magic: ``%%asp`` solves the cell and shows the visualizer."""
+from __future__ import annotations
+
+import argparse
+import shlex
+from typing import Any
+
+from IPython.core.magic import Magics, cell_magic, magics_class
+
+from .render import show
+from .solver import solve
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="%%asp", add_help=False)
+    p.add_argument("-n", "--models", type=int, default=0, help="max answer sets (0 = all)")
+    p.add_argument("-o", "--options", default="", help="extra clingo options, quoted")
+    p.add_argument("-t", "--timeout", type=float, default=10.0)
+    p.add_argument("--tab", default="animator", choices=["animator", "answers", "graph", "console"])
+    p.add_argument("--theme", default="auto", choices=["auto", "light", "dark"])
+    p.add_argument("--height", type=int, default=None)
+    p.add_argument("--out", default=None, help="store the Result in this variable")
+    return p
+
+
+@magics_class
+class AspMagics(Magics):
+    @cell_magic
+    def asp(self, line: str, cell: str) -> Any:
+        """Solve the cell with clingo and show answer sets, graph and animator.
+
+        %%asp [-n N] [-o "--opt-mode=optN"] [-t SECONDS] [--tab animator|answers|graph|console]
+              [--theme auto|light|dark] [--height PX] [--out NAME]
+        """
+        try:
+            a = _parser().parse_args(shlex.split(line))
+        except SystemExit:
+            print(self.asp.__doc__)
+            return None
+        res = solve(cell, models=a.models, options=a.options, timeout=a.timeout)
+        show(res, tab=a.tab, theme=a.theme, height=a.height)
+        if a.out:
+            self.shell.user_ns[a.out] = res
+        return None
+
+
+def load_ipython_extension(ipython: Any) -> None:
+    ipython.register_magics(AspMagics)

asp_studio/render.py

@@ -0,0 +1,61 @@
+"""Build the visualizer page (HTML) for a :class:`~asp_studio.solver.Result`."""
+from __future__ import annotations
+
+import html as _html
+import json
+from importlib import resources
+from typing import Any, Optional
+
+_STATIC = ("themes.css", "webview.css")
+_cache: dict = {}
+
+
+def _asset(name: str) -> str:
+    if name not in _cache:
+        _cache[name] = resources.files("asp_studio").joinpath("static", name).read_text(encoding="utf-8")
+    return _cache[name]
+
+
+def _js_json(value: Any) -> str:
+    """JSON that is safe to place inside a <script> element."""
+    return json.dumps(value).replace("</", "<\\/").replace("<!--", "<\\!--")
+
+
+def page(result, *, tab: str = "animator", theme: str = "auto", max_height: int = 760, title: str = "program") -> str:
+    """A complete, self-contained HTML document showing the visualizer."""
+    init = {"state": result.to_state(), "program": result.program, "tab": tab, "theme": theme,
+            "maxHeight": max_height, "title": title}
+    css = "\n".join(_asset(n) for n in _STATIC)
+    return (
+        '<!DOCTYPE html><html lang="en"><head><meta charset="utf-8">'
+        '<meta name="viewport" content="width=device-width, initial-scale=1">'
+        f"<title>ASP Studio: {_html.escape(title)}</title><style>{css}</style></head>"
+        '<body><div id="app"></div>'
+        f"<script>window.__ASP_INIT__ = {_js_json(init)};</script>"
+        f"<script>{_asset('engine.js')}</script>"
+        f"<script>{_asset('bootstrap.js')}</script>"
+        f"<script>{_asset('webview.js')}</script>"
+        "</body></html>"
+    )
+
+
+def iframe(result, *, tab: str = "animator", theme: str = "auto", height: Optional[int] = None, max_height: int = 760) -> str:
+    """The page wrapped in an isolated <iframe>, ready to display in a notebook output."""
+    doc = page(result, tab=tab, theme=theme, max_height=max_height)
+    start = height if height else 420
+    return (
+        '<iframe class="asp-studio" sandbox="allow-scripts allow-same-origin" '
+        f'style="width:100%;height:{start}px;border:0;display:block" srcdoc="{_html.escape(doc, quote=True)}"></iframe>'
+    )
+
+
+def show(program_or_result, *, tab: str = "animator", theme: str = "auto", height: Optional[int] = None,
+         max_height: int = 760, **solve_kwargs: Any) -> None:
+    """Display the visualizer in the current notebook cell. ``program_or_result`` may be ASP text or a Result."""
+    try:
+        from IPython.display import display
+    except ImportError as e:  # pragma: no cover
+        raise ImportError("asp_studio.show needs IPython: pip install 'asp-studio[notebook]'") from e
+    from .solver import Result, solve
+    result = program_or_result if isinstance(program_or_result, Result) else solve(program_or_result, **solve_kwargs)
+    display({"text/html": iframe(result, tab=tab, theme=theme, height=height, max_height=max_height)}, raw=True)

asp_studio/solver.py

@@ -0,0 +1,214 @@
+"""Solve an ASP program with the clingo Python API and keep everything the visualizer needs."""
+from __future__ import annotations
+
+import re
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+import clingo
+
+Program = Union[str, Path]
+
+_DIAG = re.compile(
+    r"^(?:<block>|<string>|-):(\d+):(\d+)(?:-(\d+))?(?::(\d+)(?:-(\d+))?)?: (error|warning|info): (.*)$"
+)
+
+
+@dataclass
+class Diagnostic:
+    line: int
+    col: int
+    end_col: int
+    severity: str
+    message: str
+    file: str = "program"
+
+
+@dataclass(repr=False)
+class Result:
+    """Outcome of :func:`solve`. Iterating yields the answer sets (lists of atom strings)."""
+
+    program: str
+    version: str = clingo.__version__
+    command: str = ""
+    result: str = "UNKNOWN"
+    models: List[List[str]] = field(default_factory=list)
+    costs: List[Optional[List[int]]] = field(default_factory=list)
+    more: bool = False
+    ms: int = 0
+    time: Optional[float] = None
+    stderr: str = ""
+    diagnostics: List[Diagnostic] = field(default_factory=list)
+    error: Optional[str] = None
+    timed_out: bool = False
+
+    def __repr__(self) -> str:
+        if self.error:
+            return f"Result(error={self.error!r})"
+        return f"Result({self.result}, {len(self.models)} model{'s' if len(self.models) != 1 else ''}, {self.ms} ms)"
+
+    @property
+    def ok(self) -> bool:
+        """True if the program ran without error (it may still be unsatisfiable)."""
+        return self.error is None
+
+    @property
+    def satisfiable(self) -> bool:
+        return self.ok and bool(self.models)
+
+    def __iter__(self):
+        return iter(self.models)
+
+    def __len__(self) -> int:
+        return len(self.models)
+
+    def __getitem__(self, i: int) -> List[str]:
+        return self.models[i]
+
+    def to_state(self) -> Dict[str, Any]:
+        """The ``solve`` object the visualizer front end renders."""
+        state: Dict[str, Any] = {
+            "engine": "python",
+            "version": self.version,
+            "command": self.command,
+            "result": self.result,
+            "models": [{"atoms": a, "costs": c} for a, c in zip(self.models, self.costs)],
+            "totalModels": len(self.models),
+            "more": self.more,
+            "ms": self.ms,
+            "time": self.time,
+            "stderr": self.stderr,
+            "capped": 0,
+            "diagnostics": [
+                {"sourceIndex": 0, "file": d.file, "line": d.line, "col": d.col, "endCol": d.end_col,
+                 "severity": d.severity, "message": d.message}
+                for d in self.diagnostics
+            ],
+        }
+        if self.error:
+            state["error"] = self.error
+            state["timedOut"] = self.timed_out
+        return state
+
+    def _repr_html_(self) -> str:  # picked up by Jupyter when a Result is the last expression of a cell
+        from .render import iframe
+        return iframe(self)
+
+    def show(self, **kwargs: Any) -> None:
+        from .render import show
+        show(self, **kwargs)
+
+
+def _read(programs: Union[Program, Sequence[Program]]) -> Tuple[str, List[Tuple[str, int]]]:
+    """Join the programs; also return (name, line count) per part so messages can be mapped back to their file."""
+    items: Iterable[Program] = [programs] if isinstance(programs, (str, Path)) else programs
+    parts: List[str] = []
+    sources: List[Tuple[str, int]] = []
+    for p in items:
+        text = p.read_text(encoding="utf-8") if isinstance(p, Path) else p
+        parts.append(text)
+        sources.append((p.name if isinstance(p, Path) else "program", len(text.split("\n"))))
+    return "\n".join(parts) + "\n", sources
+
+
+def _locate(sources: Sequence[Tuple[str, int]], line: int) -> Tuple[str, int]:
+    """Map a 1-based line of the joined program to (file name, line in that file)."""
+    start = 0
+    for name, count in sources:
+        if line - 1 < start + count:
+            return name, line - start
+        start += count
+    return (sources[-1][0], 1) if sources else ("program", line)
+
+
+def _parse_messages(messages: Sequence[str], sources: Sequence[Tuple[str, int]]) -> List[Diagnostic]:
+    out: List[Diagnostic] = []
+    for msg in messages:
+        lines = msg.split("\n")
+        m = _DIAG.match(lines[0])
+        if not m:
+            continue
+        col = int(m.group(2))
+        # `L:C1-C2` marks a range on one line; `L:C1-L2:C2` spans lines, then only the start is used
+        end = int(m.group(3)) if m.group(3) and m.group(4) is None else col + 1
+        text = m.group(7)
+        extra = [l.strip() for l in lines[1:] if l.strip() and not l.startswith("***")]
+        if extra:
+            text += "\n" + "\n".join(extra)
+        sev = {"error": "error", "info": "info"}.get(m.group(6), "warning")
+        name, line = _locate(sources, int(m.group(1)))
+        out.append(Diagnostic(line, col, end, sev, text, name))
+    return out
+
+
+def solve(
+    program: Union[Program, Sequence[Program]],
+    *,
+    models: int = 0,
+    options: Union[str, Sequence[str]] = (),
+    timeout: float = 10.0,
+) -> Result:
+    """Solve ``program`` and return a :class:`Result`.
+
+    ``program`` is ASP text, a :class:`pathlib.Path`, or a list of those (joined in order).
+    ``models`` limits the number of answer sets (0 = all). ``options`` are extra clingo options,
+    either a list or one string such as ``"--opt-mode=optN -c n=6"``. ``timeout`` is in seconds.
+    With optimisation statements and a finished search only the optimal models are kept.
+    """
+    text, sources = _read(program)
+    opts = options.split() if isinstance(options, str) else list(options)
+    args = [str(max(0, int(models)))] + opts
+    res = Result(program=text, command="clingo.Control(" + repr(args) + ")")
+    messages: List[str] = []
+    found: List[Any] = []
+    exhausted = False
+    t0 = time.perf_counter()
+
+    def on_model(m: clingo.Model) -> None:
+        found.append(([str(s) for s in m.symbols(shown=True)], list(m.cost) if m.cost else None, m.optimality_proven))
+
+    try:
+        ctl = clingo.Control(args, lambda code, msg: messages.append(msg), 50)
+        ctl.add("base", [], text)
+        ctl.ground([("base", [])])
+        handle = ctl.solve(on_model=on_model, async_=True)
+        if not handle.wait(timeout):
+            handle.cancel()
+            handle.get()
+            res.timed_out = True
+            res.error = f"Timeout after {timeout:g} s."
+        else:
+            sr = handle.get()
+            res.result = "SATISFIABLE" if sr.satisfiable else "UNSATISFIABLE" if sr.unsatisfiable else "UNKNOWN"
+            exhausted = bool(sr.exhausted)
+            res.more = bool(models) and len(found) >= models and not exhausted
+            try:
+                res.time = float(ctl.statistics["summary"]["times"]["total"])
+            except Exception:  # statistics are optional
+                res.time = None
+    except RuntimeError as e:
+        res.error = str(e)
+    res.diagnostics = _parse_messages(messages, sources)
+    if res.error and not res.timed_out and any(d.severity == "error" for d in res.diagnostics):
+        res.error = "The program has a syntax or semantic error."
+    res.stderr = "".join(m if m.endswith("\n") else m + "\n" for m in messages)
+    res.ms = round((time.perf_counter() - t0) * 1000)
+
+    if res.error is None:
+        optimising = any(f[1] for f in found)
+        keep = found
+        if optimising and exhausted:                     # search finished: only the best cost is optimal
+            best = min(tuple(f[1] or ()) for f in found)
+            keep = [f for f in found if tuple(f[1] or ()) == best]
+            res.result = "OPTIMUM FOUND"
+        seen = set()
+        for atoms, cost, _ in keep:
+            key = tuple(atoms)
+            if key in seen:
+                continue
+            seen.add(key)
+            res.models.append(atoms)
+            res.costs.append(cost)
+    return res

asp_studio/static/bootstrap.js

@@ -0,0 +1,64 @@
+/* Glue that lets media/webview.js run outside VS Code (notebook output or standalone page).
+ * Provides the small acquireVsCodeApi() surface, picks a theme and keeps the iframe height in sync. */
+(function () {
+  "use strict";
+  const init = window.__ASP_INIT__ || {};
+  const query = new URLSearchParams(location.search);       // ?theme=dark&tab=graph overrides the defaults of a standalone page
+  if (query.get("theme")) init.theme = query.get("theme");
+  if (query.get("tab")) init.tab = query.get("tab");
+  if (query.get("round") !== null && /^\d+$/.test(query.get("round"))) window.__ASP_START_ROUND__ = +query.get("round");   // animator starts at this round
+  window.__ASP_EMBED__ = true;
+  const root = document.documentElement;
+  root.classList.add("embed-doc");
+
+  /* ---- theme: explicit > VS Code variables of the host > JupyterLab > OS preference */
+  function applyTheme() {
+    if (init.theme === "light" || init.theme === "dark") { root.dataset.theme = init.theme; return; }
+    try {
+      const host = window.parent !== window ? window.parent.document : null;
+      if (!host) return;
+      const style = host.documentElement.style;
+      let n = 0;
+      for (let i = 0; i < style.length; i++) {
+        const k = style[i];
+        if (k.startsWith("--vscode-")) { root.style.setProperty(k, style.getPropertyValue(k)); n++; }
+      }
+      if (n) return;
+      const jp = host.body && host.body.dataset && host.body.dataset.jpThemeLight;
+      if (jp !== undefined) root.dataset.theme = jp === "true" ? "light" : "dark";
+    } catch (e) { /* cross-origin host: keep the OS preference */ }
+  }
+  applyTheme();
+
+  /* ---- messaging shim */
+  const TABS = { animator: "anim", anim: "anim", answers: "models", models: "models", graph: "graph", console: "console" };
+  let saved = { tab: TABS[init.tab] || "anim" };
+  window.acquireVsCodeApi = () => ({
+    postMessage(m) {
+      if (m && m.type === "ready") setTimeout(deliver, 0);
+    },
+    getState: () => saved,
+    setState: s => { saved = s; },
+  });
+
+  function deliver() {
+    const text = init.program || "";
+    const anim = text.trim() && window.AspEngine ? window.AspEngine.animationFor(text, init.title || "program") : null;
+    const solve = init.state || null;
+    window.postMessage({
+      type: "state", file: { name: init.title || "program", scope: "activeFile" }, status: solve && solve.error ? "error" : "done",
+      solve, anim, empty: !text.trim(), settings: { speed: 1400 },
+    }, "*");
+  }
+
+  /* ---- keep the surrounding iframe as tall as its content (up to maxHeight) */
+  function fit() {
+    try {
+      const f = window.frameElement;
+      if (!f) return;
+      const h = Math.ceil(document.body.getBoundingClientRect().height);
+      f.style.height = Math.min(init.maxHeight || 760, h) + "px";
+    } catch (e) { /* not embedded in an iframe */ }
+  }
+  addEventListener("load", () => { fit(); new ResizeObserver(fit).observe(document.body); });
+})();

asp_studio/static/engine.js

@@ -0,0 +1,187 @@
+/* Fixpoint engine for positive ASP programs: parser (with source positions) and
+ * naive bottom-up evaluation, round by round. Runs in Node and in the webview. */
+(function (root, factory) {
+  const api = factory();
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.AspEngine = api;
+})(typeof self !== "undefined" ? self : this, function () {
+  "use strict";
+
+  class AspError extends Error {
+    constructor(message, line) { super(message); this.name = "AspError"; this.line = line; }
+  }
+
+  /** Split on `sep`, ignoring separators nested in parentheses. */
+  function splitTop(s, sep) {
+    const out = []; let depth = 0, cur = "";
+    for (const ch of s) {
+      if (ch === "(") depth++;
+      if (ch === ")") depth--;
+      if (ch === sep && depth === 0) { out.push(cur); cur = ""; } else cur += ch;
+    }
+    if (cur.trim() !== "") out.push(cur);
+    return out.map(x => x.trim()).filter(Boolean);
+  }
+
+  const isVar = t => /^[A-Z_]/.test(t);
+
+  function parseTerm(t, line) {
+    t = t.trim();
+    if (!/^[A-Za-z0-9_]+$/.test(t)) throw new AspError("Unsupported term: " + t, line);
+    return t;
+  }
+
+  function parseAtom(s, line) {
+    s = s.trim();
+    const m = s.match(/^([a-z][A-Za-z0-9_]*)\s*(?:\((.*)\))?$/s);
+    if (!m) throw new AspError("Cannot read atom: " + s, line);
+    const args = m[2] === undefined ? [] : splitTop(m[2], ",").map(t => parseTerm(t, line));
+    return { pred: m[1], args };
+  }
+
+  /** Replace `% ...` and `%* ... *%` comments by spaces so offsets and line numbers stay valid. */
+  function blankComments(text) {
+    let out = "", i = 0;
+    const blank = s => s.replace(/[^\n]/g, " ");
+    while (i < text.length) {
+      if (text.startsWith("%*", i)) {
+        const j = text.indexOf("*%", i + 2), end = j < 0 ? text.length : j + 2;
+        out += blank(text.slice(i, end)); i = end;
+      } else if (text[i] === "%") {
+        let j = text.indexOf("\n", i); if (j < 0) j = text.length;
+        out += " ".repeat(j - i); i = j;
+      } else out += text[i++];
+    }
+    return out;
+  }
+
+  const lineAt = (starts, offset) => {            // 0-based line of a character offset
+    let lo = 0, hi = starts.length - 1;
+    while (lo < hi) { const mid = (lo + hi + 1) >> 1; if (starts[mid] <= offset) lo = mid; else hi = mid - 1; }
+    return lo;
+  };
+
+  /**
+   * Parse a positive program.
+   * Returns rules `{ head, body, cmp, text, line, endLine }` (lines are 0-based) and
+   * `rules.incomplete`: trailing text that is not yet terminated by a dot.
+   */
+  function parseProgram(text) {
+    const clean = blankComments(text);
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) if (text[i] === "\n") starts.push(i + 1);
+
+    const rules = [];
+    rules.incomplete = "";
+    const re = /\.(?=\s|$)/g;
+    let from = 0, m;
+    const statements = [];
+    while ((m = re.exec(clean))) {
+      if (clean[m.index - 1] === ".") continue;                  // range operator 1..n
+      statements.push([from, m.index]);
+      from = m.index + 1;
+    }
+    rules.incomplete = clean.slice(from).trim();
+
+    for (const [a, b] of statements) {
+      const raw = clean.slice(a, b);
+      const st = raw.trim();
+      if (!st) continue;
+      const lead = raw.length - raw.trimStart().length;
+      const line = lineAt(starts, a + lead), endLine = lineAt(starts, b);
+      if (st.startsWith("#")) continue;                            // #show, #const, ... are ignored
+      if (/\bnot\b/.test(st)) throw new AspError("Only positive programs can be animated (no `not`):\n" + st + ".", line);
+      if (/[{}]|\.\./.test(st)) throw new AspError("Choice rules and ranges (1..n) are not supported:\n" + st + ".", line);
+      const idx = st.indexOf(":-");
+      const head = idx < 0 ? st : st.slice(0, idx);
+      const bodyText = idx < 0 ? "" : st.slice(idx + 2);
+      if (idx >= 0 && head.trim() === "") throw new AspError("Constraints are not supported: " + st + ".", line);
+      const rule = { head: parseAtom(head, line), body: [], cmp: [], text: st.replace(/\s+/g, " ") + ".", line, endLine };
+      splitTop(bodyText, ",").forEach(l => {
+        const c = l.match(/^(\S+)\s*(!=|<=|>=|<|>|=)\s*(\S+)$/);
+        if (c) rule.cmp.push({ l: parseTerm(c[1], line), op: c[2], r: parseTerm(c[3], line) });
+        else rule.body.push(parseAtom(l, line));
+      });
+      const bound = new Set();
+      rule.body.forEach(at => at.args.forEach(t => { if (isVar(t)) bound.add(t); }));
+      [...rule.head.args, ...rule.cmp.flatMap(c => [c.l, c.r])].forEach(t => {
+        if (isVar(t) && !bound.has(t)) throw new AspError("Unsafe variable " + t + " in rule: " + rule.text, line);
+      });
+      rules.push(rule);
+    }
+    return rules;
+  }
+
+  const key = a => a.pred + "(" + a.args.join(",") + ")";
+
+  function holds(op, l, r) {
+    const num = /^-?\d+$/.test(l) && /^-?\d+$/.test(r);
+    const a = num ? +l : l, b = num ? +r : r;
+    return op === "!=" ? a !== b : op === "=" ? a === b : op === "<" ? a < b :
+           op === ">" ? a > b : op === "<=" ? a <= b : a >= b;
+  }
+
+  /**
+   * Naive bottom-up evaluation. `rounds[0]` holds the facts; `rounds[k]` the atoms first derived in round k.
+   * Each entry is `{ atom, rule, subst }` where `rule` indexes into `rules`.
+   */
+  function evaluate(rules, maxAtoms = 3000) {
+    const have = new Set(), byPred = {};
+    const rounds = [[]];
+    const add = a => { have.add(key(a)); (byPred[a.pred] ||= []).push(a); };
+    rules.forEach((r, i) => {
+      if (r.body.length) return;
+      const a = { pred: r.head.pred, args: r.head.args };
+      if (!have.has(key(a))) { add(a); rounds[0].push({ atom: a, rule: i, subst: {} }); }
+    });
+    for (;;) {
+      const fresh = [], seen = new Set();
+      rules.forEach((r, i) => {
+        if (!r.body.length) return;
+        const walk = (k, sub) => {
+          if (k === r.body.length) {
+            const val = t => isVar(t) ? sub[t] : t;
+            if (!r.cmp.every(c => holds(c.op, val(c.l), val(c.r)))) return;
+            const atom = { pred: r.head.pred, args: r.head.args.map(val) };
+            const kk = key(atom);
+            if (!have.has(kk) && !seen.has(kk)) { seen.add(kk); fresh.push({ atom, rule: i, subst: { ...sub } }); }
+            return;
+          }
+          const lit = r.body[k];
+          for (const fact of byPred[lit.pred] || []) {
+            if (fact.args.length !== lit.args.length) continue;
+            const s2 = { ...sub }; let ok = true;
+            for (let j = 0; j < lit.args.length && ok; j++) {
+              const t = lit.args[j];
+              if (isVar(t)) { if (t === "_") continue; if (t in s2) ok = s2[t] === fact.args[j]; else s2[t] = fact.args[j]; }
+              else ok = t === fact.args[j];
+            }
+            if (ok) walk(k + 1, s2);
+          }
+        };
+        walk(0, {});
+      });
+      if (!fresh.length) break;
+      fresh.forEach(f => add(f.atom));
+      rounds.push(fresh);
+      if (have.size > maxAtoms) throw new AspError("Too many atoms (>" + maxAtoms + "), the program may be infinite.");
+    }
+    return rounds;
+  }
+
+  /** The animator view for one program text, as the visualizer expects it (also used by the notebook output). */
+  function animationFor(text, file) {
+    try {
+      const rules = parseProgram(text), rounds = evaluate(rules);
+      return {
+        rules: rules.map(r => ({ text: r.text, file, line: r.line + 1, fact: !r.body.length })),
+        rounds: rounds.map(rd => rd.map(f => ({ pred: f.atom.pred, args: f.atom.args, atom: key(f.atom), rule: f.rule, subst: f.subst }))),
+        incomplete: rules.incomplete || "",
+      };
+    } catch (e) {
+      return { error: String(e.message), file, line: e.line !== undefined ? e.line + 1 : null };
+    }
+  }
+
+  return { AspError, parseProgram, evaluate, key, splitTop, isVar, animationFor };
+});