agentic-mcp-solver 4.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- agentic_mcp_solver-4.2.0.dist-info/METADATA +318 -0
- agentic_mcp_solver-4.2.0.dist-info/RECORD +22 -0
- agentic_mcp_solver-4.2.0.dist-info/WHEEL +4 -0
- agentic_mcp_solver-4.2.0.dist-info/entry_points.txt +5 -0
- agentic_mcp_solver-4.2.0.dist-info/licenses/LICENSE +21 -0
- mcp_solver/__init__.py +20 -0
- mcp_solver/agent/__init__.py +1 -0
- mcp_solver/agent/cli.py +496 -0
- mcp_solver/agent/harness.py +258 -0
- mcp_solver/agent/mcp_server.py +508 -0
- mcp_solver/agent/runfolder.py +159 -0
- mcp_solver/helpers/__init__.py +7 -0
- mcp_solver/helpers/maxsat.py +79 -0
- mcp_solver/helpers/pysat.py +346 -0
- mcp_solver/helpers/z3.py +213 -0
- mcp_solver/templates/__init__.py +22 -0
- mcp_solver/templates/clingo.md +1305 -0
- mcp_solver/templates/cpmpy.md +124 -0
- mcp_solver/templates/didp.md +270 -0
- mcp_solver/templates/maxsat.md +192 -0
- mcp_solver/templates/pysat.md +186 -0
- mcp_solver/templates/z3.md +165 -0
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# PySAT project prompt
|
|
2
|
+
|
|
3
|
+
You are solving Boolean satisfiability problems using PySAT (the `pysat` package,
|
|
4
|
+
installed as `python-sat`). Encode the problem in CNF, solve it with a real SAT
|
|
5
|
+
solver, and report the result. Never reason a solution out by hand and never
|
|
6
|
+
write your own search — always go through the solver; never mock a solver,
|
|
7
|
+
fabricate a model, or check constraints by hand instead of solving.
|
|
8
|
+
|
|
9
|
+
## Core Rules
|
|
10
|
+
|
|
11
|
+
1. Encode the EXACT problem as stated: exact counts, exact ranges, exact sizes.
|
|
12
|
+
Never change numbers to "simplify" — that solves a different problem.
|
|
13
|
+
2. Output ONLY valid JSON using `json.dumps()` — no other text on stdout in the
|
|
14
|
+
final program.
|
|
15
|
+
3. Follow the problem's output format specification exactly if one is given;
|
|
16
|
+
otherwise output `{"satisfiable": true/false, ...}` with a readable assignment.
|
|
17
|
+
4. `solver.solve()` returning `False` means UNSAT — that is a valid answer, not
|
|
18
|
+
an error. If you get UNSAT, re-check that every clause is justified by the
|
|
19
|
+
problem statement before reporting it.
|
|
20
|
+
5. Free solver memory: use the solver as a context manager, or call
|
|
21
|
+
`solver.delete()`.
|
|
22
|
+
|
|
23
|
+
## Basic Template
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
import json
|
|
27
|
+
from pysat.formula import CNF
|
|
28
|
+
from pysat.solvers import Glucose3
|
|
29
|
+
from mcp_solver.helpers.pysat import VariableMap, exactly_one
|
|
30
|
+
|
|
31
|
+
formula = CNF()
|
|
32
|
+
var_map = VariableMap()
|
|
33
|
+
|
|
34
|
+
# Variables: map problem entities to SAT variable ids (1-based)
|
|
35
|
+
# Constraints: formula.append([...]) clauses
|
|
36
|
+
# Solve
|
|
37
|
+
with Glucose3(bootstrap_with=formula) as solver:
|
|
38
|
+
if solver.solve():
|
|
39
|
+
model = solver.get_model()
|
|
40
|
+
assignment = var_map.interpret_model(model)
|
|
41
|
+
result = {"satisfiable": True, "assignment": assignment}
|
|
42
|
+
else:
|
|
43
|
+
result = {"satisfiable": False}
|
|
44
|
+
print(json.dumps(result))
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## SAT Variables — the two numbering systems
|
|
48
|
+
|
|
49
|
+
SAT variables must be positive integers starting at 1 (variable 0 is invalid);
|
|
50
|
+
Python iterates 0-based. Keep the two apart:
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
# Dict-based mapping (preferred for readability)
|
|
54
|
+
queen = {}
|
|
55
|
+
var_num = 1
|
|
56
|
+
for row in range(8): # 0-based iteration
|
|
57
|
+
for col in range(8):
|
|
58
|
+
queen[(row, col)] = var_num # 1-based SAT variable
|
|
59
|
+
var_num += 1
|
|
60
|
+
|
|
61
|
+
# Formula-based mapping
|
|
62
|
+
def get_var(row, col, num_cols):
|
|
63
|
+
return row * num_cols + col + 1 # +1 makes it 1-based
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Or let `VariableMap` manage ids and names:
|
|
67
|
+
|
|
68
|
+
```python
|
|
69
|
+
var_map = VariableMap()
|
|
70
|
+
x = var_map.get_id("x") # allocates 1, 2, 3, ... per name
|
|
71
|
+
node_color = var_map.get_id("node_A_Red")
|
|
72
|
+
assignment = var_map.interpret_model(model) # {"x": True, "node_A_Red": False, ...}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Interpreting the model
|
|
76
|
+
|
|
77
|
+
`solver.get_model()` returns a list of literals: positive = variable TRUE,
|
|
78
|
+
negative = variable FALSE.
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
model = solver.get_model()
|
|
82
|
+
is_true = x in model # single variable
|
|
83
|
+
solution = {name: (vid in model) for name, vid in var_map.get_mapping().items()}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## Helper library (mcp_solver.helpers.pysat)
|
|
87
|
+
|
|
88
|
+
All of these return `list[list[int]]` clauses — append each clause to your formula:
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
from mcp_solver.helpers.pysat import (
|
|
92
|
+
VariableMap,
|
|
93
|
+
at_most_one, exactly_one, # pairwise encodings
|
|
94
|
+
at_most_k, at_least_k, exactly_k, # cardinality (pairwise <=20 vars, CardEnc
|
|
95
|
+
# above — then pass top_id=<max var id
|
|
96
|
+
# in your formula> so auxiliaries don't
|
|
97
|
+
# collide with your other variables)
|
|
98
|
+
implies, mutually_exclusive, if_then_else,
|
|
99
|
+
)
|
|
100
|
+
|
|
101
|
+
for clause in exactly_k(list(queen.values()), 8):
|
|
102
|
+
formula.append(clause)
|
|
103
|
+
for clause in implies(a, b): # a -> b, i.e. [[-a, b]]
|
|
104
|
+
formula.append(clause)
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
PySAT's own `pysat.card.CardEnc` is also available if you need a specific
|
|
108
|
+
encoding, but the helpers above are the tested path.
|
|
109
|
+
|
|
110
|
+
## Common logical encodings
|
|
111
|
+
|
|
112
|
+
- a AND b implies c: `formula.append([-a, -b, c])`
|
|
113
|
+
- at least one of a set: `formula.append(list_of_vars)`
|
|
114
|
+
- exactly one value per entity (one-hot): `formula.extend(exactly_one(entity_vars))`
|
|
115
|
+
- adjacent nodes differ (per color c): `formula.append([-color[u][c], -color[v][c]])`
|
|
116
|
+
|
|
117
|
+
## PySAT Pitfalls — Avoid These
|
|
118
|
+
|
|
119
|
+
- Variable 0 does not exist; ids must start at 1.
|
|
120
|
+
- "9 colors" means `range(9)` (colors 0–8), not `range(10)` — off-by-one on
|
|
121
|
+
ranges is the #1 encoding error.
|
|
122
|
+
- Do NOT hand-roll global counters with `nonlocal` at module level; use
|
|
123
|
+
`VariableMap` (or `global` if you must).
|
|
124
|
+
- Do NOT print anything except the final JSON in the submitted program.
|
|
125
|
+
- Solvers: `Glucose3` is the default; `Cadical153` is a good alternative for
|
|
126
|
+
harder instances (`from pysat.solvers import Cadical153`).
|
|
127
|
+
|
|
128
|
+
## Output Format Rules
|
|
129
|
+
|
|
130
|
+
- Follow the problem's output JSON specification EXACTLY — field names, nesting,
|
|
131
|
+
and axis order as written; never invent an alternative encoding.
|
|
132
|
+
- Derive every output array's dimensions from parameters stated in the problem,
|
|
133
|
+
never from quantities your encoding introduced.
|
|
134
|
+
- For UNSAT problems, output the format's UNSAT form (or
|
|
135
|
+
`{"satisfiable": false}` if none is specified) — do not weaken or drop
|
|
136
|
+
constraints to force satisfiability.
|
|
137
|
+
|
|
138
|
+
## Verification Requirement (MANDATORY)
|
|
139
|
+
|
|
140
|
+
SAT encodings easily contain subtle bugs (wrong polarity, missing clauses,
|
|
141
|
+
swapped indices). Before saving, you MUST:
|
|
142
|
+
|
|
143
|
+
1. **Solve and decode** the model into problem-level values.
|
|
144
|
+
2. **Write a `verify()` function** that checks every constraint from the problem
|
|
145
|
+
statement using plain Python — independent of your CNF encoding:
|
|
146
|
+
```python
|
|
147
|
+
def verify(result):
|
|
148
|
+
# Re-derive sizes and constraints from the problem TEXT,
|
|
149
|
+
# not from your encoding's variables
|
|
150
|
+
assert len(result["queens"]) == 8
|
|
151
|
+
for (r1, c1), (r2, c2) in itertools.combinations(result["queens"], 2):
|
|
152
|
+
assert r1 != r2 and c1 != c2, "attacking pair (row/col)"
|
|
153
|
+
assert abs(r1 - r2) != abs(c1 - c2), "attacking pair (diagonal)"
|
|
154
|
+
print("All checks passed")
|
|
155
|
+
```
|
|
156
|
+
If your encoding and your verifier share an assumption, a wrong assumption
|
|
157
|
+
passes silently — re-read the problem statement when writing `verify()`.
|
|
158
|
+
Also assert the output's *structure* matches the stated format (element
|
|
159
|
+
order, axis convention, sizes) — constraint checks alone can pass a
|
|
160
|
+
transposed answer — and for problems with given input data (clues, edges),
|
|
161
|
+
check against a separately transcribed copy of the data, not the encoder's
|
|
162
|
+
variable.
|
|
163
|
+
3. **Test any provided example against your model**: if the problem statement
|
|
164
|
+
includes a concrete example solution, run it through `verify()` and check
|
|
165
|
+
it satisfies your constraints. The example is ground truth about the
|
|
166
|
+
intended problem — if it fails, your model or verifier is wrong, never the
|
|
167
|
+
example; do not dismiss it as "just illustrating the format".
|
|
168
|
+
4. **Execute the verification** via python_exec and confirm it passes.
|
|
169
|
+
`verify()` belongs to this exploration phase; the final submitted program
|
|
170
|
+
need not include it (and if it does, it must not print anything besides
|
|
171
|
+
the solution JSON).
|
|
172
|
+
5. **For an UNSAT answer**: list each clause group and the sentence of the
|
|
173
|
+
problem statement that justifies it. If any clause lacks a justification,
|
|
174
|
+
remove it and re-solve before reporting UNSAT. Also confirm the UNSAT is
|
|
175
|
+
not an artifact of over-constraining: relax one bound (one more color, one
|
|
176
|
+
more unit of budget) and check the solver then returns SAT — if even the
|
|
177
|
+
relaxation is UNSAT, suspect your encoding before the problem.
|
|
178
|
+
|
|
179
|
+
Finish by calling `submit_code` with the final, verified program as one
|
|
180
|
+
self-contained script (all imports included, no reliance on session state;
|
|
181
|
+
`mcp_solver.helpers` imports are fine — the library is available wherever the
|
|
182
|
+
program is re-executed). Do NOT call submit_code until verification passes.
|
|
183
|
+
If it fails, fix the encoding and re-verify.
|
|
184
|
+
|
|
185
|
+
That's it. Read the problem carefully, map entities to 1-based variables, encode
|
|
186
|
+
exactly what is stated, verify independently, and let the SAT solver do the search.
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
# Z3 project prompt
|
|
2
|
+
|
|
3
|
+
You are solving SMT problems using Z3 (`z3-solver`): constraint satisfaction,
|
|
4
|
+
optimization, and verification/theorem proving over integers, reals, booleans,
|
|
5
|
+
bitvectors, arrays, and uninterpreted functions. Model declaratively — never
|
|
6
|
+
enumerate or search by hand.
|
|
7
|
+
|
|
8
|
+
## Core Rules
|
|
9
|
+
|
|
10
|
+
1. Encode the EXACT problem: exact bounds, sizes, and domains as stated —
|
|
11
|
+
plus any constraints implied but not spelled out.
|
|
12
|
+
2. Output ONLY valid JSON using `json.dumps()` — no other text on stdout in
|
|
13
|
+
the final program.
|
|
14
|
+
3. EVERY task ends with a submitted, runnable Z3 program — including proof and
|
|
15
|
+
verification tasks. A prose proof, however correct, is NOT an acceptable
|
|
16
|
+
answer: encode the proof obligations in Z3, execute them via python_exec,
|
|
17
|
+
and submit the program with submit_code.
|
|
18
|
+
4. `unsat` is a valid answer. For plain constraint problems it means "no
|
|
19
|
+
solution"; for a counterexample search it means "property PROVED". State
|
|
20
|
+
the semantic result, not just the solver status (see below).
|
|
21
|
+
5. Extract values with `model[x]` after `sat` and convert to plain Python
|
|
22
|
+
(`.as_long()` for ints, `str()`/`as_fraction()` for reals, `bool(...)`
|
|
23
|
+
via `is_true`) before putting them in the JSON.
|
|
24
|
+
|
|
25
|
+
## Basic Template
|
|
26
|
+
|
|
27
|
+
```python
|
|
28
|
+
import json
|
|
29
|
+
from z3 import *
|
|
30
|
+
|
|
31
|
+
solver = Solver()
|
|
32
|
+
# Variables (Z3 constructors!), constraints via solver.add(...)
|
|
33
|
+
if solver.check() == sat:
|
|
34
|
+
model = solver.model()
|
|
35
|
+
result = {"satisfiable": True, "x": model[x].as_long()}
|
|
36
|
+
else:
|
|
37
|
+
result = {"satisfiable": False}
|
|
38
|
+
print(json.dumps(result))
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
## Python Primitives vs Z3 Variables (#1 error source)
|
|
42
|
+
|
|
43
|
+
Z3 constraints need symbolic terms. `'int' object has no attribute 'as_ast'`
|
|
44
|
+
means a Python value leaked into a Z3 position:
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
# WRONG: x = 5; solver.add(x + y == 10)
|
|
48
|
+
# RIGHT:
|
|
49
|
+
x, y = Ints("x y")
|
|
50
|
+
solver.add(x == 5, x + y == 10)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Pythonic array style — comprehensions over constructor calls:
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
arr = [Int(f"arr_{i}") for i in range(8)]
|
|
57
|
+
solver.add([arr[i] <= arr[i + 1] for i in range(7)]) # sorted
|
|
58
|
+
solver.add(Distinct(arr)) # all different
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Theorem proving: sat/unsat semantics (get this right)
|
|
62
|
+
|
|
63
|
+
To verify a property, search for a COUNTEREXAMPLE — add the NEGATION:
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
solver.add(Not(property_holds))
|
|
67
|
+
if solver.check() == unsat:
|
|
68
|
+
result = {"verified": True} # no counterexample -> property PROVED
|
|
69
|
+
else:
|
|
70
|
+
m = solver.model() # counterexample found -> property FALSE
|
|
71
|
+
result = {"verified": False, "counterexample": {...}}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
| Mode | sat means | unsat means |
|
|
75
|
+
| ----------------------- | ------------------ | ------------------ |
|
|
76
|
+
| counterexample search | property FALSE | property TRUE |
|
|
77
|
+
| direct constraint model | solution exists | no solution |
|
|
78
|
+
|
|
79
|
+
Report the SEMANTIC answer in the JSON (`verified: true`), never the raw
|
|
80
|
+
solver status alone, and never a contradictory combination.
|
|
81
|
+
|
|
82
|
+
For induction proofs: verify the base case and the inductive step with
|
|
83
|
+
separate fresh `Solver()` instances; the theorem is proved only if every
|
|
84
|
+
step's counterexample search is unsat.
|
|
85
|
+
|
|
86
|
+
## Optimization
|
|
87
|
+
|
|
88
|
+
```python
|
|
89
|
+
opt = Optimize()
|
|
90
|
+
opt.add(constraints)
|
|
91
|
+
opt.maximize(total) # or opt.minimize(...)
|
|
92
|
+
if opt.check() == sat:
|
|
93
|
+
m = opt.model()
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Helper library (mcp_solver.helpers.z3)
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
from mcp_solver.helpers.z3 import (
|
|
100
|
+
array_is_sorted, all_distinct, array_contains, # for Z3 Array objects ONLY
|
|
101
|
+
exactly_k, at_most_k, at_least_k, # over lists of Bools (PbEq/PbLe/PbGe)
|
|
102
|
+
function_is_injective, function_is_surjective,
|
|
103
|
+
smallest_subset_with_property, # minimal subset search
|
|
104
|
+
)
|
|
105
|
+
solver.add(exactly_k(selection_bools, 3))
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Caveat: `array_is_sorted`/`all_distinct`/`array_contains` quantify over Z3
|
|
109
|
+
`Array` objects. For Python lists of Z3 variables use `Distinct(arr)`, loops,
|
|
110
|
+
or `Or([arr[i] == v for i in range(n)])` instead.
|
|
111
|
+
|
|
112
|
+
## Z3 Pitfalls — Avoid These
|
|
113
|
+
|
|
114
|
+
- Integer division on `Int` truncates; use `Real`/`Q(a, b)` for exact
|
|
115
|
+
fractions when the problem is about rationals.
|
|
116
|
+
- `If(cond, a, b)` is the symbolic conditional; Python `if` on a Z3 term
|
|
117
|
+
does not branch symbolically.
|
|
118
|
+
- Bitvectors: use `BitVec`, `Extract`, `ZeroExt`; mixing widths raises sort
|
|
119
|
+
errors — align widths explicitly.
|
|
120
|
+
- Big constant enumerations are fine, but never emulate the search yourself:
|
|
121
|
+
no generate-and-test loops over the solution space.
|
|
122
|
+
- Do NOT print anything except the final JSON in the submitted program.
|
|
123
|
+
|
|
124
|
+
## Output Format Rules
|
|
125
|
+
|
|
126
|
+
- Follow the problem's output JSON specification EXACTLY.
|
|
127
|
+
- Convert every reported value to plain Python types (no Z3 objects in JSON).
|
|
128
|
+
- For verification tasks report the semantic verdict (and a counterexample
|
|
129
|
+
when one exists); for UNSAT constraint problems use the format's UNSAT form
|
|
130
|
+
or `{"satisfiable": false}`.
|
|
131
|
+
|
|
132
|
+
## Verification Requirement (MANDATORY)
|
|
133
|
+
|
|
134
|
+
1. **Solve and extract** concrete values from the model.
|
|
135
|
+
2. **Write a `verify()` function** that re-checks every constraint from the
|
|
136
|
+
problem statement using plain Python arithmetic on the extracted values —
|
|
137
|
+
independent of your Z3 encoding. Re-derive sizes and bounds from the
|
|
138
|
+
problem TEXT, not from your encoding.
|
|
139
|
+
3. **Test any provided example against your model**: if the problem statement
|
|
140
|
+
includes a concrete example solution, run it through `verify()` and check
|
|
141
|
+
it satisfies your constraints. The example is ground truth about the
|
|
142
|
+
intended problem — if it fails, your model or verifier is wrong, never the
|
|
143
|
+
example; do not dismiss it as "just illustrating the format".
|
|
144
|
+
4. **For theorem-proving results, cross-check the direction**: restate in one
|
|
145
|
+
sentence which of sat/unsat you got and what it means semantically; for a
|
|
146
|
+
"proved" claim, spot-check the property on 2–3 concrete instances with
|
|
147
|
+
plain Python.
|
|
148
|
+
5. **For optimization**: assert optimality by re-solving with a strict bound
|
|
149
|
+
(`opt2.add(objective > best)` for maximize) and confirming unsat.
|
|
150
|
+
6. **For a "no solution exists" answer**: a bare solver `unsat` is not
|
|
151
|
+
self-verifying. Independently confirm it — exhaustively enumerate the
|
|
152
|
+
domain with plain Python when it is small enough, or re-derive the
|
|
153
|
+
contradiction by hand — and re-check that every constraint you encoded is
|
|
154
|
+
justified by the problem statement.
|
|
155
|
+
7. **Execute the verification** via python_exec and confirm it passes.
|
|
156
|
+
`verify()` belongs to this exploration phase; the final submitted program
|
|
157
|
+
need not include it (and must print nothing besides the solution JSON).
|
|
158
|
+
|
|
159
|
+
Finish by calling `submit_code` with the final, verified program as one
|
|
160
|
+
self-contained script (all imports included, no reliance on session state;
|
|
161
|
+
`mcp_solver.helpers` imports are fine — the library is available wherever the
|
|
162
|
+
program is re-executed). Do NOT call submit_code until verification passes.
|
|
163
|
+
|
|
164
|
+
That's it. Use Z3 constructors for every symbolic value, keep the sat/unsat
|
|
165
|
+
semantics straight, verify with plain Python, and let Z3 do the reasoning.
|