solver-support 0.1.1__tar.gz

solver_support-0.1.1/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, András Salamon
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

solver_support-0.1.1/MANIFEST.in

@@ -0,0 +1,18 @@
+# What lands in the SOURCE distribution (`python -m build --sdist`).
+#
+# This does not affect the wheel -- the artefact `pip install solver-support`
+# actually fetches -- which carries only the solver_support package and its
+# metadata, and is already minimal. It governs the source release, which should
+# be self-contained: buildable, and testable by anyone repackaging it (a distro
+# or conda-forge recipe typically runs the suite at build time).
+#
+# setuptools' defaults already pick up README.md, LICENSE, pyproject.toml and
+# tests/test_*.py -- but NOT tests/conftest.py, whose name does not match
+# `test*`, nor the YAML fixture the registry tests load. The sdist therefore
+# shipped a test suite that could not run at all: every test needing a fixture
+# errored on a missing one. These two lines are what make it coherent.
+recursive-include tests *.py *.yaml
+
+# The docs the README points at, so the source release does not dangle links to
+# files it does not carry.
+recursive-include docs *.md

solver_support-0.1.1/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: solver-support
+Version: 0.1.1
+Summary: Generic Conjure / Savile Row / Fast Downward / SymK / ENHSP / UPF solver pipeline
+Author: András Salamon
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ott2/solver-support
+Project-URL: Repository, https://github.com/ott2/solver-support
+Project-URL: Issues, https://github.com/ott2/solver-support/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil>=5.8.0
+Requires-Dist: PyYAML>=5.4
+Dynamic: license-file
+
+# solver-support
+
+A generic, domain-agnostic pipeline for running constraint-modelling and
+planning solvers: **Conjure** / **Savile Row** (+ SAT/CP backends), **Fast
+Downward**, **SymK**, **ENHSP**, and **UPF**-constructed models. It handles the
+mechanics that every such run needs — building solver command lines from a model
+registry, spawning subprocesses with timeouts and clean teardown, naming the
+per-run files, parsing solver output into a uniform timing / cost-layer model,
+and driving the horizon (increasing-difficulty) loop.
+
+It carries **no** notion of any particular problem domain or objective. A
+consumer supplies:
+
+- its own **model registry** (a `models.yaml`) via a config path — the loader is
+  generic, the model content is the consumer's;
+- its **scoring / objective strategy** via injection — the core reports the raw
+  objective a solver emits and lets the consumer interpret it (is-this-an-
+  optimisation-model, how to read the objective, any reporting multiplier).
+
+## Status
+
+**Alpha.** The pipeline is in day-to-day use by two consumers and is covered by
+its own test suite, but this is the first public release and the API may still
+shift between 0.x versions.
+
+The package ships **unwired**: a bare `import solver_support` gives a pipeline
+that resolves no model registry and interprets no objective, because it has no
+way to guess either. A consumer registers its scoring, registry paths, warning
+logger and UPF CLI once, before first use.
+
+## Installation
+
+```bash
+pip install solver-support
+```
+
+Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
+supported deliberately). The only runtime dependencies are `psutil` and `PyYAML`.
+
+## Usage
+
+See [`docs/injection-api.md`](https://github.com/ott2/solver-support/blob/main/docs/injection-api.md)
+for the four injection points a consumer wires — model-registry paths, objective
+extraction, warning logger, UPF CLI — with a worked example.
+
+## Docs
+
+- [`injection-api.md`](https://github.com/ott2/solver-support/blob/main/docs/injection-api.md)
+  — the four seams a consumer wires.
+- [`solver-runner.md`](https://github.com/ott2/solver-support/blob/main/docs/solver-runner.md)
+  — running a solver as a subprocess: `SolverResult`, timeout vs duration, phases.
+- [`timing-model.md`](https://github.com/ott2/solver-support/blob/main/docs/timing-model.md)
+  — how solver timing is recorded, how the backends map onto one shape, and the
+  invariants parsers rely on.
+
+## Development
+
+Clone and install editable. A consumer under development alongside it is
+normally installed into the same virtualenv, so both are importable and edits to
+either take effect immediately:
+
+```bash
+git clone https://github.com/ott2/solver-support
+pip install -e solver-support
+```
+
+## Tests
+
+`pytest tests/` — the core's own suite, and the home for solver-level
+development. It runs against `solver_support` alone: no consumer need be
+installed, and none is imported.
+
+Since the core ships unwired, a test that needs a seam wired wires a stand-in
+(`tests/conftest.py`):
+
+| fixture | supplies |
+|---------|----------|
+| `fixture_registry` | a `ModelRegistry` over `tests/fixtures/models.yaml`, this suite's own synthetic config — never a consumer's |
+| `wired_stdout_score` | a consumer-style `Score: N` extractor, so a score reaches `solver_stats` |
+| `wired_timeout_score` | a consumer-style extractor for a salvaged timeout solution |
+
+Wiring a fixture config rather than mocking the registry keeps the real loader
+and accessors in the path. Anything a test needs from the registry goes in
+`tests/fixtures/models.yaml`, keeping its shape faithful to a real consumer
+config — that shape is the contract the loader implements.
+
+## Licence
+
+BSD-3-Clause — see
+[`LICENSE`](https://github.com/ott2/solver-support/blob/main/LICENSE).
+
+By András Salamon, with Claude Opus 4.8 and 5.

solver_support-0.1.1/README.md

@@ -0,0 +1,92 @@
+# solver-support
+
+A generic, domain-agnostic pipeline for running constraint-modelling and
+planning solvers: **Conjure** / **Savile Row** (+ SAT/CP backends), **Fast
+Downward**, **SymK**, **ENHSP**, and **UPF**-constructed models. It handles the
+mechanics that every such run needs — building solver command lines from a model
+registry, spawning subprocesses with timeouts and clean teardown, naming the
+per-run files, parsing solver output into a uniform timing / cost-layer model,
+and driving the horizon (increasing-difficulty) loop.
+
+It carries **no** notion of any particular problem domain or objective. A
+consumer supplies:
+
+- its own **model registry** (a `models.yaml`) via a config path — the loader is
+  generic, the model content is the consumer's;
+- its **scoring / objective strategy** via injection — the core reports the raw
+  objective a solver emits and lets the consumer interpret it (is-this-an-
+  optimisation-model, how to read the objective, any reporting multiplier).
+
+## Status
+
+**Alpha.** The pipeline is in day-to-day use by two consumers and is covered by
+its own test suite, but this is the first public release and the API may still
+shift between 0.x versions.
+
+The package ships **unwired**: a bare `import solver_support` gives a pipeline
+that resolves no model registry and interprets no objective, because it has no
+way to guess either. A consumer registers its scoring, registry paths, warning
+logger and UPF CLI once, before first use.
+
+## Installation
+
+```bash
+pip install solver-support
+```
+
+Requires Python 3.9 or newer (3.9.6 is the system Python on macOS, and is
+supported deliberately). The only runtime dependencies are `psutil` and `PyYAML`.
+
+## Usage
+
+See [`docs/injection-api.md`](https://github.com/ott2/solver-support/blob/main/docs/injection-api.md)
+for the four injection points a consumer wires — model-registry paths, objective
+extraction, warning logger, UPF CLI — with a worked example.
+
+## Docs
+
+- [`injection-api.md`](https://github.com/ott2/solver-support/blob/main/docs/injection-api.md)
+  — the four seams a consumer wires.
+- [`solver-runner.md`](https://github.com/ott2/solver-support/blob/main/docs/solver-runner.md)
+  — running a solver as a subprocess: `SolverResult`, timeout vs duration, phases.
+- [`timing-model.md`](https://github.com/ott2/solver-support/blob/main/docs/timing-model.md)
+  — how solver timing is recorded, how the backends map onto one shape, and the
+  invariants parsers rely on.
+
+## Development
+
+Clone and install editable. A consumer under development alongside it is
+normally installed into the same virtualenv, so both are importable and edits to
+either take effect immediately:
+
+```bash
+git clone https://github.com/ott2/solver-support
+pip install -e solver-support
+```
+
+## Tests
+
+`pytest tests/` — the core's own suite, and the home for solver-level
+development. It runs against `solver_support` alone: no consumer need be
+installed, and none is imported.
+
+Since the core ships unwired, a test that needs a seam wired wires a stand-in
+(`tests/conftest.py`):
+
+| fixture | supplies |
+|---------|----------|
+| `fixture_registry` | a `ModelRegistry` over `tests/fixtures/models.yaml`, this suite's own synthetic config — never a consumer's |
+| `wired_stdout_score` | a consumer-style `Score: N` extractor, so a score reaches `solver_stats` |
+| `wired_timeout_score` | a consumer-style extractor for a salvaged timeout solution |
+
+Wiring a fixture config rather than mocking the registry keeps the real loader
+and accessors in the path. Anything a test needs from the registry goes in
+`tests/fixtures/models.yaml`, keeping its shape faithful to a real consumer
+config — that shape is the contract the loader implements.
+
+## Licence
+
+BSD-3-Clause — see
+[`LICENSE`](https://github.com/ott2/solver-support/blob/main/LICENSE).
+
+By András Salamon, with Claude Opus 4.8 and 5.

solver_support-0.1.1/docs/injection-api.md

@@ -0,0 +1,137 @@
+# injection API
+
+`solver_support` ships **unwired**: a bare `import solver_support` gives a working
+pipeline that knows nothing about any problem domain. It records whatever
+objective a solver emits but cannot interpret it, resolves no model registry, and
+routes warnings to its own package logger. A **consumer** supplies the missing
+domain policy once, at its own import time, through the injection points below.
+
+Every seam follows the same shape: a module-level default, a `set_*` setter, and
+a stable wrapper (or constructor argument) that reads the current value **at call
+time**. So wiring may happen any time before first use, and the core never imports
+the consumer — the dependency arrow points one way, consumer → core.
+
+## the four seams
+
+### 1. model registry paths (`solver_support.model_registry`)
+
+The loader is generic; the model content and its packaging are the consumer's.
+
+| setter | supplies |
+|--------|----------|
+| `set_default_config_path(path)` | the consumer's `models.yaml` (a `Path` / str) |
+| `set_resource_root(root)` | root that model-file paths in the config resolve against |
+| `set_user_config_finder(finder)` | a **callable** returning an optional per-invocation user-config `Path` |
+
+`set_user_config_finder` takes a *finder*, not a fixed path, so cwd-relative
+candidates bind when the registry is constructed rather than at import. Until a
+default config path is registered, constructing `ModelRegistry()` raises
+`ModelRegistryError` rather than guessing a consumer's config.
+
+### 2. objective extraction (`solver_support.objective`)
+
+The core asks for a solution's objective at a few points but does not know how a
+domain encodes it. Register an extractor for each route the consumer uses; an
+unregistered route yields `None` (the standalone core simply records no score).
+
+| setter | extractor signature | used for |
+|--------|--------------------|----------|
+| `set_reported_score_from_solution(fn)` | `fn(solution_file) -> int \| None` | reported score read from a solution file |
+| `set_reported_score_from_stdout(fn)` | `fn(stdout) -> int \| None` | reported score printed on solver stdout |
+| `set_reported_score_from_timeout_solution(fn)` | `fn(solution_file) -> int \| None` | a salvaged, possibly-truncated timeout solution |
+| `set_raw_objective_from_solution(fn)` | `fn(solution_file) -> int \| None` | the **raw** (unscaled) objective the horizon scan compares between horizons |
+
+Keep the raw objective in model units — it drives horizon comparison — while the
+reported extractors may apply any display scaling the consumer wants.
+
+### 3. warning logger name (`solver_support.utilities`)
+
+`warn()` routes through a logger named `_warn_logger_name` (default
+`'solver_support'`). A consumer that configures its own named logger (with file /
+console handlers) points `warn()` at it so these warnings share those handlers:
+
+```python
+from solver_support import set_warn_logger_name
+set_warn_logger_name('my_runner')   # matches setup_logger('my_runner', ...)
+```
+
+### 4. UPF planner CLI (`solver_support.solver_upfplan.UpfPlanSolver`)
+
+The generic UPF driver shells out to a CLI that performs the UPF
+PDDLReader/construction and solve. There is **no** built-in default (the CLI is
+consumer-provided). Inject it per instance, or override the class attribute:
+
+```python
+UpfPlanSolver(runner, solver_name='upffd', build_mode='upf',
+              upfplan_command='my-upfplan')      # per instance (preferred)
+# or, once:
+UpfPlanSolver.UPFPLAN_COMMAND = 'my-upfplan'     # class-attribute override
+```
+
+`solve()` refuses with a clear `ValueError` if no command is configured, rather
+than shelling out to a `None`-prefixed argv.
+
+## worked example
+
+Wire everything once, at the consumer's own import time — in its
+`__init__.py`, so that every entry point and every test that imports the package
+gets an identically configured core, and nothing has to remember to wire it:
+
+```python
+# in mypuzzle_support/__init__.py
+
+# 1. scoring: register the objective extractors this domain uses. Grouping them
+#    behind one wire_into_core() keeps the registration next to the parsing.
+from . import mypuzzle_scoring
+mypuzzle_scoring.wire_into_core()
+```
+
+```python
+# in mypuzzle_support/mypuzzle_scoring.py
+import re
+from solver_support import (
+    set_reported_score_from_stdout, set_raw_objective_from_solution,
+)
+
+def _score_from_stdout(stdout):
+    m = re.search(r'^Score:\s*(-?\d+)', stdout, re.MULTILINE)
+    return int(m.group(1)) if m else None
+
+def wire_into_core():
+    set_reported_score_from_stdout(_score_from_stdout)
+    set_raw_objective_from_solution(_objective_from_solution)   # model units
+```
+
+```python
+# back in __init__.py
+
+# 2. registry packaging: where this consumer's models.yaml and model files live.
+#    A finder (not a fixed path) for the user override, so cwd-relative
+#    candidates bind when the registry is built rather than at import.
+from pathlib import Path
+from solver_support import (
+    set_default_config_path, set_resource_root, set_user_config_finder,
+)
+
+_here = Path(__file__).parent
+set_default_config_path(_here / 'config' / 'models.yaml')
+set_resource_root(_here)
+set_user_config_finder(lambda: next(
+    (p for p in (Path.cwd() / 'models.yaml',) if p.is_file()), None))
+
+# 3. warnings: funnel the core's warn() into this consumer's configured logger,
+#    so they reach the same file and console handlers as its own messages.
+from solver_support import set_warn_logger_name
+set_warn_logger_name('mypuzzle_runner')
+```
+
+and inject the UPF CLI where the solver is constructed:
+
+```python
+UpfPlanSolver(runner, solver_name=solver, build_mode=build_mode,
+              upfplan_command='mypuzzle-upfplan')
+```
+
+Each consumer registers its own scoring, its own `models.yaml`, its own logger
+name and its own UPF CLI. Nothing above is built into the core, and the core
+never imports the consumer.

solver_support-0.1.1/docs/solver-runner.md

@@ -0,0 +1,134 @@
+# solver runner
+
+`solver_runner.py` runs a solver as a subprocess and reports what happened. It
+exists because a bare `subprocess.run` cannot answer the question the pipeline
+actually asks — *did this solver fail, or did it run out of time, or did the user
+stop it?* — and because a solver that is killed must not leave a process tree
+behind. It handles:
+
+- timeouts, with the whole process tree torn down (via `psutil`);
+- signal handling, so an interrupted run shuts down cleanly rather than orphaning
+  a solver;
+- separate stdout/stderr capture (the plan stays clean on stdout while an engine
+  logs its search to stderr);
+- structured logging to console and file;
+- phase tracking, feeding the `RunSummary` (see [`timing-model.md`](timing-model.md)).
+
+## SolverResult
+
+The complete result of one execution — the raw data plus the status properties
+the pipeline branches on.
+
+```python
+SolverResult(command, returncode, stdout, stderr, duration,
+             timed_out=False, interrupted=False)
+```
+
+| field | meaning |
+|-------|---------|
+| `command: List[str]` | the command and arguments that ran |
+| `returncode: int` | process return code (0 for success) |
+| `stdout: str` / `stderr: str` | captured output, kept separate |
+| `duration: float` | **actual** seconds the command ran |
+| `timed_out: bool` | it was killed for exceeding the timeout |
+| `interrupted: bool` | it was stopped by a signal |
+
+### timeout vs duration
+
+Three easily-confused numbers:
+
+- `default_timeout` (a `SolverRunner` parameter) — the *limit*;
+- `duration` (a `SolverResult` field) — the *actual* time it ran, whether it
+  finished or was killed;
+- `timed_out` (a `SolverResult` field) — whether that limit was hit.
+
+```python
+runner = SolverRunner(default_timeout=10.0)
+
+runner.run(['sleep', '3'])    # duration ~3.0,  timed_out False, returncode 0
+runner.run(['sleep', '15'])   # duration ~10.0, timed_out True,  returncode -1
+```
+
+`duration` is ground truth for the phase, and every finer-grained solver time is
+a component of it — see the invariants in [`timing-model.md`](timing-model.md).
+
+### properties
+
+- `success: bool` — completed with return code 0, no timeout, no interruption.
+- `failed: bool` — the inverse; useful as a direct `if` on a run.
+
+Note that `failed` covers three *different* outcomes, and the pipeline usually
+cares which: check `timed_out` and `interrupted` before treating a run as a
+genuine solver failure. A timed-out anytime solver may still have banked a
+solution worth keeping.
+
+The runner applies that rule to its own logging: a timeout or an interrupt is
+recorded at INFO (`Command did not complete`), and only a solver that ran and
+exited non-zero is logged as `Command failed` at ERROR. A launch failure logs its
+own error before returning. So a consumer whose timed-out run *is* the result -
+a benchmark baseline, say - gets no spurious error rows.
+
+`run_phase` carries the same distinction into the persisted summary: the phase
+records `returncode`, `timed_out` and `launch_failed` alongside `success`, so the
+outcome can be reconstructed from a saved run without re-reading the log.
+
+- `__str__()` renders `SolverResult({command}) -> {STATUS} (rc={returncode},
+  t={duration}s)` with `STATUS` one of `SUCCESS` / `FAILED` / `TIMEOUT` /
+  `INTERRUPTED`:
+
+```
+SolverResult(echo hello) -> SUCCESS (rc=0, t=0.01s)
+SolverResult(sleep 10) -> TIMEOUT (rc=-1, t=5.00s)
+SolverResult(ls /nonexistent) -> FAILED (rc=1, t=0.01s)
+```
+
+## usage
+
+```python
+from solver_support import SolverRunner
+
+runner = SolverRunner(default_timeout=30.0)
+result = runner.run(['savilerow', 'model.eprime', 'problem.param'])
+
+if result.timed_out:
+    print(f"solver timed out after {result.duration:.1f}s")
+elif result.interrupted:
+    print("solver was interrupted")
+elif result.failed:
+    print(f"solver failed with return code {result.returncode}: {result.stderr}")
+else:
+    print(f"solved in {result.duration:.2f}s")
+```
+
+Two variants of the same call:
+
+- `run_phase(phase_name, command, expected_outputs=..., horizon_number=...)` —
+  what the pipeline uses. It runs the command *and* records a `PhaseResult` on
+  the `RunSummary`, with the parsed solver stats attached; use it for anything
+  whose timing should appear in the summary.
+- `run_simple(*command_parts)` — the terse variant, returning `result.failed`
+  (truthy on failure) for call sites that only branch on success and want no
+  phase recorded.
+
+Two optional controls, both defaulting to the historical behaviour:
+
+- `cwd=` on `run` / `run_phase` — the subprocess's working directory. Omitted, it
+  inherits the caller's, which is what the `Solver` classes rely on (they are
+  documented to run after a chdir, with paths relative to it). A consumer that
+  would rather not chdir a whole process can place each subprocess instead.
+- `log_level=` on the `SolverRunner` constructor — console verbosity for this
+  runner. `global_state.log_level()` can only ever *raise* verbosity (it floors
+  at WARNING), so this is the way to make a runner quieter. The file handler
+  captures everything regardless.
+
+## tests
+
+`tests/test_solver_runner.py` — execution outcomes (success / failure / timeout /
+interruption), process-tree and child-process cleanup, signal handling, logging
+setup, environment and working-directory handling, output edge cases (long
+output, special characters, empty commands), and integration tests that run real
+system commands.
+
+Signals are *not* handled here: `SolverRunner` runs a command and reports, while
+installing the handler and deciding what an interrupt means for the run as a
+whole belongs to the consumer's top-level runner.