Constraints module
Checks whether a plan can meet every rule you set, finds the best one, and when none exists shows which rules conflict and the least that would have to change.
On this page
What it is for
Checks whether a plan can meet every rule you set, finds the best one, and when none exists shows which rules conflict and the least that would have to change.
- You want to know whether one plan can meet all your goals and limits at once.
- Your goals cannot all hold and you want to know the least you would have to give up.
- You want to compare what-if options side by side.
- You want to know how far one assumption can move before the answer changes.
Ask your bot
You do not type commands. Ask in plain words and the bot runs the module for you.
- You ask
- Can next month's plan meet every rule we set, and if not, what is the least we would have to give up?
- What you get back
- The bot says whether a plan exists that meets every rule and which is best. If none exists, it shows the smallest sets of rules that cannot all hold and the smallest changes that would make a plan possible. It names any assumption the answer rests on.
What the bot does with it
- The bot writes the decision down with you as a model: the choices, the numbers they depend on, where each number came from, and the rules.
- It shows you the model and what changed, and stores it only after you approve.
- It asks the module for the best plan. The module says what it proved: the best plan, a plan that may not be the best, or that no plan exists.
- When no plan exists, it asks which rules conflict and which goals could be given up. Giving one up is your decision.
- It compares what-if options side by side and finds the value at which the answer changes.
- Solving needs an extra solver download, installed only when you ask for it. Without it the module still stores and checks models.
What it stores
Every stored version of a model, the history of changes and the answers you chose to keep live in one SQLite file, constraints/constraints.sqlite, in the bot's Ambitious folder (/workspace/ambitious by default). Stored versions and kept answers are added and never edited.
The module has no screens of its own. It reads JSON, writes JSON, and keeps its data under /workspace/ambitious on the bot's computer. It never sends data anywhere.
Command reference
For the technically curious. You will rarely type these yourself; the bot runs them. Every command answers with the same envelope: whether it worked, which module and command ran, the data, and a list of errors with a hint for each. Open an example to see the command and its output.
ExampleCheck a small model before storing it. It has one rule, at least two people on each shift, and one number with its source.
Command
ambitious-constraints model validate --in weekend-cover.json --jsonOutput
{
"ok": true,
"schemaVersion": 1,
"module": "constraints",
"command": "model validate",
"data": {
"valid": true,
"digest": "03bcb6eb00f988d22ec3226c1d6ea971643b3a4f4cd562e3f07ada26ba496ceb",
"problems": [],
"counts": {
"variables": 1,
"params": 1,
"constraints": 1,
"evidence": 1,
"scenarios": 0
}
},
"errors": [],
"meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}ExampleShow what storing the same model would change. Nothing is stored until the owner approves and the bot commits it.
Command
ambitious-constraints model propose --in weekend-cover-proposal.json --jsonOutput
{
"ok": true,
"schemaVersion": 1,
"module": "constraints",
"command": "model propose",
"data": {
"valid": true,
"digest": "03bcb6eb00f988d22ec3226c1d6ea971643b3a4f4cd562e3f07ada26ba496ceb",
"problems": [],
"counts": {
"variables": 1,
"params": 1,
"constraints": 1,
"evidence": 1,
"scenarios": 0
},
"model_id": "weekend-cover",
"base_version": 0,
"diff": {
"variables": {
"added": [
"people_on_shift"
],
"removed": [],
"changed": []
},
"params": {
"added": [
"minimum_cover"
],
"removed": [],
"changed": []
},
"constraints": {
"added": [
"cover"
],
"removed": [],
"changed": []
},
"scenarios": {
"added": [],
"removed": [],
"changed": []
},
"objective_changed": true,
"evidence_changed": true,
"hints_changed": false,
"unchanged": false
},
"stored": false
},
"errors": [],
"meta": { "now": "2026-03-02T09:00:00.000Z", "seed": 7, "version": "0.1.0" }
}Show every command
| commands | Lists every command the module offers. |
|---|---|
| selfcheck | Checks the installed file, the database and whether the solver is installed, and lists any problems in plain words. |
| model validate | Checks that a model is usable and lists every problem, including numbers with no evidence. |
| model propose | Shows how a model differs from the stored version. Nothing is stored. |
| model commit | Stores the approved model as a new version, and refuses if the stored model changed since it was proposed. |
| model clone | Copies a model to a new name so a variant can be tried without touching the original. |
| model get | Returns one stored version of a model. |
| model history | Returns the ordered list of changes made to one model. |
| model list | Lists the stored models. |
| solve | Finds the best plan that meets every rule, or reports that none exists, and says what was proved. |
| explain | When no plan exists, returns the smallest sets of rules that cannot all hold and the smallest sets of goals whose removal makes a plan possible. |
| whatif | Solves several named scenarios and lists what differs between their answers. |
| sweep | Tries a range of values for one number and reports where the answer changes. |
| run record | Keeps the exact answer a command returned. |
| run get | Returns one kept answer. |
| run list | Lists the kept answers. |
Source and releases
The module is open source under the Apache license. Each release carries one bundled file and its checksums; the bot installs it for you.