asp-studio 0.1.0__tar.gz

asp_studio-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yakupbulbul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asp_studio-0.1.0/PKG-INFO

@@ -0,0 +1,110 @@
+Metadata-Version: 2.4
+Name: asp-studio
+Version: 0.1.0
+Summary: Answer sets, a graph and a step-by-step animator for Answer Set Programming, in Jupyter, VS Code notebooks and the command line.
+Author: yakupbulbul
+License: MIT
+Project-URL: Homepage, https://yakupbulbul.github.io/asp-vscode/
+Project-URL: Documentation, https://yakupbulbul.github.io/asp-vscode/docs.html
+Project-URL: Source, https://github.com/yakupbulbul/asp-vscode
+Project-URL: Issues, https://github.com/yakupbulbul/asp-vscode/issues
+Project-URL: Changelog, https://github.com/yakupbulbul/asp-vscode/blob/main/CHANGELOG.md
+Keywords: asp,answer set programming,clingo,jupyter,visualization,potassco
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Education
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clingo>=5.5
+Provides-Extra: notebook
+Requires-Dist: ipython; extra == "notebook"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: ipython; extra == "test"
+Dynamic: license-file
+
+# ASP Studio for Python
+
+ASP Studio shows the answer sets of an [Answer Set Programming](https://potassco.org/) program, draws them as a graph, and steps through how a recursive program reaches its result. It works in Jupyter, in VS Code notebooks and from the command line. It uses the clingo Python API and shares its visualizer with the [ASP Studio VS Code extension](https://github.com/yakupbulbul/asp-vscode).
+
+Website and live demo: <https://yakupbulbul.github.io/asp-vscode/>
+
+```bash
+pip install "asp-studio[notebook]"      # Python 3.9 or newer
+```
+
+The `notebook` extra adds IPython for the `%%asp` magic. Without it you still get `solve()` and the command line.
+
+## In a notebook
+
+```python
+%load_ext asp_studio
+```
+
+```text
+%%asp
+parent(anna,bob). parent(bob,carl). parent(carl,eve).
+ancestor(X,Y) :- parent(X,Y).
+ancestor(X,Z) :- parent(X,Y), ancestor(Y,Z).
+```
+
+The output has four tabs. Animator steps through the rounds and shows which rule fired with which variable bindings. Answer Sets lists every model. Graph draws the atoms. Console shows clingo's messages and the position of any error.
+
+Cell options:
+
+| Option | Meaning |
+|---|---|
+| `-n 5`, `--models 5` | At most 5 answer sets (0 means all). |
+| `-o "--opt-mode=optN -c n=6"` | Extra clingo options. |
+| `-t 20` | Timeout in seconds. The default is 10. |
+| `--tab answers` | First tab to show: `animator`, `answers`, `graph` or `console`. |
+| `--theme dark` | `auto` (default), `light` or `dark`. Inside VS Code the editor theme is used. |
+| `--height 500` | Starting height in pixels. The output grows with its content. |
+| `--out res` | Keep the result in a variable called `res`. |
+
+## From Python
+
+```python
+import asp_studio as asp
+
+res = asp.solve("a :- not b. b :- not a.", models=0, timeout=10)
+res.result          # 'SATISFIABLE'
+list(res)           # [['b'], ['a']]
+res.diagnostics     # positions of errors and warnings from clingo
+res                 # as the last line of a cell: shows the visualizer
+asp.show(res, tab="graph")
+```
+
+`solve` takes ASP text, a `pathlib.Path`, or a list of those, which are joined in order. A broken program does not raise: check `res.ok` and `res.error`. With `#minimize` or `#maximize` and a finished search, only the optimal models are kept, and their costs are in `res.costs`.
+
+## Command line
+
+```bash
+asp-studio program.lp --open                # writes program.html and opens it
+asp-studio instance.lp encoding.lp -n 3     # several files are joined in order
+python -m asp_studio program.lp             # the same, without the script on PATH
+```
+
+The exit code is 0 when the program ran, 1 when it has an error (positions print as `file:line:col`) and 2 for bad arguments or unreadable input.
+
+## Notes
+
+- The animator follows positive programs only: no `not`, choice rules, constraints or ranges. For other programs it names the unsupported line, and the other three tabs still work.
+- The visualizer runs in an isolated `<iframe>`. Jupyter shows such output only in trusted notebooks.
+- Outside notebooks and VS Code, the color theme follows the operating system.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+python sync_static.py     # copy ../media/{engine.js,webview.js,webview.css,themes.css} into the package
+```
+
+The visualizer files live in `../media` and are copied into `src/asp_studio/static`. A test fails when the copies drift apart.
+
+MIT license. Not affiliated with the Potassco team.

asp_studio-0.1.0/README.md

@@ -0,0 +1,81 @@
+# ASP Studio for Python
+
+ASP Studio shows the answer sets of an [Answer Set Programming](https://potassco.org/) program, draws them as a graph, and steps through how a recursive program reaches its result. It works in Jupyter, in VS Code notebooks and from the command line. It uses the clingo Python API and shares its visualizer with the [ASP Studio VS Code extension](https://github.com/yakupbulbul/asp-vscode).
+
+Website and live demo: <https://yakupbulbul.github.io/asp-vscode/>
+
+```bash
+pip install "asp-studio[notebook]"      # Python 3.9 or newer
+```
+
+The `notebook` extra adds IPython for the `%%asp` magic. Without it you still get `solve()` and the command line.
+
+## In a notebook
+
+```python
+%load_ext asp_studio
+```
+
+```text
+%%asp
+parent(anna,bob). parent(bob,carl). parent(carl,eve).
+ancestor(X,Y) :- parent(X,Y).
+ancestor(X,Z) :- parent(X,Y), ancestor(Y,Z).
+```
+
+The output has four tabs. Animator steps through the rounds and shows which rule fired with which variable bindings. Answer Sets lists every model. Graph draws the atoms. Console shows clingo's messages and the position of any error.
+
+Cell options:
+
+| Option | Meaning |
+|---|---|
+| `-n 5`, `--models 5` | At most 5 answer sets (0 means all). |
+| `-o "--opt-mode=optN -c n=6"` | Extra clingo options. |
+| `-t 20` | Timeout in seconds. The default is 10. |
+| `--tab answers` | First tab to show: `animator`, `answers`, `graph` or `console`. |
+| `--theme dark` | `auto` (default), `light` or `dark`. Inside VS Code the editor theme is used. |
+| `--height 500` | Starting height in pixels. The output grows with its content. |
+| `--out res` | Keep the result in a variable called `res`. |
+
+## From Python
+
+```python
+import asp_studio as asp
+
+res = asp.solve("a :- not b. b :- not a.", models=0, timeout=10)
+res.result          # 'SATISFIABLE'
+list(res)           # [['b'], ['a']]
+res.diagnostics     # positions of errors and warnings from clingo
+res                 # as the last line of a cell: shows the visualizer
+asp.show(res, tab="graph")
+```
+
+`solve` takes ASP text, a `pathlib.Path`, or a list of those, which are joined in order. A broken program does not raise: check `res.ok` and `res.error`. With `#minimize` or `#maximize` and a finished search, only the optimal models are kept, and their costs are in `res.costs`.
+
+## Command line
+
+```bash
+asp-studio program.lp --open                # writes program.html and opens it
+asp-studio instance.lp encoding.lp -n 3     # several files are joined in order
+python -m asp_studio program.lp             # the same, without the script on PATH
+```
+
+The exit code is 0 when the program ran, 1 when it has an error (positions print as `file:line:col`) and 2 for bad arguments or unreadable input.
+
+## Notes
+
+- The animator follows positive programs only: no `not`, choice rules, constraints or ranges. For other programs it names the unsupported line, and the other three tabs still work.
+- The visualizer runs in an isolated `<iframe>`. Jupyter shows such output only in trusted notebooks.
+- Outside notebooks and VS Code, the color theme follows the operating system.
+
+## Development
+
+```bash
+pip install -e ".[test]"
+pytest
+python sync_static.py     # copy ../media/{engine.js,webview.js,webview.css,themes.css} into the package
+```
+
+The visualizer files live in `../media` and are copied into `src/asp_studio/static`. A test fails when the copies drift apart.
+
+MIT license. Not affiliated with the Potassco team.

asp_studio-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "asp-studio"
+version = "0.1.0"
+description = "Answer sets, a graph and a step-by-step animator for Answer Set Programming, in Jupyter, VS Code notebooks and the command line."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+authors = [{ name = "yakupbulbul" }]
+keywords = ["asp", "answer set programming", "clingo", "jupyter", "visualization", "potassco"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Framework :: Jupyter",
+  "Intended Audience :: Education",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Visualization",
+]
+dependencies = ["clingo>=5.5"]
+
+[project.optional-dependencies]
+notebook = ["ipython"]
+test = ["pytest", "ipython"]
+
+[project.scripts]
+asp-studio = "asp_studio.__main__:main"
+
+[project.urls]
+Homepage = "https://yakupbulbul.github.io/asp-vscode/"
+Documentation = "https://yakupbulbul.github.io/asp-vscode/docs.html"
+Source = "https://github.com/yakupbulbul/asp-vscode"
+Issues = "https://github.com/yakupbulbul/asp-vscode/issues"
+Changelog = "https://github.com/yakupbulbul/asp-vscode/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+asp_studio = ["static/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

asp_studio-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

asp_studio-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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