solverforge 0.4.0__cp314-cp314-win_amd64.whl

solverforge/__init__.py

@@ -0,0 +1,47 @@
+from . import console, joiner
+from .config import SolverConfig, TerminationConfig
+from .constraints import ConstraintFactory
+from .decorators import (
+    conflict_repair,
+    constraint_provider,
+    planning_entity,
+    planning_solution,
+    problem_fact,
+    scalar_group,
+)
+from .errors import CallbackError, ModelValidationError, NativeBridgeError, SolverForgeError
+from .fields import planning_id, planning_list_variable, planning_variable
+from .manager import JobHandle, SolverManager
+from .score import HardMediumSoftScore, HardSoftDecimalScore, HardSoftScore, SoftScore
+from .solver import Solver
+
+__version__ = "0.4.0"
+
+__all__ = [
+    "CallbackError",
+    "ConstraintFactory",
+    "HardMediumSoftScore",
+    "HardSoftDecimalScore",
+    "HardSoftScore",
+    "JobHandle",
+    "ModelValidationError",
+    "NativeBridgeError",
+    "SoftScore",
+    "Solver",
+    "SolverConfig",
+    "SolverForgeError",
+    "SolverManager",
+    "TerminationConfig",
+    "__version__",
+    "console",
+    "conflict_repair",
+    "constraint_provider",
+    "joiner",
+    "planning_entity",
+    "planning_id",
+    "planning_list_variable",
+    "planning_solution",
+    "planning_variable",
+    "problem_fact",
+    "scalar_group",
+]

solverforge/_native.pyi

@@ -0,0 +1,20 @@
+from typing import Any
+
+class NativeSolverError(RuntimeError): ...
+
+class SolverManager:
+    def __init__(self, config: dict[str, Any] | None = None) -> None: ...
+    def solve(self, solution: object, schema: dict[str, Any]) -> int: ...
+    def get_status(self, job_id: int) -> dict[str, object]: ...
+    def drain_events(self, job_id: int) -> list[dict[str, object]]: ...
+    def snapshot(self, job_id: int, snapshot_revision: int | None = None) -> object: ...
+    def pause(self, job_id: int) -> None: ...
+    def resume(self, job_id: int) -> None: ...
+    def cancel(self, job_id: int) -> None: ...
+    def delete(self, job_id: int) -> None: ...
+
+def solve(solution: object, schema: dict[str, Any], config: dict[str, Any] | None = None) -> object: ...
+def calculate_score(solution: object, schema: dict[str, Any]) -> object: ...
+def init_console() -> None: ...
+def validate_schema(schema: dict[str, Any]) -> None: ...
+def native_version() -> str: ...

solverforge/config.py

@@ -0,0 +1,160 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass, field
+from os import PathLike
+from pathlib import Path
+from typing import Any
+
+
+_TERMINATION_FIELDS = {
+    "seconds_spent_limit",
+    "minutes_spent_limit",
+    "best_score_limit",
+    "step_count_limit",
+    "unimproved_step_count_limit",
+    "unimproved_seconds_spent_limit",
+}
+
+
+@dataclass
+class TerminationConfig:
+    seconds_spent_limit: int | None = None
+    minutes_spent_limit: int | None = None
+    best_score_limit: str | None = None
+    step_count_limit: int | None = None
+    unimproved_step_count_limit: int | None = None
+    unimproved_seconds_spent_limit: int | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> TerminationConfig:
+        if not data:
+            return cls()
+        unknown = sorted(set(data) - _TERMINATION_FIELDS)
+        if unknown:
+            joined = ", ".join(unknown)
+            expected = ", ".join(sorted(_TERMINATION_FIELDS))
+            msg = f"unknown SolverForge termination field(s): {joined}; expected one of: {expected}"
+            raise ValueError(msg)
+        return cls(
+            seconds_spent_limit=data.get("seconds_spent_limit"),
+            minutes_spent_limit=data.get("minutes_spent_limit"),
+            best_score_limit=data.get("best_score_limit"),
+            step_count_limit=data.get("step_count_limit"),
+            unimproved_step_count_limit=data.get("unimproved_step_count_limit"),
+            unimproved_seconds_spent_limit=data.get("unimproved_seconds_spent_limit"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        data = {
+            "seconds_spent_limit": self.seconds_spent_limit,
+            "minutes_spent_limit": self.minutes_spent_limit,
+            "best_score_limit": self.best_score_limit,
+            "step_count_limit": self.step_count_limit,
+            "unimproved_step_count_limit": self.unimproved_step_count_limit,
+            "unimproved_seconds_spent_limit": self.unimproved_seconds_spent_limit,
+        }
+        return {key: value for key, value in data.items() if value is not None}
+
+
+@dataclass
+class SolverConfig:
+    seconds_spent_limit: int | None = None
+    random_seed: int | None = None
+    phases: list[dict[str, Any]] = field(default_factory=list)
+    termination: TerminationConfig | dict[str, Any] | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> SolverConfig:
+        termination_data = _termination_data_from_config_dict(data)
+        termination = TerminationConfig.from_dict(termination_data)
+        extra = {
+            key: deepcopy(value)
+            for key, value in data.items()
+            if key not in {"random_seed", "termination", "phases"} | _TERMINATION_FIELDS
+        }
+        return cls(
+            seconds_spent_limit=None,
+            random_seed=data.get("random_seed"),
+            phases=_normalize_phases(list(data.get("phases", []))),
+            termination=termination,
+            extra=extra,
+        )
+
+    @classmethod
+    def from_toml(cls, text: str) -> SolverConfig:
+        import tomllib
+
+        return cls.from_dict(tomllib.loads(text))
+
+    @classmethod
+    def load(cls, path: str | PathLike[str] = "solver.toml") -> SolverConfig:
+        return cls.from_toml(Path(path).read_text(encoding="utf-8"))
+
+    @classmethod
+    def from_file(cls, path: str | PathLike[str] = "solver.toml") -> SolverConfig:
+        return cls.load(path)
+
+    def to_dict(self) -> dict[str, Any]:
+        data: dict[str, Any] = deepcopy(self.extra)
+        if self.random_seed is not None:
+            data["random_seed"] = self.random_seed
+        termination = _termination_to_dict(self.termination)
+        if self.seconds_spent_limit is not None:
+            termination["seconds_spent_limit"] = self.seconds_spent_limit
+        if termination:
+            data["termination"] = termination
+        if self.phases:
+            data["phases"] = _normalize_phases(self.phases)
+        return data
+
+
+def _resolve_config(config: SolverConfig | dict[str, Any] | None) -> dict[str, Any] | None:
+    if isinstance(config, SolverConfig):
+        return config.to_dict()
+    if config is not None:
+        return SolverConfig.from_dict(config).to_dict()
+    path = Path("solver.toml")
+    if path.is_file():
+        return SolverConfig.load(path).to_dict()
+    return None
+
+
+def _termination_to_dict(
+    termination: TerminationConfig | dict[str, Any] | None,
+) -> dict[str, Any]:
+    if termination is None:
+        return {}
+    if isinstance(termination, TerminationConfig):
+        return termination.to_dict()
+    return TerminationConfig.from_dict(dict(termination)).to_dict()
+
+
+def _termination_data_from_config_dict(data: dict[str, Any]) -> dict[str, Any]:
+    termination = dict(data.get("termination") or {})
+    for key in _TERMINATION_FIELDS:
+        if key not in data:
+            continue
+        if key in termination and termination[key] != data[key]:
+            msg = (
+                f"conflicting SolverForge termination field `{key}`: "
+                "set it either at the top level or under `termination`, not both"
+            )
+            raise ValueError(msg)
+        termination[key] = deepcopy(data[key])
+    return termination
+
+
+def _normalize_phases(phases: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    normalized: list[dict[str, Any]] = []
+    for phase in phases:
+        phase_copy = deepcopy(phase)
+        if "termination" in phase_copy and phase_copy["termination"] is not None:
+            phase_copy["termination"] = TerminationConfig.from_dict(
+                dict(phase_copy["termination"])
+            ).to_dict()
+        if "child_phases" in phase_copy:
+            phase_copy["child_phases"] = _normalize_phases(list(phase_copy["child_phases"]))
+        normalized.append(phase_copy)
+    return normalized

solverforge/console.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from . import _native
+
+
+def init() -> None:
+    _native.init_console()

solverforge/constraints.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Self
+
+from .score import score_to_native
+
+
+@dataclass(frozen=True)
+class ConstraintPlan:
+    entity_type: type[object]
+    score_family: str = "hard_soft"
+    arity: int = 1
+    left_filters: tuple[Callable[..., bool], ...] = ()
+    right_filters: tuple[Callable[..., bool], ...] = ()
+    filters: tuple[Callable[..., bool], ...] = ()
+    group_filters: tuple[Callable[..., bool], ...] = ()
+    impact: str = "penalty"
+    weight: object = 1
+    name: str | None = None
+    right_entity_type: type[object] | None = None
+    joiners: tuple[object, ...] = ()
+    group_key: Callable[..., object] | None = None
+    balance_key: Callable[..., object] | None = None
+
+    def to_native(self) -> dict[str, object]:
+        plan: dict[str, object] = {
+            "arity": self.arity,
+            "entity_type": self.entity_type.__name__,
+            "left_filters": list(self.left_filters),
+            "right_filters": list(self.right_filters),
+            "filters": list(self.filters),
+            "group_filters": list(self.group_filters),
+            "impact": self.impact,
+            "name": self.name or f"{self.entity_type.__name__} constraint",
+        }
+        if self.right_entity_type is not None:
+            plan["right_entity_type"] = self.right_entity_type.__name__
+        if self.joiners:
+            plan["joiners"] = [joiner_to_native(joiner) for joiner in self.joiners]
+        if self.group_key is not None:
+            plan["group_key"] = self.group_key
+        if self.balance_key is not None:
+            plan["balance_key"] = self.balance_key
+        if callable(self.weight):
+            plan["weight"] = _callback_weight_placeholder(self.score_family)
+            plan["weight_callback"] = self.weight
+        else:
+            plan["weight"] = score_to_native(self.weight, self.score_family)
+        return plan
+
+
+@dataclass
+class UniConstraintStream:
+    entity_type: type[object]
+    score_family: str = "hard_soft"
+    filters: list[Callable[..., bool]] = field(default_factory=list)
+    impact: str | None = None
+    weight: object | None = None
+
+    def filter(self, predicate: Callable[..., bool]) -> Self:
+        self.filters.append(predicate)
+        return self
+
+    def penalize(self, weight: object) -> Self:
+        self.impact = "penalty"
+        self.weight = weight
+        return self
+
+    def reward(self, weight: object) -> Self:
+        self.impact = "reward"
+        self.weight = weight
+        return self
+
+    def join(
+        self,
+        target: object,
+        *joiners: object,
+    ) -> BiConstraintStream:
+        right_filters: list[Callable[..., bool]] = []
+        if isinstance(target, tuple):
+            if not target:
+                msg = "join target tuple must not be empty"
+                raise TypeError(msg)
+            stream_or_type, *tuple_joiners = target
+            target = stream_or_type
+            joiners = (*tuple_joiners, *joiners)
+        if isinstance(target, UniConstraintStream):
+            right_entity_type = target.entity_type
+            right_filters = list(target.filters)
+        elif isinstance(target, type):
+            right_entity_type = target
+        elif hasattr(target, "to_native"):
+            right_entity_type = self.entity_type
+            joiners = (target, *joiners)
+        else:
+            msg = f"unsupported join target {target!r}"
+            raise TypeError(msg)
+        return BiConstraintStream(
+            entity_type=self.entity_type,
+            score_family=self.score_family,
+            right_entity_type=right_entity_type,
+            left_filters=list(self.filters),
+            right_filters=right_filters,
+            joiners=list(joiners),
+        )
+
+    def group_by(self, key: Callable[[object], object]) -> GroupedConstraintStream:
+        return GroupedConstraintStream(
+            entity_type=self.entity_type,
+            score_family=self.score_family,
+            pre_filters=list(self.filters),
+            group_key=key,
+        )
+
+    def balance(self, key: Callable[[object], object]) -> BalanceConstraintStream:
+        return BalanceConstraintStream(
+            entity_type=self.entity_type,
+            score_family=self.score_family,
+            pre_filters=list(self.filters),
+            balance_key=key,
+        )
+
+    def named(self, name: str) -> ConstraintPlan:
+        return ConstraintPlan(
+            entity_type=self.entity_type,
+            score_family=self.score_family,
+            filters=tuple(self.filters),
+            impact=self.impact or "penalty",
+            weight=self.weight if self.weight is not None else 1,
+            name=name,
+        )
+
+
+@dataclass
+class BiConstraintStream:
+    entity_type: type[object]
+    score_family: str
+    right_entity_type: type[object]
+    left_filters: list[Callable[..., bool]] = field(default_factory=list)
+    right_filters: list[Callable[..., bool]] = field(default_factory=list)
+    filters: list[Callable[..., bool]] = field(default_factory=list)
+    joiners: list[object] = field(default_factory=list)
+    impact: str | None = None
+    weight: object | None = None
+
+    def filter(self, predicate: Callable[..., bool]) -> Self:
+        self.filters.append(predicate)
+        return self
+
+    def penalize(self, weight: object) -> Self:
+        self.impact = "penalty"
+        self.weight = weight
+        return self
+
+    def reward(self, weight: object) -> Self:
+        self.impact = "reward"
+        self.weight = weight
+        return self
+
+    def named(self, name: str) -> ConstraintPlan:
+        return ConstraintPlan(
+            entity_type=self.entity_type,
+            score_family=self.score_family,
+            arity=2,
+            left_filters=tuple(self.left_filters),
+            right_filters=tuple(self.right_filters),
+            filters=tuple(self.filters),
+            impact=self.impact or "penalty",
+            weight=self.weight if self.weight is not None else 1,
+            name=name,
+            right_entity_type=self.right_entity_type,
+            joiners=tuple(self.joiners),
+        )
+
+
+@dataclass
+class GroupedConstraintStream:
+    entity_type: type[object]
+    score_family: str
+    group_key: Callable[[object], object]
+    pre_filters: list[Callable[..., bool]] = field(default_factory=list)
+    filters: list[Callable[..., bool]] = field(default_factory=list)
+    impact: str | None = None
+    weight: object | None = None
+
+    def filter(self, predicate: Callable[..., bool]) -> Self:
+        self.filters.append(predicate)
+        return self
+
+    def penalize(self, weight: object) -> Self:
+        self.impact = "penalty"
+        self.weight = weight
+        return self
+
+    def reward(self, weight: object) -> Self:
+        self.impact = "reward"
+        self.weight = weight
+        return self
+
+    def named(self, name: str) -> ConstraintPlan:
+        return ConstraintPlan(
+            entity_type=self.entity_type,
+            score_family=self.score_family,
+            filters=tuple(self.pre_filters),
+            group_filters=tuple(self.filters),
+            impact=self.impact or "penalty",
+            weight=self.weight if self.weight is not None else 1,
+            name=name,
+            group_key=self.group_key,
+        )
+
+
+@dataclass
+class BalanceConstraintStream:
+    entity_type: type[object]
+    score_family: str
+    balance_key: Callable[[object], object]
+    pre_filters: list[Callable[..., bool]] = field(default_factory=list)
+    filters: list[Callable[..., bool]] = field(default_factory=list)
+    impact: str | None = None
+    weight: object | None = None
+
+    def filter(self, predicate: Callable[..., bool]) -> Self:
+        self.filters.append(predicate)
+        return self
+
+    def penalize(self, weight: object) -> Self:
+        self.impact = "penalty"
+        self.weight = weight
+        return self
+
+    def reward(self, weight: object) -> Self:
+        self.impact = "reward"
+        self.weight = weight
+        return self
+
+    def named(self, name: str) -> ConstraintPlan:
+        return ConstraintPlan(
+            entity_type=self.entity_type,
+            score_family=self.score_family,
+            filters=tuple(self.pre_filters + self.filters),
+            impact=self.impact or "penalty",
+            weight=self.weight if self.weight is not None else 1,
+            name=name,
+            balance_key=self.balance_key,
+        )
+
+
+class ConstraintFactory:
+    def __init__(self, *, score_family: str = "hard_soft") -> None:
+        self.score_family = score_family
+
+    def for_each(self, entity_type: type[object]) -> UniConstraintStream:
+        return UniConstraintStream(entity_type=entity_type, score_family=self.score_family)
+
+    def join(self, *_args: Any, **_kwargs: Any) -> None:
+        raise NotImplementedError("dynamic join is implemented in the native stream planner")
+
+    def if_exists(self, *_args: Any, **_kwargs: Any) -> None:
+        raise NotImplementedError("dynamic if_exists is implemented in the native stream planner")
+
+    def if_not_exists(self, *_args: Any, **_kwargs: Any) -> None:
+        raise NotImplementedError("dynamic if_not_exists is implemented in the native stream planner")
+
+    def group_by(self, *_args: Any, **_kwargs: Any) -> None:
+        raise NotImplementedError("dynamic group_by is implemented in the native stream planner")
+
+    def flattened(self, *_args: Any, **_kwargs: Any) -> None:
+        raise NotImplementedError("dynamic flattened is implemented in the native stream planner")
+
+
+def joiner_to_native(joiner: object) -> object:
+    if hasattr(joiner, "to_native"):
+        native = joiner.to_native()
+        if isinstance(native, dict):
+            return native
+    return joiner
+
+
+def _callback_weight_placeholder(score_family: str) -> dict[str, object]:
+    match score_family:
+        case "soft":
+            return {"family": "soft", "levels": [1]}
+        case "hard_soft":
+            return {"family": "hard_soft", "levels": [1, 0]}
+        case "hard_soft_decimal":
+            return {"family": "hard_soft_decimal", "levels": [1, 0]}
+        case "hard_medium_soft":
+            return {"family": "hard_medium_soft", "levels": [1, 0, 0]}
+        case _:
+            return score_to_native(1)

solverforge/decorators.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TypeVar
+
+from .fields import PlanningField
+from .score import HardSoftScore, score_family
+
+T = TypeVar("T", bound=type[object])
+
+
+def _collect_fields(cls: type[object]) -> list[dict[str, object]]:
+    fields: list[dict[str, object]] = []
+    for name, value in vars(cls).items():
+        if isinstance(value, PlanningField):
+            fields.append(
+                {
+                    "name": name,
+                    "kind": value.metadata.kind,
+                    "value_range_provider": value.metadata.value_range_provider,
+                    "allows_unassigned": value.metadata.allows_unassigned,
+                    "element_collection": value.metadata.element_collection,
+                    "pinning": value.metadata.pinning,
+                }
+            )
+    return fields
+
+
+def planning_entity(cls: T) -> T:
+    setattr(
+        cls,
+        "__solverforge_entity__",
+        {
+            "type_name": cls.__name__,
+            "fields": _collect_fields(cls),
+        },
+    )
+    return cls
+
+
+def problem_fact(cls: T) -> T:
+    setattr(
+        cls,
+        "__solverforge_fact__",
+        {
+            "type_name": cls.__name__,
+            "fields": _collect_fields(cls),
+        },
+    )
+    return cls
+
+
+def constraint_provider(fn: Callable[..., object]) -> Callable[..., object]:
+    setattr(fn, "__solverforge_constraint_provider__", True)
+    return fn
+
+
+def scalar_group(name: str) -> Callable[[Callable[..., object]], Callable[..., object]]:
+    def decorate(fn: Callable[..., object]) -> Callable[..., object]:
+        setattr(fn, "__solverforge_scalar_group__", {"name": name})
+        return fn
+
+    return decorate
+
+
+def conflict_repair(
+    *constraint_names: str,
+) -> Callable[[Callable[..., object]], Callable[..., object]]:
+    def decorate(fn: Callable[..., object]) -> Callable[..., object]:
+        setattr(fn, "__solverforge_conflict_repair__", {"constraints": list(constraint_names)})
+        return fn
+
+    return decorate
+
+
+def planning_solution(
+    *,
+    score: type[object] = HardSoftScore,
+    constraints: Callable[..., object] | None = None,
+    scalar_groups: list[Callable[..., object]] | None = None,
+    conflict_repairs: list[Callable[..., object]] | None = None,
+) -> Callable[[T], T]:
+    def decorate(cls: T) -> T:
+        setattr(
+            cls,
+            "__solverforge_solution__",
+            {
+                "type_name": cls.__name__,
+                "score_family": score_family(score),
+                "constraints": constraints,
+                "scalar_groups": list(scalar_groups or []),
+                "conflict_repairs": list(conflict_repairs or []),
+            },
+        )
+        return cls
+
+    return decorate

solverforge/errors.py

@@ -0,0 +1,15 @@
+class SolverForgeError(Exception):
+    """Base class for SolverForge Python binding errors."""
+
+
+class ModelValidationError(SolverForgeError):
+    """Raised when a Python model cannot be mapped to SolverForge metadata."""
+
+
+class CallbackError(SolverForgeError):
+    """Raised when a user callback fails during solving or scoring."""
+
+
+class NativeBridgeError(SolverForgeError):
+    """Raised when the PyO3 bridge reports a native-side failure."""
+

solverforge/events.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SolverEvent:
+    job_id: int
+    event_sequence: int
+    lifecycle_state: str
+    snapshot_revision: int | None = None
+    error: str | None = None
+