dabke 0.78.0 → 0.78.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 This changelog was generated from the git history of the project when it was
 named `scheduling-core`, prior to the rename to `dabke` in v0.78.0.
 
+## 0.78.2 (2026-02-08)
+
+- Fix solver Docker image to support both amd64 and arm64 (Apple Silicon)
+- Fix npm publish by upgrading npm before publish in CI
+
+## 0.78.1 (2026-02-08)
+
+- Add AGENTS.md and CONTRIBUTING.md
+- Improve README with hero example, "Why dabke?" section, solver quickstart, scoping and custom rules docs
+- Improve solver README with Docker Hub image reference and API docs
+- Add GitHub Actions workflow for publishing solver Docker image to Docker Hub
+
 ## 0.78.0 (2026-02-07)
 
 - Rename package from `scheduling-core` to `dabke`

package/README.md

@@ -1,18 +1,56 @@
 # dabke
 
+[![npm version](https://img.shields.io/npm/v/dabke.svg)](https://www.npmjs.com/package/dabke)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/christianklotz/dabke/actions/workflows/ci.yml/badge.svg)](https://github.com/christianklotz/dabke/actions/workflows/ci.yml)
+
 Scheduling library powered by constraint programming (CP-SAT).
 
 Define your team, shifts, coverage, and rules — dabke turns them into an optimized schedule.
 
-## Features
+```typescript
+import { ModelBuilder, HttpSolverClient } from "dabke";
+
+const builder = new ModelBuilder({
+  employees: [
+    { id: "alice", roleIds: ["server"] },
+    { id: "bob", roleIds: ["server"] },
+  ],
+  shiftPatterns: [
+    { id: "morning", startTime: { hours: 8 }, endTime: { hours: 16 } },
+    { id: "evening", startTime: { hours: 16 }, endTime: { hours: 23 } },
+  ],
+  coverage: [
+    { day: "2026-02-09", startTime: { hours: 8 }, endTime: { hours: 16 },
+      roleIds: ["server"], targetCount: 1, priority: "MANDATORY" },
+    { day: "2026-02-09", startTime: { hours: 16 }, endTime: { hours: 23 },
+      roleIds: ["server"], targetCount: 1, priority: "MANDATORY" },
+  ],
+  schedulingPeriod: { specificDates: ["2026-02-09"] },
+  ruleConfigs: [
+    { name: "max-hours-day", config: { hours: 8, priority: "MANDATORY" } },
+    { name: "min-rest-between-shifts", config: { hours: 10, priority: "MANDATORY" } },
+  ],
+});
+
+const { request } = builder.compile();
+const solver = new HttpSolverClient(fetch, "http://localhost:8080");
+const response = await solver.solve(request);
+```
+
+## Why dabke?
 
-- **Declarative scheduling** — describe what you need, not how to solve it
-- **Built-in rules** — max hours, time off, rest periods, consecutive days, and more
-- **Semantic time** — define named time periods ("lunch", "closing") that resolve per day
-- **Soft & hard constraints** — priorities from `LOW` (preference) to `MANDATORY` (hard constraint)
-- **Scoped rules** — apply rules globally, per person, per role, or per skill
-- **Validation** — detailed error reporting with coverage gaps and rule violations
-- **LLM-friendly** — ships `llms.txt` with full API docs for AI code generation
+Staff scheduling with constraint programming is dominated by Python ([OR-Tools](https://developers.google.com/optimization)) and Java ([Timefold](https://timefold.ai/)). If you're building in TypeScript, your options have been: call a Python service and figure out the model yourself, or write scheduling heuristics by hand.
+
+dabke gives you a **TypeScript-native API** for expressing scheduling problems declaratively — employees, shifts, coverage requirements, and rules — and compiles them into a CP-SAT model solved by OR-Tools. You describe _what_ you need, not _how_ to solve it.
+
+**Key differences from rolling your own:**
+
+- **Declarative rules** — express constraints like "max 8 hours/day" or "11 hours rest between shifts" as config, not code
+- **Semantic time** — define named periods ("lunch_rush", "closing") that vary by day of week
+- **Soft and hard constraints** — some rules are mandatory, others are preferences the solver optimizes for
+- **Scoped rules** — apply constraints globally, per person, per role, per skill, or during specific time periods
+- **Validation** — detailed reporting on coverage gaps and rule violations before and after solving
 
 ## Install
 
@@ -22,6 +60,28 @@ npm install dabke
 
 ## Quick Start
 
+### 1. Start the solver
+
+dabke compiles scheduling problems into a constraint model. You need a CP-SAT solver to solve it. A ready-to-use solver is included:
+
+```bash
+# Pull the solver image
+docker pull christianklotz/dabke-solver
+
+# Start it
+docker run -p 8080:8080 christianklotz/dabke-solver
+```
+
+Or build from source:
+
+```bash
+cd node_modules/dabke/solver
+docker build -t dabke-solver .
+docker run -p 8080:8080 dabke-solver
+```
+
+### 2. Build and solve a schedule
+
 ```typescript
 import {
   ModelBuilder,
@@ -34,7 +94,6 @@ import {
 const employees = [
   { id: "alice", roleIds: ["server"] },
   { id: "bob", roleIds: ["server"] },
-  { id: "charlie", roleIds: ["chef"] },
 ];
 
 // Define shift patterns
@@ -49,7 +108,7 @@ const coverage = [
     day: "2026-02-09",
     startTime: { hours: 8 },
     endTime: { hours: 16 },
-    roleIds: ["server"],
+    roleIds: ["server"] as [string],
     targetCount: 1,
     priority: "MANDATORY" as const,
   },
@@ -57,7 +116,7 @@ const coverage = [
     day: "2026-02-09",
     startTime: { hours: 16 },
     endTime: { hours: 23 },
-    roleIds: ["server"],
+    roleIds: ["server"] as [string],
     targetCount: 1,
     priority: "MANDATORY" as const,
   },
@@ -77,10 +136,15 @@ const builder = new ModelBuilder({
   ],
 });
 
-const { request } = builder.compile();
+const { request, canSolve, validation } = builder.compile();
 
-// Solve (requires a CP-SAT solver endpoint)
-const solver = new HttpSolverClient(fetch, "https://your-solver-endpoint");
+if (!canSolve) {
+  console.error("Cannot solve:", validation.errors);
+  process.exit(1);
+}
+
+// Solve
+const solver = new HttpSolverClient(fetch, "http://localhost:8080");
 const response = await solver.solve(request);
 const result = parseSolverResponse(response);
 
@@ -103,8 +167,16 @@ import { defineSemanticTimes } from "dabke";
 
 const times = defineSemanticTimes({
   lunch: [
-    { startTime: { hours: 11, minutes: 30 }, endTime: { hours: 14 }, days: ["monday", "tuesday", "wednesday", "thursday", "friday"] },
-    { startTime: { hours: 12 }, endTime: { hours: 15 }, days: ["saturday", "sunday"] },
+    {
+      startTime: { hours: 11, minutes: 30 },
+      endTime: { hours: 14 },
+      days: ["monday", "tuesday", "wednesday", "thursday", "friday"],
+    },
+    {
+      startTime: { hours: 12 },
+      endTime: { hours: 15 },
+      days: ["saturday", "sunday"],
+    },
   ],
   closing: { startTime: { hours: 21 }, endTime: { hours: 23 } },
 });
@@ -113,6 +185,10 @@ const coverage = times.coverage([
   { semanticTime: "lunch", roleIds: ["server"], targetCount: 3, priority: "MANDATORY" },
   { semanticTime: "closing", roleIds: ["server"], targetCount: 1, priority: "HIGH" },
 ]);
+
+// Resolve against actual scheduling days
+const days = ["2026-02-09", "2026-02-10", "2026-02-11"];
+const resolved = times.resolve(coverage, days);
 ```
 
 ## Built-in Rules
@@ -134,6 +210,43 @@ const coverage = times.coverage([
 
 All rules support scoping by person, role, skill, and time period (date ranges, days of week, recurring periods).
 
+### Scoping Example
+
+```typescript
+// Students can work max 4 hours on weekdays
+{
+  name: "max-hours-day",
+  config: {
+    roleIds: ["student"],
+    hours: 4,
+    dayOfWeek: ["monday", "tuesday", "wednesday", "thursday", "friday"],
+    priority: "MANDATORY",
+  },
+}
+
+// Alice has time off next week
+{
+  name: "time-off",
+  config: {
+    employeeIds: ["alice"],
+    dateRange: { start: "2026-02-09", end: "2026-02-13" },
+    priority: "MANDATORY",
+  },
+}
+```
+
+### Soft vs. Hard Constraints
+
+Rules with `priority: "MANDATORY"` are hard constraints — the solver will not violate them. Rules with `LOW`, `MEDIUM`, or `HIGH` priority are soft constraints — the solver tries to satisfy them but will trade them off against each other to find the best overall schedule.
+
+```typescript
+// Hard: legally required rest period
+{ name: "min-rest-between-shifts", config: { hours: 11, priority: "MANDATORY" } }
+
+// Soft: prefer to keep Bob under 30 hours/week
+{ name: "max-hours-week", config: { employeeIds: ["bob"], hours: 30, weekStartsOn: "monday", priority: "MEDIUM" } }
+```
+
 ## Validation
 
 dabke validates schedules and reports coverage gaps and rule violations:
@@ -162,6 +275,37 @@ for (const s of summaries) {
 }
 ```
 
+## Custom Rules
+
+dabke's rule system is extensible. You can create custom rules that integrate with the model builder:
+
+```typescript
+import { createCpsatRuleFactory, type CompilationRule } from "dabke";
+
+function createNoSundayWorkRule(config: { priority: "MANDATORY" | "HIGH" }): CompilationRule {
+  return {
+    compile(b) {
+      for (const emp of b.employees) {
+        for (const day of b.days) {
+          const date = new Date(`${day}T00:00:00Z`);
+          if (date.getUTCDay() !== 0) continue; // Sunday = 0
+          for (const pattern of b.shiftPatterns) {
+            if (!b.canAssign(emp, pattern)) continue;
+            b.addLinear([{ var: b.assignment(emp.id, pattern.id, day), coeff: 1 }], "<=", 0);
+          }
+        }
+      }
+    },
+  };
+}
+
+const customRules = createCpsatRuleFactory({
+  "no-sunday-work": createNoSundayWorkRule,
+});
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide on writing custom rules.
+
 ## LLM Integration
 
 dabke ships an `llms.txt` file with complete API documentation, designed for AI code generation:
@@ -178,9 +322,23 @@ Or read the file directly:
 cat node_modules/dabke/llms.txt
 ```
 
-## Solver
+## Testing
+
+dabke provides test utilities for running integration tests against the solver:
+
+```typescript
+import { startSolverContainer } from "dabke/testing";
+
+const solver = await startSolverContainer();
+const response = await solver.client.solve(request);
+solver.stop();
+```
+
+This starts a Docker container with the solver, waits for it to be healthy, and provides a pre-configured `HttpSolverClient`.
+
+## Contributing
 
-dabke compiles scheduling problems into a JSON-based constraint model. You need a CP-SAT solver service to solve it. The model format is compatible with Google OR-Tools CP-SAT solver.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, how to add rules, and contribution guidelines.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dabke",
-  "version": "0.78.0",
+  "version": "0.78.2",
   "license": "MIT",
   "description": "Scheduling library powered by constraint programming (CP-SAT)",
   "author": "Christian Klotz <hello@christianklotz.co.uk>",

package/solver/README.md

@@ -1,23 +1,48 @@
-# Scheduler Solver Service
+# dabke solver
 
-Minimal FastAPI service that accepts scheduling primitives (variables, constraints, optional objective) and solves them with OR-Tools CP-SAT.
+Minimal FastAPI service that solves scheduling models with [OR-Tools CP-SAT](https://developers.google.com/optimization/cp/cp_solver).
 
-## Local run
+Receives a JSON constraint model from dabke's `ModelBuilder`, returns optimized assignments.
 
-```sh
-uv sync
-uvicorn solver.app:app --reload --port 8080
+## Quick start (Docker)
+
+```bash
+# Use the published image
+docker pull christianklotz/dabke-solver
+docker run -p 8080:8080 christianklotz/dabke-solver
+
+# Or build from source
+docker build -t dabke-solver .
+docker run -p 8080:8080 dabke-solver
 ```
 
-## Docker
+Then point `HttpSolverClient` at it:
 
-```sh
-docker build -t scheduler-solver .
-docker run -p 8080:8080 scheduler-solver
+```typescript
+import { HttpSolverClient } from "dabke";
+
+const solver = new HttpSolverClient(fetch, "http://localhost:8080");
+```
+
+## Local development
+
+```bash
+uv sync
+uvicorn solver.app:app --reload --port 8080
 ```
 
 ## Tests
 
-```sh
+```bash
 uv run pytest
 ```
+
+## API
+
+### `GET /health`
+
+Returns `{ "status": "ok" }`.
+
+### `POST /solve`
+
+Accepts a solver request JSON body, returns assignments. See dabke's `SolverRequest` type for the schema.