Skip to content

Commit f4f8a90

Browse files
blackopsreplblackopsrepl
committed
update project roadmap
1 parent c1a2795 commit f4f8a90

File tree

1 file changed

+162
-51
lines changed

1 file changed

+162
-51
lines changed

‎content/en/docs/overview.md‎

Lines changed: 162 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -14,60 +14,171 @@ This page presents the SolverForge project overview and official development roa
1414

1515
SolverForge is a high-performance, 100% Timefold-compatible constraint solver focused on delivering a first-class developer experience for Python and Rust.
1616

17-
## Core objective
17+
## Core Objective
1818

19-
- Provide the Python and Rust ecosystems with a first-class, high-performance Constraint Programming and Optimization toolset
20-
- Deliver a seamless developer experience and enable new workflows in ML, data science, and operations research
19+
To provide the Rust, Python and broader language ecosystems with a first-class, high-performance Constraint Programming and Optimization solver, offering a seamless experience and unlocking new possibilities for the ML, data science, and systems programming communities.
2120

22-
## Core challenge: the Python–Java bridge
21+
## Core Innovation: WASM + HTTP Bridge Architecture
2322

24-
Most JVM-backed Python tooling is limited by the interoperability layer between Python and Java. Our strategy is a ground-up rewrite of that layer in native Rust using `PyO3` and `JNI` so we can eliminate the bridge bottleneck and achieve near-native performance.
23+
Unlike traditional approaches that rely on complex JNI bridges or interpreter overhead, SolverForge eliminates these bottlenecks entirely through a novel architecture:
2524

26-
## Roadmap
25+
1. **WebAssembly-compiled constraints** - Constraint predicates are compiled to WASM and executed directly in the JVM via the Chicory WASM runtime
26+
2. **HTTP/JSON communication** - Clean separation between language bindings and the solver service
27+
3. **Native Rust core** - Language-agnostic core library with zero-cost abstractions
28+
4. **No JNI complexity** - Pure HTTP interface eliminates the need for platform-specific native bindings
2729

28-
We’re executing a three-phase plan to preserve continuity for current users while delivering a production-ready native solution.
30+
This architecture provides near-native performance while maintaining complete language independence.
2931

30-
### Phase 1 — Stabilize the legacy bridge (Present → Q4 2025)
31-
Objective: Maintain continuity for existing Timefold users with a supported, debranded continuation of the old Python API.
32-
33-
Key deliverables:
34-
- `solverforge-legacy` (released): a maintained fork of Timefold 1.24.0. Installable via `pip install solverforge-legacy`. Serves as a stable baseline for production users.
35-
- `solverforge-quickstarts`: central repository of quickstarts and reproducible benchmarks.
36-
Status: Complete — provides continuity for existing projects.
37-
38-
### Phase 2 — Alpha: native Rust solver (Q4 2025 → Q1 2026)
39-
Objective: Ship an alpha release with a native Rust backend that removes the Python→Java bridge overhead.
40-
41-
Key deliverables:
42-
- `solverforge-solver`: a ground-up rewrite in Rust using `PyO3` and direct `JNI` integration with the Timefold JVM core.
43-
- Full API compatibility with the discontinued Timefold Python API (API surface parity).
44-
- Lambda support:
45-
- Simple lambdas: translated to Java bytecode for native performance.
46-
- Complex lambdas: efficient proxy fallbacks to preserve Python semantics and feature parity.
47-
- Performance target: within ~0.5% overhead of pure Java.
48-
Status: Active development — core infrastructure implemented and functional.
49-
50-
### Phase 3 — Production release & ecosystem expansion (H1 2026 → Q3 2026)
51-
Objective: Harden the Rust solver for production, publish stable packages, deepen documentation, and expand integrations into the ML ecosystem.
52-
53-
Key deliverables:
54-
- Production PyPI package: `blackops` (expected `pip install blackops`).
55-
- Full documentation: installation, migration notes from Timefold, and advanced usage patterns.
56-
- Advanced quickstarts: predictive and ML-integrated scheduling examples (e.g., simple regressors to forecast demand).
57-
- Native Rust API: a first-class Rust client for pure Rust applications.
58-
- Near-zero-overhead `PyO3` Python API.
59-
- HuggingFace engagement: Dockerized quickstarts and example models to attract ML practitioners.
60-
61-
## How you can contribute
62-
63-
This project thrives on community involvement. You can help in several ways:
64-
65-
- Test & benchmark: try `solverforge-legacy` and run examples from `solverforge-quickstarts`. Report issues, share performance numbers, and attach reproducible benchmarks.
66-
- Join the discussion: tell us which features, integrations, or APIs matter most for your workflows.
67-
- Contribute code: PRs, bug fixes, and documentation improvements are welcome.
68-
- Spread the word: star the repositories and share the project with colleagues in scheduling, optimization, and ML.
69-
70-
## Where to go next
71-
72-
- Quickstart guides: see the project’s quickstart guides in the docs.
73-
- Examples & quickstarts: explore `solverforge-quickstarts` for reproducible examples and benchmarks.
32+
## What We've Achieved
33+
34+
### ✅ Core Architecture (Completed - Q4 2025)
35+
36+
**Repository**: [solverforge/solverforge](https://github.com/solverforge/solverforge) (v0.1.56)
37+
38+
- **Complete Rust core library** (`solverforge-core`) - Language-agnostic foundation
39+
- Domain model definition with planning annotations (@PlanningEntity, @PlanningVariable, etc.)
40+
- Comprehensive constraint streams API (forEach, filter, join, groupBy, complement, flattenLast)
41+
- Advanced collectors (count, countDistinct, loadBalance)
42+
- Full score type system (Simple, HardSoft, HardMediumSoft, Bendable, BigDecimal variants)
43+
- Score analysis with constraint breakdown and indictments
44+
45+
- **WASM module generation** with proper memory alignment
46+
- Domain object layout with 32-bit and 64-bit type alignment
47+
- Field accessors (getters/setters)
48+
- Constraint predicates with complex logic (conditionals, arithmetic, range checking)
49+
- Primitive list operations (LocalDate[], LocalDateTime[], etc.)
50+
51+
- **Java service integration** (`timefold-wasm-service` submodule)
52+
- Chicory WASM runtime integration
53+
- Dynamic bytecode generation for domain classes and constraint providers
54+
- Host function provider for WASM-Java interop
55+
- HTTP endpoints for solving and score analysis
56+
57+
- **End-to-end integration tests**
58+
- Employee scheduling with 5 complex constraints
59+
- Temporal types (LocalDate, LocalDateTime) with proper alignment
60+
- Weighted penalties and custom weighers
61+
- Load balancing with fair distribution
62+
63+
## Roadmap Phases
64+
65+
### Phase 1: Foundation & Proof of Concept ✅ (Complete)
66+
67+
**Status**: Complete as of Q4 2025
68+
69+
**Achievements**:
70+
- ✅ Core Rust library with language-agnostic types
71+
- ✅ Complete constraint streams API
72+
- ✅ WASM generation pipeline
73+
- ✅ HTTP communication layer
74+
- ✅ Java service integration
75+
- ✅ Memory alignment correctness
76+
- ✅ End-to-end solving with real constraint problems
77+
78+
### Phase 2: Performance Optimization & Python Bindings (Q1 2026 - Q2 2026)
79+
80+
**Objective**: Achieve production-grade performance and deliver Python bindings via PyO3
81+
82+
**Key Deliverables**:
83+
- **Performance optimization**:
84+
- WASM module caching optimization for repeated solves
85+
- Export function lookup optimization
86+
- Incremental scoring with delta calculations
87+
- Join indexing for O(1) lookups
88+
89+
- **Python bindings** (`solverforge-python`):
90+
- PyO3-based native extension module
91+
- Pythonic API matching Timefold Python conventions
92+
- Type hints and comprehensive documentation
93+
- PyPI package: `pip install solverforge`
94+
95+
- **Enhanced testing**:
96+
- Complete benchmark suite supporting all official Timefold quickstarts
97+
- Performance regression tests
98+
- Cross-language validation tests
99+
100+
### Phase 3: Production Readiness & Ecosystem Expansion (H2 2026)
101+
102+
**Objective**: Deliver production-ready solver with comprehensive ecosystem support
103+
104+
**Key Deliverables**:
105+
- **Production release**: Stable v1.0.0 release
106+
- Comprehensive API documentation
107+
- Seamless migration from solverforge-legacy or Timefold Python
108+
- Performance tuning guide
109+
- Production deployment patterns
110+
111+
- **Language bindings expansion**:
112+
- 1:1 Timefold-compatible bindings in Python
113+
- Native Rust API for pure Rust applications
114+
115+
- **Advanced features**:
116+
- Custom move selectors
117+
- Real-time solving with event streaming
118+
- Multi-stage solving
119+
- Constraint configuration at runtime
120+
121+
- **ML/AI integration examples (?)**:
122+
- Predictive scheduling using ML forecasts
123+
- HuggingFace integration demos
124+
- Dockerized quickstarts for easy experimentation
125+
- Integration with popular Python data stack (pandas, numpy, polars)
126+
127+
## Technical Architecture
128+
```
129+
┌───────────────────────────────────────────────────────────────┐
130+
│ Language Bindings │
131+
│ (Python, JavaScript, Rust, Go) │
132+
└───────────────────────────────────────────────────────────────┘
133+
│
134+
▼
135+
┌───────────────────────────────────────────────────────────────┐
136+
│ solverforge-core (Rust) │
137+
│ │
138+
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
139+
│ │Domain │ │Constr-│ │ WASM │ │ HTTP │ │
140+
│ │Model │ │ aint │ │Builder│ │Client │ │
141+
│ │ │ │Stream │ │ │ │ │ │
142+
│ └───────┘ └───────┘ └───────┘ └───────┘ │
143+
└───────────────────────────────────────────────────────────────┘
144+
│
145+
HTTP/JSON + WASM
146+
│
147+
▼
148+
┌───────────────────────────────────────────────────────────────┐
149+
│ timefold-wasm-service (Java) │
150+
│ │
151+
│ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │
152+
│ │Chicory│ │Dynamic│ │Timefld│ │ Host │ │
153+
│ │ WASM │ │Bytcde │ │Solver │ │ Func │ │
154+
│ │Runtime│ │ Gen │ │Engine │ │ tions│ │
155+
│ └───────┘ └───────┘ └───────┘ └───────┘ │
156+
└───────────────────────────────────────────────────────────────┘
157+
```
158+
159+
## How You Can Contribute
160+
161+
This project thrives on community input. Here's how you can help:
162+
163+
1. **Test the core library**: Clone the repository and run the integration tests
164+
```bash
165+
git clone https://github.com/solverforge/solverforge
166+
cd solverforge
167+
cargo test --workspace
168+
```
169+
170+
2. **Benchmark your use cases**: We're collecting real-world constraint problems to ensure SolverForge works well for diverse scenarios
171+
172+
3. **Contribute to Python bindings**: We're starting work on PyO3 bindings - contributions welcome!
173+
174+
4. **Join the discussion**: Share your thoughts on this roadmap! What features are most critical for your use case?
175+
176+
5. **Spread the word**: Star the GitHub repository and share this project with anyone interested in constraint optimization
177+
178+
## Why SolverForge?
179+
180+
- **Language independence**: Write constraints in Python, Rust, JavaScript, or any language
181+
- **No JNI complexity**: Clean HTTP/JSON interface eliminates platform-specific native code
182+
- **Near-native performance**: WASM-compiled constraints with minimal overhead
183+
- **Modern architecture**: Built for cloud-native deployment and microservices
184+
- **Open source**: Apache 2.0 license, community-driven development

0 commit comments

Comments
 (0)