dabke 0.83.0 → 0.84.0

package/solver/tests/test_solver.py

@@ -1,5 +1,16 @@
-from solver.models import Constraint, Objective, SolverRequest, Term, Variable
-from solver.solver import solve_request
+import pytest
+
+from solver.models import (
+    Constraint,
+    Objective,
+    Options,
+    SolverObjectiveStage,
+    SolverRequest,
+    SolverStageResult,
+    Term,
+    Variable,
+)
+from solver.solver import _aggregate_stage_status, solve_request
 
 
 def test_linear_feasible_solution():
@@ -134,11 +145,11 @@ def test_soft_constraint_reports_violation_when_id_provided():
     response = solve_request(request)
 
     assert response.status == "OPTIMAL"
-    assert response.softViolations is not None
-    assert response.softViolations[0].constraintId == "coverage:test:2024-02-01:540"
-    assert response.softViolations[0].violationAmount == 1
-    assert response.softViolations[0].targetValue == 1
-    assert response.softViolations[0].actualValue == 0
+    assert response.softConstraintViolations is not None
+    assert response.softConstraintViolations[0].constraintId == "coverage:test:2024-02-01:540"
+    assert response.softConstraintViolations[0].violationAmount == 1
+    assert response.softConstraintViolations[0].targetValue == 1
+    assert response.softConstraintViolations[0].actualValue == 0
 
 
 def test_infeasible_solution_reports_solution_info():
@@ -154,3 +165,348 @@ def test_infeasible_solution_reports_solution_info():
 
     assert response.status == "INFEASIBLE"
     assert response.solutionInfo is not None
+
+
+def test_infeasible_solution_reports_tracked_constraint_ids():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        options=Options(diagnostics="hard"),
+        constraints=[
+            Constraint(
+                type="linear",
+                terms=[Term(var="x", coeff=1)],
+                op="==",
+                rhs=0,
+                id="must-be-zero",
+            ),
+            Constraint(
+                type="linear",
+                terms=[Term(var="x", coeff=1)],
+                op="==",
+                rhs=1,
+                id="must-be-one",
+            ),
+        ],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "INFEASIBLE"
+    assert response.hardConstraintConflicts is not None
+    assert {conflict.constraintId for conflict in response.hardConstraintConflicts} == {
+        "must-be-zero",
+        "must-be-one",
+    }
+
+
+def test_infeasible_solution_omits_hard_conflicts_by_default():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(type="linear", terms=[Term(var="x", coeff=1)], op="==", rhs=0, id="zero"),
+            Constraint(type="linear", terms=[Term(var="x", coeff=1)], op="==", rhs=1, id="one"),
+        ],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "INFEASIBLE"
+    assert response.hardConstraintConflicts is None
+
+
+def test_lexicographic_minimization_freezes_stage_1_before_stage_2():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[],
+        objectiveStages=[
+            SolverObjectiveStage(id="minimize-x", sense="minimize", terms=[Term(var="x", coeff=1)]),
+            SolverObjectiveStage(id="maximize-x", sense="maximize", terms=[Term(var="x", coeff=1)]),
+        ],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "OPTIMAL"
+    assert response.values == {"x": 0}
+    assert response.stageResults is not None
+    assert [stage.id for stage in response.stageResults] == ["minimize-x", "maximize-x"]
+    assert [stage.objectiveValue for stage in response.stageResults] == [0, 0]
+
+
+def test_lexicographic_maximization_freezes_stage_1_before_stage_2():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[],
+        objectiveStages=[
+            SolverObjectiveStage(id="maximize-x", sense="maximize", terms=[Term(var="x", coeff=1)]),
+            SolverObjectiveStage(id="minimize-x", sense="minimize", terms=[Term(var="x", coeff=1)]),
+        ],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "OPTIMAL"
+    assert response.values == {"x": 1}
+    assert response.stageResults is not None
+    assert [stage.objectiveValue for stage in response.stageResults] == [1, 1]
+
+
+def test_staged_soft_linear_slack_belongs_to_declared_stage():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(
+                type="soft_linear",
+                terms=[Term(var="x", coeff=1)],
+                op=">=",
+                rhs=1,
+                penalty=10,
+                id="want-x",
+                stage="first",
+            ),
+            Constraint(
+                type="soft_linear",
+                terms=[Term(var="x", coeff=1)],
+                op="<=",
+                rhs=0,
+                penalty=100,
+                id="avoid-x",
+                stage="second",
+            ),
+        ],
+        objectiveStages=[
+            SolverObjectiveStage(id="first", sense="minimize", terms=[]),
+            SolverObjectiveStage(id="second", sense="minimize", terms=[]),
+        ],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "OPTIMAL"
+    assert response.values == {"x": 1}
+    assert response.stageResults is not None
+    assert [stage.objectiveValue for stage in response.stageResults] == [0, 100]
+    assert response.softConstraintViolations is not None
+    assert [violation.constraintId for violation in response.softConstraintViolations] == ["avoid-x"]
+
+
+def test_unknown_soft_stage_is_rejected():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(
+                type="soft_linear",
+                terms=[Term(var="x", coeff=1)],
+                op="<=",
+                rhs=0,
+                penalty=1,
+                stage="missing",
+            )
+        ],
+        objectiveStages=[SolverObjectiveStage(id="known", sense="minimize", terms=[Term(var="x", coeff=1)])],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "ERROR"
+    assert response.error is not None
+    assert "not declared" in response.error
+
+
+def test_missing_soft_stage_is_rejected_in_staged_mode():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(
+                type="soft_linear",
+                terms=[Term(var="x", coeff=1)],
+                op="<=",
+                rhs=0,
+                penalty=1,
+            )
+        ],
+        objectiveStages=[SolverObjectiveStage(id="known", sense="minimize", terms=[Term(var="x", coeff=1)])],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "ERROR"
+    assert response.error is not None
+    assert "requires stage" in response.error
+
+
+def test_objective_and_objective_stages_are_rejected():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[],
+        objective=Objective(sense="minimize", terms=[Term(var="x", coeff=1)]),
+        objectiveStages=[SolverObjectiveStage(id="stage", sense="minimize", terms=[Term(var="x", coeff=1)])],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "ERROR"
+    assert response.error is not None
+    assert "cannot both be present" in response.error
+
+
+def test_satisfy_mode_ignores_soft_penalties_and_returns_hard_feasible_solution():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(type="linear", terms=[Term(var="x", coeff=1)], op="==", rhs=1),
+            Constraint(
+                type="soft_linear",
+                terms=[Term(var="x", coeff=1)],
+                op="<=",
+                rhs=0,
+                penalty=100,
+                id="prefer-zero",
+            ),
+        ],
+        mode="satisfy",
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "OPTIMAL"
+    assert response.values == {"x": 1}
+    assert response.softConstraintViolations == []
+    assert response.statistics is not None
+    assert "objectiveValue" not in response.statistics
+
+
+def test_satisfy_mode_validates_soft_constraints_with_unknown_variables():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(
+                type="soft_linear",
+                terms=[Term(var="missing", coeff=1)],
+                op="<=",
+                rhs=0,
+                penalty=100,
+            ),
+        ],
+        mode="satisfy",
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "ERROR"
+    assert response.error is not None
+    assert "Unknown variable missing" in response.error
+
+
+def test_satisfy_mode_validates_soft_constraint_required_fields():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(
+                type="soft_linear",
+                terms=[Term(var="x", coeff=1)],
+                op="<=",
+                rhs=0,
+            ),
+        ],
+        mode="satisfy",
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "ERROR"
+    assert response.error is not None
+    assert "requires terms, op, rhs, and penalty" in response.error
+
+
+def test_objective_stages_with_solution_limit_one_is_rejected():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[],
+        objectiveStages=[SolverObjectiveStage(id="stage", sense="minimize", terms=[Term(var="x", coeff=1)])],
+        options=Options(solutionLimit=1),
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "ERROR"
+    assert response.error is not None
+    assert "solutionLimit=1" in response.error
+
+
+def test_stage_metadata_is_returned():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[],
+        objectiveStages=[SolverObjectiveStage(id="stage", sense="minimize", terms=[Term(var="x", coeff=1)])],
+    )
+
+    response = solve_request(request)
+
+    assert response.stageResults is not None
+    assert len(response.stageResults) == 1
+    stage_result = response.stageResults[0]
+    assert stage_result.id == "stage"
+    assert stage_result.status == "OPTIMAL"
+    assert stage_result.objectiveValue == 0
+    assert stage_result.bestObjectiveBound == 0
+    assert stage_result.solveTimeMs >= 0
+
+
+def test_staged_failure_omits_values_when_no_stage_has_succeeded():
+    request = SolverRequest(
+        variables=[Variable(type="bool", name="x")],
+        constraints=[
+            Constraint(type="linear", terms=[Term(var="x", coeff=1)], op="==", rhs=0),
+            Constraint(type="linear", terms=[Term(var="x", coeff=1)], op="==", rhs=1),
+        ],
+        objectiveStages=[SolverObjectiveStage(id="stage", sense="minimize", terms=[Term(var="x", coeff=1)])],
+    )
+
+    response = solve_request(request)
+
+    assert response.status == "INFEASIBLE"
+    assert response.values is None
+    assert "values" not in response.model_dump(exclude_unset=True)
+
+
+def test_aggregate_stage_status_returns_optimal_when_all_stages_are_optimal():
+    stage_results = [
+        SolverStageResult(id="stage-1", status="OPTIMAL", solveTimeMs=1),
+        SolverStageResult(id="stage-2", status="OPTIMAL", solveTimeMs=1),
+    ]
+
+    assert _aggregate_stage_status(stage_results) == "OPTIMAL"
+
+
+def test_aggregate_stage_status_downgrades_when_later_stage_is_feasible():
+    stage_results = [
+        SolverStageResult(id="stage-1", status="OPTIMAL", solveTimeMs=1),
+        SolverStageResult(id="stage-2", status="FEASIBLE", solveTimeMs=1),
+    ]
+
+    assert _aggregate_stage_status(stage_results) == "FEASIBLE"
+
+
+def test_aggregate_stage_status_downgrades_when_earlier_stage_is_feasible():
+    stage_results = [
+        SolverStageResult(id="stage-1", status="FEASIBLE", solveTimeMs=1),
+        SolverStageResult(id="stage-2", status="OPTIMAL", solveTimeMs=1),
+    ]
+
+    assert _aggregate_stage_status(stage_results) == "FEASIBLE"
+
+
+def test_aggregate_stage_status_returns_first_terminal_status():
+    stage_results = [
+        SolverStageResult(id="stage-1", status="OPTIMAL", solveTimeMs=1),
+        SolverStageResult(id="stage-2", status="TIMEOUT", solveTimeMs=1),
+        SolverStageResult(id="stage-3", status="ERROR", solveTimeMs=1),
+    ]
+
+    assert _aggregate_stage_status(stage_results) == "TIMEOUT"
+
+
+def test_aggregate_stage_status_rejects_empty_stage_results():
+    with pytest.raises(ValueError, match="empty stage results"):
+        _aggregate_stage_status([])

package/src/client.schemas.ts

@@ -55,6 +55,7 @@ export const LinearConstraintSchema = z.object({
   terms: z.array(SolverTermSchema),
   op: z.union([z.literal("<="), z.literal(">="), z.literal("==")]),
   rhs: z.number(),
+  id: z.string().optional(),
 });
 
 export const SoftLinearConstraintSchema = z.object({
@@ -64,6 +65,7 @@ export const SoftLinearConstraintSchema = z.object({
   rhs: z.number(),
   penalty: z.number(),
   id: z.string().optional(),
+  stage: z.string().optional(),
 });
 
 export const ExactlyOneConstraintSchema = z.object({
@@ -118,6 +120,13 @@ export const SolverObjectiveSchema = z.object({
   terms: z.array(SolverTermSchema),
 });
 
+export const SolverObjectiveStageSchema = SolverObjectiveSchema.extend({
+  id: z.string(),
+});
+
+export const SolverModeSchema = z.enum(["optimize", "satisfy"]);
+export const SolverDiagnosticModeSchema = z.enum(["none", "hard"]);
+
 // --------------------------------------------------------------------------
 // Options schema
 // --------------------------------------------------------------------------
@@ -125,20 +134,109 @@ export const SolverObjectiveSchema = z.object({
 export const SolverOptionsSchema = z.object({
   timeLimitSeconds: z.number().optional(),
   solutionLimit: z.number().optional(),
+  diagnostics: SolverDiagnosticModeSchema.optional(),
 });
 
 // --------------------------------------------------------------------------
 // Request/Response schemas
 // --------------------------------------------------------------------------
 
-export const SolverRequestSchema = z.object({
-  variables: z.array(SolverVariableSchema),
-  constraints: z.array(SolverConstraintSchema),
-  objective: SolverObjectiveSchema.optional(),
-  options: SolverOptionsSchema.optional(),
+export const SolverStatusSchema = z.enum(["OPTIMAL", "FEASIBLE", "INFEASIBLE", "TIMEOUT", "ERROR"]);
+
+export const SolverStageResultSchema = z.object({
+  id: z.string(),
+  status: SolverStatusSchema,
+  objectiveValue: z.number().optional(),
+  bestObjectiveBound: z.number().optional(),
+  solveTimeMs: z.number(),
 });
 
-export const SolverStatusSchema = z.enum(["OPTIMAL", "FEASIBLE", "INFEASIBLE", "TIMEOUT", "ERROR"]);
+export const SolverRequestSchema = z
+  .object({
+    variables: z.array(SolverVariableSchema),
+    constraints: z.array(SolverConstraintSchema),
+    objective: SolverObjectiveSchema.optional(),
+    objectiveStages: z.array(SolverObjectiveStageSchema).optional(),
+    mode: SolverModeSchema.optional(),
+    options: SolverOptionsSchema.optional(),
+  })
+  .superRefine((request, ctx) => {
+    if (request.objective && request.objectiveStages) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["objectiveStages"],
+        message: "objective and objectiveStages cannot both be present",
+      });
+    }
+
+    if (request.objectiveStages !== undefined) {
+      if (request.objectiveStages.length === 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["objectiveStages"],
+          message: "objectiveStages cannot be empty",
+        });
+      }
+
+      const seenStageIds = new Set<string>();
+      for (const [index, stage] of request.objectiveStages.entries()) {
+        if (seenStageIds.has(stage.id)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["objectiveStages", index, "id"],
+            message: `Duplicate objective stage id ${stage.id}`,
+          });
+        }
+        seenStageIds.add(stage.id);
+      }
+
+      if (request.options?.solutionLimit === 1) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["options", "solutionLimit"],
+          message: "objectiveStages cannot be used with solutionLimit=1",
+        });
+      }
+
+      for (const [index, constraint] of request.constraints.entries()) {
+        if (constraint.type !== "soft_linear") continue;
+
+        if (constraint.stage === undefined) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["constraints", index, "stage"],
+            message: "Soft linear constraint requires stage when objectiveStages are used",
+          });
+          continue;
+        }
+
+        if (!seenStageIds.has(constraint.stage)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["constraints", index, "stage"],
+            message: `Soft linear constraint stage ${constraint.stage} is not declared`,
+          });
+        }
+      }
+    }
+
+    if (request.mode === "satisfy") {
+      if (request.objective) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["objective"],
+          message: 'mode "satisfy" cannot be used with objective',
+        });
+      }
+      if (request.objectiveStages) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["objectiveStages"],
+          message: 'mode "satisfy" cannot be used with objectiveStages',
+        });
+      }
+    }
+  });
 
 export const SolverStatisticsSchema = z.object({
   solveTimeMs: z.number().optional(),
@@ -146,18 +244,37 @@ export const SolverStatisticsSchema = z.object({
   branches: z.number().optional(),
 });
 
-export const SoftConstraintViolationSchema = z.object({
+export const SolverSoftConstraintViolationSchema = z.object({
   constraintId: z.string(),
   violationAmount: z.number(),
   targetValue: z.number(),
   actualValue: z.number(),
 });
 
-export const SolverResponseSchema = z.object({
-  status: SolverStatusSchema,
+export const SolverHardConstraintConflictSchema = z.object({
+  constraintId: z.string(),
+});
+
+const SolverResponseBaseSchema = z.object({
   values: z.record(z.string(), z.number()).optional(),
   statistics: SolverStatisticsSchema.optional(),
   error: z.string().optional(),
   solutionInfo: z.string().optional(),
-  softViolations: z.array(SoftConstraintViolationSchema).optional(),
+  hardConstraintConflicts: z.array(SolverHardConstraintConflictSchema).optional(),
+  stageResults: z.array(SolverStageResultSchema).optional(),
 });
+
+const SuccessfulSolverResponseSchema = SolverResponseBaseSchema.extend({
+  status: z.union([z.literal("OPTIMAL"), z.literal("FEASIBLE")]),
+  softConstraintViolations: z.array(SolverSoftConstraintViolationSchema),
+});
+
+const NonSuccessfulSolverResponseSchema = SolverResponseBaseSchema.extend({
+  status: z.union([z.literal("INFEASIBLE"), z.literal("TIMEOUT"), z.literal("ERROR")]),
+  softConstraintViolations: z.array(SolverSoftConstraintViolationSchema).optional(),
+});
+
+export const SolverResponseSchema = z.union([
+  SuccessfulSolverResponseSchema,
+  NonSuccessfulSolverResponseSchema,
+]);

package/src/client.ts

@@ -9,6 +9,9 @@ export type {
   SolverConstraint,
   SolverTerm,
   SolverObjective,
+  SolverObjectiveStage,
+  SolverMode,
+  SolverStageResult,
   FetcherLike,
 } from "./client.types.js";