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 solve still runs through the native SolverForge engine.
Installation
python3.14 -m pip install solverforge
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 |
| Scores | SoftScore, HardSoftScore, HardSoftDecimalScore, HardMediumSoftScore |
| Direct solve | Solver.solve(...), Solver.analyze(...) |
| Retained jobs | SolverManager |
| Runtime config | SolverConfig, dictionaries, or solver.toml |
Package Details
| Surface | Current state |
|---|---|
| Package name | solverforge |
| Version | 0.4.0 |
| Python requirement | >=3.14 |
| Repository | SolverForge/solverforge-py |
Sections
- Getting Started - install the package, write a minimal model, solve it, and pass config
- Modeling - classes, decorators, scalar variables, list variables, score families, and schema inference
- Constraints - callback stream shapes, joins, grouping, balance scoring, and unsupported top-level methods
- Solving & Runtime - synchronous solves, score analysis, solver config, retained jobs, and dynamic move support
- Hospital Example - the FastAPI example, retained lifecycle endpoints, and public dataset shape