blackopsrepl commited on
Commit
53664d2
·
verified ·
1 Parent(s): cc6c5d9

Upload README.md with huggingface_hub

Browse files
Files changed (1) hide show
  1. README.md +237 -0
README.md ADDED
@@ -0,0 +1,237 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ title: SolverForge Furnace
3
+ emoji: 🔥
4
+ colorFrom: orange
5
+ colorTo: red
6
+ sdk: docker
7
+ app_port: 7860
8
+ pinned: false
9
+ license: apache-2.0
10
+ short_description: SolverForge heat-treatment furnace scheduling example
11
+ ---
12
+
13
+ # SolverForge Furnace
14
+
15
+ ![SolverForge Furnace screenshot](docs/screenshot.png)
16
+
17
+ `solverforge-furnace` is a SolverForge heat-treatment scheduling app with
18
+ retained jobs, a furnace schedule timeline, operator roster views, and a
19
+ browser workspace built on the shared `solverforge-ui` shell.
20
+
21
+ It answers one concrete question:
22
+
23
+ "Given furnaces, work orders, task operators, and a weekly shift roster, when
24
+ should each order run, on which furnace, and which operator performs each
25
+ manual task?"
26
+
27
+ ## Quick Start
28
+
29
+ ```sh
30
+ make run-release
31
+ ```
32
+
33
+ Then open `http://localhost:7860`.
34
+
35
+ To inspect the supported command surface:
36
+
37
+ ```sh
38
+ make help
39
+ ```
40
+
41
+ ## Documentation Map
42
+
43
+ - `README.md`
44
+ Quick start, model concepts, validation, REST API, and solver policy.
45
+ - `WIREFRAME.md`
46
+ As-built architecture and runtime/data flow across backend, runtime, and UI.
47
+ - `AGENTS.md`
48
+ Codex-facing maintenance, validation, and documentation rules.
49
+ - `Makefile`
50
+ Supported local commands for development, validation, Docker, and Space work.
51
+ - `Dockerfile`
52
+ Docker Space image build using Rust 1.95 and the declared crates.io line.
53
+
54
+ ## Current Dependency Shape
55
+
56
+ - Package: `solverforge-furnace`; version is declared in `Cargo.toml`
57
+ - Release binary: `solverforge-furnace`
58
+ - Rust: `1.95`
59
+ - SolverForge runtime: `solverforge` `0.19.4`
60
+ - Browser UI assets: `solverforge-ui` `0.6.5`
61
+ - Scaffold metadata: `solverforge-cli` `2.2.2` in `solverforge.app.toml`
62
+
63
+ The app serves registry-backed Rust dependencies, local static browser modules,
64
+ and Axum API routes from one process.
65
+
66
+ ## Model Concepts
67
+
68
+ - `Furnace`, `WorkOrder`, `Operator`, `Shift`, and `ShiftCoverageDemand` are
69
+ problem facts: input data the solver reads but does not move.
70
+ - `FurnaceAssignment` is a planning entity: one batch decision per work order.
71
+ Its `assignment` variable combines the target furnace and 15-minute start slot
72
+ into a single scalar value, and its four task variables pick the operator for
73
+ load/build, program, quench, and unload.
74
+ - `OperatorShiftAssignment` is a planning entity: one row per operator and
75
+ roster day. Its `shift_type` variable chooses Morning, Afternoon, Night, or
76
+ Off.
77
+ - `Plan` is the planning solution with the current `HardSoftScore`.
78
+
79
+ Time is measured in minutes since Monday 00:00 over a seven-day horizon with a
80
+ 15-minute time step. A batch always moves through a heating ramp followed by a
81
+ soak. Around each batch the app books four manual tasks relative to the batch
82
+ start and end: load/build, program, quench when the process requires it, and
83
+ unload.
84
+
85
+ The app ships one deterministic `STANDARD` dataset with 11 furnaces, 155 work
86
+ orders, 39 operators, 22 shifts, and 44 coverage demands. It starts with every
87
+ order and operator unassigned, so the timeline is empty until the solver runs.
88
+
89
+ ## Constraints
90
+
91
+ Hard constraints:
92
+
93
+ - Every work order must be scheduled.
94
+ - A furnace must support the order process, temperature, and load.
95
+ - A batch must finish inside the seven-day horizon.
96
+ - Batches on the same furnace cannot overlap and must respect the thermal
97
+ changeover gap.
98
+ - Each manual task window must be owned by a single shift.
99
+ - Assigned tasks require a scheduled batch.
100
+ - Every required manual task must receive an operator.
101
+ - The operator must have the task's skill and be rostered on the owning shift.
102
+ - An operator cannot be double-booked across overlapping task windows.
103
+ - Each `(shift, role)` coverage demand must be staffed.
104
+ - Monitoring capacity must cover ramp, soak, and task load in every 15-minute
105
+ bucket.
106
+ - Day-only operators cannot work nights.
107
+ - Consecutive days must respect minimum rest.
108
+ - Operators cannot exceed the weekly visible-shift and consecutive-night limits.
109
+
110
+ Soft constraints:
111
+
112
+ - Express, Urgent, and Standard orders are penalized by lateness with
113
+ priority-weighted cost.
114
+ - Thermal changeover cost is minimized.
115
+ - Early finishing above the due time is mildly penalized.
116
+ - Night starts for non-carburizing/non-nitriding work are discouraged.
117
+ - Overtime above the target weekly shift count is penalized.
118
+ - Working shifts are balanced across operators.
119
+
120
+ ## REST API
121
+
122
+ - `GET /health`
123
+ - `GET /info`
124
+ - `GET /demo-data`
125
+ - `GET /demo-data/{id}`
126
+ - `POST /jobs`
127
+ - `GET /jobs/{id}`
128
+ - `DELETE /jobs/{id}`
129
+ - `GET /jobs/{id}/status`
130
+ - `GET /jobs/{id}/snapshot`
131
+ - `GET /jobs/{id}/analysis`
132
+ - `GET /jobs/{id}/analysis/{constraint_name}`
133
+ - `POST /jobs/{id}/pause`
134
+ - `POST /jobs/{id}/resume`
135
+ - `POST /jobs/{id}/cancel`
136
+ - `GET /jobs/{id}/events`
137
+
138
+ `snapshot_revision={n}` is optional for snapshots and analysis. SSE clients
139
+ receive a bootstrap event and then live retained-job events.
140
+
141
+ ## Solver Policy
142
+
143
+ `solver.toml` is embedded by `Plan` and is the runtime source of truth.
144
+
145
+ - `random_seed = 42` keeps the demo reproducible.
146
+ - Three grouped construction phases assign furnace slots
147
+ (`weakest_fit_decreasing`), the operator roster (`cheapest_insertion`), and
148
+ task operators (`weakest_fit`), each with
149
+ `construction_obligation = "assign_when_candidate_exists"`.
150
+ - A variable-neighborhood-descent local search performs hard repair with
151
+ compound conflict-repair and grouped-scalar selectors.
152
+ - A simulated-annealing polish phase uses `decay_rate = 0.999985`,
153
+ `hard_regression_policy = "never_accept_hard_regression"`, and an
154
+ `accepted_count` forager with `limit = 256`.
155
+ - Solving stops after 45 seconds, or after 12 seconds without improvement.
156
+
157
+ The slow acceptance test expects solving to reach hard feasibility from the
158
+ fully unassigned public instance while soft penalties continue to represent
159
+ schedule quality.
160
+
161
+ ## Validation
162
+
163
+ Standard validation:
164
+
165
+ ```sh
166
+ make test
167
+ ```
168
+
169
+ Full local validation:
170
+
171
+ ```sh
172
+ make ci-local
173
+ ```
174
+
175
+ Slow acceptance solve:
176
+
177
+ ```sh
178
+ make test-slow
179
+ ```
180
+
181
+ `make test` runs Rust tests, frontend syntax checks, and a Playwright browser
182
+ smoke. `make ci-local` adds formatting, clippy, release build, and Docker image
183
+ build. `make pre-release` runs `ci-local` plus the slow acceptance solve.
184
+
185
+ ## Hugging Face Space Deployment
186
+
187
+ This repo is Docker-Space ready. The Space reads the README front matter,
188
+ builds `Dockerfile`, and expects the app to bind `PORT=7860`.
189
+
190
+ Local Space-equivalent commands:
191
+
192
+ ```sh
193
+ make space-build
194
+ make space-run
195
+ ```
196
+
197
+ ## Read The Code In This Order
198
+
199
+ 1. `src/domain/mod.rs`
200
+ The `planning_model!` manifest and public domain exports.
201
+ 2. `src/domain/plan.rs`
202
+ The `Plan` solution, fact collections, and entity collections.
203
+ 3. `src/domain/resources.rs`
204
+ `Furnace`, `WorkOrder`, `Operator`, `Shift`, and `ShiftCoverageDemand`.
205
+ 4. `src/domain/furnace.rs` and `src/domain/coverage.rs`
206
+ The two planning entities and their derived task/roster helpers.
207
+ 5. `src/constraints/mod.rs` and `src/constraints/*.rs`
208
+ The score model, one rule group per file.
209
+ 6. `src/data/data_seed/`
210
+ The deterministic `STANDARD` demo generator.
211
+ 7. `src/solver/service.rs`
212
+ Retained-job orchestration over `SolverManager<Plan>`.
213
+ 8. `src/solver/scalar_groups.rs` and `src/solver/conflict_repair.rs`
214
+ The grouped scalar providers and conflict-directed repair providers that
215
+ `solver.toml` refers to by name.
216
+ 9. `src/api/routes/` and `src/api/dto/`
217
+ HTTP routes, transport DTOs, and live-event streaming.
218
+ 10. `static/app/runtime.js` and `static/app/schedule.js`
219
+ Browser boot sequence, solver controls, and furnace timeline rendering.
220
+
221
+ ## Project Shape
222
+
223
+ - `src/domain/`
224
+ Planning model, domain types, planning variables, and derived indexes.
225
+ - `src/constraints/`
226
+ Incremental SolverForge scoring rules.
227
+ - `src/data/`
228
+ Deterministic heat-treatment demo-data generator.
229
+ - `src/solver/`
230
+ Retained-job facade, scalar-group providers, conflict-repair providers, and
231
+ runtime event payload formatting.
232
+ - `src/api/`
233
+ Axum routes, DTOs, and SSE endpoint.
234
+ - `static/`
235
+ Browser workspace built on stock `solverforge-ui` assets.
236
+ - `Makefile`
237
+ Contains the inline `test-e2e` Playwright smoke for the served app.