Documentation
Build SolverForge planning models in Python and solve them with the native SolverForge engine.
SolverForge Python
SolverForge Python lets Python users define planning models with ordinary classes, decorators, functions, and lambdas. Decorators mark planning entities, variables, and solutions. Constraint providers return Python callback-based rules. The binding compiles that authored schema into the same immutable runtime graph used by native SolverForge models; it does not maintain a second Python selector or move engine.
Installation
Install the current public PyPI package:
python3.14 -m pip install "solverforge==0.6.3"
Use the tagged source checkout when developing the repository examples or inspecting the complete source:
git clone https://github.com/SolverForge/solverforge-py.git
cd solverforge-py
git checkout v0.6.3
make develop
. .venv/bin/activate
Basic Workflow
- Define facts and planning entities as Python classes.
- Mark scalar or list planning variables on entity classes.
- Add a
@planning_solution(...)class that owns the collections. - Write constraint callbacks with
ConstraintFactory. - Call
Solver.solve(...)for a direct solve orSolverManagerfor retained jobs, snapshots, pause, resume, and cancel.
API Surface
| Use | API |
|---|---|
| Model classes | @planning_solution, @planning_entity, @problem_fact |
| Planning fields | planning_id, planning_variable, planning_list_variable |
| Constraints | @constraint_provider, ConstraintFactory, joiner |
| Grouped scalar repair | scalar_assignment_group, ScalarGroupLimits, @scalar_group, @conflict_repair |
| Candidate ordering | @candidate_metric, selection_order, selection_metric |
| List metadata | ListRouteHooks, ListSavingsHooks, RowField, SolutionField, EntityCallback, SolutionCallback |
| Scores | SoftScore, HardSoftScore, HardSoftDecimalScore, HardMediumSoftScore |
| Direct solve | Solver.solve(...), Solver.analyze(...) |
| Retained jobs | SolverManager, telemetry_detail(...), QualifiedCandidateTraceProvenance |
| Runtime config | SolverConfig, dictionaries, or solver.toml |
| Embedded UI assets | solverforge.ui.asset(...), solverforge.ui.asset_paths() |
Package Details
| Surface | Current state |
|---|---|
| Package name | solverforge |
| Documented source line | 0.6.3 |
| Published PyPI version | 0.6.3 |
| Python requirement | >=3.14 |
| Runtime base | solverforge 0.19.1 |
| Embedded UI base | solverforge-ui 0.7.0 |
| Repository | SolverForge/solverforge-py |
Sections
- Getting Started - install the package, write a minimal model, solve it, and pass config
- Modeling - classes, decorators, scalar variables, assignment groups, scoped list metadata, candidate metrics, score families, and schema compilation
- Constraints - callback stream shapes, joins, grouping, balance scoring, and unsupported top-level methods
- Solving & Runtime - synchronous solves, score analysis, compiled runtime config, retained jobs, candidate traces, qualified provenance, and dynamic move support
- Hospital Example - the FastAPI example, retained lifecycle endpoints, and public dataset shape
- Deliveries Example - the route-owning list-variable example, explicit CVRP route/savings metadata, route snapshots, and insertion recommendations