dabke 0.78.0

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "dabke",
+  "version": "0.78.0",
+  "license": "MIT",
+  "description": "Scheduling library powered by constraint programming (CP-SAT)",
+  "author": "Christian Klotz <hello@christianklotz.co.uk>",
+  "homepage": "https://github.com/christianklotz/dabke#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/christianklotz/dabke.git"
+  },
+  "bugs": {
+    "url": "https://github.com/christianklotz/dabke/issues"
+  },
+  "keywords": [
+    "scheduling",
+    "staff-scheduling",
+    "constraint-programming",
+    "cp-sat",
+    "workforce-management",
+    "optimization",
+    "operations-research",
+    "or-tools"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "src",
+    "solver",
+    "llms.txt",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./llms": {
+      "types": "./dist/llms.d.ts",
+      "default": "./dist/llms.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "npm run typecheck && npm run test:unit",
+    "test:unit": "vitest run --project=unit",
+    "test:unit:watch": "vitest --watch --project=unit",
+    "test:integration": "[ -f .env ] && { set -a; source .env; set +a; } && vitest run --project=integration",
+    "test:integration:watch": "[ -f .env ] && { set -a; source .env; set +a; } && vitest --watch --project=integration",
+    "generate:llmstxt": "tsx scripts/generate-llmstxt.ts && oxfmt --write llms.txt src/llms.ts"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "commander": "^14.0.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/solver/Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1
+WORKDIR /app
+
+# Install uv from official image
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
+
+# Copy dependency files first for layer caching
+COPY pyproject.toml uv.lock ./
+
+# Sync dependencies only (skip local package since src/ doesn't exist yet)
+RUN uv sync --frozen --no-dev --no-install-project
+
+# Copy application source
+COPY src/ ./src/
+
+# Install the local package now that source exists
+RUN uv sync --frozen --no-dev
+
+# Use the venv
+ENV PATH="/app/.venv/bin:$PATH"
+
+# Server configuration
+ENV PORT=8080
+EXPOSE 8080
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8080/health')"
+
+CMD ["sh", "-c", "exec uvicorn solver.app:app --host 0.0.0.0 --port ${PORT} --workers 1"]

package/solver/README.md

@@ -0,0 +1,23 @@
+# Scheduler Solver Service
+
+Minimal FastAPI service that accepts scheduling primitives (variables, constraints, optional objective) and solves them with OR-Tools CP-SAT.
+
+## Local run
+
+```sh
+uv sync
+uvicorn solver.app:app --reload --port 8080
+```
+
+## Docker
+
+```sh
+docker build -t scheduler-solver .
+docker run -p 8080:8080 scheduler-solver
+```
+
+## Tests
+
+```sh
+uv run pytest
+```

package/solver/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "scheduler-solver"
+version = "0.1.0"
+description = "CP-SAT solver microservice for scheduling primitives"
+requires-python = ">=3.11,<3.13"
+dependencies = [
+  "fastapi>=0.115.0",
+  "uvicorn[standard]>=0.32.0",
+  "pydantic>=2.10.0",
+  "ortools>=9.15.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.3.3", "httpx>=0.28.1"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = "src"
+
+[dependency-groups]
+dev = ["pytest>=8.3.3", "httpx>=0.28.1"]

package/solver/src/solver/__init__.py

@@ -0,0 +1 @@
+"""Scheduler solver service package."""

package/solver/src/solver/app.py

@@ -0,0 +1,24 @@
+"""FastAPI entrypoint for the solver service."""
+
+from fastapi import FastAPI
+
+from .models import SolverRequest, SolverResponse
+from .solver import solve_request
+
+app = FastAPI(
+    title="Scheduler Solver",
+    description="CP-SAT solver for scheduling primitives",
+    version="0.1.0",
+)
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    """Health probe endpoint."""
+    return {"status": "ok", "service": "scheduler-solver"}
+
+
+@app.post("/solve", response_model=SolverResponse)
+async def solve(request: SolverRequest) -> SolverResponse:
+    """Solve a scheduling model described by primitive constraints."""
+    return solve_request(request)

package/solver/src/solver/models.py

@@ -0,0 +1,120 @@
+"""Pydantic models for solver requests and responses."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class Variable(BaseModel):
+    """Decision variable.
+
+    Supported types:
+    - bool: boolean variable
+    - int: integer variable with bounds
+    - interval: (optional) fixed interval with an absolute start/end and fixed size.
+      When presenceVar is provided, the interval is optional and active iff the
+      boolean presenceVar is true.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["bool", "int", "interval"]
+    name: str
+
+    # int
+    min: int | None = None
+    max: int | None = None
+
+    # interval
+    start: int | None = None
+    end: int | None = None
+    size: int | None = None
+    presenceVar: str | None = None
+
+
+class Term(BaseModel):
+    """Linear term var * coeff."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    var: str
+    coeff: int
+
+
+class Constraint(BaseModel):
+    """Supported constraint primitives."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid")
+
+    type: Literal[
+        "linear",
+        "soft_linear",
+        "exactly_one",
+        "at_most_one",
+        "implication",
+        "bool_or",
+        "bool_and",
+        "no_overlap",
+    ]
+    terms: list[Term] | None = None
+    op: Literal["<=", ">=", "=="] | None = None
+    rhs: int | None = None
+    penalty: int | None = None
+    vars: list[str] | None = None
+    intervals: list[str] | None = None
+    if_: str | None = Field(default=None, alias="if")
+    then: str | None = None
+    id: str | None = None
+
+
+class Objective(BaseModel):
+    """Optional objective definition."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    sense: Literal["minimize", "maximize"]
+    terms: list[Term]
+
+
+class Options(BaseModel):
+    """Solver tuning options."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    timeLimitSeconds: float = 60.0
+    solutionLimit: int | None = None  # Only solutionLimit=1 is supported (stops after first feasible solution)
+
+
+class SolverRequest(BaseModel):
+    """Request payload accepted by the solver service."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    variables: list[Variable]
+    constraints: list[Constraint]
+    objective: Objective | None = None
+    options: Options | None = None
+
+
+class SoftConstraintViolation(BaseModel):
+    """A soft constraint violation in the solver output."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    constraintId: str
+    violationAmount: int
+    targetValue: int
+    actualValue: int
+
+
+class SolverResponse(BaseModel):
+    """Response payload produced by the solver service."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    status: Literal["OPTIMAL", "FEASIBLE", "INFEASIBLE", "TIMEOUT", "ERROR"]
+    values: dict[str, int] | None = None
+    statistics: dict[str, int | float] | None = None
+    error: str | None = None
+    solutionInfo: str | None = None
+    softViolations: list[SoftConstraintViolation] | None = None

package/solver/src/solver/solver.py

@@ -0,0 +1,359 @@
+"""CP-SAT solver translation layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable, Optional
+
+from ortools.sat.python import cp_model
+
+from .models import (
+    Constraint,
+    Objective,
+    Options,
+    SolverRequest,
+    SolverResponse,
+    SoftConstraintViolation,
+    Term,
+    Variable,
+)
+
+
+@dataclass
+class _VariableBounds:
+    """Simple bounds container for quick min/max calculations."""
+
+    lower: int
+    upper: int
+
+
+@dataclass
+class _TrackedSoftConstraint:
+    """Tracks soft constraints with identifiers for post-solve diagnostics."""
+
+    constraint_id: str
+    violation_var: cp_model.IntVar
+    target_value: int
+    comparator: str
+    terms: list[Term]
+
+
+def _collect_bounds(variables: Iterable[Variable]) -> dict[str, _VariableBounds]:
+    bounds: dict[str, _VariableBounds] = {}
+    for var in variables:
+        if var.type == "bool":
+            bounds[var.name] = _VariableBounds(0, 1)
+        elif var.type == "int":
+            if var.min is None or var.max is None:
+                raise ValueError(f"Int variable {var.name} requires min and max")
+            bounds[var.name] = _VariableBounds(var.min, var.max)
+        elif var.type == "interval":
+            # Interval variables are not referenced in linear expressions.
+            continue
+        else:
+            raise ValueError(f"Unknown variable type {var.type}")
+    return bounds
+
+
+def _term_range(term: Term, bounds: _VariableBounds) -> tuple[int, int]:
+    coeff = term.coeff
+    if coeff >= 0:
+        return coeff * bounds.lower, coeff * bounds.upper
+    return coeff * bounds.upper, coeff * bounds.lower
+
+
+def _expression_range(terms: list[Term], bounds: dict[str, _VariableBounds]) -> tuple[int, int]:
+    min_expr = 0
+    max_expr = 0
+    for term in terms:
+        if term.var not in bounds:
+            raise ValueError(f"Unknown variable {term.var}")
+        term_min, term_max = _term_range(term, bounds[term.var])
+        min_expr += term_min
+        max_expr += term_max
+    return min_expr, max_expr
+
+
+def _sum_expr(exprs: list[cp_model.LinearExpr]) -> Optional[cp_model.LinearExpr]:
+    if not exprs:
+        return None
+    total = exprs[0]
+    for expr in exprs[1:]:
+        total += expr
+    return total
+
+
+def _add_linear_constraint(model: cp_model.CpModel, constraint: Constraint, vars_map: dict[str, cp_model.IntVar]) -> None:
+    if not constraint.terms or constraint.op is None or constraint.rhs is None:
+        raise ValueError("Linear constraint requires terms, op, and rhs")
+    expr = sum(vars_map[t.var] * t.coeff for t in constraint.terms)
+    match constraint.op:
+        case "<=":
+            model.Add(expr <= constraint.rhs)
+        case ">=":
+            model.Add(expr >= constraint.rhs)
+        case "==":
+            model.Add(expr == constraint.rhs)
+        case _:
+            raise ValueError(f"Unsupported linear operator {constraint.op}")
+
+
+def _add_soft_linear_constraint(
+    model: cp_model.CpModel,
+    constraint: Constraint,
+    vars_map: dict[str, cp_model.IntVar],
+    bounds: dict[str, _VariableBounds],
+    penalty_terms: list[cp_model.LinearExpr],
+    tracked_constraints: list[_TrackedSoftConstraint],
+    constraint_index: int,
+) -> None:
+    if not constraint.terms or constraint.op is None or constraint.rhs is None or constraint.penalty is None:
+        raise ValueError("Soft linear constraint requires terms, op, rhs, and penalty")
+
+    min_expr, max_expr = _expression_range(constraint.terms, bounds)
+    max_violation = 0
+    violation: cp_model.IntVar | None = None
+    expr = sum(vars_map[t.var] * t.coeff for t in constraint.terms)
+    constraint_id = constraint.id or f"soft_{constraint_index}"
+    match constraint.op:
+        case "<=":
+            max_violation = max(0, max_expr - constraint.rhs)
+            violation = model.NewIntVar(0, max_violation, f"violation_{constraint_id}")
+            model.Add(expr <= constraint.rhs + violation)
+        case ">=":
+            max_violation = max(0, constraint.rhs - min_expr)
+            violation = model.NewIntVar(0, max_violation, f"violation_{constraint_id}")
+            model.Add(expr + violation >= constraint.rhs)
+        case _:
+            raise ValueError(f"Unsupported soft linear operator {constraint.op}")
+
+    if violation is None:
+        raise ValueError("Soft linear constraint failed to create violation variable")
+
+    if max_violation > 0:
+        penalty_terms.append(violation * constraint.penalty)
+        if constraint.id is not None:
+            tracked_constraints.append(
+                _TrackedSoftConstraint(
+                    constraint_id=constraint_id,
+                    violation_var=violation,
+                    target_value=constraint.rhs,
+                    comparator=constraint.op,
+                    terms=constraint.terms,
+                )
+            )
+
+
+def _add_exactly_one(model: cp_model.CpModel, constraint: Constraint, vars_map: dict[str, cp_model.IntVar]) -> None:
+    if not constraint.vars:
+        raise ValueError("Exactly one constraint requires vars")
+    literals = [vars_map[v] for v in constraint.vars]
+    model.AddExactlyOne(literals)
+
+
+def _add_at_most_one(model: cp_model.CpModel, constraint: Constraint, vars_map: dict[str, cp_model.IntVar]) -> None:
+    if not constraint.vars:
+        raise ValueError("At most one constraint requires vars")
+    literals = [vars_map[v] for v in constraint.vars]
+    model.AddAtMostOne(literals)
+
+
+def _add_implication(model: cp_model.CpModel, constraint: Constraint, vars_map: dict[str, cp_model.IntVar]) -> None:
+    if constraint.if_ is None or constraint.then is None:
+        raise ValueError("Implication constraint requires if/then")
+    model.AddImplication(vars_map[constraint.if_], vars_map[constraint.then])
+
+
+def _add_bool_or(model: cp_model.CpModel, constraint: Constraint, vars_map: dict[str, cp_model.IntVar]) -> None:
+    if not constraint.vars:
+        raise ValueError("Bool OR constraint requires vars")
+    literals = [vars_map[v] for v in constraint.vars]
+    model.AddBoolOr(literals)
+
+
+def _add_bool_and(model: cp_model.CpModel, constraint: Constraint, vars_map: dict[str, cp_model.IntVar]) -> None:
+    if not constraint.vars:
+        raise ValueError("Bool AND constraint requires vars")
+    literals = [vars_map[v] for v in constraint.vars]
+    model.AddBoolAnd(literals)
+
+
+def _add_no_overlap(
+    model: cp_model.CpModel,
+    constraint: Constraint,
+    intervals_map: dict[str, cp_model.IntervalVar],
+) -> None:
+    if not constraint.intervals:
+        raise ValueError("NoOverlap constraint requires intervals")
+    intervals = [intervals_map[name] for name in constraint.intervals]
+    model.AddNoOverlap(intervals)
+
+
+def _build_objective(
+    model: cp_model.CpModel,
+    objective: Objective | None,
+    vars_map: dict[str, cp_model.IntVar],
+    penalty_terms: list[cp_model.LinearExpr],
+) -> bool:
+    penalty_expr: cp_model.LinearExpr | None = _sum_expr(penalty_terms)
+
+    if objective:
+        objective_terms: list[cp_model.LinearExpr] = (
+            [vars_map[t.var] * t.coeff for t in objective.terms] if objective.terms else []
+        )
+        obj_expr: cp_model.LinearExpr | None = _sum_expr(objective_terms)
+        if penalty_expr is not None and obj_expr is not None:
+            expr = obj_expr + penalty_expr if objective.sense == "minimize" else obj_expr - penalty_expr
+        elif obj_expr is not None:
+            expr = obj_expr
+        elif penalty_expr is not None:
+            expr = penalty_expr if objective.sense == "minimize" else -penalty_expr
+        else:
+            return False
+
+        if objective.sense == "maximize":
+            model.Maximize(expr)
+        else:
+            model.Minimize(expr)
+        return True
+
+    if penalty_expr is not None:
+        model.Minimize(penalty_expr)
+        return True
+
+    return False
+
+
+def solve_request(request: SolverRequest) -> SolverResponse:
+    """Solve a scheduling request."""
+    try:
+        model = cp_model.CpModel()
+
+        var_bounds = _collect_bounds(request.variables)
+        vars_map: dict[str, cp_model.IntVar] = {}
+        intervals_map: dict[str, cp_model.IntervalVar] = {}
+
+        # Variable creation
+        for var in request.variables:
+            if var.type == "bool":
+                vars_map[var.name] = model.NewBoolVar(var.name)
+            elif var.type == "int":
+                if var.min is None or var.max is None:
+                    raise ValueError(f"Int variable {var.name} requires min and max")
+                vars_map[var.name] = model.NewIntVar(var.min, var.max, var.name)
+            elif var.type == "interval":
+                if var.start is None or var.end is None or var.size is None:
+                    raise ValueError(f"Interval variable {var.name} requires start, end, and size")
+                if var.end - var.start != var.size:
+                    raise ValueError(
+                        f"Interval variable {var.name} inconsistent: end-start={var.end - var.start} != size={var.size}"
+                    )
+
+                start = model.NewConstant(var.start)
+                end = model.NewConstant(var.end)
+                size = var.size
+
+                if var.presenceVar is None:
+                    intervals_map[var.name] = model.NewIntervalVar(start, size, end, var.name)
+                else:
+                    if var.presenceVar not in vars_map:
+                        raise ValueError(
+                            f"Interval variable {var.name} references unknown presenceVar {var.presenceVar}"
+                        )
+                    presence = vars_map[var.presenceVar]
+                    intervals_map[var.name] = model.NewOptionalIntervalVar(start, size, end, presence, var.name)
+            else:
+                raise ValueError(f"Unsupported variable type {var.type}")
+
+        penalty_terms: list[cp_model.LinearExpr] = []
+        tracked_constraints: list[_TrackedSoftConstraint] = []
+        constraint_index = 0
+
+        for constraint in request.constraints:
+            match constraint.type:
+                case "linear":
+                    _add_linear_constraint(model, constraint, vars_map)
+                case "soft_linear":
+                    _add_soft_linear_constraint(
+                        model,
+                        constraint,
+                        vars_map,
+                        var_bounds,
+                        penalty_terms,
+                        tracked_constraints,
+                        constraint_index,
+                    )
+                    constraint_index += 1
+                case "exactly_one":
+                    _add_exactly_one(model, constraint, vars_map)
+                case "at_most_one":
+                    _add_at_most_one(model, constraint, vars_map)
+                case "implication":
+                    _add_implication(model, constraint, vars_map)
+                case "bool_or":
+                    _add_bool_or(model, constraint, vars_map)
+                case "bool_and":
+                    _add_bool_and(model, constraint, vars_map)
+                case "no_overlap":
+                    _add_no_overlap(model, constraint, intervals_map)
+                case _:
+                    raise ValueError(f"Unsupported constraint type {constraint.type}")
+
+        has_objective = _build_objective(model, request.objective, vars_map, penalty_terms)
+
+        solver = cp_model.CpSolver()
+        options: Options = request.options or Options()
+        solver.parameters.max_time_in_seconds = options.timeLimitSeconds
+        if options.solutionLimit == 1:
+            solver.parameters.stop_after_first_solution = True
+
+        status = solver.Solve(model)
+
+        status_map: dict[int, str] = {
+            cp_model.OPTIMAL: "OPTIMAL",
+            cp_model.FEASIBLE: "FEASIBLE",
+            cp_model.INFEASIBLE: "INFEASIBLE",
+            cp_model.MODEL_INVALID: "ERROR",
+            cp_model.UNKNOWN: "TIMEOUT",
+        }
+        status_text = status_map.get(int(status), "ERROR")
+
+        if status not in (cp_model.OPTIMAL, cp_model.FEASIBLE):
+            return SolverResponse(
+                status=status_text,
+                solutionInfo=solver.response_proto.solution_info or None,
+            )
+
+        statistics: dict[str, int | float] = {
+            "solveTimeMs": int(solver.wall_time * 1000),
+            "conflicts": solver.num_conflicts,
+            "branches": solver.num_branches,
+        }
+
+        if has_objective:
+            statistics["objectiveValue"] = solver.objective_value
+            statistics["bestObjectiveBound"] = solver.best_objective_bound
+
+        soft_violations: list[SoftConstraintViolation] = []
+        for tracked in tracked_constraints:
+            violation_amount = int(solver.value(tracked.violation_var))
+            if violation_amount <= 0:
+                continue
+            actual_value = sum(int(solver.value(vars_map[t.var])) * t.coeff for t in tracked.terms)
+            soft_violations.append(
+                SoftConstraintViolation(
+                    constraintId=tracked.constraint_id,
+                    violationAmount=violation_amount,
+                    targetValue=tracked.target_value,
+                    actualValue=actual_value,
+                )
+            )
+
+        return SolverResponse(
+            status=status_text,
+            values={name: int(solver.value(var)) for name, var in vars_map.items()},
+            statistics=statistics,
+            softViolations=soft_violations if soft_violations else None,
+        )
+    except Exception as exc:  # pragma: no cover - surfaced in response
+        return SolverResponse(status="ERROR", error=str(exc))