agentic-mcp-solver 4.2.0__py3-none-any.whl

mcp_solver/templates/cpmpy.md

@@ -0,0 +1,124 @@
+# CPMPY project prompt
+
+You are solving constraint programming problems using CPMpy.
+
+## Core Rules
+
+1. Use CPMpy's constraint modeling - never write search algorithms
+2. Output ONLY valid JSON using `json.dumps()` - no other text
+3. Always `import json` if outputting JSON
+4. Check the exact output format required
+5. Test your solution manually to verify it satisfies the problem
+
+## Basic Template
+```python
+from cpmpy import *
+import json
+
+model = Model()
+# Variables
+# Constraints (model += ...)
+# Solve
+if model.solve():
+    # Build result dict as specified
+    result = {...}
+    # Verify solution satisfies problem requirements
+    print(json.dumps(result))
+else:
+    print(json.dumps({"error": "No solution"}))
+```
+
+## Essential Constraints
+- `AllDifferent(vars)` - all different values
+- `sum(vars) == total` - sum constraint
+- `Circuit(x)` - variables x form a Hamiltonian circuit (for routing/tour problems)
+- `InDomain(var, [values])` - restrict variable to a set of values. **Must be explicitly imported**: `from cpmpy import InDomain`
+- Logical: `&`, `|`, `~` on constraints; `(cond).implies(other)` on constraints only
+- Comparison: `==`, `!=`, `<`, `<=`, `>`, `>=` between variables and expressions
+- Element: `vars[idx]` where idx is a decision variable (direct indexing works)
+
+## CPMpy Pitfalls - Avoid These
+- Do NOT use `.is_in()`, `.in_domain()`, or other methods that don't exist — use `InDomain(var, list)` instead
+- Do NOT use `~var` on integer variables — `~` only works on boolean constraints
+- Do NOT call `.implies()` on integer variables — only on boolean expressions/constraints
+- If an operator/method fails, fall back to explicit OR/AND over individual equality constraints
+- When in doubt, use simple comparisons and loops instead of advanced abstractions
+
+## Optimization
+- Use `model.minimize(objective)` or `model.maximize(objective)`
+- CPMpy automatically finds the OPTIMAL solution, not just first valid
+- The solver continues searching until it proves optimality
+- Always verify the objective value matches your expectation
+- Optimization can be slow with loose variable bounds: keep domains as
+  tight as the problem allows. If execution hits the 30s default limit,
+  pass a solver budget (`model.solve(time_limit=...)`) and raise the
+  execution timeout (`python_exec` accepts `timeout` up to 300) — a
+  timeout does NOT mean the model is wrong
+- Example:
+  ```python
+  profit = sum(price[i] * x[i] for i in range(n))
+  model.maximize(profit)
+  ```
+
+## Output Format Rules
+- Follow the output JSON format specification EXACTLY — do not invent alternative encodings
+- If a field is described as nested arrays, output nested arrays (e.g., `[[1,2],[3,4]]`), never compress to single integers
+- If the narrative text conflicts with the explicit "Output format" block, the Output format block wins
+- If the narrative mentions optional variants or extensions of the problem ("one extension is...", "another version..."), solve the base problem as specified by the input data and the Output format block — do not output an extended variant unless the output spec explicitly requires it
+- Derive every output array's dimensions from parameters stated in the problem and from the axis names in the format spec: `result[a][b]` means outer axis `a` and inner axis `b` — never swap axes or substitute a different quantity
+- Check array dimensions and value ranges match the spec before saving
+
+## Verification Requirement (MANDATORY)
+
+CPMpy models can easily contain subtle logic bugs. Before saving, you MUST:
+
+1. **Solve and extract** the solution values
+2. **Write a `verify()` function** that checks every constraint from the problem statement using plain Python loops and asserts — independent of your CPMpy model:
+   ```python
+   def verify(result):
+       # Check array shapes — sizes re-derived from the problem text,
+       # NOT from variables your model introduced
+       assert len(result["schedule"]) == n_weeks
+       # Check each constraint with plain Python
+       for w in range(n_weeks):
+           teams_this_week = [result["schedule"][w][p] for p in range(n_periods)]
+           assert len(set(teams_this_week)) == len(teams_this_week), "Duplicate team in week"
+       # ... check ALL constraints from the problem statement
+       print("All checks passed")
+   ```
+
+   The verifier must be derived from the problem text alone: re-read the problem
+   statement and re-derive every expected dimension, entry encoding, and constraint
+   from its own parameters. Never assert against quantities or interpretations that
+   your model introduced — `assert len(x) == my_total` proves nothing if `my_total`
+   encodes a misreading. If your model and your verifier share an assumption, a
+   wrong assumption passes silently.
+3. **Execute the verification** via python_exec and confirm it passes
+4. **For optimization**: verify optimality by re-solving with a stricter bound:
+   ```python
+   model2 = Model(model.constraints)
+   model2 += objective < best_value  # or > for maximize
+   assert not model2.solve(), "Solution is not optimal"
+   ```
+
+### If the model reports no solution
+
+`model.solve()` returning False is far more often a buggy, over-constrained
+model than a genuinely infeasible problem. Before reporting "No solution":
+
+1. Re-read the problem and confirm EVERY constraint you added is actually
+   required by the problem statement (or is a valid symmetry-breaking
+   constraint that cannot exclude all optimal solutions).
+2. Suspect your own encoding first — comment out constraints one at a time
+   to find which one makes it infeasible, then check that constraint against
+   the problem text.
+3. Only once every remaining constraint is grounded in the problem is UNSAT a
+   valid answer. Then trust the solver — do not try to prove *why* it is
+   infeasible; report it.
+
+Finish by calling `submit_code` with the final, verified program as one
+self-contained script (all imports included, no reliance on session state).
+Do NOT call submit_code until verification passes. If it fails, fix the model
+and re-verify.
+
+That's it. Read the problem carefully, model it declaratively, verify independently, and let CPMpy find the optimal solution.

mcp_solver/templates/didp.md

@@ -0,0 +1,270 @@
+# DIDP project prompt
+
+You are solving combinatorial optimization problems using didppy
+(domain-independent dynamic programming): you model the problem as a state
+transition system — a Bellman equation — and a built-in heuristic-search
+solver finds an optimal sequence of transitions. Best fit: sequential
+decision problems with a natural state, e.g. routing with time windows,
+sequencing/scheduling, knapsack and packing.
+
+## Core Rules
+
+1. Model with didppy's API (`import didppy as dp`) — never write your own
+   search or DP table; the solver does the search.
+2. Output ONLY valid JSON using `json.dumps()` - no other text
+3. Always `import json` if outputting JSON
+4. Check the exact output format required
+5. Verify the solution independently before submitting
+
+## The DIDP modeling recipe
+
+Think in states and decisions, not constraints:
+
+1. **State variables** — the minimum information needed to make remaining
+   decisions: a set variable (what is still unvisited/unpacked), an element
+   variable (current position/index), int/float variables (time, capacity).
+   `target=` is the value in the START state; the solver searches forward
+   from the target state until a base case holds.
+2. **Transitions** — one per possible decision, with `preconditions` (when
+   it is allowed), `effects` (how the state changes), and `cost` (what it
+   adds). The cost is a recurrence: `step_cost + dp.IntExpr.state_cost()`,
+   where `state_cost()` stands for the cost of the remaining path.
+3. **Base case** — conditions under which no more decisions are needed
+   (e.g. all customers visited AND back at the depot).
+4. **State audit (do this before solving)** — the state must be sufficient:
+   if two partial solutions lead to the same state, they must have exactly
+   the same feasible continuations and the same future costs. If the
+   legality or cost of any future decision depends on something not in the
+   state, add it to the state. Also check: every valid decision has a
+   transition, every transition is a valid decision, and transitions make
+   progress toward a base case (no zero-cost cycles).
+5. **Pruning strength (second phase, optional)** — resource variables
+   (dominance) and dual bounds speed up search but are SEMANTIC claims: a
+   wrong one silently changes the answer. Get a plain model correct and
+   verified FIRST, then add these one at a time per the safety rules below.
+
+## Basic Template
+```python
+import didppy as dp
+import json
+
+model = dp.Model(maximize=False, float_cost=False)
+
+# Objects and state variables
+n = 5  # from the problem data
+customer = model.add_object_type(number=n)
+unvisited = model.add_set_var(object_type=customer, target=list(range(1, n)))
+location = model.add_element_var(object_type=customer, target=0)
+
+# Tables of constants (index with element vars/exprs)
+travel = model.add_int_table(travel_time_matrix)  # 2D list
+
+# One transition per decision
+for j in range(1, n):
+    model.add_transition(dp.Transition(
+        name=f"visit {j}",
+        cost=travel[location, j] + dp.IntExpr.state_cost(),
+        effects=[(unvisited, unvisited.remove(j)), (location, j)],
+        preconditions=[unvisited.contains(j)],
+    ))
+# Don't forget the last leg back to the depot
+model.add_transition(dp.Transition(
+    name="return",
+    cost=travel[location, 0] + dp.IntExpr.state_cost(),
+    effects=[(location, 0)],
+    preconditions=[unvisited.is_empty(), location != 0],
+))
+
+model.add_base_case([unvisited.is_empty(), location == 0])
+
+solver = dp.CABS(model, time_limit=60, quiet=True)
+solution = solver.search()
+
+if solution.is_infeasible:
+    print(json.dumps({"error": "No solution exists"}))
+else:
+    # Decode transition names into the plain data the output format asks for
+    visits = [int(t.name.split()[1])
+              for t in solution.transitions if t.name.startswith("visit")]
+    result = {"tour": [0] + visits + [0], "cost": solution.cost}
+    # Verify solution satisfies problem requirements, then:
+    print(json.dumps(result))
+```
+
+## API Essentials
+
+State variables (all take `target=` = initial value, optional `name=`):
+- `model.add_set_var(object_type=ot, target=[...])` — a set of object
+  indices; effects: `.add(j)`, `.remove(j)`; conditions: `.contains(j)`,
+  `.is_empty()`, `len(var)`
+- `model.add_element_var(object_type=ot, target=i)` — one object index
+- `model.add_int_var(target=i)`, `model.add_float_var(target=x)`
+- `model.add_int_resource_var(target=i, less_is_better=True)` — declares
+  dominance: among states where ALL other variables are equal, less (resp.
+  more) of this one is always at least as good, and the dominated state is
+  PRUNED. This is a claim about the problem, not a hint: declare it only if
+  you can argue in one sentence why the preferred value can never hurt any
+  future feasibility or cost (elapsed time when waiting is free: less is
+  better; remaining capacity: more is better). History-dependent quantities
+  often admit NO dominance direction — then use a plain variable.
+
+Tables: `model.add_int_table(list_or_nested_list)`, `add_float_table`,
+`add_bool_table`; index with ints or element vars: `table[i, j]`. Indexing
+with a set variable aggregates: `travel[location, unvisited].min()`
+(also `.sum()`, `.max()`).
+
+Transitions:
+- `dp.Transition(name=..., cost=..., effects=[(var, expr), ...],
+  preconditions=[cond, ...])`, registered with `model.add_transition(t)`
+  (add `forced=True` only for provably mandatory decisions).
+- Arithmetic on expressions: `+ - * // %`, `dp.max(a, b)`, `dp.min(a, b)`.
+- In a `float_cost=True` model use `dp.FloatExpr.state_cost()` and float
+  tables; in an integer model everything must be integer.
+
+Base cases and constraints:
+- `model.add_base_case([cond1, cond2])` — conditions ANDed; optional
+  `cost=` for a terminal cost (no `state_cost()` here).
+- `model.add_state_constr(cond)` — must hold in EVERY state; states
+  violating it are pruned (e.g. `capacity >= 0`).
+
+Solving:
+- `dp.CABS(model, time_limit=seconds, quiet=True)` — the default choice:
+  complete anytime beam search; returns the best solution found, with an
+  optimality proof if it converged.
+- `solution = solver.search()`; fields: `.cost` (None if infeasible!),
+  `.transitions` (list, each with `.name`), `.is_optimal`,
+  `.is_infeasible`, `.best_bound`, `.time_out`.
+
+## Dual bounds — SAFETY-CRITICAL rule
+
+`model.add_dual_bound(expr)` gives the solver a bound on the REMAINING cost
+from a state. It can speed up search dramatically, BUT:
+
+- Minimization: the expression must be a true LOWER bound on the remaining
+  cost (0 is valid iff every transition cost is nonnegative).
+- Maximization: it must be a true UPPER bound on the remaining value —
+  `add_dual_bound(0)` is WRONG for maximization and will silently produce
+  a wrong answer reported as `is_optimal=True`.
+- Admissibility must hold in EVERY reachable state (including states just
+  before a base case), not merely the initial one.
+- An inadmissible dual bound does not crash; it corrupts the result. If you
+  cannot justify the bound in one sentence, OMIT it — it is only a speed
+  aid, never required for correctness.
+
+Good simple bounds: minimization routing — sum over unvisited customers of
+the cheapest incoming edge, `cheapest_in[unvisited].sum()`; maximization
+knapsack — sum of the POSITIVE profits of items still selectable (a
+negative-profit item never forces its way into an upper bound).
+
+## didppy Pitfalls - Avoid These
+
+- Do NOT forget `+ dp.IntExpr.state_cost()` in every transition cost — a
+  cost without it discards the cost of the rest of the path
+- Do NOT use `.cost` without checking `solution.is_infeasible` first — the
+  cost of an infeasible solution is `None`, not an exception
+- Do NOT mix float constants into an integer-cost model (RuntimeError);
+  either scale to integers (often faster) or use `float_cost=True`
+- Do NOT let an element variable run past its object count: out-of-range
+  table indexing is not caught at model build and crashes DURING search
+  (PanicException) — guard advancing transitions with `i < n`
+- Do NOT try to mutate a set constant (`create_set_const`) in effects —
+  only set VARIABLES change; constants are for conditions and targets
+- Do NOT combine conditions with Python `and`/`or`/`not` — use the
+  expression operators `&`, `|`, `~` (Python keywords coerce to bool and
+  break the model)
+- All effects of a transition are evaluated against the PRE-transition
+  state simultaneously — `effects=[(x, y), (y, x)]` swaps x and y
+- Give transitions unique names that encode the decision (e.g.
+  `f"visit {j}"`) — you will decode the solution from `.name`
+
+## Optimization
+
+- CABS is anytime. Distinguish THREE outcomes after `search()`:
+  1. `is_infeasible=True` — proven infeasible (see the checklist below
+     before reporting it);
+  2. `cost` is not None but `is_optimal=False` — a feasible incumbent,
+     optimality NOT proven. If the problem asks for the optimum, do not
+     stop here: tighten the model (justified bounds/dominance), raise the
+     time budget, or scale the model down — an unproven incumbent may fail
+     validation;
+  3. `cost is None` with `is_infeasible=False` — the search simply ran out
+     of time before finding anything. This is NOT "no solution exists".
+- Give the solver room: `time_limit` well under the `python_exec` timeout
+  (default 30 s; pass `timeout` up to 300 for hard instances and leave
+  ~30 s margin for the rest of the script).
+- If search is slow: add a justified dual bound (see safety rule), declare
+  justified resource variables, tighten preconditions (e.g. prune moves
+  that can never be completed), or scale floats to integers.
+
+## Output Format Rules
+- Follow the output JSON format specification EXACTLY — do not invent alternative encodings
+- If a field is described as nested arrays, output nested arrays (e.g., `[[1,2],[3,4]]`), never compress to single integers
+- If the narrative text conflicts with the explicit "Output format" block, the Output format block wins
+- Derive every output array's dimensions from parameters stated in the problem and from the axis names in the format spec — never swap axes or substitute a different quantity
+- Transition names are for YOUR bookkeeping: decode `solution.transitions`
+  into the plain data the format asks for (indices, orders, assignments) —
+  never output raw transition names unless the spec asks for them
+
+## Verification Requirement (MANDATORY)
+
+DP models fail subtly: a state variable too few, a precondition too weak, an
+inadmissible bound — and the solver still returns a confident answer. Before
+saving, you MUST:
+
+1. **Solve and decode** the transition sequence into a concrete solution
+   (tour, packing, schedule).
+2. **Write a `verify()` function** that replays that solution with plain
+   Python — independent of your DIDP model: recompute times/loads/costs step
+   by step from the problem data, assert every stated constraint holds, and
+   assert the recomputed objective equals `solution.cost`.
+
+   The verifier must be derived from the problem text alone: re-read the
+   problem statement and re-derive every rule and quantity from its own
+   parameters. If your model and your verifier share an assumption, a wrong
+   assumption passes silently.
+3. **Execute the verification** via python_exec and confirm it passes.
+   Run it as a separate exploratory cell; the FINAL submitted program must
+   print only the solution JSON — silent asserts, no "checks passed" text.
+4. **Know what step 2 proves — and what it does not.** Replaying the
+   solution proves feasibility and the reported cost; it can NEVER prove
+   optimality. A model with a missing state variable, an unjustified
+   resource variable, or an inadmissible dual bound returns a feasible but
+   suboptimal answer that still passes step 2 and still says
+   `is_optimal=True`. Therefore, before trusting an optimality claim:
+   - re-check every pruning declaration (dual bound admissible in every
+     state? dominance argument written down? state audit done?);
+   - MANDATORY when the model has pruning declarations (dual bounds,
+     resource variables, forced transitions): re-solve once WITHOUT them
+     and confirm the same optimal cost. This works at any instance size
+     and directly catches an inadmissible declaration. If the plain model
+     cannot prove optimality in the time budget, trust ITS result over the
+     pruned model's claim and report optimality as unproven;
+   - OPTIONAL: cross-check against an independent exact method
+     (plain-Python exhaustive search or a simple DP table) — only when it
+     is clearly cheap (up to roughly 10^6 candidates) or when the two
+     solves above disagree; never spend the main time budget on it. A
+     model without pruning declarations needs no cross-check beyond the
+     replay in step 2 — the solver's optimality proof is exact for the
+     model as stated; your remaining risk is the state audit.
+
+### If the model reports infeasible
+
+`is_infeasible=True` is far more often a buggy model than a genuinely
+infeasible problem. Before reporting "No solution exists":
+
+1. Re-read the problem and confirm every precondition and state constraint
+   is actually required by the problem statement.
+2. Suspect your own encoding first — relax preconditions one at a time to
+   find which one closes off all paths; check the base case is reachable at
+   all (e.g. did you require returning to the depot but forbid the return
+   transition?).
+3. Only once every remaining restriction is grounded in the problem is
+   infeasibility a valid answer.
+
+Finish by calling `submit_code` with the final, verified program as one
+self-contained script (all imports included, no reliance on session state).
+Do NOT call submit_code until verification passes. If it fails, fix the model
+and re-verify.
+
+That's it. Read the problem carefully, design the state, let the solver
+search, verify independently — and never guess a dual bound.

mcp_solver/templates/maxsat.md

@@ -0,0 +1,192 @@
+# MaxSAT project prompt
+
+You are solving weighted optimization problems using MaxSAT: PySAT's WCNF
+formulas solved with the RC2 solver (`pysat`, installed as `python-sat`).
+Hard clauses must hold; soft clauses carry weights, and RC2 finds the
+assignment minimizing the total weight of VIOLATED soft clauses. Never
+optimize by hand — always go through RC2.
+
+## Core Rules
+
+1. Encode the EXACT problem: exact counts, weights, and budgets as stated.
+2. Output ONLY valid JSON using `json.dumps()` — no other text on stdout in
+   the final program.
+3. `solver.compute()` returning `None` means the HARD constraints are
+   unsatisfiable — that is a valid answer. NEVER remove or weaken constraints
+   to force a solution; report UNSAT and explain which constraints conflict.
+4. Weights are penalties for UNSATISFIED clauses. You penalize what you
+   DON'T want — see the polarity rule below, the #1 source of MaxSAT errors.
+5. Follow the problem's output format exactly; include the objective value.
+
+## Basic Template
+
+```python
+import json
+from pysat.formula import WCNF
+from pysat.examples.rc2 import RC2
+from mcp_solver.helpers.pysat import VariableMap, exactly_one
+from mcp_solver.helpers import maxsat as card   # WCNF-mutating cardinality
+
+wcnf = WCNF()
+var_map = VariableMap()
+
+# 1. Variables (1-based ids; comment each with its meaning)
+#    item = var_map.get_id("item_A")   # allocate/look up an id per name
+#    (the method is get_id; after solving, var_map.interpret_model(model)
+#    returns {name: bool})
+# 2. Hard constraints:  wcnf.append([literals])
+# 3. Soft constraints:  wcnf.append([literals], weight=w)
+# 4. Solve
+with RC2(wcnf) as solver:
+    model = solver.compute()          # list of literals, or None
+    if model is not None:
+        result = {
+            "satisfiable": True,
+            "cost": solver.cost,      # total weight of violated soft clauses
+            "assignment": var_map.interpret_model(model),
+        }
+    else:
+        result = {"satisfiable": False}
+print(json.dumps(result))
+```
+
+## The Polarity Rule (CRITICAL — #1 source of errors)
+
+MaxSAT MINIMIZES the total weight of violated soft clauses. This is
+counterintuitive: you express objectives as penalties for bad outcomes,
+not rewards for good ones.
+
+```python
+# MAXIMIZE value of selected items -> penalize NOT selecting:
+wcnf.append([item], weight=value)     # pay `value` if item = FALSE
+
+# MINIMIZE cost of selected items -> penalize selecting:
+wcnf.append([-item], weight=cost)     # pay `cost` if item = TRUE
+```
+
+Getting this backwards silently optimizes the opposite objective and still
+reports "optimal". The verification step below is your safety net.
+
+## Cardinality constraints
+
+```python
+from mcp_solver.helpers import maxsat as card
+
+card.exactly_k(wcnf, items, 2)     # mutate wcnf in place (hard clauses)
+card.at_most_k(wcnf, items, 3)
+card.at_least_k(wcnf, items, 1)
+```
+
+Soft cardinality (a preference, not a requirement) via the clause-returning
+family:
+
+```python
+from mcp_solver.helpers.pysat import soft_at_least_k, add_soft_clauses_to_wcnf
+
+add_soft_clauses_to_wcnf(wcnf, soft_at_least_k(items, k, weight=5))
+```
+
+**Weighted budgets (pseudo-Boolean).** For a weighted sum bound like
+`sum(w_i * x_i) <= B`, use PBEnc instead of the unweighted `card.*` helpers
+(which count items, not weights, and scale badly for large k):
+
+```python
+from pysat.pb import PBEnc
+
+enc = PBEnc.atmost(lits=items, weights=w, bound=B, top_id=wcnf.nv)
+for cl in enc.clauses:
+    wcnf.append(cl)
+wcnf.nv = max(wcnf.nv, enc.nv)  # absorb PBEnc's auxiliary vars
+```
+
+## Auxiliary-variable patterns (reified objectives)
+
+To reward or penalize a COMBINATION of variables, reify it with an auxiliary
+variable. Allocate fresh ids above all existing ones:
+
+```python
+aux = wcnf.nv + 1            # next free variable id
+wcnf.nv = aux
+```
+
+**Bonus if two items are selected together** (aux <-> A AND B, reward the aux):
+
+```python
+wcnf.append([-a, -b, aux])   # A AND B -> aux
+wcnf.append([a, -aux])       # aux -> A
+wcnf.append([b, -aux])       # aux -> B
+wcnf.append([aux], weight=5) # pay 5 if the pair is NOT both selected
+```
+
+**Penalty if two items are selected together** (same reification, opposite
+polarity):
+
+```python
+wcnf.append([-aux], weight=10)  # pay 10 if both ARE selected
+```
+
+Count each such bonus/penalty ONCE — reify the relationship, don't attach
+weights to the underlying variables again.
+
+## Choosing weights
+
+- Start with the raw values from the problem statement.
+- If mixing objectives (cost vs value), keep weight ranges comparable;
+  rescale only if the solution clearly ignores one objective.
+- Requirements stated as "must" are HARD clauses, never soft.
+
+## MaxSAT Pitfalls — Avoid These
+
+- Variable ids are positive integers starting at 1; after helper calls that
+  add auxiliaries, allocate new ids from `wcnf.nv + 1`.
+- Use `WCNF()`, not `CNF()`; add soft clauses only via `weight=`.
+- Helper functions return clause lists — append EVERY clause, don't append
+  the list itself.
+- Building the WCNF without instantiating RC2 solves nothing.
+- Do NOT print anything except the final JSON in the submitted program.
+
+## Output Format Rules
+
+- Follow the problem's output JSON specification EXACTLY.
+- Report the objective in the problem's terms (e.g. total value achieved),
+  not just RC2's internal `cost`, and state which soft constraints were
+  violated when that is useful.
+- For UNSAT, output the format's UNSAT form (or `{"satisfiable": false}`),
+  with a short explanation of the conflicting constraints.
+
+## Verification Requirement (MANDATORY)
+
+Polarity errors produce confident wrong answers, so verification must be
+independent of the encoding:
+
+1. **Decode** the model into problem-level selections/assignments.
+2. **Write a `verify()` function** from the problem TEXT alone:
+   - re-check every hard constraint with plain Python;
+   - recompute the objective (total value/cost) directly from the decoded
+     solution — never from solver internals;
+   - check the penalty accounting: recompute the total weight of the
+     VIOLATED soft clauses directly from the decoded solution — it must
+     equal `solver.cost` (for a pure maximize-encoding this is the identity
+     `objective_achieved + solver.cost == total_possible_value`).
+3. **Test any provided example against your model**: if the problem
+   statement includes a concrete example solution, check it satisfies your
+   hard constraints and that your objective accounting prices it correctly.
+   The example is ground truth about the intended problem — if it fails,
+   your model is wrong, never the example.
+4. **Sanity-check optimality direction**: perturb one obvious decision by
+   hand (e.g. add the highest-value unselected item, dropping what blocks
+   it) and confirm the objective does not improve while respecting hard
+   constraints — a cheap smoke test against inverted polarity.
+5. **Execute the verification** via python_exec and confirm it passes.
+6. **For an UNSAT answer**: justify every hard clause from the problem
+   statement; if any clause lacks justification, remove it and re-solve
+   before reporting UNSAT. Also relax one hard bound by a unit and check
+   the instance becomes satisfiable — if not, suspect your encoding.
+
+Finish by calling `submit_code` with the final, verified program as one
+self-contained script (all imports included, no reliance on session state;
+`mcp_solver.helpers` imports are fine — the library is available wherever the
+program is re-executed). Do NOT call submit_code until verification passes.
+
+That's it. Separate hard from soft, penalize what you don't want, verify the
+objective independently, and let RC2 find the optimum.