solver-support 0.1.1__py3-none-any.whl

solver_support/solver_upfplan.py

@@ -0,0 +1,168 @@
+"""
+UPF solver implementation - the single class behind every UPF-routed model.
+
+UpfPlanSolver drives the consumer's UPF planner CLI through run_phase, so it
+inherits the timeout/signal handling and SIGTERM summary generation every solver
+gets. The CLI name is not baked in: the consumer supplies it (``upfplan_command=``
+or by overriding the ``UPFPLAN_COMMAND`` class attribute). It reaches a UPF engine
+by the two routes that CLI supports, selected here by ``build_mode``:
+
+  - build_mode is None (PDDL models, e.g. pddlnoaxiom): pass ``--domain`` so the
+    CLI reads the PDDL through unified_planning's PDDLReader and solves with the
+    engine chosen by the effective ``--tune`` (enhsp-opt / fast-downward / symk;
+    see ModelRegistry.get_upf_engine). The same class therefore backs the upfenhsp,
+    upffd and upfsymk solvers. The CLI streams that engine's progress live,
+    so run_phase tees it to the terminal the way fd/symk do.
+
+  - build_mode is 'upf'/'upflocal' (constructed models): pass ``--build`` so the
+    CLI builds the Problem in Python and solves it with the tune's engine (Fast
+    Downward blind by default; upfenhsp defaults to the metric-optimal enhsp-opt).
+    This replaces the former UPFSolver/UPFLocalSolver classes; that path buffers the
+    engine output (it surfaces only once solving finishes) and emits a scored plan.
+
+Optimality is a ``--tune`` dial, not a solver name: every upf* solver optimises the
+score by default (upffd/upfsymk are cost-optimal by construction, upfenhsp defaults
+to enhsp-opt), and satisficing ENHSP is opt-in via ``--tune satisficing``.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from .solver_base import Solver
+from .global_state import global_state
+
+
+class UpfPlanSolver(Solver):
+    """Solver that runs a model through a UPF engine (PDDL or constructed)."""
+
+    # CLI entry point that does the UPF PDDLReader/construction + OneshotPlanner
+    # solve. No generic default (the CLI is consumer-provided); a consumer sets it
+    # per instance via ``upfplan_command=`` or by overriding this class attribute.
+    UPFPLAN_COMMAND: Optional[str] = None
+
+    def __init__(self, solver_runner, solver_name: str = "upfenhsp",
+                 build_mode: Optional[str] = None,
+                 upfplan_command: Optional[str] = None):
+        super().__init__(solver_runner)
+        self.solver_name = solver_name
+        # None -> read PDDL via --domain; 'upf'/'upflocal' -> construct via --build.
+        self.build_mode = build_mode
+        # The consumer's UPF planner CLI; an explicit argument wins, else the
+        # class-attribute override, else unset.
+        self.upfplan_command = upfplan_command or self.UPFPLAN_COMMAND
+
+    def _tune_fd_search(self, registry, tune, engine_name) -> Optional[str]:
+        """FD search config for the active tune - only for fast-downward engines
+        (enhsp/symk ignore it, and get_upf_fd_search returns None for them anyway)."""
+        if not (engine_name and engine_name.startswith('fast-downward')):
+            return None
+        try:
+            return registry.get_upf_fd_search(self.solver_name, tune)
+        except Exception:
+            return None
+
+    def solve(self, param_file: Path, **kwargs) -> Optional[Path]:
+        """
+        Solve the problem in ``param_file`` through a UPF engine.
+
+        Args:
+            param_file: generated PDDL problem (PDDL models) or .upf instance
+                (constructed upf/upflocal models)
+            **kwargs: model_path (PDDL domain) - required unless build_mode is set
+
+        Returns:
+            Path to the solution file if a plan was found, else None.
+        """
+        # Effective --tune: an explicit --tune wins, else the model's pinned default.
+        # It selects the UPF engine (the optimality mode) the way it selects
+        # savilerow's sat_args or the direct enhsp -planner (see get_upf_engine).
+        # upfenhsp defaults to the metric-optimal engine so a plain run maximises the
+        # score, matching the cost-optimal upffd/upfsymk; --tune satisficing opts out.
+        if not self.upfplan_command:
+            raise ValueError(
+                "no UPF planner command configured; pass upfplan_command= to "
+                "UpfPlanSolver or set its UPFPLAN_COMMAND to the consumer's UPF CLI")
+
+        registry = global_state.model_registry
+        tune = self._effective_tune()
+
+        if self.build_mode:
+            # Constructed models build the Problem in Python (no PDDL domain). The
+            # engine comes from the effective tune, so the axiom-free builds
+            # (upflocalnoaxiom) can be solved by an axiom-rejecting engine like ENHSP,
+            # not just Fast Downward.
+            try:
+                engine_name = registry.get_upf_engine(self.solver_name, tune)
+            except Exception:
+                engine_name = None
+            engine_name = engine_name or 'fast-downward'
+            cmd = [self.upfplan_command, "--build", self.build_mode,
+                   "-s", engine_name, str(param_file)]
+            # For the fast-downward engine the tune also picks the FD search config
+            # (upffd: optimal blind vs satisficing greedy); forward it so --build
+            # honours --tune instead of the search compile_and_solve would pin.
+            fd_search = self._tune_fd_search(registry, tune, engine_name)
+            if fd_search:
+                cmd += ["--fd-search", fd_search]
+            self.logger.info(f"Building UPF model '{self.build_mode}' (engine: {engine_name})")
+        else:
+            model_path = kwargs.get('model_path')
+            if not model_path:
+                raise ValueError(
+                    "model_path (PDDL domain) is required for the upfplan solver")
+
+            # UPF engine name comes from the effective tune (upfenhsp: optimal ->
+            # enhsp-opt by default, satisficing -> enhsp, anytime -> enhsp-any),
+            # defaulting to the bare 'enhsp' engine if the solver defines none.
+            try:
+                engine_name = registry.get_upf_engine(self.solver_name, tune)
+            except Exception:
+                engine_name = None
+            engine_name = engine_name or 'enhsp'
+
+            cmd = [
+                self.upfplan_command,
+                "--domain", str(model_path),
+                "--engine", engine_name,
+            ]
+            # Optional fast-downward search config from the active tune (upffd: optimal
+            # blind vs satisficing greedy), so the upffd config both measures pure UPF
+            # overhead against the direct fd path (blind) and exposes the search dial.
+            fd_search = self._tune_fd_search(registry, tune, engine_name)
+            if fd_search:
+                cmd += ["--fd-search", fd_search]
+            cmd.append(str(param_file))
+
+            self.logger.info(f"Running UPF engine '{engine_name}'")
+
+        # Forward debug so the upfplan subprocess's diagnostics (the compilation
+        # trace, the dumped compiled problem) print on its stderr under the
+        # consumer's debug flag (its `-d` / `--debug`) - where run_phase
+        # captures/tees them, and clear of the plan-only stdout the .solution is
+        # built from.
+        if global_state.debug:
+            cmd.append("--debug")
+
+        result = self.runner.run_phase("solving", cmd, expected_outputs=[])
+
+        if result.interrupted:
+            self.logger.warning("upfplan solver was interrupted")
+            return None
+
+        # Timeout with no plan is a timeout (mirrors UPF/pddl handling).
+        self._handle_timeout_result(result, "upfplan solver")
+
+        if result.success and result.stdout and result.stdout.strip():
+            solution_file = self._generate_solution_file_path()
+            solution_file.write_text(result.stdout)
+            if self.runner.summary.phases:
+                self.runner.summary.phases[-1].output_files = [str(solution_file)]
+            self.logger.info(f"upfplan solution written to {solution_file}")
+            return solution_file
+
+        if result.success:
+            self.logger.warning("upfplan solver produced no plan")
+            return None
+
+        self.logger.warning(f"upfplan solver failed: {result.stderr}")
+        return None

solver_support/utilities.py

@@ -0,0 +1,146 @@
+'''
+utility functions
+'''
+
+import sys
+import logging
+from datetime import datetime
+from typing import Optional
+from pathlib import Path
+
+# Logger name that warn() routes through. Defaults to the package logger so the
+# core is usable standalone; a consumer that configures its own named logger (with
+# file/console handlers) can point warn() at it via set_warn_logger_name() so these
+# warnings share the consumer's handlers. Read at call time, so wiring may happen
+# any time before the first warn().
+_warn_logger_name = 'solver_support'
+
+
+def set_warn_logger_name(name: str) -> None:
+    """Route warn() through the logger called ``name``.
+
+    Consumers call this once (e.g. at import) to funnel core warnings into their
+    own configured logger, preserving pre-extraction behaviour where warnings
+    reached the runner's log file/console handlers.
+    """
+    global _warn_logger_name
+    _warn_logger_name = name
+
+
+def warn(s, verbose_only: bool = False):
+    """
+    Print a warning message to stderr.
+
+    Args:
+        s: Warning message
+        verbose_only: If True, only print when verbose mode is enabled (but still logged to file)
+    """
+    # Get the logger for proper structured logging (name is consumer-configurable)
+    logger = logging.getLogger(_warn_logger_name)
+
+    if verbose_only:
+        # Log at INFO level: will appear in log file but not console in non-verbose mode
+        # (console handler is set to WARNING level in non-verbose mode)
+        logger.info(s)
+    else:
+        # Regular warning: always print to stderr
+        logger.warning(s)
+        print('Warning: %s, continuing' % s, file=sys.stderr)
+
+def arrayify(d):
+    '''
+    Make an array from a dict with contiguous string-numeric keys.
+    '''
+    return [ d[i] for i in sorted(d.keys(), key=int) ]
+
+def indices(d):
+    '''
+    Return properly ordered array indices for pseudo-array dict.
+    '''
+    return [ i for i in sorted(d.keys(), key=int) ]
+
+def format_timestamp() -> str:
+    '''
+    Generate timestamp format YYYYMMDDHHMMSS for use in filenames.
+    '''
+    return datetime.now().strftime("%Y%m%d%H%M%S")
+
+
+class BrokenPipeHandler(logging.StreamHandler):
+    """
+    Custom logging handler that gracefully handles broken pipe errors.
+    
+    This is needed when piping output to commands like 'head' that may
+    close the pipe early, causing BrokenPipeError exceptions.
+    """
+    def emit(self, record):
+        try:
+            super().emit(record)
+        except BrokenPipeError:
+            # Ignore broken pipe errors (e.g., when piping to head)
+            pass
+        except Exception:
+            # Silently ignore other exceptions to prevent recursion
+            pass
+
+
+def setup_logger(name: str, log_file: Optional[Path] = None, log_level: int = logging.INFO) -> logging.Logger:
+    """
+    Set up a logger with consistent formatting and broken pipe handling.
+    
+    Args:
+        name: Logger name
+        log_file: Optional file path for logging (if None, only console logging)
+        log_level: Console logging level (file always captures everything)
+        
+    Returns:
+        Configured logger instance
+    """
+    logger = logging.getLogger(name)
+    logger.setLevel(logging.DEBUG)  # Logger itself should allow all levels
+    
+    # Clear any existing handlers
+    logger.handlers.clear()
+    
+    # Shared formatter for both console and file output
+    log_format = logging.Formatter('%(asctime)s [%(levelname)s] %(message)s', datefmt='%Y%m%d %H:%M:%S')
+    
+    # Console handler with broken pipe handling - respects user verbosity
+    console_handler = BrokenPipeHandler(sys.stdout)
+    console_handler.setLevel(log_level)  # Console respects user's verbosity setting
+    console_handler.setFormatter(log_format)
+    logger.addHandler(console_handler)
+    
+    # File handler if log file specified
+    if log_file:
+        file_handler = logging.FileHandler(log_file, mode='a')
+        file_handler.setLevel(logging.DEBUG)  # File should capture everything
+        file_handler.setFormatter(log_format)
+        logger.addHandler(file_handler)
+    
+    return logger
+
+def relativize_path(path: str, output_dir: Path) -> str:
+    """
+    Convert absolute paths to relative paths based on output directory.
+    
+    Args:
+        path: File path (absolute or relative)
+        output_dir: Output directory for relativization
+        
+    Returns:
+        Path relative to output directory, or original path if conversion fails
+    """
+    try:
+        path_obj = Path(path)
+        if path_obj.is_absolute():
+            # Convert to relative path from output directory
+            relative_path = path_obj.relative_to(output_dir)
+            return str(relative_path)
+        else:
+            # Already relative, return as-is
+            return path
+    except (ValueError, OSError):
+        # If relative_to fails (path not under output_dir), return original
+        return path
+

solver_support-0.1.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,21 @@
+solver_support/__init__.py,sha256=b227_QtUysX4TjTJ3479hJ7TxtPb0XOJJ3MFAawHgh8,3824
+solver_support/command_builders.py,sha256=i9inzQg8O_bQdg67Phx3fSX6mPIDZG8stH6nzqoRLBI,15920
+solver_support/file_management.py,sha256=3rMyl7kSVFDTSbbz3plx_ZLJHxAtt3nDYcJMK8GwF_c,8756
+solver_support/global_state.py,sha256=yf2v6SeXKlSXp6Sr3cTY2SQILJaBH9wiMOTOZbnOQNI,2132
+solver_support/horizon_utils.py,sha256=FvdLQmUmfWOcy07KRgkmdmSusjtEmLcCkMyikKBk2JM,16070
+solver_support/model_registry.py,sha256=DeHofjm5YgLHaNrE_98kx4uj3e0Jw4KUIXjZ81x6ms4,31382
+solver_support/objective.py,sha256=BciFu6AJNhMakXesQ4DXE7k2w1O6xB6ISHGogM5GCVk,4161
+solver_support/run_summary.py,sha256=IV_tY8j49gEsJsTQ8e-S5gaLIRJ5ssUQ0Tk-wYY6pW0,16566
+solver_support/solver_base.py,sha256=-9agNTxOYzSuhedodmZ7-A6j1SibahCFLbGrGsfKam8,4878
+solver_support/solver_enhsp.py,sha256=3EyU0xtkyqpSDdEyNDeqpJMomfBds9QceiR1FLyKEZI,4289
+solver_support/solver_fd.py,sha256=8I0cmCB-p0q63yokX01D527lLIBtVi-_Fo-E2PxXCpk,12325
+solver_support/solver_horizon.py,sha256=-ob2Q6ifhN3aknZWm-SqgquivIa_ZYkK7aPoMEeFCAw,30538
+solver_support/solver_runner.py,sha256=yFw35qZGyvjfBlC6og2Wno7eN8zRkVKv1stSoiCVPeg,30363
+solver_support/solver_stats.py,sha256=kIOeebbicXcVQooJgjMMS0PHtB1LTFTUbJqSn0lDpkU,34910
+solver_support/solver_upfplan.py,sha256=F4y1urb1KHAjNN3OcrqfKfMAXW646rg7EtVROgFvU6M,8250
+solver_support/utilities.py,sha256=Aan8L-OTSzEpNf8-krrP1cfh5FMUmYDGkKn4KRJQfqM,4920
+solver_support-0.1.1.dist-info/licenses/LICENSE,sha256=xaDouhdJlWIrxBMOcomqpCBqJsc4MgHFknB4l9yT6QM,1523
+solver_support-0.1.1.dist-info/METADATA,sha256=_2Ffip1nOU9l_X58tjkl86QrAzayb3Y4strQOTU2DsE,5053
+solver_support-0.1.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+solver_support-0.1.1.dist-info/top_level.txt,sha256=GmfATXT2pguSk0_6_J-3chal_ql5vxBmXGacUWTBe5w,15
+solver_support-0.1.1.dist-info/RECORD,,

solver_support-0.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

solver_support-0.1.1.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+solver_support