solverforge 0.2.6__tar.gz → 0.3.0__tar.gz

{solverforge-0.2.6 → solverforge-0.3.0}/Cargo.lock

@@ -1507,7 +1507,7 @@ dependencies = [
 
 [[package]]
 name = "solverforge"
-version = "0.2.6"
+version = "0.3.0"
 dependencies = [
  "solverforge-core",
  "solverforge-derive",
@@ -1516,7 +1516,7 @@ dependencies = [
 
 [[package]]
 name = "solverforge-core"
-version = "0.2.6"
+version = "0.3.0"
 dependencies = [
  "base64",
  "indexmap",
@@ -1532,7 +1532,7 @@ dependencies = [
 
 [[package]]
 name = "solverforge-derive"
-version = "0.2.6"
+version = "0.3.0"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -1544,8 +1544,9 @@ dependencies = [
 
 [[package]]
 name = "solverforge-python"
-version = "0.2.6"
+version = "0.3.0"
 dependencies = [
+ "env_logger",
  "log",
  "pyo3",
  "rust_decimal",
@@ -1559,7 +1560,7 @@ dependencies = [
 
 [[package]]
 name = "solverforge-service"
-version = "0.2.6"
+version = "0.3.0"
 dependencies = [
  "base64",
  "chrono",
@@ -1655,6 +1656,15 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "test-support"
+version = "0.3.0"
+dependencies = [
+ "proptest",
+ "serde_json",
+ "solverforge-core",
+]
+
 [[package]]
 name = "thiserror"
 version = "2.0.17"

{solverforge-0.2.6 → solverforge-0.3.0}/Cargo.toml

@@ -3,7 +3,7 @@ members = ["solverforge-core", "solverforge-python", "solverforge-service"]
 resolver = "2"
 
 [workspace.package]
-version = "0.2.6"
+version = "0.3.0"
 edition = "2021"
 license = "Apache-2.0"
 repository = "https://github.com/solverforge/solverforge"

solverforge-0.3.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: solverforge
+Version: 0.3.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Summary: Python bindings for SolverForge constraint solver
+Keywords: constraint,solver,optimization,scheduling,planning
+License: Apache-2.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://solverforge.org
+Project-URL: Documentation, https://docs.solverforge.org
+Project-URL: Repository, https://github.com/solverforge/solverforge
+Project-URL: Bug Tracker, https://github.com/solverforge/solverforge/issues
+Project-URL: Changelog, https://github.com/solverforge/solverforge/blob/main/CHANGELOG.md
+
+# SolverForge Python
+
+Python bindings for the SolverForge constraint solver.
+
+## Installation
+
+```bash
+pip install solverforge
+```
+
+## Quick Start
+
+```python
+from solverforge import (
+    planning_entity, planning_solution, constraint_provider,
+    PlanningId, PlanningVariable, PlanningListVariable,
+    HardSoftScore, SolverFactory, TerminationConfig,
+)
+
+@planning_entity
+class Lesson:
+    id: str
+    subject: str
+    timeslot: str | None = None
+    room: str | None = None
+
+@planning_solution
+class Timetable:
+    timeslots: list[str]
+    rooms: list[str]
+    lessons: list[Lesson]
+    score: HardSoftScore | None = None
+
+@constraint_provider
+def define_constraints(factory):
+    return [
+        factory.for_each(Lesson)
+            .join(Lesson, equal(lambda l: l.room), equal(lambda l: l.timeslot))
+            .filter(lambda l1, l2: l1.id < l2.id)
+            .penalize(HardSoftScore.ONE_HARD)
+            .as_constraint("Room conflict"),
+    ]
+
+# Solve
+solver = SolverFactory.create(Timetable, define_constraints)
+    .with_termination(TerminationConfig.with_spent_limit("PT30S"))
+    .build()
+solution = solver.solve(problem)
+```
+
+## Features
+
+### Domain Modeling
+
+```python
+from solverforge import (
+    planning_entity, planning_solution,
+    PlanningVariable, PlanningListVariable,
+    InverseRelationShadow, IndexShadow, PreviousElementShadow, NextElementShadow,
+)
+
+# Standard planning variable
+@planning_entity
+class Shift:
+    id: str
+    employee: str | None = None  # Assigned by solver
+
+# List planning variable (vehicle routing)
+@planning_entity
+class Vehicle:
+    id: str
+    visits: list[str] = []  # List of visit IDs, assigned by solver
+
+# Shadow variables (auto-updated when list changes)
+@planning_entity
+class Visit:
+    id: str
+    vehicle: str | None = None      # @InverseRelationShadowVariable
+    index: int | None = None        # @IndexShadowVariable
+    previous: str | None = None     # @PreviousElementShadowVariable
+    next: str | None = None         # @NextElementShadowVariable
+```
+
+### Constraint Streams
+
+```python
+from solverforge import (
+    equal, less_than, greater_than, overlapping, filtering,
+    count, sum_, min_, max_, to_list, to_set,
+)
+
+@constraint_provider
+def constraints(factory):
+    return [
+        # forEach / forEachIncludingUnassigned / forEachUniquePair
+        factory.for_each(Lesson),
+        factory.for_each_including_unassigned(Lesson),
+        factory.for_each_unique_pair(Lesson, equal(lambda l: l.timeslot)),
+
+        # filter
+        factory.for_each(Lesson)
+            .filter(lambda l: l.room is not None),
+
+        # join with joiners
+        factory.for_each(Lesson)
+            .join(Room, equal(lambda l: l.room, lambda r: r.id)),
+
+        # ifExists / ifNotExists
+        factory.for_each(Lesson)
+            .if_exists(Conflict, equal(lambda l: l.id, lambda c: c.lesson_id)),
+
+        # groupBy with collectors
+        factory.for_each(Lesson)
+            .group_by(lambda l: l.room, count())
+            .filter(lambda room, cnt: cnt > 1)
+            .penalize(HardSoftScore.ONE_HARD, lambda room, cnt: cnt - 1),
+
+        # map / expand / flattenLast
+        factory.for_each(Vehicle)
+            .flatten_last(lambda v: v.visits),
+    ]
+```
+
+### SolverManager (Multi-Problem Solving)
+
+```python
+from solverforge import SolverManager, HttpSolverService
+
+service = HttpSolverService("http://localhost:8080")
+manager = SolverManager(Timetable, define_constraints, service)
+
+# Solve multiple problems concurrently
+manager.solve("problem-1", problem1)
+manager.solve("problem-2", problem2)
+
+# Check solutions
+solution = manager.get_best_solution("problem-1")
+if solution:
+    print(f"Score: {solution.score}")
+
+# Terminate
+manager.terminate("problem-1")
+manager.terminate_all()
+```
+
+### ConstraintVerifier (Testing)
+
+```python
+from solverforge import ConstraintVerifier
+
+verifier = ConstraintVerifier.build(Timetable, define_constraints)
+
+# Test specific constraint
+verifier.verify_that(lambda f: f.for_each(Lesson)...)
+    .given(lesson1, lesson2)
+    .penalizes_by(1)
+
+# Test entire solution
+verifier.verify_that()
+    .given_solution(solution)
+    .scores(HardSoftScore.of(-2, -10))
+```
+
+### Score Types
+
+```python
+from solverforge import (
+    SimpleScore, HardSoftScore, HardMediumSoftScore,
+    BendableScore, SimpleDecimalScore, HardSoftDecimalScore,
+)
+
+score = HardSoftScore.of(-2, -15)
+print(f"Hard: {score.hard_score}, Soft: {score.soft_score}")
+print(f"Feasible: {score.is_feasible()}")
+
+# Arithmetic
+combined = score + HardSoftScore.of(0, -5)
+```
+
+### Solver Configuration
+
+```python
+from solverforge import (
+    SolverFactory, SolverConfig, TerminationConfig,
+    EnvironmentMode, MoveThreadCount,
+)
+
+solver = SolverFactory.create(Timetable, define_constraints)
+    .with_termination(
+        TerminationConfig()
+            .with_spent_limit("PT5M")
+            .with_unimproved_spent_limit("PT1M")
+            .with_best_score_feasible(True)
+    )
+    .with_environment_mode(EnvironmentMode.REPRODUCIBLE)
+    .with_random_seed(42)
+    .with_move_thread_count(MoveThreadCount.AUTO)
+    .build()
+```
+
+## Requirements
+
+- Python 3.13+ (required for modern AST support)
+- Java 21+ (for solver service, auto-started)
+
+## License
+
+Apache-2.0
+

solverforge-0.3.0/README.md

@@ -0,0 +1,208 @@
+# SolverForge Python
+
+Python bindings for the SolverForge constraint solver.
+
+## Installation
+
+```bash
+pip install solverforge
+```
+
+## Quick Start
+
+```python
+from solverforge import (
+    planning_entity, planning_solution, constraint_provider,
+    PlanningId, PlanningVariable, PlanningListVariable,
+    HardSoftScore, SolverFactory, TerminationConfig,
+)
+
+@planning_entity
+class Lesson:
+    id: str
+    subject: str
+    timeslot: str | None = None
+    room: str | None = None
+
+@planning_solution
+class Timetable:
+    timeslots: list[str]
+    rooms: list[str]
+    lessons: list[Lesson]
+    score: HardSoftScore | None = None
+
+@constraint_provider
+def define_constraints(factory):
+    return [
+        factory.for_each(Lesson)
+            .join(Lesson, equal(lambda l: l.room), equal(lambda l: l.timeslot))
+            .filter(lambda l1, l2: l1.id < l2.id)
+            .penalize(HardSoftScore.ONE_HARD)
+            .as_constraint("Room conflict"),
+    ]
+
+# Solve
+solver = SolverFactory.create(Timetable, define_constraints)
+    .with_termination(TerminationConfig.with_spent_limit("PT30S"))
+    .build()
+solution = solver.solve(problem)
+```
+
+## Features
+
+### Domain Modeling
+
+```python
+from solverforge import (
+    planning_entity, planning_solution,
+    PlanningVariable, PlanningListVariable,
+    InverseRelationShadow, IndexShadow, PreviousElementShadow, NextElementShadow,
+)
+
+# Standard planning variable
+@planning_entity
+class Shift:
+    id: str
+    employee: str | None = None  # Assigned by solver
+
+# List planning variable (vehicle routing)
+@planning_entity
+class Vehicle:
+    id: str
+    visits: list[str] = []  # List of visit IDs, assigned by solver
+
+# Shadow variables (auto-updated when list changes)
+@planning_entity
+class Visit:
+    id: str
+    vehicle: str | None = None      # @InverseRelationShadowVariable
+    index: int | None = None        # @IndexShadowVariable
+    previous: str | None = None     # @PreviousElementShadowVariable
+    next: str | None = None         # @NextElementShadowVariable
+```
+
+### Constraint Streams
+
+```python
+from solverforge import (
+    equal, less_than, greater_than, overlapping, filtering,
+    count, sum_, min_, max_, to_list, to_set,
+)
+
+@constraint_provider
+def constraints(factory):
+    return [
+        # forEach / forEachIncludingUnassigned / forEachUniquePair
+        factory.for_each(Lesson),
+        factory.for_each_including_unassigned(Lesson),
+        factory.for_each_unique_pair(Lesson, equal(lambda l: l.timeslot)),
+
+        # filter
+        factory.for_each(Lesson)
+            .filter(lambda l: l.room is not None),
+
+        # join with joiners
+        factory.for_each(Lesson)
+            .join(Room, equal(lambda l: l.room, lambda r: r.id)),
+
+        # ifExists / ifNotExists
+        factory.for_each(Lesson)
+            .if_exists(Conflict, equal(lambda l: l.id, lambda c: c.lesson_id)),
+
+        # groupBy with collectors
+        factory.for_each(Lesson)
+            .group_by(lambda l: l.room, count())
+            .filter(lambda room, cnt: cnt > 1)
+            .penalize(HardSoftScore.ONE_HARD, lambda room, cnt: cnt - 1),
+
+        # map / expand / flattenLast
+        factory.for_each(Vehicle)
+            .flatten_last(lambda v: v.visits),
+    ]
+```
+
+### SolverManager (Multi-Problem Solving)
+
+```python
+from solverforge import SolverManager, HttpSolverService
+
+service = HttpSolverService("http://localhost:8080")
+manager = SolverManager(Timetable, define_constraints, service)
+
+# Solve multiple problems concurrently
+manager.solve("problem-1", problem1)
+manager.solve("problem-2", problem2)
+
+# Check solutions
+solution = manager.get_best_solution("problem-1")
+if solution:
+    print(f"Score: {solution.score}")
+
+# Terminate
+manager.terminate("problem-1")
+manager.terminate_all()
+```
+
+### ConstraintVerifier (Testing)
+
+```python
+from solverforge import ConstraintVerifier
+
+verifier = ConstraintVerifier.build(Timetable, define_constraints)
+
+# Test specific constraint
+verifier.verify_that(lambda f: f.for_each(Lesson)...)
+    .given(lesson1, lesson2)
+    .penalizes_by(1)
+
+# Test entire solution
+verifier.verify_that()
+    .given_solution(solution)
+    .scores(HardSoftScore.of(-2, -10))
+```
+
+### Score Types
+
+```python
+from solverforge import (
+    SimpleScore, HardSoftScore, HardMediumSoftScore,
+    BendableScore, SimpleDecimalScore, HardSoftDecimalScore,
+)
+
+score = HardSoftScore.of(-2, -15)
+print(f"Hard: {score.hard_score}, Soft: {score.soft_score}")
+print(f"Feasible: {score.is_feasible()}")
+
+# Arithmetic
+combined = score + HardSoftScore.of(0, -5)
+```
+
+### Solver Configuration
+
+```python
+from solverforge import (
+    SolverFactory, SolverConfig, TerminationConfig,
+    EnvironmentMode, MoveThreadCount,
+)
+
+solver = SolverFactory.create(Timetable, define_constraints)
+    .with_termination(
+        TerminationConfig()
+            .with_spent_limit("PT5M")
+            .with_unimproved_spent_limit("PT1M")
+            .with_best_score_feasible(True)
+    )
+    .with_environment_mode(EnvironmentMode.REPRODUCIBLE)
+    .with_random_seed(42)
+    .with_move_thread_count(MoveThreadCount.AUTO)
+    .build()
+```
+
+## Requirements
+
+- Python 3.13+ (required for modern AST support)
+- Java 21+ (for solver service, auto-started)
+
+## License
+
+Apache-2.0

{solverforge-0.2.6 → solverforge-0.3.0}/pyproject.toml

@@ -4,19 +4,17 @@ build-backend = "maturin"
 
 [project]
 name = "solverforge"
-version = "0.2.6"
+version = "0.3.0"
 description = "Python bindings for SolverForge constraint solver"
 readme = "README.md"
 license = { text = "Apache-2.0" }
-requires-python = ">=3.10"
+requires-python = ">=3.13"
 classifiers = [
     "Programming Language :: Rust",
     "Programming Language :: Python :: Implementation :: CPython",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
-    "Programming Language :: Python :: 3.11",
-    "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
@@ -32,7 +30,7 @@ Repository = "https://github.com/solverforge/solverforge"
 Changelog = "https://github.com/solverforge/solverforge/blob/main/CHANGELOG.md"
 
 [tool.maturin]
-features = ["pyo3/extension-module", "pyo3/abi3-py310"]
+features = ["pyo3/extension-module", "pyo3/abi3-py313"]
 python-source = "python"
 module-name = "solverforge._solverforge"
 manifest-path = "solverforge-python/Cargo.toml"

{solverforge-0.2.6 → solverforge-0.3.0}/python/solverforge/__init__.py

@@ -57,6 +57,9 @@ from solverforge._solverforge import (
     SolveResponse,
     SolverFactory,
     Solver,
+    SolverManager,
+    SolverJob,
+    SolverJobStatus,
     # Constraint streams
     ConstraintFactory,
     UniConstraintStream,
@@ -131,6 +134,9 @@ __all__ = [
     "SolveResponse",
     "SolverFactory",
     "Solver",
+    "SolverManager",
+    "SolverJob",
+    "SolverJobStatus",
     # Constraint streams
     "ConstraintFactory",
     "UniConstraintStream",

{solverforge-0.2.6/solverforge-python → solverforge-0.3.0}/python/solverforge/solver/__init__.py

@@ -82,6 +82,9 @@ class SolverJob(Generic[Solution_, ProblemId_]):
                 self._final_best_solution_consumer(response.solution)
 
         except Exception as e:
+            import logging
+
+            logging.getLogger(__name__).error("Solver failed: %s", e, exc_info=True)
             with self._lock:
                 self._exception = e
                 self._status = SolverStatus.NOT_SOLVING

solverforge-0.3.0/solverforge-core/README.md

@@ -0,0 +1,118 @@
+# solverforge-core
+
+Language-agnostic core library for SolverForge constraint solving.
+
+## Overview
+
+This crate provides the foundation for SolverForge's constraint solving capabilities:
+
+- **Value types** - `Value`, `ObjectHandle`, `FunctionHandle`
+- **Score types** - `SimpleScore`, `HardSoftScore`, `HardMediumSoftScore`, `BendableScore` (+ decimal variants)
+- **Domain modeling** - `PlanningAnnotation`, `DomainModel`, `DomainClass`, `FieldDescriptor`
+- **Constraint streams** - `Constraint`, `ConstraintSet`, `StreamComponent`, `Joiner`, `Collector`
+- **Expression DSL** - `Expr`, `Expression`, `NamedExpression` for type-safe constraint building
+- **Solver** - `SolverBuilder`, `TypedSolver`, `SolverManager`, `SolverFactory`
+- **WASM generation** - `WasmModuleBuilder`, `PredicateDefinition`
+
+## Usage
+
+```toml
+[dependencies]
+solverforge-core = "0.2"
+```
+
+### Score Types
+
+```rust
+use solverforge_core::{HardSoftScore, HardMediumSoftScore, SimpleScore};
+
+let score = HardSoftScore::of(-2, -15);
+assert_eq!(score.hard_score(), -2);
+assert!(score.is_feasible() == false);
+
+let simple = SimpleScore::of(100);
+let hms = HardMediumSoftScore::of(0, -5, -10);
+```
+
+### Constraint Streams
+
+```rust
+use solverforge_core::{Constraint, StreamComponent, Joiner, WasmFunction, Collector};
+
+let constraint = Constraint::new("Room conflict")
+    .with_stream(StreamComponent::for_each("Lesson"))
+    .with_stream(StreamComponent::join_with_joiners(
+        "Lesson",
+        vec![
+            Joiner::equal(WasmFunction::new("getRoom")),
+            Joiner::equal(WasmFunction::new("getTimeslot")),
+        ],
+    ))
+    .with_stream(StreamComponent::filter(WasmFunction::new("isDifferent")))
+    .with_stream(StreamComponent::penalize("1hard"));
+```
+
+### Expression DSL
+
+```rust
+use solverforge_core::{Expr, NamedExpression, IntoNamedExpression, StreamComponent};
+use solverforge_core::wasm::FieldAccessExt;
+
+// Build type-safe expressions
+let has_room = Expr::is_not_null(Expr::param(0).get("Lesson", "room"))
+    .named_as("lesson_has_room");
+
+// Use in stream components
+let filter = StreamComponent::filter_expr(has_room);
+```
+
+### SolverManager (Multi-Problem Solving)
+
+```rust
+use solverforge_core::{SolverManager, HttpSolverService, TerminationConfig};
+use std::sync::Arc;
+
+let service = Arc::new(HttpSolverService::new("http://localhost:8080"));
+let mut manager = SolverManager::<Timetable, String>::new(service)
+    .with_termination(TerminationConfig::new().with_spent_limit("PT5M"));
+
+// Solve multiple problems concurrently
+manager.solve("problem-1".to_string(), problem1)?;
+manager.solve("problem-2".to_string(), problem2)?;
+
+// Check solutions
+if let Some(solution) = manager.get_best_solution(&"problem-1".to_string())? {
+    println!("Score: {:?}", solution.score());
+}
+
+manager.terminate_all();
+```
+
+### Shadow Variables
+
+```rust
+use solverforge_core::PlanningAnnotation;
+
+// Available shadow variable types
+let index = PlanningAnnotation::index_shadow("visits");
+let next = PlanningAnnotation::next_element_shadow("visits");
+let prev = PlanningAnnotation::previous_element_shadow("visits");
+let anchor = PlanningAnnotation::anchor_shadow("chain");
+let inverse = PlanningAnnotation::inverse_relation_shadow("vehicle", "visits");
+```
+
+## Architecture
+
+```
+solverforge-core
+├── constraints/    # Constraint streams, joiners, collectors
+├── domain/         # Domain model, annotations, shadow variables
+├── solver/         # SolverBuilder, SolverManager, HTTP client
+├── wasm/           # WASM module generation, expression compiler
+├── score/          # Score types (Simple, HardSoft, etc.)
+└── analysis/       # Score explanation, constraint matches
+```
+
+## License
+
+Apache-2.0